Examples and recommended usage of XML documents following the eolas format. The author disclaims all copyrights and releases this document into the public domain. $Id: example.xml,v 1.24 2009/05/24 21:47:50 jmates Exp $

Eolas is a simple XMLExtensible Markup Language 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 XMLExtensible Markup Language does not apply.

Eolas documents should be created from a pre-built template, which should contain all the extra cruft required by XMLExtensible Markup Language 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 DTDDocument Type Description file for the final word on how things are laid out. XSLTExtensible Stylesheet Language Transformations and CSSCascading Style Sheets can be used to control the rendition and display of the XMLExtensible Markup Language in web browsers—consult the stylesheets directory for more details on that process.

The following is a depth check on subsection support.

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-func> - perl functions: -X.

<perl-module> - perl modules, with auto-links to documentation: File::Temp.

<perl-pod> - perl POD: perlre.

<man> - Unix manuals (ls, pfctl).

<rfc> - Requests for Comments: 1234, 99999.

<acronym> - acronyms, like MTAMail Transport Agent

<link> - HTML <a href=""> using xlink:href instead. Note that certain elements accept the xlink:href attribute, which is usually 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.

<script> - Sial.org scripts, such as .

Images too, if you really need them. And SVGScalable Vector Graphics images, which get handled slightly differently than bitmaps.

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.

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.

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 scp ~/.ssh/id_dsa.pub server.example.com: cat id_dsa.pub >> ~/.ssh/authorized_keys

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 browser 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

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.

Foo

Not much to say about Foo.

Bar

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!

Post list text block to confirm post-list spacing.

Inside this link, xlink:href or auto-generated links should not replace the parent link: File::AtomicWrite ls perlfunc unlink. And, to check up on whitespace handling: File::AtomicWritelsperlfuncunlink.