FRUNDIS_SYNTAX(5) File Formats Manual FRUNDIS_SYNTAX(5)

frundis —
semantic markup language for formatting documents

The frundis language is a semantic markup language with a roff-like syntax for supporting authoring of a variety of light to medium weight documents, from novels to technical tutorials. It relies on the exporting capabilities of the tool frundis(1) to LaTeX, XHTML, EPUB, markdown and groff mom.

The manual is organized as follows. Language syntax is described in the LANGUAGE SYNTAX AND SEMANTICS section. The MACRO OVERVIEW and MACRO REFERENCE sections describe built-in macros. Section FORMATS concerns target format specific questions. The PARAMETERS section describes some global configuration parameters. Section EXAMPLES contains examples of frundis source.

There are two sorts of lines: lines beginning with the control character ‘.’, called “macro lines”, and lines formed of free-form text, called “text lines”. Apart from specific rules explained in subsection Macro lines, text processing follows the rules explained in subsections Comments and Escape Sequences. The Processing subsection explains how frundis source files are processed.

In this document, the term “whitespace” refers to any space character in the Unicode range.

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.

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 start with a backslash character ‘\’, which is the only character that needs to be escaped. The accepted sequences are described in the following table:

Input Description
\e a literal backslash ‘\’ character
\& a non-printing zero-width character
\~ a non-breaking space
\*[name] variable interpolation, see #dv macro description.
\$N numbered argument
\$[name] named argument
\$?[name] named flag
\$@ argument list

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.

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

This section is an overview of the macros with short descriptions, and some common options. Detailed descriptions can be found in the MACRO REFERENCE section.

Pt declare a new part
Ch declare a new chapter
Sh declare a new section
Ss declare a new subsection
Tc print table of contents: [-mini] [-summary] [-type]
P break a paragraph
D start a text dialogue paragraph

Bd, Ed display block: [-t tag]
Bl, El list block: [-t type]
It list item
Ta table cell separator

Lk format a hyperlink: url [text]
Sm, Bm, Em arbitrary phrasing text markup: [-t tag]
Sx make a cross-reference: label args ...

If include a frundis source file: [-as-is [-t tag]] [-f formats] path
Im include an image: [-link url] src [caption]

Ft, Bf, Ef as-is or specially filtered text: -f formats [-t tag]

X define exporting parameters and tags: set | | |

#de, #. define a macro: [-f formats] name
#dv define a variable: [-f formats] name args ...
#if, #; conditional: [-f formats] [string]
#run run command: args ...

Currently several target formats are supported: LaTeX, XHTML, EPUB, markdown and groff mom. Some parameters apply only to a specific target format, see the PARAMETERS section. In particular, the parameters epub-version and xhtml5 allow to choose which version of EPUB and XHTML to produce. When a macro accepts a formats argument, xhtml refers to XHTML, epub refers to EPUB, latex refers to LaTeX, markdown refers to markdown, and mom refers to groff mom. Several formats can be specified at once by separating them by commas. Note: only XHTML, EPUB and LaTeX output formats are considered complete and mature.

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 ‘#’.

This section is a reference of all macros, in alphabetic order.

Begin a display block. The syntax is as follows:
.Bd [-id label] [-r] [-t tag]

The optional tag argument 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.

Begin a filter block. The syntax is as follows:
.Bf -f formats [-ns] [-t tag]

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

Begin a list. The syntax is as follows:
.Bl [-id label] [-t type] [args ...]

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 only allowed in lists of type verse, where it is used to 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.

Begin semantic markup block. The syntax is as follows:
.Bm [-id label] [-ns] [-r] [-t tag]

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.

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

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.

End a display block. The syntax is as follows:
.Ed [-t tag]

The optional -t tag argument can be provided to state that the macro should end a corresponding Bd with the same tag. When provided, frundis will show improved error messages for unclosed blocks. It is particularly useful in combination with user defined macros.

End a filter block. The syntax is as follows:
.Ef [-ns]

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

End a list.

End markup started by a corresponding Bm macro. The syntax is as follows:
.Em [-t tag] [delimiter]

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.

One line filter. The syntax is as follows:
.Ft -f formats [-ns] [-t tag] args ...

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:

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.

Include a file. The syntax is as follows:
.If [-as-is [-ns] [-t tag]] [-f formats] path

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.

Include an image. The syntax is as follows:
.Im [-id label] [-link url] [-ns] src [caption] [delimiter]

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.

For html, 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.

A list item. The syntax is as follows:
.It [args ...]

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.

Format a hyperlink. The syntax is as follows:
.Lk [-ns] url [text] [delimiter]

The optional delimiter argument and the -ns flag work as in the Sm macro.

The hyperref package is required for LaTeX.

Break a paragraph. The syntax is as follows:
.P [args ...]

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.

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

Declare a new section. The syntax is as follows:
.Sh [-id label] [-nonum] args ...

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 class the name of the macro, and where N is such that the hierarchical order between header macros Pt, Ch, Sh, and Ss is satisfied.

Semantic Markup. The syntax is as follows:
.Sm [-id label] [-ns] [-t tag] args ... [delimiter]

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, 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

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

Make a cross-reference. The syntax is as follows:
.Sx [-ns] label [args ...] [delimiter]

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.

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

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

Print a table of contents. The syntax is as follows:
.Tc [-mini] [-nonum] [-summary] [-title text] [-type]

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.

