+
+ 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 :
+
+- <link ref="xxx"/> will create a link to the documentation page associated with this reference (defined in references.xml)
+- <link url="http://..."/> will create a link to the url
+
+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 or <br/>, But beware of < and > (you must replace them with < and >)
+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 :
+- xmllint from libxml2 is used to validate the xml pages to be processed. It's in the debian package libxml2
+- xsltproc from libxslt processes the xml files to generate the html pages. It's in the libxslt tarballs or in the xsltproc debian package
+
+
+
diff --git a/documentation/plugins/Makefile b/documentation/plugins/Makefile
new file mode 100644
index 0000000..2519f22
--- /dev/null
+++ b/documentation/plugins/Makefile
@@ -0,0 +1,59 @@
+# Path
+DIR = $(notdir $(PWD))
+OUTPUT = ../HTML
+
+ifeq "$(DIR)" "lcd4linux"
+ DIR =
+endif
+
+ifeq "$(DIR)" ""
+ XSLTPROC = xsltproc
+else
+ XSLTPROC = xsltproc --stringparam class $(DIR) --stringparam root "../"
+endif
+
+XMLVALID = xmllint --noout --valid
+
+NAMES=$(shell find . -name "*.xml" -exec basename {} .xml \;)
+
+html: $(patsubst %.xml,%.html,$(wildcard *.xml))
+html-forced: $(patsubst %.xml,%.html-forced,$(wildcard *.xml))
+
+%.html: %.xml %.xml-check output
+ $(XSLTPROC) $< > $(OUTPUT)/$(DIR)/$@
+
+%.html-forced: %.xml output
+ $(XSLTPROC) $< > $(OUTPUT)/$(DIR)/$(patsubst %.xml,%.html,$<)
+
+check: $(patsubst %.xml, %.xml-check, $(wildcard *.xml))
+
+%.xml-check: %.xml
+ @echo "*** Validation of $<"
+ $(XMLVALID) $<
+
+output:
+ test -d $(OUTPUT) || `mkdir $(OUTPUT); cp ../data/doc.css $(OUTPUT); cp -R ../data/images $(OUTPUT)`
+ test -d $(OUTPUT)/$(DIR) || mkdir $(OUTPUT)/$(DIR)
+
+clean:
+ rm -f $(OUTPUT)/$(DIR)/*.html
+
+clean-bak:
+ rm -f *~ *.bak
+
+help:
+ @echo -e ""
+ @echo -e "Usage :"
+ @echo -e "-------"
+ @echo -e "make or make html : builds all possible html pages from xml files"
+ @echo -e "make %.html : builds the %.html page from %.xml"
+ @echo -e ""
+ @echo -e "make html-forced : builds all possible html pages from xml files (no validity check)"
+ @echo -e "make %.html-forced : builds the %.html page from %.xml (no validity check)"
+ @echo -e ""
+ @echo -e "make check : checks the validity of all possible xml files"
+ @echo -e "make %.xml-check : checks the validity of %.xml"
+ @echo -e ""
+ @echo -e "make clean : deletes all generated html pages"
+ @echo -e "make clean-bak : deletes *~ and *.bak files"
+ @echo -e ""
diff --git a/documentation/plugins/index.xml b/documentation/plugins/index.xml
new file mode 100644
index 0000000..8e803ae
--- /dev/null
+++ b/documentation/plugins/index.xml
@@ -0,0 +1,14 @@
+
+
+
+