Copyright © 2005 Davor Ocelic
Copyright © 2005 Interchange Development Group
This documentation is free; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
It is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
Abstract
Table of Contents
Since XMLDOCS is based on DocBook XML, the usual DocBook XML rules apply: XML markup consists of XML "tags" (same style as HTML tags), but all of which must be opened (and closed — you cannot omit the closing tag) respecting the hierarchy of tags within a document. In addition, attributes must always be quoted. These two rules are non-negotiable with DocBook XML. Here's an example:
<?xml version="1.0" standalone="no"?> <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook-Interchange XML V4.2//EN" "../docbook/docbookxi.dtd"> <article id='xmldocs'> <sect1> <title>Test title</title> <para> <!-- COMMENT: Beginning of a paragraph --> It is <emphasis>very</emphasis> important to read this line. Some lines are <emphasis role='bold'>boldly bolder</emphasis> than others. The <database>products</database> database contains products. </para> </sect1> </article>
As you can see, XML can look structured and all, but there's so much overhead involved in writing XML documentation. For example, I wouldn't know offhand how to define DOCTYPE properly — I just took the effort of learning it once, and I kept copy/pasting it ever since.
XMLDOCS aims to be as overhead-free and efficient as possible to write. This, however, leads us to mention four main differences between DocBook XML and XMLDOCS:
A lot of XMLDOCS markup and content is autogenerated. For example, all Interchange source code shown is taken out of CVS, and is therefore always up to date. The same goes for information such as say, file version numbers and modification times.
Instead of writing complete XML documents (those that contain XML
"head and tail" and would be valid if taken standalone), in XMLDOCS
you only need to
provide short blocks of input to predefined "slots". These slots
already provide all needed XML wrapping, so you can get onto writing
actual text right away. For example, the opening
<para> and the closing
</para> are always part of the template, so
you can (and in fact, must) omit them when filling in the
documentation slots.
DocBook XML supports "entities". Entities are something like variables
and are inserted using
&NAME;
<!-- Generic DocBook XML way: --> Please see the <olink targetdoc='confs' targetptr='Catalog'><option>Catalog</option></olink> configuration directive. <!-- XMLDOCS way: --> Please see the &conf-Catalog; configuration directive. <!-- Or, another example: --> Add the following to your <filename>catalog.cfg</filename>: Add the following to your &ccf;:
In XMLDOCS, we use a controlled set of XML tags, plus few Interchange-specific ones. For example, all Perl functions are marked up using DocBook XML's <function>, while all "mv" variables are marked up using our custom <mv> tag.
Here's the reduced set of DocBook XML tags (and our custom ones) at your disposal in XMLDOCS (in alphabetical order):
application - software program name, such as QuickBooks
arg - part of the Synopsis line, can be used with choice = plain, opt (default) or required to decorate argument with nothing, [], or {} appropriately
blockquote - quotes, citations
classname - Perl module name, such as Image::Size
code - chunks of actual code. Use to display ITL/Perl/any-other code examples inline, such as [scratch tempvar]
command - computer command name (usually Unix command), such as ls
computeroutput - output as you would get from a computer, such as the output of ls
constant, such as MAXPATHLEN
database - everything related to a database. Used to mark up tables or table fields (use class='field' attribute for fields), such as products or sku
emphasis - renders as italic or bold with role='bold'
envar - environment variable, usually as seen by the web server or IC, such as REMOTE_PORT
errorcode - some error code, such as 6
errorname - error name, such as ENOENT
errortext - such as Page not found
filename - file and directory (class='directory') names, such as /etc/syslog.conf or /etc/init.d/
filter - Interchange filter name (XMLDOCS extension to DocBook XML), such as <filter>entities</filter>
function - function name, such as syscall64()
group - grouping of arguments inside Synopsis line
guibutton - identify buttons in the web gui, such as
guiicon - icon in the web gui
guilabel - label in the web GUI
guimenu - menu in the web GUI
guisubmenu - submenu in the web gui
hardware - piece of hardware, such as motherboard
important - important block, stands out
itemizedlist - wrapper for a bulleted list
keysym - Key sym, such as Ctrl+c
listitem - element inside itemizedlist
literal - every literal (verbatim) value, such as standard keep
note - note block, stands out
olink - linking between separate documents
para - the standard paragraph element, used all over the place
programlisting - example of code or text that the user is supposed to enter
replaceable - identify replaceable parts everywhere, such as PID in kill -9 PID
returnvalue - command return value
sbr - starts a newline. Useful in Synopsis, or if you don't want to split the paragraph in two, which then generates a wide spacing
screen - used as element in which you display existing interchange source (this is mostly in autogenerated pages but can be used manually)
subscript
superscript
systemitem - various system items, see possible class="" values
tip - tip block, stands out
ulink - link to external resources
warning - warning block, stands out
xref - link within the same document