Macro lines

Macro lines begin with the control character ‘.’, followed by a macro name, with optional horizontal whitespace between both. Macro lines can be continued in several lines by using a backslash ‘\’ at the end of the line. Whitespace is used to delimit arguments, unless it appears inside a pair of quote characters ‘"’. A literal character ‘"’ can be rendered inside a quoted string by doubling it.

Comments

In any type of line, text beginning by ‘\"’ is ignored until the end of the line. Lines with only a control character ‘.’ and optional trailing horizontal whitespace are ignored, also.

Escape Sequences

Escape sequences start with a backslash character ‘\’, which is the only character that needs to be escaped. The accepted sequences are described in the following table:

The character ‘\&’ can be in particular used to allow printing of a period ‘.’ at the beginning of a line. See #de macro description for a detailed description of the argument and flag escapes.

Processing

frundis files are processed in two phases: a first pass is used to collect information (such as TOC information), and a second pass builds the output document.

Structure

Displays and lists

Miscellaneous phrasing markup

Include external files

Filters

Tags and global parameters

Macros, variables and conditionals

Restricted mode

Restricted mode (option -t of frundis(1)) is an experimental mode of operation with a restricted macro-set, and a somewhat different behaviour more template-friendly. In particular, text blocks and phrasing macros don't implicitly generate begin and end paragraph markers, and arguments -b and -e of X mtag are not escaped. The exported macros are as follows: Bd, Bf, Bm, Ed, Ef, Em, Ft, If, Sm, and X, as well as macros starting with ‘#’.

Bd

Begin a display block. The syntax is as follows:

Bd is a generic macro for styled blocks, whose styling and exact semantics are controlled by the optional tag argument, which can be div, or a new tag created by a previous X dtag macro declaration. The value div is the default tag. The optional -r flag states that the corresponding Ed should specify -t option.

The optional label option argument works as in the Sm macro.

The Bd macro terminates previous paragraph text, if any.

A div block actually does nothing in LaTeX apart from terminating any previous paragraph. It is rendered as a “div” element in html.

Bf

Begin a filter block. The syntax is as follows:

This is a multi-line version of the Ft macro.

Bl

Begin a list. The syntax is as follows:

The optional type argument can be item for a simple list (this is the default), enum for an enumerated list, desc for a description list, table for a table, or verse for writing a verse poem. The optional args arguments are used in verse and table lists to provide a title; arguments are joined with spaces interleaved. When a title is provided, table lists are added to the list of tables generated by Tc -lot.

The optional -id works as in the Sm macro.

Lists of type item or enum can be nested. The P macro is handled specially in lists of type verse, marking the start a new stanza.

In html, Bl -t verse lists are rendered within a “div” element with class “verse”. The verse package is required for LaTeX with Bl -t verse lists.

Bm

Begin semantic markup block. The syntax is as follows:

This macro is a multi-line version of the Sm macro. The markup spans through paragraphs until a corresponding Em macro is encountered.

The optional -ns flag works as in Sm. The -r plays the same role as in the Bd macro.

Ch

Declare a new chapter. Same syntax as the Sh macro.

D

Start a new dialogue. This macro breaks a paragraph as the P macro, but then a new paragraph is started with a marker starting a dialogue. The default marker can be changed by setting the dmark parameter. See the PARAMETERS section.

Ed

End a display block. The syntax is as follows:

The optional -t tag argument can be provided to state that the macro should end a corresponding Bd with the same tag. It is particularly useful when defining opening/closing pairs of user defined macros, in which the first starts a display block and the second closes it. Using the tag will ensure error messages about unclosed blocks do not get confused when nesting with differently tagged display blocks, accurately pointing out which block is unclosed.

Ef

End a filter block. The syntax is as follows:

The -ns flag can be used to specify that no space should be appended at the end of the block.

El

End a list.

Em

End markup started by a corresponding Bm macro. The syntax is as follows:

The optional closing delimiter follows the same semantics as described in the Sm macro below, except that it can be any string.

The optional -t tag plays the same role as in the Ed macro. The optional -ns flag specifies that no space is wanted before further paragraph text.

Ft

One line filter. The syntax is as follows:

The formats argument specifies that the macro should apply only when exporting to some specific target formats. See the FORMATS section for a list of possible values for the formats argument. When it applies, the args arguments are joined with spaces interleaved and rendered as-is. Specific frundis language escape rules still apply, but format specific ones don't.

The -t tag optional argument specifies that text should be pre-processed by a special filter, as specified by an X ftag invocation, or by one of the following built-in filters:

escape

Text will be rendered escaped, but without any additional processing.

In the case that the -t option is specified, the -f option is no more mandatory.

The optional -ns flag follows the same semantics as in the Sm macro.

If

Include a file. The syntax is as follows:

The path argument specifies the path to the file that should be included. The optional formats argument specifies that the file should be included only for a particular target format, see the FORMATS section for details. The optional -as-is flag specifies that the file should be included "as-is", without interpreting it as a frundis file.

