FRUNDIS_SYNTAX(5)

NAME
frundis - semantic 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 and EPUB.

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 ‘\’ at the end of the line. Whitespace is used to delimit arguments, unless it appears inside a pair of quotes characters ‘"’. A literal character ‘"’ can be rendered inside a quoted string by doubling it. If an argument begins with a ‘"’ without a corresponding closing ‘"’ then all text following the ‘"’ to the end of the line forms a single argument.

  Comments
In any type of line, text beginning by a ‘\"’ is ignored to 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

The character ‘\&’ can be in particular used to allow printing of a period ‘’. at the beginning of a line.

  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:
[-id label] [-t tag]
Bl, El | list block:
[-t type]
It | list item
 | | table cell separator

  Miscellaneous phrasing markup
 | format a hyperlink:
[-ns] url [link-text]
Sm, Bm, | arbitrary phrasing text markup:
[-id label] [-ns] [-t tag]
 | make a cross-reference:
[-id] [-name link-text] [-ns] [-t type]

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

  Format specific markup
, Bf, Ef | as-is text for specific target format:
-f formats [-filter cmd]

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

  Macros, variables and state control
#de,
#. | define a macro: [-f formats] [-perl] name
#dv | define a variable:
[-f formats] name args ...
#if,
#; | conditional: [-f formats] [string]
#fl | modify state flags:
flag [value]

FORMATS
Currently three target formats are supported: LaTeX, XHTML and EPUB. 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 value concerns XHTML, the epub value concerns EPUB, and the latex value concerns LaTeX. Several formats can be specified at once by separating them by commas.

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] [-t tag]

The optional tag argument can be div, literal, or a new tag created by a previous X macro declaration. The value div is the default tag.

The Bd macro terminates any eventual opened paragraph.

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

A literal block will be rendered as a “pre” element in html, or a “verbatim” environment in LaTeX. A div block actually does nothing in LaTeX apart from terminating any previous paragraph, and is rendered as a “div” element in html.

The verbatim package is necessary for LaTeX with Bd -t literal blocks.

  Bf
Begin as-is block for a specific target format. The syntax is as follows:

.Bf -f formats [-filter cmd] [-ns] [-t tag]

This is a multi-line version of the macro, with the exception of the -t option that allows to use tags that use some custom filters defined with a X ftag invocation. In the case in that the -t option is specified, the -f option is no more mandatory.

  Bl
Begin a list. The syntax is as follows:

.Bl [-columns (number | string)] [-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 writting 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.

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 option -columns is used and required, when exporting to LaTeX, for lists of type table, and can use as argument either the number of columns in the table, or a literal LaTeX columns specification such as "|l|l|". 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] [-t tag]

This macro is a multi-line version of the Sm macro. The markup spans through paragraphs until a corresponding macro is encountered. The optional -ns flag follows the same semantics as in Sm.

  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 delimiter marking the start of a dialogue. The default delimiter can be changed by setting the dmark parameter. See the PARAMETERS section.

  Ed
End a display block.

  Ef
End a target format specific block.

  El
End a list.

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

. [delimiter]

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

One line target format specific entry. The syntax is as follows:

. -f formats [-filter cmd] [-ns] 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 -filter cmd optional argument pipes text through shell command cmd before rendering. The optional -ns flag follows the same semantics as in the Sm macro.

  If
Include a file. The syntax is as follows:

