3. Some details

3.1. Concepts

An input text consists of constructs. A construct is (in general) separated from other constructs by blank lines. Some constructs are one-line only, and after a one-line construct, the trailing blank line may be ommitted. In the previous chapter, we saw the constructs paragraph, table and list. A list of the constructs is in the table below:

Within constructs, requests can be made. For example, within a paragraph, some text may be requested as bold. These are format requests. Some are not really used for formatting, but they are called that anyway. You may notice that, for example .image is both a construct and a format request. If it is a format request, the image is presented as in-line with the text, whereas if it is used as a construct, the image is placed on it's own.

Most format requests are terminated by the end of line (except for example the .block request)

3.2. Specific fonts

It is possible to use a specific font for parts of the text. If you want to change the font for all the text, use stylesheets.

The request for a text in a specific font is:

 .font [font name][size] text

For example:

 .font PinyonScript18 PinyonScript.

produces PinyonScript. Note that the fontname may be ommitted or the size, but not both. Of course, the fonts need to be available in the output processors.

If the fontname is ommitted, the current font is used, so .font 16 would produce a larger text. If the size is ommitted, the font is used in the same size as the current, so .font courierbolditalic bold and italic would produce bold and italic text.

The available fonts are stored in /usr/local/share/in3/fontmap and the first column is the one used in in3. A list can be generated with cut -d "tab" -f1 /usr/local/share/in3/fontmap

3.3. Characters

In3 tries its best to produce the right characters. That is not always straight forward, because the output handlers (groff or web browser) may have different ideas about what character is which.

To help in the translation, /usr/local/chare/in3/in3charmap1 contains a translation for web and groff. The file also contains a number of "percent-translations", for example: %%;8X; produces ✄. A percent translation always starts with a %%; and always ends with a ;. A special is the %%;%%;; which translates to %%;. So %%;%%;;8X produces %%;8X; A list of characters is available in the appendix.

It is possible to add your own translation in meta.in with an .in3charmap request. The syntax is:

 .in3charmap "in3-character","groff-character","html-character"

All the three characters must be present, even if they are empty. None of the characters may have a "," in them. The example below allows a quoted tab-character "tab" to be displayed:

 .in3charmap "%%;qtab;",""\s-6tab\s+6"",""<span style="font-size:0.4em">tab</span>""

The extra translations are read from meta.in for all processing, even for complete.in which may not be obvious directly.

3.4. Left notes and side notes

Left notes are short scribbles in the left margin. They are, for example, used when typesetting theater plays:

A .back request, a table, a list or a heading at any level stops the hanging indenting.

Side notes may be more elaborate. They are placed in a column on the right side of the paragraph. Normally, when a side note appears somewhere in the text, the column on the right is reserved in the whole document.

Whether the column is reserved is detemined by the variable notes.

This means, that it is possible to supress the side note column by setting notes to 0. It is advised to do so at a natural moment (just before a header, a list or a table), because doing it in the middle of a paragraph will produce surprising results, like wrong line length or dropped text.

Left and side notes are collected per paragraph and put in coluns to the right and left. Numbering of the side notes is restarted at the beginning of each paragraph.

Where a left note is a simple scriple in the left margin, a side note can have an actual referral. The formatting of the sidenote is determined by the following variables:

The variables sidechar and sideref can have a referral to the value of sidenumber.

3.5. Indent after

A special formatting request is the indent after =========> It is there for very specific cases: plays in rhyme.

3.6. Tables

We've already touched upon the tables. We've seen:

• Tables are created of tab-separated fields
• A cell can span columns if it contains <cs=...>
• A cell can span rows if it contains <rs=...>
• Format requests can be made in a cell (e.g. .b for bold )

In addition, a cell may contain <format=x> to set the alignment. X can be:

We also saw, that requests are possible in table cells. However, some requests require a new line (think of blocks). A combination of %n% replaces a newline in a cell. This allows us to create a table with:

    normal%n%.b bold%n%normal   norm%n%.u under%n%norm
    normal text%n%.b bold       and%n%.i italic%n%text

which gives:

Tables tend to expand to the complete width of the page. In3 will try to guess which column should be expanded. However, sometimes that is not a good idea. The variable tableexpand can be set to no to prevent table expansion, or to yes to enable it. As an example: the previous example table with .set tableexpand no gives:

The effect is mainly for the PS and PDF output. In html, no specific change will be visible.

For more flexibility, the variable colwidth can be set to a comma-separated list of column widths. The numbers are a percentage of the line length to the right side of the page, so overwriting the right margin. An x in a field will expand the table via this field, an empty field will allow the output processor to make a guess what the width could be. This is for PDFs. It also works well for simple tables, but if you use row- or columnspan, it quickly becomes very complex.

3.7. Pipe tables

There is another way, perhaps more intiutive to enter a table. You can draw a table with | and - symbols. There are a number of limitations; for example: you cannot use a | in the table text. Also, <format=xxx> is not supported. But, on the otherhand, it is much easier to include formatting commands.

|---------------------|
|  head               |
|---------------------|
| col 1  | col 2 +  3 |
|--------|------------|
|        | col  | col |
| col 1  | .b 2 |.u 3 |
|        |------|-----|
|        |  a   |  b  |
|---------------------|
| .block eqn          |
| r sup 2 over n sup 2|
| .block              |
|---------------------|

head
col 1	col 2 + 3
col 1	col 2	col 3
	a	b

Some rules:

• A pipe table starts with |- in the first column of the input text
• The first and last column must be a | symbol
• A | is a column separator. Always. So no | symbols are allowed in the text.
• A horizontal separation between two cells must be at least 4 dashes (----)
• Composed letters must be written out. For example: é must be written as %'e; This is because the translation of characters to percent-notation will mess-up the pipe-alignments.
• Leading and trailing spaces in a cell are deleted
• No allignment hints are allowed

3.8. csvfile

Another option to make a simple table is to include a separate csv file. The request would be:

 .csvfile file.csv [ separator ]

where separator is the field separator, which can be a comma, a colon or a semi-colon. Fields may be quoted with single or double quotes. No colspan or rowspan is supported. As an example, including a file test.csv with the contents:

a;b;c
d;e;f

would give:

3.9. Chapter, sections et cetera

Text is normally divided into chapters, sections et cetera. In3 uses the request . .h1 Chapter title for chapter titles, .h2 Section title for section titles and so on until .h9. If you think you need more levels, than you should rethink your approach to the subject. Or maybe In3 is just not for you.

Unnumbered headings can also be used using .hu followed by a number. The following sequence is an example with .h3, .hu3, .h3. Note how the numbering continues, eventhough the number is not printed.

3.9.1. H3 heading with number

Unnumbered heading at level 3

3.9.3. H3 heading with number