The optional -t works as in the Ft macro.

Relative path arguments search for files in the current directory, and then for files specified in the FRUNDISLIB environment variable, as specified in the frundis(1) manpage.

Im

Include an image. The syntax is as follows:

The src argument is the path or url to the image. If a caption is provided, the image is rendered as a figure with caption, and an entry is added in the list of figures generated by Tc -lof. Otherwise, the image is rendered in-line, and delimiter and the -ns work as in the Sm macro. In both cases, the -id option follows the same semantics as in the Sm macro.

When exporting to XHTML, the optional -link url embeds the image in a hyperlink given by url. The optional -alt text provides alternate text for the “alt” attribute. If the -alt option is not passed, the “alt” attribute is set to caption if specified, or leaved empty otherwise. If a caption is provided, in html the macro renders as a “div” element with “class” attribute “figure”, and in LaTeX it is rendered as a centered figure with caption.

The graphicx package is required for LaTeX.

It

A list item. The syntax is as follows:

The args arguments are joined, with spaces interleaved, and used as text for the item in case of an item or verse list, as the text to be described in the case of a desc list, and as the text of the first cell in a row in a table list.

Lk

Format a hyperlink. The syntax is as follows:

The optional delimiter argument and the -ns flag work as in the Sm macro. The optional args arguments are joined with spaces interleaved to provide text for the link.

The hyperref package is required for LaTeX.

P

Break a paragraph. The syntax is as follows:

The P macro is optional just after or before a header macro. If args arguments are provided, a new paragraph is started, the args are joined with spaces interleaved and used as a header for the new paragraph.

If no args are provided, the macro has no effect before and after display blocks or lists for XHTML and EPUB outputs, but in LaTeX a newline will be inserted in these cases. The new paragraph has class “paragraph” in XHTML and EPUB. The header appears as argument to a “paragraph” command in LaTeX, and within a “strong” element with class “paragraph” in XHTML and EPUB.

Pt

Declare a new part. Same syntax as the Sh macro.

Sh

Declare a new section. The syntax is as follows:

The args arguments are joined with spaces interleaved to form the name of the section. The optional -nonum flag specifies that the section should not be numbered.

The optional label option argument follows the same semantics as with the Sm macro.

In XHTML and EPUB, a header is rendered as an “hN” element, with the name of the macro as a class attribute, and where N is such that the hierarchical order between header macros Pt, Ch, Sh, and Ss is satisfied.

Sm

Semantic Markup. The syntax is as follows:

The optional tag argument attaches some special semantics to the text, according to the rules defined in a prior X macro line declaration. The args arguments are joined with spaces interleaved to form the text to markup. If the last argument is a punctuation closing delimiter, it is excluded from the markup, but no space is interleaved between it and the text. This allows to avoid unwanted space before punctuation, such as it would occur when putting punctuation in the next text or macro line. Currently, a Unicode punctuation character, possibly preceded by a non-breaking space ‘\~’, is considered a punctuation delimiter.

The optional -ns flag specifies that no newline should be inserted after any preceding paragraph text.

The optional label option argument can be used to provide an identifier for use in a further Sx -id invocation. The label should be both a valid “id” html attribute and a valid LaTeX label.

The Sm macro can also be used inline as an argument to a header macro, Sx macro, P macro, It macro, Lk or a Ta macro. Fine-grained control over the words to mark can be obtained by the use of the Bm and Em macros. As a result of this special treatment, these macro names need to be escaped in order to appear as-is. For example:

.\" Emphasis of the word "Frundis". Note the "\&" after "Em".
.Ch The Bm Frundis Em \& Manual
.\" To get "Sm" as-is:
.Ch All About the \&Sm Macro

Ss

Declare a new subsection. Same syntax as the Sh macro.

Sx

Make a cross-reference. The syntax is as follows:

If given, args arguments are joined with spaces interleaved, and used as text for the cross-reference link. Otherwise, the header number, title or label are used as the text. The argument label should correspond to a valid label passed to any macro supporting -id option.

The optional delimiter argument and the optional -ns flag follow the same semantics as in the Sm macro.

The hyperref package is required for LaTeX. Cross-references are not implemented for the markdown format, text will appear as-is.

Ta

Table cell separator in Bl -t table lists. The syntax is as follows:

The args arguments are joined with spaces interleaved, and used as text for the new cell.

Tc

Print a table of contents. The syntax is as follows:

The type can be toc for a table of contents, lof for a list of figures and lot for a list of tables. The default is toc. The -summary flag specifies that only a summary without sections and subsections should be printed. The -mini flag specifies that a local table of contents should be printed, that is a list of sections within chapter, or a list of chapters after a part declaration. If -summary and -mini are combined, only sections will be printed for chapter local table of contents.