.If [-as-is [-filter cmd | -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 -filter cmd is used to pass the text of the file through shell command cmd before rendering. The optional -t option specifies that a filter defined with a X ftag invocation for tag tag should be used.

In the case of including a frundis file, the path can be specified using a double colon:: to separate directories, in which case the suffix ‘.frundis’ is appended, and path should not contain periods. 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 [-link url] 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 a delimiter can be specified 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 src 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.

Format a hyperlink. The syntax is as follows:

. [-ns] url [link-text] [delimiter]

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

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 attachs some special semantic 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 is to allow avoiding 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. See the #fl macro for more fine-grained control over spacing.

The optional label option argument can be used to provide an identifier for use in a further -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, macro, P macro, or an item macro of a description list, allowing for more semantic control in these special cases. Fine-grained control over the words to mark can be obtained by the use of the Bm and 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.

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

. [-id] [-name link-text] [-ns] [-t type] args ... [delimiter]

The args arguments are joined with spaces interleaved. If -id is not present, they should form a valid header title, or figure caption if type is lof, or table title if type is lot. If -id is present, the arguments are used as an identifier specified manually. The optional delimiter argument and the optional -ns flag follow the same semantics as in the Sm macro. The link text for the cross-reference is derived from args, or link-text if the optional -name link-text is provided.

The hyperref package is necessary for LaTeX.

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

.| [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 -t tag -f formats [-c cmd] [-b opening] [-e closing]
.X dtag -t tag -f formats [-c cmd]
.X ftag -t tag [-f formats] (-shell shell-cmd | -code perl-code)

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 semantic 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. Finally, the opening and closing arguments specify optional enclosing text within the scope of cmd.

The.X dtag form creates a new tag for use in a posterior Bd display block macro declaration, with special semantic 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.X ftag form creates a new tag for use in a posterior Bf -t or If -as-is invocation. The -shell option accepts a command to which to pipe text. The -code option accepts as argument perl code that compiles to a subroutine in the same way as with the #de macro. The text to filter is accessible through the text() method.

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] [-perl] 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.

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.

If a syntax error is encountered in the defined macro, the reported line number will be the line number of the user macro invocation.

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

If the -perl flag is used, the macro definition is treated as Perl code. Note that ‘\’ needs to be escaped as in normal frundis source. When writing a macro with perl code, it should be remembered that frundis uses an information collecting pass, and then a processing pass, as explained in the Processing subsection.

The macro definition is compiled to a subroutine and accepts an object argument with the following methods, in alphabetic order:

args()
    Returns a reference to the list of unescaped (apart from variable interpolation) arguments passed to the macro. Alternatively, the global variable @Arg can be used directly.

call($macro, @arg)
    Call the macro named $macro with arguments @arg.

diag_error($msg)
diag_fatal($msg)
diag_warning($msg)
    Report respectively a syntax error, fatal error or warning with message $msg. It will be automatically prefixed with location information.

escape($text)
    Escape frundis source text but don't apply escape rules specific to the target language. Suitable for text that is not going to be printed or needs special preprocessing.

escape_text($text)
    Escape regular text according to rules of the target language. Suitable for immediate printing.

file()
    Returns the current source file name.

flag($flag, [$value])
    Get or set boolean flags. If $value is provided, the flag $flag is set to it, otherwise the current value corresponding to key $flag is returned. New or modified flags can be used in posterior #fl invocations. Flags starting by an underscore are reserved for internal use and should not be used.

format()
    Returns the current exporting format. Can be epub, latex or xhtml.

get_close_delim()
    Get closing delimiter in a phrasing macro. Updates arguments array.

ivars()
    Returns a reference to a hash map from information variables to values. The difference with the vars method is that the hash is not reinitialized after information collecting pass, and that these variables cannot be interpolated. It can be used to collect informations for posterior use in the processing phase.

lnum()
    Returns the current line number.

loX_entry_infos($opts)
    Collect information to use later with the xhtml_loX method or in a macro invocation. The $opts argument should be a hash reference with keys: title for the title of the element to be referenced; count for the position in the list; class for the class that corresponds to the argument of the corresponding xhtml_loX($class) call and the type in macro invocation; href_prefix for the prefix that is used between the “#” and the value of count in the href.

macro()
    Returns the name of the invoked macro.

new_id($id)
    Declare an identifier for future use in a -id invocation. It should be used in the same chapter (or beginning of part) as the one of the element whose identifier is $id.

param($param, [$value])
    Get or set parameters. If $value is provided, the parameter $param is set to it, otherwise the current value corresponding to key $param is returned. New or modified parameters can be redefined in posterior #X set invocations. Parameters starting by an underscore are reserved for internal use and should not be used. Parameters are only set during information collecting phase.

parse_options($spec)
    Parse options from option specification $spec and returns a hash map from options to values. The $spec variable should be a hash reference. Keys are options names, and values can be “b” for a boolean flag, or “s” for an option that requires a string argument. Updates arguments array.

phrasing_macro_begin($no_space)
    Handle accumulated text lines for phrasing macro. If $no_space is true, then a chomp of the text will be done.

phrasing_macro_end()
    Handle accumulated text lines for end phrasing macro (such as).

process()
    Whether in information collecting pass, or in processing pass, see Processing.

text([$text])
    Return or set accumulated text from text lines.

vars()
    Returns a reference to the hash map from variables to values of variables defined with the #dv macro. The hash is reinitialized between information collecting phase and processing phase. If being portable matters, you should prefix yourself variable names with a “package” name such as “package::varname” or use only one key and a hash reference value, for example, as frundis doesn't support namespaces.

xhtml_gen_href($prefix, $count)
    Get an href for use in an “href” html attribute. Suitable to create custom index generation and cross-reference macros. The variable $prefix is appended after the “#” character, to allow for multiple classes of identifiers. The variable $count is appended after the prefix.

xhtml_loX($class)
    Generate a list of cross-references to specific elements. The $class argument should correspond to a valid class defined by the loX_entry_infos method described above, or one of the predefined classes lot, lof and lop (list of poems).

  #dv
Define a variable. The syntax is as follows:

.#dv [-f formats] name args ...

The args are 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].

  #fl
Modify state flags. The syntax is as follows:

    .#fl flag [value]

If value is provided, state corresponding to flag is set to value, otherwise current value associated with flag is negated.

The list of supported state flags is as follows:

fr-nbsp-auto
    Add necessary non-breaking spaces automatically. Used only when lang parameter is set to fr. Defaults to 1.
ns  No-space mode. Defaults to 0. If set to a non-zero value, whitespace won't be inserted between macro arguments, and before or after phrasing macro invocations.

  #if
Begin a conditional. The syntax is as follows:

    .#if [-f formats] [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.

The #if macros can be nested.

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. It is en by default. If set to fr necessary non-breaking spaces to satisfy french typographic rules will be added automatically, unless a zero-width ‘\&’ character is used between punctuation and text, or the state value of key fr-nbsp-auto is set to a zero value, see the #fl macro.

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.

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-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 .
    .\" 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
    .Sh Section Title
    .\" Include contents of another file
    .If section-content.frundis
    .Sh Another Section
    .\" Cross-reference to the first section
    As we saw in section
    .Sx Section Title
    .\" ...
    .\" Cross-reference to the first section with link text "first section"
    See the
    .Sx -name "first section" Section Title .

Syntax highlighting through external command:

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

Defining a macro with perl code:

    .\" This macro can be used to index particular words
    .#de -f xhtml -perl keyword
        my $self = shift;
        my $close_delim = $self->get_close_delim();
        my $vars = $self->vars;
        $vars->{index_count}++;
        my $id   = "kwd$vars->{index_count}";
        my $text = $self->escape_text(join(" ", @Arg));
        unless ($self->process) {
            $self->new_id($id);
            $self->loX_entry_infos(
               {
                   title       => $text,
                   count       => $vars->{index_count},
                   class       => "lok",
                   href_prefix => "kwd",
               }
            );
            return;
        }
        $self->phrasing_macro_begin();
        my $space = $self->flag("ns") ? "" : "\en";
        print qq|<span class="keyword" id="$id">|,
          $text, "</span>", $close_delim, $space;
    .#.
    Now
    .keyword special-word
    and
    .keyword another-special-word .
    .\" Define a macro that prints a "list of keywords"
    .#de -f xhtml -perl print-lok
        my $self = shift;
        return unless $self->process;
        # enclose within a <div> and terminate any paragraph
        $self->call("Bd");
        $self->xhtml_loX("lok");  # print the list
        $self->call("Ed");
    .#.
    .\" Print an index of links to special words introduced
    .\" with a ".keyword" invocation.
    .print-lok

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

SEE ALSO
frundis(1) Text::Frundis

HISTORY
The frundis language was created originally for supporting the development of the fantasy saga El Ciclo de Shaedra, http://bardinflor.perso.aquilenet.fr/shaedra/. Incidentally, frundis is also the name of a character of the saga.

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.