mirror of
https://github.com/netfun2000/lcd4linux.git
synced 2026-02-27 09:44:34 +08:00
[lcd4linux @ 2004-06-02 05:27:59 by reinelt]
added documentation tree git-svn-id: https://ssl.bulix.org/svn/lcd4linux/trunk@458 3ae390bd-cb1e-0410-b409-cd5a39f66f1f
This commit is contained in:
reinelt
59
documentation/lcd4linux/Makefile
Normal file
59
documentation/lcd4linux/Makefile
Normal file
@@ -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 ""
|
||||
32
documentation/lcd4linux/bug_report.xml
Normal file
32
documentation/lcd4linux/bug_report.xml
Normal file
@@ -0,0 +1,32 @@
|
||||
<?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 report bugs or get support</title>
|
||||
<ref>bug_report</ref>
|
||||
<links>
|
||||
<link ref="contact"/>
|
||||
</links>
|
||||
</head>
|
||||
<body>
|
||||
You've checked twice your configuration, but &l4l; keeps complaining, prints horrible things on your display or even crashes. What to do ?
|
||||
|
||||
<h2>Configuration problems and minor bugs</h2>
|
||||
<ul>
|
||||
<li>Your display doesn't want to work, prints strange things or keeps blank ?</li>
|
||||
<li>You can't get a plugin to work, there are ???? or **** where you wanted to display the temperature ?</li>
|
||||
<li>You noticed a strange behavior from &l4l; or a plugin ?</li>
|
||||
</ul>
|
||||
You should contact the lcd4linux-users maillist, and post a detailled report containing at least :
|
||||
<ul>
|
||||
<li>the &l4l; version you use.</li>
|
||||
<li>a description of what happens</li>
|
||||
<li>if relevant, a description of your display (especially for HD44780-based displays)</li>
|
||||
<li>a log of &l4l; output ( <tt>lcd4linux -vvv > log</tt> )</li>
|
||||
<li>a copy of your lcd4linux.conf file</li>
|
||||
</ul>
|
||||
<note>If you use some plugins (mysql, mail, ...), lcd4linux.conf may contain passwords and other private information. For your privacy, we recommend you to replace these information with ***** before attaching your configuration file</note>
|
||||
|
||||
</body>
|
||||
</doc>
|
||||
50
documentation/lcd4linux/example.xml
Normal file
50
documentation/lcd4linux/example.xml
Normal file
@@ -0,0 +1,50 @@
|
||||
<?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>The title of the page The title of the page</title>
|
||||
<version>0.1</version>
|
||||
<ref>doc_example</ref>
|
||||
<links>
|
||||
<link ref="i2c_sensors"/>
|
||||
<link url="http://lcd4linux.sf.net"/>
|
||||
<link url="http://lcd4linux.sf.net">SourceForge</link>
|
||||
</links>
|
||||
<history>
|
||||
<revision version="0.1" by="Xavier">
|
||||
The first, and only version ever ;)
|
||||
</revision>
|
||||
<revision version="0.0" by="Xavier">
|
||||
TEST
|
||||
</revision>
|
||||
</history>
|
||||
<state finished="true" proofread="true"/>
|
||||
</head>
|
||||
<body>
|
||||
<h2>This is the text of the page, we can use xhtml tags here and there are some helpers : </h2>
|
||||
<cmd><cmd> Will be used to indicate <tt>console commands</tt>, or other things</cmd>
|
||||
<conf><conf> Is to format lcd4linux.conf examples</conf>
|
||||
<note><note> Will display a div with the message, to add a tip, or an explanation</note>
|
||||
<warn><warn> Will work just as <note>, but for more important messages</warn>
|
||||
<new date="01/01/01" title="test new"><new> is to display boxes with news, for the main page or, as an example for displays/plugins pages to show news in the features</new> <br />
|
||||
|
||||
<link ref="plugin_i2c_sensors"/>
|
||||
|
||||
There will be other helpers : <image>, <link>, <table> ...<br />
|
||||
|
||||
If you look at the sources of this page, there are a lot of information in the head. They will be used for internal processing, and some will be displayed (for example <links> will define links to be put in a 'See also' box, with links to related articles, websites, ...<br />
|
||||
|
||||
We'll use 'standard' xhtml tags <br /> <b><b></b> <i><i></i> <tt><tt></tt> <small><small></small> <big><big></big> and others, not really proceced by xslt.
|
||||
<h2><h2></h2> <h3><h3></h3> <h4><h4></h4> <h5><h5></h5> <h6><h6></h6>
|
||||
|
||||
<h2>test</h2>
|
||||
<h3>one</h3>
|
||||
<h3>two</h3>
|
||||
<h3>three</h3>
|
||||
<h2>AAAA</h2>
|
||||
<h3>one</h3>
|
||||
<h3>two</h3>
|
||||
<h3>three</h3>
|
||||
</body>
|
||||
</doc>
|
||||
17
documentation/lcd4linux/index.xml
Normal file
17
documentation/lcd4linux/index.xml
Normal file
@@ -0,0 +1,17 @@
|
||||
<?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>&L4L; documentation index</title>
|
||||
<ref>index</ref>
|
||||
</head>
|
||||
<body>
|
||||
<h2>&L4L;</h2>
|
||||
<index/>
|
||||
<h2><a href="drivers/index.html">Drivers</a></h2>
|
||||
<index class="drivers"/>
|
||||
<h2><a href="plugins/index.html">Plugins</a></h2>
|
||||
<index class="plugins"/>
|
||||
</body>
|
||||
</doc>
|
||||
102
documentation/lcd4linux/write_doc.xml
Normal file
102
documentation/lcd4linux/write_doc.xml
Normal file
@@ -0,0 +1,102 @@
|
||||
<?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>
|
||||
Reference in New Issue
Block a user