<?xml version="1.0" encoding="UTF-8" standalone="no" ?> <?xml-stylesheet type="text/xsl" href="../xsl/doc.xsl"?> <!DOCTYPE doc SYSTEM "../dtd/doc.dtd"> <doc> <head> <title>How to write documentation for &l4l; ?</title> <ref>write_doc</ref> <!-- <links> <link ref="i2c_sensors"/> </links>--> </head> <body> <h2>Overview</h2> <p>The &l4l; documentation is composed of XML files which are processed with XSL stylesheets to produce XHTML files. There these XML files are writen in a syntax similar to the HTML syntax, plus some helpers.</p> <p>The whole documentation is generated through a make system, which uses <tt>xmllint</tt> to check the validy of the xml files and <tt>xsltproc</tt> to process them and generate the XHTML pages. <i>These two programs are mandatory</i></p> <h2>The syntax</h2> A doc page looks like this : <conf><?xml version="1.0" encoding="UTF-8" standalone="no" ?> <?xml-stylesheet type="text/xsl" href="../xsl/doc.xsl"?> <!DOCTYPE doc SYSTEM "../dtd/doc.dtd"> <doc> <head> <title>How to write documentation for &l4l; ?</title> <ref>write_doc</ref> <links> <link ref="http://lcd4linux.sf.net"/> </links> </head> <body> ... </body> </doc> </conf> <li>The three first lines are the preambule of the file, don't touch them.</li> <li>The root of the document is <tt><doc></tt>, it's the equivalent of <html>.</li> <li>Then, there's a <tt><head></tt> node, containing the information about the page. See later for the childs.</li> <li>The core of the doc is the <body> node, like in HTML, containing the content.</li> <h3>The <head></h3> The head contains some information about the document : <li><title> is the title of the document, which will be displayed as a <h1></li> <li><ref> is a unique reference for the document, which is assumed to be the same as in <i>references.xml</i> (we'll discuss later about this file)</li> <li><links> is the section responsible of the "See Alo" box, containing links to other help pages, or to urls. It can contain several <link> elements, whose syntax is explained in the next part.</li> <li>There may be other elements, but we'll only use these ones for now.</li> <h3>The helpers</h3> You can use a lot of helpers in the body : <li><link> is a helper to create links. It is used with one of these two arguments : <ul> <li><tt><link ref="xxx"/></tt> will create a link to the documentation page associated with this reference (defined in <i>references.xml</i>)</li> <li><tt><link url="http://..."/></tt> will create a link to the url</li> </ul> Note that if you don't provide a text, the text of the link will be the label of the reference or the url. You can specify a text writing <tt><link url="http://...">TEXT</link></tt> </li> <warn>As this is XML, you <b>must</b> close all the tags you open, or use self-closing tags for empty ones :<br/>For example, you have to write <tt><br/></tt> but not <tt><br>.</tt></warn> <li><cmd> Opens a box with write text on black background, used to indicate something's happening in a console (compilation, logs, ...). The text is in "pre" mode, so spaces and newlines are kept, no need of &nbsp; or <br/>, <b>But beware of < and ></b> (you must replace them with &lt; and &gt;)</li> <cmd>xav:~$ echo "An example of <cmd> box" An example of <cmd> box xav:~$ </cmd> <li><conf> works like <cmd> but with black text on grey background, to print lcd4linux.conf examples.</li> <conf>Widget Lightning { class 'icon' speed 100 visible cpu('busy', 500)-50 bitmap { row1 '...***' row2 '..***.' row3 '.***..' row4 '.****.' row5 '..**..' row6 '.**...' row7 '**....' row8 '*.....' } }</conf> <li><note> is to display a box with a small icon, to point out a detail, or an advice</li> <note>To dry a wet cat, don't put it in a microwave ;)</note> <li><warn> works like <note> but with a red exclamation mark and a red border, to display warnings. In general, use a note for a detail or an advice and warn to point configuration problems, hardware hazards, or other happy things ;)</li> <warn>We're not responsible for damages caused to your microwave if you don't read the above note !</warn> <li><index> is a cool thing. It displays the list of pages of a specified class. It's used to display indexes. For example <index class="drivers"/> will display a list of all pages about drivers. If there's no class specified, it'll parse the list of pages of the "lcd4linux" class.</li> <li><new> is in the DTD, but is not yet implemented :/</li> <li>You can use any other XHTML-valid tag. The most used should be : <br/> <h2> <h3> <li> <b> <i> <tt> ...</li> <h3>references.xml</h3> There's a file in <tt>data/</tt> called <tt>references.xml</tt>. It isn't processed directly, but is used to parse links and indexes. It's syntax is quite straightforward, so I won't explain it.<br/> You must add a new entry in it for each page you write so that other pages can have links to it and index it. <note>A null <class/> attribute corresponds to the lcd4linux class. It's not a bug, it's a feature, used to make links (the lcd4linux class is in the root of the documentation)</note> <h2>The compilation system</h2> The documentation is compiled with a Makefile build system. There's a toplevel Makefile which calls the apropriate targets in each subdirs which contains xml files (for the moment, <tt>lcd4linux</tt>, <tt>drivers</tt> and <tt>plugins</tt>). In these subdirs, the Makefile is a link to <tt>Makefile.generic</tt>.<br/> To compile the documentation, just type make at the toplevel, and look in the <tt>HTML</tt> folder. Type make help for help ;) <warn>Two programs are mandatory to build the documentation : <ul><li><tt>xmllint</tt> from libxml2 is used to validate the xml pages to be processed. It's in the debian package <tt>libxml2</tt></li> <li><tt>xsltproc</tt> from libxslt processes the xml files to generate the html pages. It's in the libxslt tarballs or in the <tt>xsltproc</tt> debian package</li></ul> </warn> </body> </doc>