3. In language specification
3.1. Special Characters
Some characters have a special meaning.
Character
|
When
|
Meaning
|
{tab}
|
always
|
Tab is an indication that a format construct (leftnote, table or list) is used
|
..
|
beginning of line
|
A dot at the beginning of a line indicates a request
|
%
|
when interpret=2
|
Next characters are interpreted
|
-
|
beginning of line or after tab(s)
|
list item in a dash-list
|
#
|
beginning of line or after tab(s)
|
list item in a numbered-list (unless #-- or #!)
|
@
|
beginning of line or after tab(s)
|
list item in a alpha-list
|
The translation table for the % translations is the in3charmap.
3.2. Implemented requests
3.2.1. Comments
Lines starting with
#!
or
#--
are treated as comments and are written to STDERR.
3.2.2. General formatting
request
|
argument
|
meaning
|
empty line or .
|
Ends an alinea, if an alinea is open
|
|
text{tab}
|
text
|
a text with a left note
|
back
|
none
|
Ends a section with left notes
|
br
|
none
|
force a line break
|
center
|
text
|
center the text on a new line
|
note
|
text
|
text is a footnote
|
side
|
side note text
|
Specifies a referral to side notes
|
3.2.3. Lists
request
|
argument
|
meaning
|
-{tab}
|
text
|
dash list item
|
{tab}-{tab}
|
text
|
second level dash list
|
@{tab}
|
text
|
alphabetized list item
|
{tab}@{tab}
|
text
|
second level alphabetized list
|
#{tab}
|
text
|
numbered list item
|
{tab}#{tab}
|
text
|
second level numbered list
|
3.2.4. Character format
request
|
argument
|
meaning
|
b
|
text
|
text must be written in bold
|
fix
|
text
|
fixed font text
|
i
|
text
|
italicized text
|
u
|
text
|
Underline text
|
lst
|
text
|
Put the line as a separate line as fixed
|
3.2.5. Headers
request
|
argument
|
meaning
|
h{0-5}
|
text
|
create a chapter/section/... title
|
header
|
none
|
include the file header if that seems appropriate
|
hu
|
text
|
Header, unnumbered
|
appendix
|
none
|
change level 1 header to alpha-style and start from A
|
3.2.6. Other
request
|
argument
|
meaning
|
author
|
text
|
specify the name(s) of the author(s)
|
title
|
text
|
specify the title for the documen
|
subtitle
|
text
|
specify the subtitle for the documen
|
keywords
|
comma separates list
|
set a list of keywords for HTML-meta
|
cover
|
file name
|
use the image in file name as cover
|
global
|
variable value
|
set the variable to value globally
|
hr
|
none
|
horizontal line
|
html
|
htmlcode
|
insert the htmlcode in the HTML-documents only
|
img
|
image captiontext scale
|
include an image here; caption text is optional; scale is optional, but it must be numbers only
|
video
|
video file
|
add a video (in www) or an image from a video (in pdf)
|
link
|
link text
|
provide a link
|
headerlink
|
link text
|
a link that is used only in the header
|
map
|
image image_file
|
Map creates a clickable map in HTML or an image in PDF.
|
map
|
field link coordinates
|
Creates a click-field on the current map.
|
set
|
variable value
|
set the variable to value from now on
|
date
|
none
|
print the date on which the in to in3 processor ran.
|
3.2.7. Blocks
Tables, maps, images and lists are defined as block requests. They should start on a new alinea
and end with an alinea (i.e. a blank line).
There are a few block-specific requests.
pre
|
none
|
starts or stops a pre-formatted text
|
block
|
type name
|
creates a specific block type with a specific name
|
block format
|
formatstring
|
specifies formats for the block
|
block
|
(without args)
|
close the block
|
A block is a set of lines that are handled by an additional program. The output-handlers
should provide a comparable output for HTML, text et cetera, but the format may vary
wildly.
Output handlers may even crash if the block contents poses an impossible problem
for them. The output handler for text has a problem with anything graphical.
There is some influence on the formatting possible
with the
block format
request, but it is up to the output handler to determine whether such a request is
silently ignored or honored. The general format of the format string is a number of
variable=value
pairs, separated by spaces.
Currently implemented is:
variable
|
HTML
|
www
|
pdf
|
txt
|
meaning
|
scale=75
|
x
|
-
|
-
|
-
|
Scale the output of the block to 75%
|
The following block types are implemented:
pre
|
Acts the same as the pre request.
|
gnuplot
|
The external program gnuplot is used to create an image that is included.
|
eqn
|
The lines are fed through eqn to provide a graphical image.
|
texeqn
|
The lines are passed to LaTex for formatting
|
pic
|
The lines are processed by pic to provide a graphical image.
|
music
|
The lines are passed to Lilypond for music typesetting.
|
classxx
|
The lines are formatted as classxx (with xx the name). See stylesheets.
|
If the name of the block is missing, there will be some random name, which is
most likely relatively unique.
In addition, a request
codefile
can be used to generate a pre-formated block of text from an external file.
3.3. Variables
The concept of variables is used to control the behavior of the in-scripts. Variables may be
set globally or from a point in the text. If a variable is set as global, the last value in the
input file is used from the beginning. Global variables may be overridden by set requests.
Variables have consequences.
Variable
|
active
|
Meaning
|
interpret
|
global
|
0=only accented characters 1=% style interpretation 2=direct interpretation |
notes
|
direct
|
0=no left or side notes 1=only leftnotes 2=only sidenotes 3=both |
H1
|
direct
|
Number for the next chapter
|
H2
|
direct
|
Number for the next section
|
H3
|
direct
|
Number for the next paragraph
|
H4
|
direct
|
Number for the next sub-paragraph
|
markdown
|
direct
|
if 1, accept markdown format requests, 0=don't
|
inlineemp
|
direct
|
1=accept underscore underlining, star bolding and markdown links; 0=don't
|
font
|
next alinea
|
The next alinea uses the specified font.
|
Variables may have initial values
variable
|
initial value
|
interpret
|
1
|
H1
|
if the file name starts with a number and an underscore, the value of that number (e.g. 3_title: H1=3)
|
markdown
|
0, but if -m is given: 1
|
inlineemp
|
1
|
3.3.1. Interpret, markdown and inlineemp
Intrepret does an interpretation of character combinations. The character translations are governed by
character maps in
/usr/local/share.
The character maps are also used to translate non-asii characters to the different output channels.
This means that the translation is done by
in3html
and
in3tbl
(the second pass).
% argument
|
translation
|
8x
|
✂
|
8X
|
✄
|
phone
|
✆
|
plane
|
✈
|
mail
|
✉
|
write
|
✍
|
pen
|
✑
|
check
|
✓
|
CHECK
|
✔
|
wrong
|
✗
|
WRONG
|
✘
|
cross
|
✝
|
CROSS
|
✞
|
david
|
✡
|
star
|
✩
|
snow
|
❄
|
Enthusiastic markdown users would like to use mark-down syntax. The following requests
are implemented. Inlineemp allows a subset of markdown to be used.
markdown
format
request
|
allowed
when
|
use of _ or * emphasis
|
markdown=1 or inlineemp=1
|
use of [] links
|
markdown=1 or inlineemp=1
|
use of > instead of .pre
|
markdown=1
|
==== for chapters
|
markdown=1
|
---- for sections
|
markdown=1
|
hashes for titles
|
markdown=1
|
lists with 1. or a.
|
markdown=1
|
3.3.2. Notes
Notes allows you to change the notes-style.
You may be tempted to do so, but most of the times, it is unnecessary and a bad idea.
3.3.3. H1, H2 etc.
These are the chapter numbers. Chapter numbers can be set in different ways:
-
via -c on the command line of in3
-
via the 1_-prefix on the filename (1 for chapter number 1 etc.)
-
via set H1 2
This also makes it possible to, for example, skip paragraph numbers to confuse the readers.
3.3.4. font
Font allows you to specify the font for the next alinea. Font is changed back to
none
at the end of the alinea. Font changes are implemented differently for the different
output processors.
in3tbl
will change the font to 1 if the font is times, 6 if the font is courier, or to the named
font otherwise.
in3html
will change the style of the alinea to alinea, for example, alineatimes, alineaheletica
etc. It is up to the css to select the correct font and its alternatives.
fonts