Eolas

Eolas is a simple Extensible Markup Language (XML) format used to generate narrative-centric documentation and presentations. This document provides an overview of the various features of the specification and their usage, plus additional recommendations on style where XML does not apply.

Basics

Eolas documents should be created from a pre-built template, which should contain all the extra cruft required by XML documents. Use UTF-8 encoding where possible. Eolas documents consist of a leading <summary> element, which contains relevant overview details, followed by at least on <section> element containing the meat of the document. <section> may be nested to produce subsections. Consult the Document Type Description (DTD) file for the final word on how things are layed out.

XSLT and CSS can be used to control the rendition and display of the XML in web browsers— see the stylesheets for more details on that process.

Sections

The following is a depth check on subsection support.

Three

Four

Five

Six

Seven

Eight

Markup

There are various text markup elements, ranging from HTML-compatible to computer system related ones.

<input> - text the user will input into a computer, e.g. textfield values: foobar.
<em> - from HTML, for emphasis to the reader.
<code> - catch-all element for computer-related markup.
<cmd> - inline shell commands, like ls -al.
<cmd-arg> - arguments to inline shell commands (use -ali for inode display).
<gui> - catch-all for user interaction with captive user interface elements. (From the File menu, select Save As....)
<file> - filenames of all sorts and kinds, like /etc/mail.
<file-glob> - for (Unix) shell-style globbing of filenames, e.g. *html.
<host> - system hostnames, example.org.
<perl-module> - perl modules, with auto-links to documentation: File::Temp.
<man> - Unix manuals (ls(1), pfctl(8)).
<rfc> - Requests for Comments: [RFC 1234], [RFC 99999].
<acronym> - acronyms, like Mail Transport Agent (MTA)
<link> - HTML <a href=""> using xlink:href instead. Note that certain elements accept the xlink:href attribute, which is preferable to doing <link xlink:href=""><foo>bar</foo></link> nesting.
<book> - books, for example XML in a Nutshell: A Desktop Quick Reference or Amazon Hacks: 100 Industrial-Strength Tips and Tools.

Images too, if you really need them.

And Scalable Vector Graphics (SVG) images, which get handled slightly differently than bitmaps.

Text Blocks

There are three general text blocks, <info>, <note>, and <warn>. <info> should be used where possible, and is the equivalent of a paragraph block in HTML. The other two block styles allow one to tag data as more important or critical— computer documentation often contains many noteworthy pitfalls.

This is the <note> block style, with some filler text to hopefully get in a line or two. There is no style guide whether a block such as this should really be a standard paragraph, or just a quick sentence.

This is the <warn> block style.

Data Blocks

Examples | Wrapping

Display of data from computers (shell commands, output thereof, contents of configuration files) is handled by <data> blocks, which contain either <line> or <shell> elements. User input may be indicated inside <line> elements via the <input> element. Use the <em> element to bring a reader’s attention to something, and <comment> to denote things the shell or reader will generally ignore.

Examples

Lines without <shell> elements are placed into a different CSS class, which allows the denotation of the shell examples differently from those just containing data.

# how long priv. allowance lasts
Defaults timestamp_timeout=15

# only allow on single terminal
Defaults tty_tickets
# require a tty to prevent clever hacks
Defaults requiretty

# do not lecture those who presumably know
Defaults:%wheel !lecture

The prefix attribute for <shell> can be used to specify a custom shell prompt, which indicates shell commands to the reader. The prefix can also be used to denote different shells ($ for a bourne-based shell or % for a C-ish shell), users (# for the superuser), or other metadata related to the commands being run.

$ sudo -s
Password: your password # will not echo
# uptime
2:29PM up 1 day, 22:30, 5 users, load averages: 0.46, 0.36, 0.37

client$ scp ~/.ssh/id_dsa.pub server.example.com:
server$ cat id_dsa.pub >> ~/.ssh/authorized_keys

Wrapping

Text wrapping in data blocks poses problems, as either one loses the initial (and often important) whitespace on each line of text, or the text runs long off the right-hand side of the browser display. This was solved by setting preformatted text for data blocks (to preserve initial whitespace) and then allowing the author to insert <rbr/> to tell the XSLT engine where to insert line breaks. This will need to be a browser-specific alteration, and means to get at the unaltered data should be provided where relevant.

$ echo test of a very long line that would otherwise run off the right hand side\ of a browser window
test of a very long line that would otherwise run off the right hand side of a b↵
rowser window

Generally, data in <line> elements should be broken down as an 80-column terminal would display it. <shell> element contents will need to be broken down where appropriate or by logical groups. For example, a perl script can be presented on two lines, one for each -e argument.

# perl -ple 'BEGIN { $n=0; select $fh }' \ -e 'open $fh, ">card$n.vcf" and $n++ if /^BEGIN:VCARD$/' all.vcf

Lists

At present, two forms of lists are supported— ordered (<enum>) and unordered (<list>). Lists and list elements (<li>) accept the standard HTML CSS attributes for fancier markup in resulting browsers, if required.

Unordered list item 1.
Unordered list item 2.

First.
Second.

A more complex nested example.

Not much to say about Foo.

First.

Just a test.

Second.

Some data, described in a run-on sentence as we need to see sometimes how very long <li> content is displayed under the browser in question. Had this been a real run-on, the system would have caught on fire.

$ xsltproc test.xsl test.xml > test.html
$ open -a OmniWeb test.html

¡Ése es todo, gente!