Declare exporting parameters. The syntax is as follows:
.X set [-f formats] parameter value
.X mtag -f formats -t tag [-c cmd] [-b opening] [-e closing] [-a |key|value]
.X dtag -f formats -t tag [-c cmd] [-a |key|value]
.X ftag [-f formats] -t tag (-shell args ... | -gsub /string/replacement | -regexp /pattern/replacement)

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.

Define a macro. The syntax is as follows:
.#de [-f formats] name
macro definition
.#.

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

.name

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.

Define a variable. The syntax is as follows:
.#dv [-f formats] name args ...

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.

Begin a conditional. The syntax is as follows:
.#if [-eq cmpstr] [-f formats] [-not] [string]
body of conditional
.#;

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 a command. The syntax is as follows:
.#run args ...

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.

This section is a list of the parameters that can be set with the X macro, along with their descriptions, in alphabetic order.
The mark that starts a dialogue.
The author of the document.
The date of the document.
The title of the document.
The path to the cover.
The path to the css file to use when exporting to EPUB.
The path to a file containing epub metadata entries.
Subject description for epub.
The epub version to produce. Can be 2 or 3.
The text to use as unique identifier for epub. Useful mainly for deterministic tests.
The language in which the source is written (eg. en, es, fr, etc.). If set to fr, the non-breaking spaces required to satisfy French typographic rules will be checked and added automatically as necessary, unless a zero-width ‘\&’ character is used between punctuation and text.
Path to a custom LaTeX preamble file (text before the “\begin{document}” ). Without this option, a simple preamble with just the necessary, using metadata from the document-author, document-date and document-title parameters, will be used.
Use an automatic XeLaTeX preamble instead of a plain LaTeX one.
Path to a custom groff mom preamble file (text before “.START” ).
Character to use for rendering non-breaking spaces. It defaults to ‘~’ for LaTeX, and to the no-break space ‘0x0a’ unicode character for XHTML and EPUB.
If set to a non-zero value, a title page will be created using metadata from the document-author, document-date and document-title parameters.
Path to XHTML file providing additional bottom content just before terminating body in each file, after the navigation bar.
Path to the css file when exporting to XHTML. It will appear as-is in the XHTML file.
Automatic index generation in multi-file XHTML documents. The value can be full for a full table of contents, summary for a summary, and none to not print any automatic table of contents. The value full is the default.
Path to favicon.
In multi-file XHTML documents, the text of the link to the index.html page. If not specified, a default value is used for a few languages, and others get an up arrow symbol by default.
Path to XHTML file providing additional top content just after body in each file, before the navigation bar.
If set to a non-zero value, HTML5 will be produced.

A novel will mostly look like this: 
.Ch The Name of The Chapter
Some interesting introductory text.
.P
Second paragraph where serious things start. Some character says:
.D
This is the start of an
.\" Some emphasis
.Sm interesting
novel.
.P
And etc.

Defining tags and macros:

.\" Define a tag "book-title" for HTML and EPUB rendered as an "<em>" element
.X mtag -t book-title -f xhtml,epub -c em
.\" Define a tag "book-title" for latex rendered as an "\emph{...}" command
.X mtag -t book-title -f latex -c emph
.\" now we can write:
The book title is
.Sm -t book-title The Title Of The Book .
.\" Make an alias using a macro:
.#de BT
.Sm -t book-title \$@
.#.
.\" now the same as before can be written:
.BT The Title Of The Book .
.\" Define a macro to produce an <hr> within a <div> in HTML
.#de hr
.Bd
.Ft -f xhtml <hr>
.Ed
.#.
.\" And now we can call it this way:
.hr

Links and images:

.\" Define a hyperlink with label "Frundis Homepage"
.Lk http://bardinflor.perso.aquilenet.fr/frundis/intro-en "Frundis Homepage"
.\" Include an image
.Im /path/to/image.png
.\" Include an image with caption "Image" and a link to a bigger image
.Im -link /url/to/image-big.png /path/to/image.png Image

Table of contents and cross-references:

.\" Print Table of Contents
.Tc
.\" Define section with a label
.Sh -id label1 Section Title
.\" Include contents of another file
.If section-content.frundis
.Sh Another Section
.\" Cross-reference to the first section using label
As we saw in the
.Sx label1 first section .

Syntax highlighting through external command:

.\" Source code highlight with the GNU source-highlight program
.\" (see https://www.gnu.org/software/src-highlite/)
.X ftag -f xhtml -t sh-perl -shell "source-highlight -s perl"
.Bf -f xhtml -t sh-perl
print "Hello, World!\en";
.Ef
.\" Or with the highlight program
.\" (see http://www.andre-simon.de/doku/highlight/en/highlight.php)
.X ftag -f xhtml -t highlight-perl -shell "highlight --syntax perl"
.Bf -f xhtml -t highlight-perl
print "Hello, World!\en";
.Ef

More examples can be found by looking at the test files in the testdata/t/data and testdata/t/data-dirs directories, in the doc/examples directory, or at the sources of the Shaedra fantasy saga, see HISTORY.

frundis(1)

The frundis language was created originally for supporting the development of the fantasy saga El Ciclo de Shaedra. Incidentally, frundis is also the name of a character of the saga. The original Perl program was rewritten in Go during the development of the Cycle of Dashvara.

Many macro names are inspired from the language mdoc(7) for formatting manual pages.

A quoted argument isn't interpreted literally. For this purpose the ‘\&’ zero-width character should be used.
November 9, 2019 OpenBSD 6.5