io7m-kstructural 0.3.1 Documentation
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Contents
  ─────────────────────────────────────────────────────────────────────────────
  1 Package Information .......................................................
    1.1 Orientation ........................................... pkg.orientation
    1.2 Installation ..........................................................
    1.3 Platform Specific Issues ..............................................
    1.4 License ...............................................................
  2 Tutorial ......................................................... tutorial
    2.1 Overview ..............................................................
  3 Tools .....................................................................
    3.1 Command Line Usage ...................................... tools.cmdline
    3.2 Maven Plugin Usage ........................................ tools.maven
  4 Exhaustive Example ............................................. exhaustive
    4.1 Exhaustive Example ....................................................


1 Package Information
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Contents
  ─────────────────────────────────────────────────────────────────────────────
  1.1 Orientation ............................................. pkg.orientation
    1.1.1 Overview ............................................................
    1.1.2 Metadata ....................................... pkg.orientation.meta
    1.1.3 Semantic Simplicity .................................................
    1.1.4 Lightweight Syntax ..................................................
    1.1.5 Portability .........................................................
    1.1.6 Specification .......................................................
    1.1.7 Modular Documents ........................... pkg.orientation.modular
    1.1.8 Comparison With Other Systems .......................................
  1.2 Installation ............................................................
    1.2.1 Source compilation ..................................................
    1.2.2 Maven ...............................................................
  1.3 Platform Specific Issues ................................................
  1.4 License .................................................................


1.1 Orientation [id: pkg.orientation]

1.1.1 Overview

1     The structural language is a syntactically lightweight language for
      writing technical documentation.

1.1.2 Metadata [id: pkg.orientation.meta]

1     The structural language allows for tagging of terms with metadata. For
      example, in this document, every reference to the name structural is
      tagged with "package". Individual terms within a document are given
      semantic meaning. The available tags are entirely user-defined: The
      language merely provides a way to apply tags, but does not define any
      tags of its own.

1.1.3 Semantic Simplicity

1     The structural language currently defines around twenty elements. The
      language is trivial to learn, the number of possible permutations of
      elements is low, and the output is predictable.

1.1.4 Lightweight Syntax

1     The structural language defines an abstract model for documents as an
      algebraic data type. It then defines multiple formats, all of which
      compile down to the same internal model. The canonical format is defined
      in terms of s-expressions and can be parsed at a basic level by any
      standard s-expression parser. An XML format with a full RELAX-NG schema
      is provided for legacy compatibility. Additionally, an imperative format
      is provided that allows for syntax that is only slightly more heavyweight
      than Markdown whilst still allowing for the same control over metadata
      [ref: pkg.orientation.meta] and document structure. Documents may freely
      combine elements written in any of the formats via the standard import
      [ref: pkg.orientation.modular] mechanism [0].

1.1.5 Portability

