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
com.io7m.kstructural
io7m-kstructural-frontend
0.1.0
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 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
A paragraph
$ 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
────────────────────────────
com.io7m.kstructural
io7m-kstructural-maven-plugin
0.3.1
exec-multi
compileXHTML
process-resources
src/main/resources/documentation/documentation.sd
target/documentation/
XHTML_MULTI_PAGE
src/main/resources/documentation/brand.xml
true
true
true
true
true
documentation.css
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.