in3 documentation

6. Images and blocks

6.1. Images

Images are used with the .img or .map tags. The configyour-script will try to match the image in the .in file with an existing image file. There is a sequence to the matching:

If an .xcf exists, use that, else
if a .dia exists, use that one, else
if a .gnuplot exists, use that, else
if a .eqn exists, use that

Note that gnuplot and eqn images can be created in blocks, which keeps the information with the rest of the text, and which may be more flexible.

Example of a .xcf image: The image below is defined as img IMG_9039.png

Example of an image generated by dia :

And an example of a gnuplot. The gnuplot file contains:

set terminal png size 400,300 enhanced font "Helvetica,20"
set output 'gnuplot.png'
plot sin(x) title 'Sine Function', tan(x) title 'Tangent'

eqn can also be used to generate an image. The EQ and EN tags must be present and the source file must end with .eqn

An example

 .EQ
 sqrt a+b = int a sup { i pi } d omega
 .EN

gives:

These image-types are handled mainly by the configyour-script.

6.2. Blocks

Blocks are sets that are handled separately. They may be processed by an external program, or provide specific information for a pre-processor of groff. Blocks can be named; if they are not named, a name is generated for the block. The behavior of blocks can be different per output-processor. For example: pic-blocks are handled as in-file commands for pic in the groff-back-end (in3tbl), but are used to create an png image for the HTML back-ends (in3html).

There are two sorts of blocks:

inline
stand alone

Inline blocks are created either with the .inline request, or by adding a .block format inline to a block. An inline block must not terminate a paragraph; there cannot be an empty line above it and there should not be an empty line following it.

Stand alone blocks, on the contrary, must be preceded by an empty line and followed by an empty line.

6.2.1. pre

The pre-blocktype is equivalent to the blocks created with the .pre tag. These kind of blocks are never used as in-line. Example:

 .block pre
 a
  aa
    aaa
  aa
 a
 .block

will create:

a
 aa
   aaa
 aa
a

6.2.2. gnuplot

Gnuplot blocks are always handled by an external program, gnuplot. As an example:

 .block gnuplot
 set multiplot                       # multiplot mode (prompt changes to 'multiplot')
 set size 1, 0.5
 set origin 0.0,0.5
 plot sin(x), log(x)
 set origin 0.0,0.0
 plot sin(x), log(x), cos(x)
 unset multiplot  
 .block

will create:

There is of course a decision whether you want to specify the block in-line, or use a separate file and let the configyour scripts handle everything. What I do is when possible, keep it in a block, but is required, a separate gnuplot file can be used.

6.2.3. pic

A pic block uses pic to generate a simple drawing. For the tbl back-end, this means adding the lines as a .pic drawing. For the HTML back-end, groff is used to create a png file.

 .block pic
 .block format scale=10
 box; arrow;circle; arrow;ellipse;
 .block

will create:

Pic is used to create simple drawings. If you need something more elaborate, use a drawing program. gimp or diagram or something like that.

6.2.4. eqn

For simple equations, use the blocktype eqn. As an example,

 The following equation
 .inline eqn a sub i = 4 + b sup 2 - i
 is quite useful.

will produce The following equation inline.6.4>

is quite useful.

Like pic, the block is interpreted by the pre-processor for groff.

6.2.5. texeqn

If the equations get more complicated or if you are diving in parts that are not well supported in eqn , you might want to use a latex expression. Texeqn blocks automatically handle all latex eccentricities so you can concentrate on the equation.

 .block texeqn
 F(x,y)=0 ~~\mbox{and}~~
 \left| \begin{array}{ccc}
   F''_{xx} & F''_{xy} &  F'_x \\
   F''_{yx} & F''_{yy} &  F'_y \\
   F'_x     & F'_y     & 0 
   \end{array}\right| = 0
 .block

gives:

Texeqns are always embedded as a picture.

6.2.6. music

Music blocks are interpreted by lilypond with the page options set thus that the figure doesn't have large empty spaces. As an example:

 .block music
 \relative c'' {
 \new PianoStaff <<
 \new Staff { \time 2/4 c4 e | g g, | }
 \new Staff { \clef "bass" c,,4 c' | e c | }
 >>
 }
 .block

produces:

It must be said that, though in3 is able to include images produced by lilypond, if you want to do serious typesetting of music, lilypond is, as stand alone, extremely powerful.

6.2.7. Class blocks

It is possible to create a block with a specific style. These are called class blocks. The syntax is:

 .block classxxx
 text within the block
 .block

The style must begin with the word class and the styles should be defined in the stylesheet(s).