1     The kstructural implementation is written primarily in the Kotlin [url:
      http://kotlinlang.org/] language using APIs defined in Java 8. The
      implementation can therefore execute on any JVM supporting Java 8 and
      above. This also means that the language can be used to generate
      documentation as part of the build process for Java based projects
      without having to assume the existence of any platform-specific native
      binaries.

1.1.6 Specification

1     The structural language is carefully and unambiguously specified as an
      executable Haskell specification.

1.1.7 Modular Documents [id: pkg.orientation.modular]

1     The structural language supports modular documents with a simple import
      system: Documents may import elements or raw text from files, so large
      technical manuals can be cleanly separated into files based on logical
      content. Intra-document links are fully supported and full referential
      integrity checks are performed to ensure that links always point to
      elements that actually exist. Circular imports are detected and
      prevented. Additionally, the parsers are constructed to be secure by
      default: Malicious documents cannot import files outside of a given base
      directory, and in the case of the XML encoding, cannot cause the XML
      parser to perform requests over the network for remote content.

1.1.8 Comparison With Other Systems

1     In the table below, Metadata should be taken to mean that the language
      allows for expressing the semantic meaning of the contents of the
      documents, as opposed to just being a series of formatting commands.

2     Semantic Simplicity is a somewhat subjective (but somewhat measurable)
      judgement of how simple the conceptual model is of each language. An
      excellent way to measure this aspect of a language is to attempt to come
      up with a definition of an algebraic type that is able to represent a
      parsed and validated document in the given language [1].

3     Lightweight Syntax is an indication of the ratio between markup and
      actual document content. For example, XML is notoriously verbose and the
      text of some documents can often consist more of XML elements than actual
      content.

4     The term Specification should be taken to mean that both the language has
      a complete formal specification of the syntax and the underlying semantic
      model, and that documents can be machine-checked against this
      specification. The important point is: For a given document, can a
      machine determine unambiguously whether or not a document is valid? This
      is critical for both for ensuring that documents remain accessible
      decades into the future, and for ensuring that different implementations
      of languages assign the same meaning to documents: If a language does not
      have a machine-checkable specification, then users of that language are
      locked into that implementation of the language perpetually. Languages
      are assigned a value of Informal if they have at least made an attempt at
      a complete specification even if the specification is ambiguous,
      unimplementable, and/or does not provide any means to check documents.

5     The term Portability should be taken to mean that the language either has
      a platform-independent implementation, or implementations exist for
      multiple platforms [2].

6     The term Modular Documents should be taken to mean that a language
      provides a way to break documents into multiple files. Languages are
      assigned a value of Import if they have a language-supported system that
      actually parses external files and performs substitutions into an
      abstract syntax tree. Languages are assigned a value of Include if they
      only implement a simple-minded system akin to macro expansions or the C
      preprocessor (where the contents of external files are simply dumped
      verbatim into the current file and the whole mess is parsed as one unit).

      1.1.8.7 Feature Comparison
      ──────────────────────────

      ┌─────────────────────────┬────────────────────────────────┬─────────────────────────────┬──────────────────────────────┬─────────────────────────────┬───────────────────────────┬──────────────────────────────┬──────────────────────────────────────┬───────────────────────────┐
      │                         │ structural                     │ DocBook                     │ Markdown                     │ Texinfo                     │ troff                     │ AsciiDoc                     │ reStructuredText                     │ LaTeX                     │
      ├─────────────────────────┼────────────────────────────────┼─────────────────────────────┼──────────────────────────────┼─────────────────────────────┼───────────────────────────┼──────────────────────────────┼──────────────────────────────────────┼───────────────────────────┤
      │ Metadata                │ Yes                            │ Yes                         │ No                           │ No                          │ No                        │ No                           │ No                                   │ No                        │
      ├─────────────────────────┼────────────────────────────────┼─────────────────────────────┼──────────────────────────────┼─────────────────────────────┼───────────────────────────┼──────────────────────────────┼──────────────────────────────────────┼───────────────────────────┤
      │ Semantic Simplicity     │ Yes                            │ No                          │ Maybe [3]                    │ No                          │ No                        │ No                           │ No                                   │ No                        │
      │                         │                                │                             │                              │                             │                           │                              │                                      │                           │
      ├─────────────────────────┼────────────────────────────────┼─────────────────────────────┼──────────────────────────────┼─────────────────────────────┼───────────────────────────┼──────────────────────────────┼──────────────────────────────────────┼───────────────────────────┤
      │ Lightweight Syntax      │ Yes                            │ No                          │ Yes                          │ Yes                         │ Yes                       │ Yes                          │ Yes                                  │ Questionable              │
      │                         │                                │                             │                              │                             │                           │                              │                                      │                           │
      ├─────────────────────────┼────────────────────────────────┼─────────────────────────────┼──────────────────────────────┼─────────────────────────────┼───────────────────────────┼──────────────────────────────┼──────────────────────────────────────┼───────────────────────────┤
      │ Specification           │ Yes                            │ Yes                         │ Informal                     │ No                          │ No                        │ No                           │ Informal                             │ No                        │
      ├─────────────────────────┼────────────────────────────────┼─────────────────────────────┼──────────────────────────────┼─────────────────────────────┼───────────────────────────┼──────────────────────────────┼──────────────────────────────────────┼───────────────────────────┤
      │ Portability             │ Yes                            │ Yes                         │ Maybe [4]                    │ Yes                         │ Maybe [5]                 │ Yes                          │ Yes                                  │ Yes                       │
      ├─────────────────────────┼────────────────────────────────┼─────────────────────────────┼──────────────────────────────┼─────────────────────────────┼───────────────────────────┼──────────────────────────────┼──────────────────────────────────────┼───────────────────────────┤
      │ Modular Documents       │ Import                         │ Import                      │ No                           │ Include                     │ No                        │ Include                      │ No                                   │ Include                   │
      └─────────────────────────┴────────────────────────────────┴─────────────────────────────┴──────────────────────────────┴─────────────────────────────┴───────────────────────────┴──────────────────────────────┴──────────────────────────────────────┴───────────────────────────┘






8     The DocBook [url: http://docbook.org] system is similar to structural in
      that it allows for metadata within a document. DocBook, however, takes a
      different approach in that it defines elements for all of the things that
      authors may be expected to talk about in technical documentation. For
      example, if an author wants to tag a name as being the name of a software
      package, the name has to be contained within a package [url:
      http://docbook.org/tdg5/en/html/package.html] element. In terms of
      semantic simplicity, the sheer number of defined elements and the
      resulting possible permutations of elements mean that it is difficult to
      make the case that DocBook is in any way simple. In the author's
      experience, there are many combinations of elements in DocBook that are
      valid according to the schema but cannot actually be used in practice
      because the resulting XHTML output becomes ugly or difficult to style in
      a useful manner. DocBook is, however, strongly and unambiguously
      specified: If a document is well-formed XML, it can be machine-checked
      against the published schema and it is immediately known whether or not
      the document is valid. DocBook also allows for modular documents via the
      standard XML XInclude [url: https://www.w3.org/TR/xinclude/] mechanism.
      Unfortunately, due to DocBook being defined in XML, writing documents
      using it can be an exercise in physical stamina. XML is notorious for
      being syntactically heavyweight and really requires editor support to
      avoid causing repetitive strain injury.

9     Markdown [url: http://daringfireball.net/projects/markdown/] was
      originally designed as a trivial text format intended for quick
      conversion to HTML. Additionally, Markdown is intended to be readable
      without processing. Unfortunately, the original description of Markdown
      has numerous ambiguities, meaning that almost every implementation of the
      format differs in important ways. It was also designed with the
      incredibly poorly thought out idea that no document should be considered
      invalid; every mistake simply causes silent failure or corrupted output.
      It offers absolutely no standard way to incorporate metadata into
      documents: Terms may be marked as being bold, italic, or monospace, and
      very little else. It offers no way to make documents modular, and most
      implementations require the user to manually concatenate their documents
      into one large file before passing it to the Markdown processor. An
      attempt has been made to formalize a compatible common subset of Markdown
      into a system known as CommonMark [url: http://commonmark.org/].
      Unfortunately, after two years, the compatible subset is still rather
      poorly specified and contains almost none of the features of any existing
      implementation such as footnotes and intra-document links [6].

10    GNU Texinfo [url: https://www.gnu.org/software/texinfo/texinfo.html] is a
      typesetting system similar to LaTeX [ref: pkg.orientation.latex] and has
      all of the same advantages and flaws as that system.

11    troff [url: https://www.gnu.org/software/groff/] is a somewhat archaic
      UNIX typesetting tool primarily used to construct manual pages. Due to
      being a macro-based typesetting system (albeit a drastically simpler
      one), it suffers from most of the same disadvantages as LaTeX [ref:
      pkg.orientation.latex]. The syntax, however, is extremely lightweight and
      easy to parse.

12    LaTeX [url: https://latex-project.org/] is a set of macros for the TeX
      [url: http://tug.org/] typesetting system. While it produces very
      aesthetically pleasing output and has moderately lightweight syntax, it
      suffers from an excruciatingly error-prone document authoring workflow
      due to its macro-based nature. The user is forced to manage the state of
      an enormous imperative typesetting engine, error messages are
      incomprehensible at best and typically contain layers of elements that
      have appeared from inside expanded macros. Users are forced to use
      external packages of macros to get support for basic features such as
      images, and due to the complete lack of a type system or indeed any kind
      of module system at all, packages can and do break when combined in
      unexpected ways. The language has no specification, and an include -based
      system for modular documents (made extremely dangerous by the presence of
      the global state machine). The kstructural implementation of the
      structural language currently contains support for producing LaTeX code.
      This protects users from having to have anything to do with the LaTeX or
      TeX system directly.

13    AsciiDoc [url: http://www.methods.co.nz/asciidoc/] is a Python-based text
      document format. It has all of the advantages and disadvantages of a
      Markdown [ref: pkg.orientation.markdown] based system but supports a
      drastically larger feature set than most Markdown implementations. It
      also contains an insecure-by-default [url:
      http://www.methods.co.nz/asciidoc/chunked/apc.html] mode of operation
      that makes evaluating arbitrary documents a risky proposition. It has no
      specification.

14    reStructuredText [url:
      http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html] is a
      text document format in the style of AsciiDoc [ref:
      pkg.orientation.asciidoc]. It has the same advantages and disadvantages
      as both AsciiDoc and Markdown. It has what appears to be a fairly
      complete informal specification, but does not have any way to determine
      if a given document is valid or not.

1.2 Installation

1.2.1 Source compilation

1     The project can be compiled and installed with Maven [url:
      http://maven.apache.org]:

2     $ mvn -C clean install

1.2.2 Maven

1     Regular releases are made to the Central Repository [url:
      http://search.maven.org/#search%7Cga%7C1%7Ckstructural], so it's possible
      to use the io7m-kstructural package in your projects with the following
      Maven dependencies:

2     <!-- For the user-friendly frontend Java API -->
      <dependency>
        <groupId>com.io7m.kstructural</groupId>
        <artifactId>io7m-kstructural-frontend</artifactId>
        <version>0.1.0</version>
      </dependency>

3     All io7m.com [url: http://io7m.com] packages use Semantic Versioning [7],
      which implies that it is always safe to use version ranges with an
      exclusive upper bound equal to the next major version - the API of the
      package will not change in a backwards-incompatible manner before the
      next major version.

1.3 Platform Specific Issues

1     There are currently no known platform-specific issues.

1.4 License

1     All files distributed with the io7m-kstructural package are placed under
      the following license:

      1.4.2.2 License
      ───────────────

      Copyright © 2016 <code@io7m.com> http://io7m.com

      Permission to use, copy, modify, and/or distribute this software for any
      purpose with or without fee is hereby granted, provided that the above
      copyright notice and this permission notice appear in all copies.

      THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
      WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
      MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
      ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
      WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
      ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
      OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.


2 Tutorial [id: tutorial]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Contents
  ─────────────────────────────────────────────────────────────────────────────
  2.1 Overview ................................................................


2.1 Overview

1     The structural language is intended to be syntactically lightweight
      language for writing technical documentation.

2     The language is currently missing a tutorial, so instead, here is the
      source code for the documentation that you are currently reading.

      2.1.3 Documentation Listing
      ───────────────────────────

      • pkg-install.sdi [url: pkg-install.sdi]
      • pkg-license.sdi [url: pkg-license.sdi]
      • pkg-overview.sdi [url: pkg-overview.sdi]
      • pkg-platform.sdi [url: pkg-platform.sdi]
      • pkg.sdi [url: pkg.sdi]
      • tools-cmdline.sdi [url: tools-cmdline.sdi]
      • tools-maven.sdi [url: tools-maven.sdi]
      • tools.sdi [url: tools.sdi]
      • tutorial.sdi [url: tutorial.sdi]
      • complete.sd [url: complete.sd]
      • documentation.sd [url: documentation.sd]
      • listing.sd [url: listing.sd]



3 Tools
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Contents
  ─────────────────────────────────────────────────────────────────────────────
  3.1 Command Line Usage ........................................ tools.cmdline
    3.1.1 Synopsis ............................................................
    3.1.2 check ........................................... tools.cmdline.check
    3.1.3 compile-xhtml ........................... tools.cmdline.compile_xhtml
    3.1.4 compile-latex ........................... tools.cmdline.compile_latex
    3.1.5 compile-plain ........................... tools.cmdline.compile_plain
    3.1.6 convert ....................................... tools.cmdline.convert
  3.2 Maven Plugin Usage .......................................... tools.maven
    3.2.1 Synopsis ............................................................
    3.2.2 Skipping ........................................... tools.maven.skip


3.1 Command Line Usage [id: tools.cmdline]

3.1.1 Synopsis

1     The kstructural command processes structural documents.
      Usage: kstructural [options] [command] [command options]

2     The command line tool is distributed as part of the executable
      io7m-kstructural-cmdline-0.3.1-main.jar file (referred to as
      kstructural.jar in usage examples, for brevity):

3     $ java -jar io7m-kstructural-cmdline-0.3.1-main.jar

3.1.2 check [id: tools.cmdline.check]

1     The check subcommand parses and validates the given document.

      3.1.2.2 Check Subcommand
      ────────────────────────

      check      Check document syntax and structure
        Usage: check [options]
          Options:
            * -file
                Input file
              -verbose
                Set the minimum logging verbosity level
                Default: info
                Possible Values: [trace, debug, info, warn, error]



3     The command exits with code 0 if no errors occurred, and a positive exit
      code otherwise.

      3.1.2.4 Checking Example
      ────────────────────────

      $ java -jar kstructural.jar check -file valid.sd
      $ echo $?
      0

      $ java -jar kstructural.jar check -file invalid.sd
      ERROR com.io7m.kstructural.frontend.KSOpCheck: invalid.sd: 1:14: Expected an inline element.
        Expected: [symbol:{image | include | link-ext | link | term | verbatim | footnote-ref | table | list-ordered | list-unordered} ... ]
        Received: [invalid]
      $ echo $?
      1


3.1.3 compile-xhtml [id: tools.cmdline.compile_xhtml]

1     The compile-xhtml subcommand parses and validates the given document, and
      then generates XHTML pages based on the content.

      3.1.3.2 XHTML Compilation Subcommand
      ────────────────────────────────────

      compile-xhtml      Compile documents to XHTML
        Usage: compile-xhtml [options]
          Options:
            -brand-bottom
               Append the contents of the given XML file to each XHTML page's body
               element
            -brand-top
               Prepend the contents of the given XML file to each XHTML page's
               body element
            -css-create-default
               Create the default CSS files in the output directory
               Default: true
            -css-extra-styles
               A comma-separated list of extra CSS styles (as URIs) that will be
               used for each page
               Default: []
            -css-include-default
               Include links to the default CSS files
               Default: true
          * -file
               Input file
          * -output-dir
               The directory in which output files will be written
            -pagination
               The type of XHTML pagination that will be used
               Default: multi
               Possible Values: [single, multi]
            -render-toc-document
               Render a table of contents at the document level
               Default: true
            -render-toc-part
               Render a table of contents at the part level
               Default: true
            -render-toc-section
               Render a table of contents at the section level
               Default: true
            -verbose
               Set the minimum logging verbosity level
               Default: info
               Possible Values: [trace, debug, info, warn, error]



3     The -brand-bottom option specifies an XML file that will be appended to
      the body of each generated XHTML page. This effectively allows for custom
      footers on generated pages. Note that the XML file is parsed and the
      element is appended to the AST of each generated page. This guarantees
      that the output is well formed (although not necessarily valid) XHTML.

4     The -brand-top option specifies an XML file that will be prepended to the
      body of each generated XHTML page. This effectively allows for custom
      headers on generated pages. Note that the XML file is parsed and the
      element is prepended to the AST of each generated page. This guarantees
      that the output is well formed (although not necessarily valid) XHTML.

5     The -css-create-default option specifies that the default CSS files used
      by the kstructural should be written to the output directory. This option
      can be set to false if entirely custom CSS is to be used.

6     The -file option specifies the input file.

7     The -css-include-default option specifies that links to the default CSS
      files used by the kstructural should be generated in each XHTML page.
      This option can be set to false if entirely custom CSS is to be used.

8     The -output-dir option specifies the output directory.

9     The -pagination option specifies how the generated XHTML should be
      paginated. A value of single indicates that the output should be one
      large XHTML page. A value of multi indicates that a new page should be
      created for each document, part, and section.

10    The -render-toc-document option specifies whether or not a table of
      contents should be generated for the main document.

11    The -render-toc-section option specifies whether or not a table of
      contents should be generated at the start of each section.

12    The -render-toc-part option specifies whether or not a table of contents
      should be generated at the start of each part.

13    The -verbose option specifies the level of logging desired.

14    The command exits with code 0 if no errors occurred, and a positive exit
      code otherwise.

      3.1.3.15 XHTML Compilation Example
      ──────────────────────────────────

      $ java -jar kstructural.jar compile-xhtml -file valid.sd -output-dir /tmp
      $ echo $?
      0

      $ java -jar kstructural.jar compile-xhtml -pagination single -file valid.sd -output-dir /tmp
      $ echo $?
      0

      $ file /tmp/index-m.xhtml
      /tmp/index-m.xhtml: XML 1.0 document, ASCII text, with very long lines, with CRLF line terminators
      $ file /tmp/index.xhtml
      /tmp/index.xhtml: XML 1.0 document, ASCII text, with very long lines, with CRLF line terminators


3.1.4 compile-latex [id: tools.cmdline.compile_latex]

1     The compile-latex subcommand parses and validates the given document, and
      then generates LaTeX based on the content.

      3.1.4.2 LaTeX Compilation Subcommand
      ────────────────────────────────────

      compile-latex      Compile documents to LaTeX
        Usage: compile-latex [options]
          Options:
          * -file
               Input file
          * -output-dir
               The directory in which output files will be written
            -type-map
               A file containing type name to LaTeX emphasis mappings
            -verbose
               Set the minimum logging verbosity level
               Default: info
               Possible Values: [trace, debug, info, warn, error]



3     The -file option specifies the input file.

4     The -output-dir option specifies the output directory.

5     The -type-map option specifies a file that contains a set of mappings
      from terms to emphasis types. This is used to mark specific terms as
      being displayed in a monospaced font, in bold, or in italic. The file
      contains one line per term and has the following grammar:

      3.1.4.6 LaTeX Type Map Grammar
      ──────────────────────────────

      mapping =
        term_name , ':' , style ;

      term_character =
        p{isLetter} | p{isNumber}_ ;

      term_name =
        term_character , { term_character } ;

      style =
        "bold" | "mono" | "italic" ;



7     For example, the following type map makes all text tagged with function
      monospaced, all text tagged with package bold, and all text tagged with
      term italic:

      3.1.4.8 LaTeX Type Map Example
      ──────────────────────────────

      package  : bold
      function : mono
      term     : italic


9     The -verbose option specifies the level of logging desired.

10    The command exits with code 0 if no errors occurred, and a positive exit
      code otherwise.

      3.1.4.11 LaTeX Compilation Example
      ──────────────────────────────────

      $ java -jar kstructural.jar compile-latex -file valid.sd -output-dir /tmp
      $ echo $?
      0

      $ file /tmp/main.tex
      /tmp/main.tex: ASCII text, with very long lines


3.1.5 compile-plain [id: tools.cmdline.compile_plain]

1     The compile-plain subcommand parses and validates the given document, and
      then generates plain text based on the content.

      3.1.5.2 Plain Compilation Subcommand
      ────────────────────────────────────

      compile-plain      Compile documents to plain text
        Usage: compile-plain [options]
          Options:
          * -file
               Input file
          * -output-dir
               The directory in which output files will be written
            -verbose
               Set the minimum logging verbosity level
               Default: info
               Possible Values: [trace, debug, info, warn, error]



3     The -file option specifies the input file.

4     The -output-dir option specifies the output directory.

5     The -verbose option specifies the level of logging desired.

6     The command exits with code 0 if no errors occurred, and a positive exit
      code otherwise.

      3.1.5.7 Plain Compilation Example
      ─────────────────────────────────

      $ java -jar kstructural.jar compile-plain -file valid.sd -output-dir /tmp
      $ echo $?
      0

      $ file /tmp/main.txt
      /tmp/main.tex: UTF-8 Unicode text


3.1.6 convert [id: tools.cmdline.convert]

1     The convert subcommand parses and validates the given document, and then
      converts it to one of the supported structural formats.

      3.1.6.2 Convert Subcommand
      ──────────────────────────

      convert      Convert documents between input formats
        Usage: convert [options]
          Options:
          * -file
               Input file
            -format
               The format that will be used for exported documents
               Default: canonical
               Possible Values: [canonical, imperative, xml]
            -indent
               The number of spaces that will be used to indent documents
               Default: 2
            -no-imports
               Export as one large document that does not contain any imports
               Default: false
          * -output-dir
               The directory in which output files will be written
            -verbose
               Set the minimum logging verbosity level
               Default: info
               Possible Values: [trace, debug, info, warn, error]
            -width
               The maximum width in characters that will be used when formatting
               documents
               Default: 80



3     The command exits with code 0 if no errors occurred, and a positive exit
      code otherwise.

      3.1.6.4 Conversion Example
      ──────────────────────────

      $ cat valid.sd
      [document
        [title A document]
        [section
          [title A section]
          [paragraph A paragraph]]]

      $ java -jar kstructural.jar convert -file valid.sd -output-dir /tmp -format imperative
      $ java -jar kstructural.jar convert -file valid.sd -output-dir /tmp -format xml

      $ cat /tmp/main.xml
      <?xml version="1.0" encoding="UTF-8"?>
      <s:document s:title="A document" xmlns:s="http://schemas.io7m.com/structural/3.0.0">
        <s:section s:title="A section">
          <s:paragraph>A paragraph</s:paragraph>
        </s:section>
      </s:document>

      $ cat /tmp/main.sdi
      [document [title A document]]
      [section [title A section]]
      [paragraph]
      A paragraph



3.2 Maven Plugin Usage [id: tools.maven]

3.2.1 Synopsis

1     The kstructural Maven plugin processes documents during a Maven build.

2     The plugin currently exposes the command line's compile-xhtml [ref:
      tools.cmdline.compile_xhtml], compile-latex [ref:
      tools.cmdline.compile_latex], and compile-plain [ref:
      tools.cmdline.compile_plain] commands via the compileXHTML, compileLaTeX,
      and compilePlain Maven goals to produce XHTML, LaTeX, and plain text
      documentation during the build. The goals have the exact same behaviour
      as the command-line subcommands and the parameters have the same names
      modulo differences in casing, so the command line documentation should be
      consulted for information on the behaviour of the parameters.

      3.2.1.3 Maven Plugin Example
      ────────────────────────────

      <plugin>
        <groupId>com.io7m.kstructural</groupId>
        <artifactId>io7m-kstructural-maven-plugin</artifactId>
        <version>0.3.1</version>
        <executions>
          <execution>
            <id>exec-multi</id>
            <goals>
              <goal>compileXHTML</goal>
            </goals>
            <phase>process-resources</phase>
            <configuration>
              <documentFile>src/main/resources/documentation/documentation.sd</documentFile>
              <outputDirectory>target/documentation/</outputDirectory>
              <pagination>XHTML_MULTI_PAGE</pagination>
              <brandTopFile>src/main/resources/documentation/brand.xml</brandTopFile>
              <renderTOCDocument>true</renderTOCDocument>
              <renderTOCSection>true</renderTOCSection>
              <renderTOCPart>true</renderTOCPart>
              <cssIncludeDefault>true</cssIncludeDefault>
              <cssCreateDefault>true</cssCreateDefault>
              <cssExtraStyles>
                <param>documentation.css</param>
              </cssExtraStyles>
            </configuration>
          </execution>
        </executions>
      </plugin>


3.2.2 Skipping [id: tools.maven.skip]

1     Set the property kstructural.skip to true to skip execution of the
      plugin.

      3.2.2.2 Skipping Execution
      ──────────────────────────

      $ mvn -Dkstructural.skip=true clean package


4 Exhaustive Example [id: exhaustive]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Contents
  ─────────────────────────────────────────────────────────────────────────────
  4.1 Exhaustive Example ......................................................
    4.1.1 Overview ............................................................
    4.1.2 Footnotes ...........................................................
    4.1.3 Images ..............................................................
    4.1.4 Links ...............................................................
    4.1.5 Lists ...............................................................
    4.1.6 Nested Lists ........................................................
    4.1.7 Table ...............................................................
    4.1.8 Table (Headless) ....................................................
    4.1.9 Table (Mixed) .......................................................
    4.1.10 Term ...............................................................
    4.1.11 Verbatim ...........................................................
    4.1.12 ASCII ..............................................................
    4.1.13 LaTeX ..............................................................
    4.1.14 Target ........................................... exhaustive.target


4.1 Exhaustive Example

4.1.1 Overview

1     This section represents an exhaustive example of every element available
      in the structural language. See the source code listing [complete.sd]
      [url: complete.sd].

4.1.2 Footnotes

1     This is a reference to a footnote [8].

4.1.3 Images

1     This paragraph contains an image: [image: strawberry.png] (A strawberry.)

4.1.4 Links

1     This is an internal link [ref: exhaustive.target]. This is an external
      link [url: http://io7m.com].

4.1.5 Lists

1     An unordered list contained within this paragraph as inline content:
      • One
      • Two
      • Three


2     An ordered list contained within this paragraph as inline content:
      0.  One
      1.  Two
      2.  Three


4.1.6 Nested Lists

1     A nested unordered list contained within this paragraph as inline
      content:
      • • One
        • Two
        • Three

      • • One
        • Two
        • Three

      • • One
        • Two
        • Three



2     A nested ordered list contained within this paragraph as inline content:
      0.  0.  One
          1.  Two
          2.  Three

      1.  0.  One
          1.  Two
          2.  Three

      2.  0.  One
          1.  Two
          2.  Three



4.1.7 Table

1     The paragraph contains a simple 3x3 table with a head:
      ┌────────────────┬────────────────┬──────────────────┐
      │ One            │ Two            │ Three            │
      ├────────────────┼────────────────┼──────────────────┤
      │ Top Left       │ Top Middle     │ Top Right        │
      │                │                │                  │
      ├────────────────┼────────────────┼──────────────────┤
      │ Middle Left    │ Middle Middle  │ Middle Right     │
      │                │                │                  │
      ├────────────────┼────────────────┼──────────────────┤
      │ Bottom Left    │ Bottom Middle  │ Bottom Right     │
      └────────────────┴────────────────┴──────────────────┘


4.1.8 Table (Headless)

1     The paragraph contains a simple 3x3 table without a head:
      ┌────────────────────────────────┬────────────────────────────────┬────────────────────────────────┐
      │ Top Left                       │ Top Middle                     │ Top Right                      │
      ├────────────────────────────────┼────────────────────────────────┼────────────────────────────────┤
      │ Middle Left                    │ Middle Middle                  │ Middle Right                   │
      ├────────────────────────────────┼────────────────────────────────┼────────────────────────────────┤
      │ Bottom Left                    │ Bottom Middle                  │ Bottom Right                   │
      └────────────────────────────────┴────────────────────────────────┴────────────────────────────────┘


4.1.9 Table (Mixed)

1     The paragraph contains a table with differently sized rows:
      ┌────────────────────────────────┬─────────────────────────────┐
      │ Top One                        │ Top Two                     │
      ├────────────────────────────────┼─────────────────────────────┼──────────────────────────┐
      │ Middle One                     │ Middle Two                  │ Middle Three             │
      ├────────────────────────────────┼─────────────────────────────┴──────────────────────────┘
      │ Bottom One                     │
      └────────────────────────────────┘


4.1.10 Term

1     This paragraph contains a selection of terms: mono, bold, italic.

4.1.11 Verbatim

1     This paragraph contains verbatim text:
      This is verbatim text.

4.1.12 ASCII

1     This paragraph contains the entire ASCII space. Note that unrepresentable
      characters may be replaced with U+FFFD:
               

                        
      ! " # $ % & ' ( ) * + , - . / 0 1 2 3 4 5 6 7 8 9 : ; < = > ? @
      A B C D E F G H I J K L M N O P Q R S T U V W X Y Z [ \ ] ^ _ `
      a b c d e f g h i j k l m n o p q r s t u v w x y z { | } ~ 

2     This paragraph contains the entire ASCII space again, but not contained
      within a verbatim element:
      ! " # $ % & ' ( ) * + , - . / 0 1 2 3 4 5 6 7 8 9 : ; < = > ? @
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z [ \ ] ^ _ `
a b c d e f g h i j k l m n o p q r s t u v w x y z { | } ~ 

4.1.13 LaTeX

1     This paragraph contains text intended to injure the LaTeX backend by
      trying to insert an \end{verbatim} command inside a verbatim element:
      \end{verbatim}

4.1.14 Target [id: exhaustive.target]

1     This subsection is the target of an earlier link.


Footnotes
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[0]   Doing this for an imperative state machine such as LaTeX could easily
      become a research-level project.

[1]   This again assumes the existence of an unambiguous formal specifications
      so that multiple interoperable implementations can actually exist!

[2]   Users of Markdown are resigned to the fact that they are writing
      documents in an implementation-specific dialect of Markdown because there
      is no other alternative. This is an incredibly poor long-term strategy.

[3]   The CommonMark specification has a simple semantic model due to including
      almost nothing.

[4]   There are Markdown implementations for most languages. However, there may
      not be an implementation that supports the specific dialect the author
      has used.

[5]   Being a traditional UNIX tool, the troff tool is unlikely to be pleasant
      to use outside of UNIX.

[6]   Although elements written in the XML format cannot import non-XML
      elements due to limitations with XInclude [url:
      https://www.w3.org/TR/xinclude/].

[7]   http://semver.org [url: http://semver.org]

[8]   This is the footnote content.

