From 2e3c73e0883a2bdfa525fc6fe4e10d30971d9651 Mon Sep 17 00:00:00 2001 From: reinelt <> Date: Wed, 2 Jun 2004 05:28:06 +0000 Subject: [lcd4linux @ 2004-06-02 05:27:59 by reinelt] added documentation tree --- documentation/lcd4linux/write_doc.xml | 102 ++++++++++++++++++++++++++++++++++ 1 file changed, 102 insertions(+) create mode 100644 documentation/lcd4linux/write_doc.xml (limited to 'documentation/lcd4linux/write_doc.xml') diff --git a/documentation/lcd4linux/write_doc.xml b/documentation/lcd4linux/write_doc.xml new file mode 100644 index 0000000..b8d243d --- /dev/null +++ b/documentation/lcd4linux/write_doc.xml @@ -0,0 +1,102 @@ + + + + + + How to write documentation for &l4l; ? + write_doc + + + +

Overview

+

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.

+

The whole documentation is generated through a make system, which uses xmllint to check the validy of the xml files and xsltproc to process them and generate the XHTML pages. These two programs are mandatory

+ +

The syntax

+A doc page looks like this : +<?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> + + +
  • The three first lines are the preambule of the file, don't touch them.
    • +
  • The root of the document is <doc>, it's the equivalent of <html>.
    • +
  • Then, there's a <head> node, containing the information about the page. See later for the childs.
    • +
  • The core of the doc is the <body> node, like in HTML, containing the content.
    • + +

    The <head>

    +The head contains some information about the document : +
  • <title> is the title of the document, which will be displayed as a <h1>
    • +
  • <ref> is a unique reference for the document, which is assumed to be the same as in references.xml (we'll discuss later about this file)
    • +
  • <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.
    • +
  • There may be other elements, but we'll only use these ones for now.
    • + +

    The helpers

    +You can use a lot of helpers in the body : +
  • <link> is a helper to create links. It is used with one of these two arguments : + +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 <link url="http://...">TEXT</link> +
    • +As this is XML, you must close all the tags you open, or use self-closing tags for empty ones :
    For example, you have to write <br/> but not <br>.     + +
  • <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/>, But beware of < and > (you must replace them with &lt; and &gt;)
    • +xav:~$ echo "An example of <cmd> box" +An example of <cmd> box +xav:~$ + +
  • <conf> works like <cmd> but with black text on grey background, to print lcd4linux.conf examples.
    • +Widget Lightning { + class 'icon' + speed 100 + visible cpu('busy', 500)-50 + bitmap { + row1 '...***' + row2 '..***.' + row3 '.***..' + row4 '.****.' + row5 '..**..' + row6 '.**...' + row7 '**....' + row8 '*.....' + } +} +
  • <note> is to display a box with a small icon, to point out a detail, or an advice
    • +To dry a wet cat, don't put it in a microwave ;) +
  • <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 ;)
    • +We're not responsible for damages caused to your microwave if you don't read the above note ! +
  • <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.
    • +
  • <new> is in the DTD, but is not yet implemented :/
    • +
  • You can use any other XHTML-valid tag. The most used should be : <br/> <h2> <h3> <li> <b> <i> <tt> ...
    • + +

    references.xml

    +There's a file in data/ called references.xml. 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.
    +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. +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) + +

    The compilation system

    +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, lcd4linux, drivers and plugins). In these subdirs, the Makefile is a link to Makefile.generic.
    +To compile the documentation, just type make at the toplevel, and look in the HTML folder. Type make help for help ;) +Two programs are mandatory to build the documentation : + + + +     -- cgit v1.2.3