FRUNDIS_SYNTAX(5) File Formats Manual FRUNDIS_SYNTAX(5)

NAME

frundissemantic markup language for formatting documents

DESCRIPTION

The frundis language intends to be 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.

LANGUAGE SYNTAX AND SEMANTICS

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

Macro lines begin with the control character ‘.’, followed by a macro name, with optional horizontal whitespace between the two. 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:
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.

Processing

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.

MACRO OVERVIEW

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.

Structure

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

Displays and lists

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

Miscellaneous phrasing markup

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

Include external files

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

Filters

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

Tags and global parameters

X define exporting parameters and tags: set | mtag | dtag | ftag

Macros, variables and conditionals

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

FORMATS

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, the xhtml refers to XHTML, the epub refers to EPUB, the latex refers to LaTeX, the markdown refers to markdown, and the 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

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 allowed macros are as follows: Bd, Bf, Bm, Ed, Ef, Em, Ft, If, Sm, and X, as well as macros starting with ‘#’.

MACRO REFERENCE

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

Bd

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 macro declaration. The value div is the default tag. The optional label option argument follows the same semantics as with the Sm macro.
The Bd macro terminates any eventual opened paragraph.
The optional -r flag states that the corresponding Ed should specify -t option. This allows for better error messages in case of unclosed block, and is particularly useful in combination with user defined macros.
A div block actually does nothing in LaTeX apart from terminating any previous paragraph, and is rendered as a “div” element in html.

Bf

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.

Bl

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 follows the same semantics as with 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 necessary for LaTeX with Bl -t verse lists.

Bm

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 follows the same semantics as in Sm.
The -r plays the same role as with the Bd macro.

Ch

Declare a new chapter. The syntax is the same as with 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:
.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. Useful to provide friendly error messages, particularly in combination with user defined macros.

Ef

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.

El

End a list.

Em

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 with the Ed macro.

Ft

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 optional -ns flag follows the same semantics as in the Sm macro.
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.

If

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 option has the same semantics as with 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:
.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 flag follow the same semantics as in the Sm macro. In both cases, the -id option follows the same semantics as with 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 necessary for LaTeX.

It

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.

Lk

Format a hyperlink. The syntax is as follows:
.Lk [-ns] url [text] [delimiter]
The optional delimiter argument and the -ns flag follow the same semantics as in the Sm macro.
The hyperref package is necessary for LaTeX.

P

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.

Pt

Declare a new part. The syntax is the same as with the Sh macro.

Sh

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.

Sm

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, eventually preceded by a non-breaking space ‘\~’, is considered a punctuation delimiter.
The optional -ns flag specifies that no newline should be inserted after eventual 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

Ss

Declare a new subsection. The syntax is the same as with the Sh macro.

Sx

Make a cross-reference. The syntax is as follows:
.Sx [-ns] label args ... [delimiter]
The args arguments are joined with spaces interleaved, and used as text for the cross-reference link. 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 necessary for LaTeX. Cross-references do not work for the markdown format, text will appear as-is.

Ta

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.

Tc

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 necessary for LaTeX if the -mini flag is used.

X

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 the name of the LaTeX command or HTML element that will be used while exporting, and defaults to emph and em respectively. Note that cmd should be the name of a phrasing html element or LaTeX command that can be found inside a paragraph, such as a “span” element for html, and which follows normal escaping rules of the target format in this context. 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. 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:
.#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 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:
.#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.

#if

Begin a conditional. The syntax is as follows:
.#if [-f formats] [-not] [string] 
body of conditional 
.#;
The body of conditional can consist of any number of frundis text and macro lines. The optional -f formats argument specifies that the conditional should be executed only for specific target formats, see FORMATS for a description of possible values for formats. The optional string argument specifies that the conditional should be executed only if string is non-zero and non-null. At least one of formats or string should be specified. The -not flag negates the condition.
The #if macros can be nested.

#run

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.

PARAMETERS

This section is a list of the parameters that can be set with the X macro, along with their descriptions, in alphabetic order.
 
 
dmark
The mark that starts a dialogue.
 
 
document-author
The author of the document.
 
 
document-date
The date of the document.
 
 
document-title
The title of the document.
 
 
epub-cover
The path to the cover.
 
 
epub-css
The path to the css file to use when exporting to EPUB.
 
 
epub-metadata
The path to a file containing epub metadata entries.
 
 
epub-subject
Subject description for epub.
 
 
epub-version
The epub version to produce. Can be 2 or 3.
 
 
epub-uuid
The text to use as unique identifier for epub. Useful mainly for deterministic tests.
 
 
lang
The language in which the source is written (eg. en, es, fr, etc.). If set to fr necessary non-breaking spaces to satisfy French typographic rules will be checked and added automatically as necessary, unless a zero-width ‘\&’ character is used between punctuation and text.
 
 
latex-preamble
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.
 
 
latex-xelatex
Use an automatic XeLaTeX preamble instead of a plain LaTeX one.
 
 
mom-preamble
Path to a custom groff mom preamble file (text before “.START” ).
 
 
nbsp
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.
 
 
title-page
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.
 
 
xhtml-bottom
Path to xhtml file providing additional bottom content just before terminating body in each file, after the navigation bar.
 
 
xhtml-css
Path to the css file when exporting to XHTML. It will appear as-is in the XHTML file.
 
 
xhtml-index
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.
 
 
xhtml-favicon
Path to favicon.
 
 
xhtml-go-up
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.
 
 
xhtml-top
Path to XHTML file providing additional top content just after body in each file, before the navigation bar.
 
 
xhtml5
If set to a non-zero value, html5 will be produced.

EXAMPLES

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.

SEE ALSO

frundis(1)

HISTORY

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.

CAVEATS

A quoted argument isn't interpreted literally. For this purpose the ‘\&’ zero-width character should be used.
June 1, 2017 OpenBSD 6.1