[docs] xmldocs - docelic modified 2 files
docs at icdevgroup.org
docs at icdevgroup.org
Tue Sep 21 14:37:31 EDT 2004
User: docelic
Date: 2004-09-21 18:37:31 GMT
Modified: . TODO
Added: guides xmldocs.xml
Log:
NEW DOCUMENT: XMLDOCS authoring guide
Revision Changes Path
1.19 +5 -5 xmldocs/TODO
rev 1.19, prev_rev 1.18
Index: TODO
===================================================================
RCS file: /var/cvs/xmldocs/TODO,v
retrieving revision 1.18
retrieving revision 1.19
diff -u -r1.18 -r1.19
--- TODO 21 Sep 2004 15:59:11 -0000 1.18
+++ TODO 21 Sep 2004 18:37:31 -0000 1.19
@@ -17,6 +17,8 @@
- Add a note that we're focusing on really basic stuff that won't change
over time (the criteria we used to determine what's for iccattut and what
isn't)
+- not to forget, fix cases where context goes to negative values, and make
+ cache target in Makefile
- In iccattut:
- mention which paths would be valid for /usr/local tarball
@@ -70,6 +72,9 @@
Long-term:
- filenames in Source contexts should also be clickable. this is longterm
because it'll involve perltidy and other stuff I have in mind ...
+- rebuild the make system
+- isolate build steps and make it possible to build specific "pages"
+ without the rest
DOCUMENTATION ITSELF:
- Resolve items from tmp/missing file. (You need to run 'make' in your tree
@@ -115,8 +120,3 @@
New docs:
- promotional
- new developer howto
-
-
-guibutton
-mv
-literal for values
1.1 xmldocs/guides/xmldocs.xml
rev 1.1, prev_rev 1.0
Index: xmldocs.xml
===================================================================
<?xml version="1.0" standalone="no"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook-Interchange XML V4.2//EN"
"docbook/docbookix.dtd">
<article id='xmldocs'>
<articleinfo>
<title>Interchange Guides: the XMLDOCS Documentation System</title>
<titleabbrev>xmldocs</titleabbrev>
<edition>version xml0.1a</edition>
<copyright>
<year>2004</year>
<holder>Davor Ocelic</holder>
</copyright>
<copyright>
<year>2004</year>
<holder>Interchange Development Group</holder>
</copyright>
<authorgroup>
<author>
<firstname>Davor</firstname><surname>Ocelic</surname>
<email>docelic at icdevgroup.org</email>
</author>
</authorgroup>
<legalnotice>
<para>
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.
</para>
<para>
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.
</para>
</legalnotice>
<abstract>
<para>
The purpose of this document is to give you a
<emphasis>Quick Start</emphasis> on XMLDOCS authoring.
Where appropriate (and needed for context reasons), we will discuss the underlying technologies, Interchange sources and the XMLDOCS layer organization.
</para>
<para>
After this, you might be interested in more technical reading found in <filename>xmldocs/README</filename>.
</para>
</abstract>
</articleinfo>
<sect1 id='Introduction'>
<title>Introduction</title>
<!-- <para>
Before I officially joined the &ICDEVGROUP;, I have already identified the
weak points in the documentation system used. I found that:
</para>
<itemizedlist>
<listitem><para>
The SDF/POD format caused too much "overhead" every time you wanted to
add a piece of information (and everything had to be added manually). Also,
the available SDF/POD tools and output formats were inflexible and not
up to today's open documentation standards.
</para></listitem>
<listitem><para>
The documentation itself didn't (quite) keep up with the development;
a lot of items were never documented. The parts that were, were more or
less valid but did not include details and insights, and did not
<emphasis>feel</emphasis> current.
</para></listitem>
</itemizedlist> -->
<para>
</para>
<para>
At first (after joining the ICDEVGROUP), I wasn't openly suggesting a
complete documentation redesign because I thought I wasn't in position
to propose bigger procedural changes. However, I was encouraged by
Stefan "Racke" Hornburg to investigate this possibilty ;-)
</para>
<para>
My general idea was to link the documentation to the Interchange sources,
and use <emphasis>auto-generation</emphasis> where ever possible.
In a private e-mail thread, Stefan suggested using XML as the base. As XML
is definitely better than any custom system I can come up with, this was a
push in the right direction.
</para>
<para>
The main Interchange XMLDOCS goals (as mentioned in my first -core post from Tue Jul 6 17:59:25 EDT 2004) are:
<itemizedlist>
<listitem><para>
Minimizing the documentation writing overhead (clean and easy authoring
system <emphasis>and</emphasis> autogeneration of all information the
computer can derive with no human intervention),
</para></listitem>
<listitem><para>
Standard, flexible format for good readability and easy contribution,
</para></listitem>
<listitem><para>
Increase in overall documentation accuracy and completeness,
</para></listitem>
<listitem><para>
Higher-quality output formats.
</para></listitem>
</itemizedlist>
</para>
</sect1>
<sect1 id='DocumentationStructure'>
<title>Documentation Structure</title>
<para>
So, the current system is split into the following categories:
<itemizedlist>
<listitem><para>
Guides (easy reading, mostly prose and not overly technical documents serving as an "illustrated introduction" to the subject, take iccattut for example)
</para></listitem>
<listitem><para>
HOWTOs (quick, on-topic, technical solutions)
</para></listitem>
<listitem><para>
Reference sets (quick, on-topic descriptions and usage examples of
Interchange "symbols" - global variables, pragmas, user tags, system
tags, ...).
</para>
<para>
<command>The source .xml files for the reference sets are autogenerated
</command>. The <command>bin/stattree</command> script collects all
needed information from Interchange sources and saves it to cache files.
<command>bin/refs-autogen</command> reads the cache files, supplements
that information with data from
<filename class='directory'>refs/*/*</filename> files and generates the
final <filename>refs/*.xml</filename> sources.
</para></listitem>
<listitem><para>
Glossary, where the glossary terms are kept in
<filename>glossary/*</filename> files. The glossary itself, <filename>
guides/glossary.xml</filename> is then autogenerated by
<command>bin/glossary-autogen</command>.
</para></listitem>
</itemizedlist>
</para>
</sect1>
<sect1 id='TheAuthoringQuickStart'>
<title>The Authoring QuickStart</title>
<para>
The documentation writing procedure is not always the same, it depends
on the actual part of the content you want to write/update.
</para>
<sect2>
<title>Guides</title>
<para>
To modify an existing guide, simply edit <filename>guides/<replaceable>name</replaceable>.xml</filename>.
</para>
<para>
To start a new guide, create a new <filename>guides/<replaceable>name</replaceable>.xml</filename> file. For a quickstart, copy the exact structure as you see in the existing <literal>iccattut</literal> guide. The iccattut guide will always reflect the current standard.
</para>
<para>
To make the new guide build as part of the global <command>make</command>
procedure, nothing needs to be done; the guide is auto-located and built.
To build it manually, invoke <command>make OUTPUT/<replaceable>name</replaceable>.<replaceable>format</replaceable></command>, where 'format' represents typical filename extensions (such as .html or .ps). If you leave ".<replaceable>format</replaceable>" unspecified, the chunked HTML version will be built and, of course, saved to <filename>OUTPUT/<replaceable>name</replaceable>/</filename>.
</para>
</sect2>
<sect2>
<title>HOWTOs</title>
<para>
To modify an existing HOWTO item, simply edit <filename>howtos/<replaceable>name</replaceable>.xml</filename>.
</para>
<para>
To start a new HOWTO, create a new <filename>howtos/<replaceable>name</replaceable>.xml</filename> file. For a quickstart, copy the exact structure as you see in the existing <literal>custom-sendmail-routine.xml</literal> HOWTO. It will always reflect the current standard.
</para>
<para>
To make the new HOWTO entry build as part of the global
<command>make</command>
procedure, you need to edit <filename>howtos/howtos.xml</filename>. Search for <literal>custom-sendmail</literal> in it and make your new entries look like the existing ones.
HOWTOs can't be built separately. To build the HOWTO collection,
invoke <command>make OUTPUT/howtos.<replaceable>format</replaceable></command>, where 'format' represents typical filename extensions (such as .html or .ps). If you leave ".<replaceable>format</replaceable>" unspecified, the chunked HTML version of the HOWTO collection will be built and, of course, saved to <filename>OUTPUT/howtos/</filename>.
</para>
</sect2>
<sect2>
<title>Symbols (pragmas, globvars, tags, ...)</title>
<para>
Symbols are a little different. The XMLDOCS system does an
investigation and discovers everything about all the symbols and types
(except for the last part of the prose text that a human needs to write).
</para>
<para>
So the procedure here is different: the system knows which symbols it
wants to document, all you have to do is put those bits of
human-information to places where xmldocs will look for.
</para>
<para>
To document a new symbol, run <command>bin/editem <replaceable>name</replaceable></command>. This will create skeleton files (<filename>refs/<replaceable>name</replaceable>/*</filename>) and load them all up in your editor. When you edit all files, the symbol will be documented.
</para>
<para>
After you've added a symbol, you need to regenerate the
<filename>refs/*.xml</filename> file(s) which
it affected: <command>rm tmp/refs-autogen; make tmp/refs-autogen</command>.
Then run the appropriate generator (like say, <command>make OUTPUT/globvars.html</command>) or the global build routine (<command>make distclean all</command>).
</para>
<para>
Note that the refentries can (and are) built in manpage format as well.
To generate the manpages, run <command>make OUTPUT/<replaceable>group</replaceable>.man</command>, where <literal>group</literal> is pragmas, globvars, usertags, systemtags, uitags... The output manpages will be placed to <filename class='directory'>OUTPUT/man/</filename>.
</para>
<para>
To modify an existing symbol, simply edit the appropriate files in <filename>refs/<replaceable>name</replaceable>/</filename>.
</para>
</sect2>
<sect2>
<title>Glossary</title>
<para>
To add a new glossary entry, create the <filename>glossary/<replaceable>name</replaceable></filename> file (copy the structure from <filename>glossary/pragma</filename>).
</para>
<para>
To modify an existing item, edit the appropriate <filename class='directory'>glossary/</filename> file.
</para>
<para>
To build the glossary source, run <command>make guides/glossary.xml</command>. To build the glossary output, run <command>make OUTPUT/glossary.<replaceable>format</replaceable>.</command>. Otherwise the glossary output would be autogenerated during the overall <command>make</command> procedure (it's source goes to <filename class='directory'>guides/</filename> where it is picked up automatically).
</para>
</sect2>
</sect1>
<sect1 id='FileFormats'>
<title>File Formats</title>
<para>
There are few different file types whose structure needs to be specified:
</para>
<sect2>
<title>Guides</title>
<para>
Guides use no pre-processing and are written in pure XML. There
is a simple "preprocessor" script I wrote in <filename>bin/pp</filename>,
but it's up to you to put the source through it and commit valid XML
to the CVS. For the usage examples and features, see script header.
(It comes handy when you're writing large portions of XML from scratch).
What you can use are, of course - just like in any other XML chunk,
the XML entities defined in <filename>docbook/docbookxi.dtd</filename>.
</para>
</sect2>
<sect2>
<title>HOWTOs</title>
<para>
HOWTOs do not use any preprocessing/autogenerating layer either, but
are included in the main <filename>howtos/howtos.xml</filename> file, so
the chunks you write must not be standalone. The parent element you need
to use is the XML's <chapter> tag, without any XML document type.
In it, you use valid XML and entities.
</para>
</sect2>
<sect2>
<title>Symbols</title>
<para>
Symbols are a little different. In general, the symbol refentry pages
already contain all the fields, you only need to provide contents for
them. To minimize overhead, fields have some default headers and footers
which you then must omit from your chunks.
</para>
<para>
You can also create more files that begin with the same name, and
are then appended to the section one after another. This is most suitable
for examples, so see <xref linkend='Example'/>.
</para>
<para>
In general, all files are handled generically and will be included
if you name them after the appropriate refentry page section that you want
to modify. Keep in mind that all files (other than the "strong"
<filename>control</filename> one) append instead of overriding existing
information.
</para>
<sect3>
<title>control</title>
<para>
The <filename>control</filename> file contains "key: value" pairs
on each line. Comments (#....) can be used at the beginning of the line.
Otherwise, 'value's are left-trimmed and then recorded <literal>verbatim
</literal>.
</para>
<para>
Note that the values in this file override (do not append!)
information already known to the generator script (if any).
</para>
<para>
"Keys" can be anything, but some of them have a special meaning (and
defining any others makes no sense except for future functionality),
and some of them must be specified because they have no useful
defaults:
<itemizedlist>
<listitem><para>
purpose: one-line description. No default, must be specified.
</para></listitem>
<listitem><para>
default: default value. This is symbol-dependent (it makes sense
with, for example, pragmas or global variables). For other symbols
(say, tags), this is unused.
</para></listitem>
<listitem><para>
missing: A free-form text that is appended to <filename>tmp/missing</filename> entry for a particular item. Good for a per-item TODO list and important notes. While <filename>tmp/missing</filename> is not empty, you must not feel bored :)
</para></listitem>
<listitem><para>
author: specific symbol's/feature's author. 3rd party people need a
name and email, such as Mirko Star <mstar at aol.com>;
ICDEVGROUP members are specified like "Davor Ocelic,
&ICDEVGROUP;", where the ICDEVGROUP entity expands to a suitable
string (full team name and link currently). If no author is
specified, the default shows the team name, not mentioning any
individual specifically.
</para></listitem>
<listitem><para>
ignore: Usually you specify it only if you want to ignore an item
(cause it not to be autogenerated and visible). "ignore: yes" works
fine.
</para></listitem>
<listitem><para>
see also: very powerful feature. List related symbol names, system
commands or other arbitrary items. Non-IC symbols listed get passed
as-is, IC symbols get rendered with a clickable link to the item
and the connection is automatically 2-way (if you mention "B" in
"A"'s See Also list, the B's list will automatically get A in its
see also list).
</para></listitem>
</itemizedlist>
</para>
</sect3>
<sect3>
<title>synopsis</title>
<para>
The <filename>synopsis</filename> file needs tyo contain complete
<cmdsynopsis> block. See the
<ulink url="http://www.docbook.org/tdg/en/html/cmdsynopsis.html">
docbook's cmdsynopsis element</ulink> for a complete description.
</para>
<para>
The synopsis must be provided, or the appropriate "missing"
entry appears in <filename>tmp/missing</filename>.
</para>
</sect3>
<sect3 id='Description'>
<title>description</title>
<para>
This file is meant to contain prose and is pre-wrapped in
the <para> tag. If, for the purpose of your description, you
need new paragraphs, simply use </para><para> to
separate them, but always omit the starting <para> and
ending </para>.
</para>
<para>
Note that this is only possible because our Perl scripts do the
merging before the source XML is passed to the XML tools; if XML
tools had to deal with this directly, you'd get a "chunk not balanced"
error and it wouldn't be possible.
</para>
<para>
The description must be provided, or the appropriate "missing"
entry appears in <filename>tmp/missing</filename>.
</para>
</sect3>
<sect3>
<title>notes</title>
<para>
Same as <xref linkend='Description'/>. May be left empty.
</para>
</sect3>
<sect3 id='Example'>
<title>example*</title>
<para>
The example files must contain an <example> element (which
usually contains the <title>, short <para> with description
and <programlisting> with the actual code or syntax to be shown).
</para>
<para>
It is possible (and welcomed) to have multiple example files. They will
all be added as separate examples, and their order in the documentation
will be dictated by their alphabetical order on the filesystem
(the order in which readdir() reads them). Simply name additional files
following the regex: /example[\-\.\+_:\d].*/.
</para>
<para>
At least one example must be provided, or the appropriate "missing"
entry appears in <filename>tmp/missing</filename>.
</para>
</sect3>
</sect2>
<sect2>
<title>Glossary</title>
<para>
The glossary skeleton is autogenerated. All you need to do is place
items in the <filename class='directory'>glossary/</filename>
directory. Each file there (filename is irrelevant) must contain a
valid <glossentry> element. See <filename>glossary/pragma</filename>
for an example.
</para>
</sect2>
</sect1>
<sect1 id='XMLGuidelines'>
<title>XML Guidelines</title>
<sect2 id='XMLConventions'>
<title>XML Conventions</title>
<para>
Although you will be writing valid XML, there are few conventions
on top of XML that would be very good to follow:
</para>
<itemizedlist>
<listitem><para>
Always provide <literal>id=''</literal> parameter to sections that
get built to separate files in chunked HTML mode (this includes
the top-level elements like <book>s and <article>s,
and first-level subelements, like <chapter>s and <sect1>s).
</para></listitem>
<listitem><para>
All <literal>id=''</literal>s you provide must be named after the
actual section title, with spaces condensed and first characters
capitalized. For example, "Introduction to Interchange" would become
<literal>id='IntroductiontoInterchange'</literal>.
</para></listitem>
<listitem><para>
Use built-in XML commands to link between sections and documents
where ever appropriate. If you're mentioning a resource for which
either a separate section or refentry exists in XMLDOCS (or is
completely external, such as a different website), please properly
mark that with XML.
</para></listitem>
<listitem><para>
If you have a longer phrase that keeps repeating every now and then
(and especially if it's also wrapped in some kind of a link element),
consider adding it as an XML entity to
<filename>docbook/docbookxi.dtd</filename> and then just refer to it
using the entity name; like you can write &IC; to produce &IC;.
</para></listitem>
<listitem><para>
When ever you are documenting a particular item and you think you need
to mention some other item's properties there, you're running into a
possible problem of spreading the documentation for a particular item
in many places which can go out of date.<sbr/>
So please avoid that, make all the details appear only once, and that
in the most appropriate place (which is, obviously, the original item
page).<sbr/>
Therefore, in such cases simply provide a link to the appropriate item
and describe its behavior or nuances there, on its own page (usually in
the general "Description" or "Notes" sections).
</para></listitem>
<listitem><para>
Always use spaces instead of TABs (2 spaces for 1 TAB) to indent
the text that will appear in the
generated output files (that includes sample external files and/or
code blocks that you directly include in the document). XML tolerates
TABs more or less, but doesn't like them. And it also causes problems
in fixed width outputs, like manpages.
</para></listitem>
<listitem><para>
For XML, you must write tags in all lowercase because there's no
other way, but please use only lowecase in HTML examples too, and
make the HTML code xhtml-compatible (in essence, the compatibility
comes down to using all lowercase, quoting all option arguments,
and closing all tags; i.e.: <img src="..path.."/>)
</para></listitem>
</itemizedlist>
</sect2>
<sect2>
<title>Useful XML Tags</title>
<para>
I have identified some of the most useful tags that we'll be using
in XMLDOCS:
</para>
<para>
<ulink url="http://www.docbook.org/tdg/en/html/acronym.html">acronym</ulink><sbr/>
<ulink url="http://www.docbook.org/tdg/en/html/application.html">application</ulink> - software program name<sbr/>
<ulink url="http://www.docbook.org/tdg/en/html/arg.html">arg</ulink> - part of the cmdsynopsis element<sbr/>
<ulink url="http://www.docbook.org/tdg/en/html/blockquote.html">blockquote</ulink><sbr/>
<ulink url="http://www.docbook.org/tdg/en/html/cmdsynopsis.html">cmdsynopsis</ulink> - the parent element for all synopsis lines<sbr/>
<ulink url="http://www.docbook.org/tdg/en/html/code.html">code</ulink> - chunks of actual code. Use to display ITL/Perl/any-other code examples inline<sbr/>
<ulink url="http://www.docbook.org/tdg/en/html/command.html">command</ulink> - computer command name (usually Unix command)<sbr/>
<ulink url="http://www.docbook.org/tdg/en/html/computeroutput.html">computeroutput</ulink><sbr/>
<ulink url="http://www.docbook.org/tdg/en/html/constant.html">constant</ulink><sbr/>
<ulink url="http://www.docbook.org/tdg/en/html/database.html">database</ulink> - everything related to a database. See class='' option to it<sbr/>
<ulink url="http://www.docbook.org/tdg/en/html/emphasis.html">emphasis</ulink> - renders as italic text<sbr/>
<ulink url="http://www.docbook.org/tdg/en/html/envar.html">envar</ulink> - environment variable, such as REMOTE_PORT<sbr/>
<ulink url="http://www.docbook.org/tdg/en/html/errorcode.html">errorcode</ulink><sbr/>
<ulink url="http://www.docbook.org/tdg/en/html/errorname.html">errorname</ulink><sbr/>
<ulink url="http://www.docbook.org/tdg/en/html/errortext.html">errortext</ulink> - such as "Page not found"<sbr/>
<ulink url="http://www.docbook.org/tdg/en/html/errortype.html">errortype</ulink><sbr/>
<ulink url="http://www.docbook.org/tdg/en/html/example.html">example</ulink> - parent element for all examples<sbr/>
<ulink url="http://www.docbook.org/tdg/en/html/filename.html">filename</ulink> - file and directory (class='directory') names<sbr/>
<ulink url="http://www.docbook.org/tdg/en/html/firstterm.html">firstterm</ulink> - first occurence of a term. Renders as italic<sbr/>
<ulink url="http://www.docbook.org/tdg/en/html/footnote.html">footnote</ulink><sbr/>
<ulink url="http://www.docbook.org/tdg/en/html/function.html">function</ulink> - function name, such as syscall64()<sbr/>
<ulink url="http://www.docbook.org/tdg/en/html/group.html">group</ulink> - grouping of args inside cmdsynopsis<sbr/>
<ulink url="http://www.docbook.org/tdg/en/html/guibutton.html">guibutton</ulink> - identify buttons in the (web) gui, such as <guibutton>Finalize!</guibutton><sbr/>
<ulink url="http://www.docbook.org/tdg/en/html/guiicon.html">guiicon</ulink><sbr/>
<ulink url="http://www.docbook.org/tdg/en/html/guilabel.html">guilabel</ulink><sbr/>
<ulink url="http://www.docbook.org/tdg/en/html/guimenu.html">guimenu</ulink><sbr/>
<ulink url="http://www.docbook.org/tdg/en/html/guimenuitem.html">guimenu</ulink><sbr/>
<ulink url="http://www.docbook.org/tdg/en/html/guisubmenu.html">guisubmenu</ulink><sbr/>
<ulink url="http://www.docbook.org/tdg/en/html/hardware.html">hardware</ulink> - piece of hardware<sbr/>
<ulink url="http://www.docbook.org/tdg/en/html/important.html">important</ulink><sbr/>
<ulink url="http://www.docbook.org/tdg/en/html/itemizedlist.html">itemizedlist</ulink> - most commonly used type of list<sbr/>
<ulink url="http://www.docbook.org/tdg/en/html/keysym.html">keysym</ulink><sbr/>
<ulink url="http://www.docbook.org/tdg/en/html/keyword.html">keyword</ulink> - identifies a word as important for the document categorization/search<sbr/>
<ulink url="http://www.docbook.org/tdg/en/html/link.html">link</ulink><sbr/>
<ulink url="http://www.docbook.org/tdg/en/html/listitem.html">listitem</ulink> - element inside itemizedlist<sbr/>
<ulink url="http://www.docbook.org/tdg/en/html/literal.html">literal</ulink> - literal (verbatim) value, such as <literal>standard keep</literal><sbr/>
mv - identify form variable, such as <mv>mv_return_all</mv> (XMLDOCS extension to DocBook XML)<sbr/>
<ulink url="http://www.docbook.org/tdg/en/html/note.html">note</ulink><sbr/>
<ulink url="http://www.docbook.org/tdg/en/html/olink.html">olink</ulink><sbr/>
<ulink url="http://www.docbook.org/tdg/en/html/option.html">option</ulink> - use it to mark Interchange config directives (like say, MailOrderTo or Variable)<sbr/>
<ulink url="http://www.docbook.org/tdg/en/html/para.html">para</ulink> - the standard paragraph element<sbr/>
pragma - Interchange pragma name (XMLDOCS extension to DocBook XML)<sbr/>
<ulink url="http://www.docbook.org/tdg/en/html/programlisting.html">programlisting</ulink><sbr/>
<ulink url="http://www.docbook.org/tdg/en/html/prompt.html">prompt</ulink> - computer prompt, such as Login:<sbr/>
<ulink url="http://www.docbook.org/tdg/en/html/replaceable.html">replaceable</ulink> - identified the replaceable part in the cmdsynopsis element<sbr/>
<ulink url="http://www.docbook.org/tdg/en/html/returnvalue.html">returnvalue</ulink><sbr/>
<ulink url="http://www.docbook.org/tdg/en/html/sbr.html">sbr</ulink> - starts a newline. Useful in cmdsynopsis or if you don't want to split the paragraph in two, which then generates a wide spacing<sbr/>
<ulink url="http://www.docbook.org/tdg/en/html/screen.html">screen</ulink> - used as element in which you display existing interchange source (this is mostly in autogenerated pages but can be used manually)<sbr/>
<ulink url="http://www.docbook.org/tdg/en/html/subscript.html">subscript</ulink><sbr/>
<ulink url="http://www.docbook.org/tdg/en/html/superscript.html">superscript</ulink><sbr/>
<ulink url="http://www.docbook.org/tdg/en/html/systemitem.html">systemitem</ulink> - various system items, see possible class='' values<sbr/>
tag - Interchange tag name (XMLDOCS extension to DocBook XML)<sbr/>
<ulink url="http://www.docbook.org/tdg/en/html/term.html">term</ulink><sbr/>
<ulink url="http://www.docbook.org/tdg/en/html/tip.html">tip</ulink><sbr/>
<ulink url="http://www.docbook.org/tdg/en/html/ulink.html">ulink</ulink><sbr/>
<ulink url="http://www.docbook.org/tdg/en/html/userinput.html">userinput</ulink> - similar to <command> but here you can also include parameters, actually the complete command line the user would run<sbr/>
<ulink url="http://www.docbook.org/tdg/en/html/varname.html">varname</ulink> - variable name, such as MV_PAGE<sbr/>
<ulink url="http://www.docbook.org/tdg/en/html/warning.html">warning</ulink><sbr/>
<ulink url="http://www.docbook.org/tdg/en/html/wordasword.html">wordasword</ulink><sbr/>
<ulink url="http://www.docbook.org/tdg/en/html/xref.html">xref</ulink><sbr/>
</para>
</sect2>
</sect1>
<sect1>
<title>Conclusion</title>
<para>
I believe I have succeeded in making XMLDOCS fairly convenient to author
new documents and keep them current with time.
</para>
<para>
If we want to make &IC; recognized globally (for which it definitely
has the perspective, but it's not there just yet), then having a complete,
up to date, clear and verbose documentation set is something that's
almost implied.
</para>
<para>
It would be best if all developers would write both the pieces of
software and the accompanying documentation. However,
from the past I have somehow seen that you are not too willing
to write the documentation (or that was because of all the problems with
the old documentation system).
</para>
<para>
So, the bottom line is that I really want you to write the documentation,
but I will not impose any requirements on the structure. That means
you can:
</para>
<itemizedlist>
<listitem><para>
Update the existing files with proper tagging (XML or whatever is
the document's format), or
</para></listitem>
<listitem><para>
Update the existing files <emphasis>without</emphasis> properly tagging
everything. I will be monitoring all commits and I am willing to fix
all the formatting if you're willing to write the docs in the first
place. Or,
</para></listitem>
<listitem><para>
Provide verbose commit messages <emphasis>and state that you will
not</emphasis> update the documentation, so me or Racke will reformat
it properly and commit it to XMLDOCS, or
</para></listitem>
<listitem><para>
You can write completely unformated text without even using XML and
commit it somewhere in the
<filename class='directory'>pending/</filename> directory. Me or Racke
would pick it up and properly update the docs. Just please include
enough information (be as verbose as possible), so that we have enough
words we can rephrase and enough information to work on.
</para></listitem>
</itemizedlist>
</sect1>
</article>
More information about the docs
mailing list