The -nonum flag specifies, for XHTML and EPUB, that entries should not be numbered. The -title text can be used to specify a title for XHTML and EPUB. When -mini is not specified in table of contents, the default is to use the title of the document, as specified by the document-title parameter. If an empty title is provided, no title will be print. In HTML, the index is rendered as an unordered list in a “div” element with “class” attribute “lof”, “lot” or “toc” according to the -type flag.

The minitoc package is required for LaTeX if the -mini flag is used.

X

Declare exporting parameters. The syntax is as follows:

The .X set form allows to assign a value to a parameter. See the PARAMETERS section for a description of available parameters.

The .X mtag form creates a new tag for use in a posterior Bm or Sm macro declaration, with special semantics attached. The name of the tag is used as “class” attribute for XHTML or EPUB. The optional cmd specifies which kind of markup to use, and depends on the target format. It defaults to emph for LaTeX, and em for XHTML. Note that cmd should be the name of a phrasing HTML element or a LaTeX command that can be found inside a paragraph and follows normal escaping rules; for example, “span” for XHTML is a valid value for cmd, but “pre” is not. When exporting to groff mom, cmd is used as an argument to a \f[...] font inline escape, so it can for example be B, I, BI or R. Markdown uses * by default for cmd. Finally, the opening and closing arguments specify optional enclosing text within the scope of cmd. The -a option allows to add a list of key/value attributes. The first character is used as separator. The attributes are used as standard attributes in HTML, and options between square brackets in LaTeX.

The .X dtag form creates a new tag for use in a posterior Bd display block macro declaration, with special semantics attached. As with the .X mtag form, the name of the tag is used as “class” attribute for XHTML or EPUB. The optional cmd follows the same semantics as in the .X mtag form, except that in LaTeX it will be used as an environment name. If no cmd is specified, the block will be rendered without environment in LaTeX (just a blank line before and after the block), and as a “div” element in HTML. The -a option behaves in the same way as with the . X mtag form.

The .X ftag form creates a new tag for use in a posterior Bf, Ft or If invocation. The -shell option accepts a command to which to pipe text through stdin, with otherwise the same behavior and restrictions as the #run macro. The -gsub option accepts a list of string/replacement pairs, and the -regexp option accepts a pair pattern/replacement. In both cases, the delimiter is given by the first character of the argument.

In all cases, the formats argument specifies that the macro should apply only when exporting to some specific target formats. See the FORMATS section for a description of possible values for the formats argument.

The X macros are executed in the information gathering pass, before any macro prints text, see Processing. If a parameter is defined more than once, the last definition prevails.

#de

Define a macro. The syntax is as follows:

The macro definition can consist of any number of frundis text and macro lines. The defined macro can be invoked later as follows:

The invocation of the macro will be replaced by the macro definition.

Any occurrence of \$N in the macro definition, where N is a decimal number, will be replaced by the Nth argument passed to the invoked macro. Interpolation in a macro is done in a single argument, quotes are not needed.

Any occurrence of \$@ will be replaced by the list of all the remaining positional arguments. If it appears as a whole argument of a macro, it expands as a list of arguments to this macro. Otherwise, it is interpolated within an argument or text block by joining arguments with spaces.

Any occurrence of \$[name] will be replaced by the argument arg provided to the option -name when invoking the macro. Replacement is done following the same conventions as with \$N style arguments.

Any occurrence of \$?[name] will be replaced with a true value if the flag -name is provided when invoking the macro, or a false value otherwise.

The formats optional argument specifies that the macro definition concerns only some specific target formats, see the FORMATS section for a description of available values for formats.

The #de macros cannot be nested.

Note: macros are evaluated dynamically. In particular, interpolation is done on use.

#dv

Define a variable. The syntax is as follows:

The args are joined with space interleaved, and used as a new value for the variable with name name. If -f formats is provided, the macro invocation applies only for specific target formats, see the FORMATS section.

A defined variable can then be interpolated in text lines and macro lines arguments with \*[name]. As a special case, if name starts with ‘$’ and is not defined, it is looked up in the environment; if it is not found, the empty string is returned. Use of an undefined variable is an error in the general case.

#if

Begin a conditional. The syntax is as follows:

The body of conditional can consist of any number of frundis text and macro lines. The optional -eq cmpstr argument specifies that the body should be executed only if cmpstr and string are equal. The optional -f formats argument specifies that the body should be executed only for specific target formats, see FORMATS for a description of possible values for formats. If -eq is not provided, the optional string argument specifies that the body should be executed only if string is non-zero and non-null. At least one among -eq, -f or string should be provided. The -not flag negates the whole condition.

The #if macros can be nested.

#run

Run a command. The syntax is as follows:

If several arguments are provided, the first is used as the name of the command, and the rest as arguments. If only one argument is provided, and it contains spaces, it is passed to the shell (non portable). Standard output of the command is printed as-is in the output document.

Note: this command is disallowed by default. See frundis(1) for details.