[docs] xmldocs - docelic modified 4 files
docs at icdevgroup.org
docs at icdevgroup.org
Sat Oct 23 12:38:30 EDT 2004
User: docelic
Date: 2004-10-23 16:38:30 GMT
Modified: . Makefile TODO
Modified: docbook autodefs.ent
Modified: guides xmldocs.xml
Log:
- guides/xmldocs.xml: Update completely for up-to-dateness
- Makefile: add dependency
- TODO: mention upcoming problems
Revision Changes Path
1.33 +3 -1 xmldocs/Makefile
rev 1.33, prev_rev 1.32
Index: Makefile
===================================================================
RCS file: /var/cvs/xmldocs/Makefile,v
retrieving revision 1.32
retrieving revision 1.33
diff -u -r1.32 -r1.33
--- Makefile 18 Oct 2004 14:58:51 -0000 1.32
+++ Makefile 23 Oct 2004 16:38:29 -0000 1.33
@@ -178,7 +178,9 @@
refs/%.xml: BNAME = $(subst refs/,,$@)
$T/%.list: FNAME = $(subst .list,,$(BNAME))
refs/%.xml: FNAME = $(subst .xml,,$(BNAME))
-$T/%.list refs/%.xml: $(foreach icver,$(IC_VERSIONS),cache/$(icver)/.cache.bin) bin/refs-autogen
+# A little 'overwork' here: we reegenerate all .xml files even if just
+# one file changes.
+$T/%.list refs/%.xml: $(foreach icver,$(IC_VERSIONS),cache/$(icver)/.cache.bin) $(shell find refs/ -regex '.+[^(\.xml)]$$') bin/refs-autogen
# PEH, -g is useless since tags migrate between tag groups
#bin/refs-autogen -g $(FNAME) -o $@ $(BOTH) $(IC_VERSIONS)
bin/refs-autogen -o $@ $(BOTH) $(IC_VERSIONS)
1.40 +4 -0 xmldocs/TODO
rev 1.40, prev_rev 1.39
Index: TODO
===================================================================
RCS file: /var/cvs/xmldocs/TODO,v
retrieving revision 1.39
retrieving revision 1.40
diff -u -r1.39 -r1.40
--- TODO 20 Oct 2004 15:44:35 -0000 1.39
+++ TODO 23 Oct 2004 16:38:29 -0000 1.40
@@ -11,6 +11,10 @@
- ./files/ directory is not properly referenced from chunked documents.
Solve by using entities?
+- It's now obvious that multiple symbols will have the same names. This
+ calls for renaming every refs/* file to refs/*.<symbolType> (and all
+ other changes following from that).
+
- In iccattut:
- make a "translation map" of /etc/interchange/* to RPM-equivs.
- item for package names, like interchange-cat-foundation, wenglish, etc..
1.4 +20 -73 xmldocs/docbook/autodefs.ent
rev 1.4, prev_rev 1.3
Index: autodefs.ent
===================================================================
RCS file: /var/cvs/xmldocs/docbook/autodefs.ent,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- autodefs.ent 20 Oct 2004 21:17:41 -0000 1.3
+++ autodefs.ent 23 Oct 2004 16:38:30 -0000 1.4
@@ -7,79 +7,23 @@
<!ENTITY convert_date "<filter>convert_date</filter>">
<!ENTITY md5 "<filter>md5</filter>">
<!ENTITY line "<filter>line</filter>">
-<!ENTITY urlencode "<filter>urlencode</filter>">
-<!ENTITY gate "<filter>gate</filter>">
-<!ENTITY last_non_null "<filter>last_non_null</filter>">
-<!ENTITY mac "<filter>mac</filter>">
-<!ENTITY nullselect "<filter>nullselect</filter>">
-<!ENTITY alphanumeric "<filter>alphanumeric</filter>">
-<!ENTITY name "<filter>name</filter>">
-<!ENTITY option_format "<filter>option_format</filter>">
-<!ENTITY urldecode "<filter>urldecode</filter>">
-<!ENTITY pgbool "<filter>pgbool</filter>">
-<!ENTITY small "<filter>small</filter>">
-<!ENTITY zerofix "<filter>zerofix</filter>">
-<!ENTITY colons_to_null "<filter>colons_to_null</filter>">
-<!ENTITY null_to_space "<filter>null_to_space</filter>">
-<!ENTITY alpha "<filter>alpha</filter>">
-<!ENTITY html2text "<filter>html2text</filter>">
-<!ENTITY options2line "<filter>options2line</filter>">
-<!ENTITY uc "<filter>uc</filter>">
-<!ENTITY textarea_get "<filter>textarea_get</filter>">
-<!ENTITY null_to_comma "<filter>null_to_comma</filter>">
-<!ENTITY bold "<filter>bold</filter>">
-<!ENTITY tabbed "<filter>tabbed</filter>">
-<!ENTITY textarea_put "<filter>textarea_put</filter>">
-<!ENTITY large "<filter>large</filter>">
-<!ENTITY lookup "<filter>lookup</filter>">
-<!ENTITY commify "<filter>commify</filter>">
-<!ENTITY dos "<filter>dos</filter>">
-<!ENTITY namecase "<filter>namecase</filter>">
-<!ENTITY checkbox "<filter>checkbox</filter>">
-<!ENTITY digits_dot "<filter>digits_dot</filter>">
-<!ENTITY tt "<filter>tt</filter>">
-<!ENTITY filesafe "<filter>filesafe</filter>">
-<!ENTITY integer "<filter>integer</filter>">
-<!ENTITY pagefile "<filter>pagefile</filter>">
-<!ENTITY strftime "<filter>strftime</filter>">
-<!ENTITY encode_entities "<filter>encode_entities</filter>">
-<!ENTITY mailto "<filter>mailto</filter>">
-<!ENTITY line2options "<filter>line2options</filter>">
-<!ENTITY compress_space "<filter>compress_space</filter>">
-<!ENTITY space_to_null "<filter>space_to_null</filter>">
-<!ENTITY word "<filter>word</filter>">
-<!ENTITY decode_entities "<filter>decode_entities</filter>">
-<!ENTITY show_null "<filter>show_null</filter>">
-<!ENTITY date_change "<filter>date_change</filter>">
-<!ENTITY backslash "<filter>backslash</filter>">
-<!ENTITY pre "<filter>pre</filter>">
-<!ENTITY no_white "<filter>no_white</filter>">
-<!ENTITY strikeout "<filter>strikeout</filter>">
-<!ENTITY restrict_html "<filter>restrict_html</filter>">
-<!ENTITY upload "<filter>upload</filter>">
-<!ENTITY text2html "<filter>text2html</filter>">
-<!ENTITY digits "<filter>digits</filter>">
-<!ENTITY yesno "<filter>yesno</filter>">
-<!ENTITY unix "<filter>unix</filter>">
-<!ENTITY pgbooln "<filter>pgbooln</filter>">
-<!ENTITY mime_type "<filter>mime_type</filter>">
-<!ENTITY calculated "<filter>calculated</filter>">
-<!ENTITY italics "<filter>italics</filter>">
-<!ENTITY null_to_colons "<filter>null_to_colons</filter>">
<!ENTITY set-cookie "<tag>set-cookie</tag>">
<!ENTITY tree "<tag>tree</tag>">
-<!ENTITY subtotal "<tag>subtotal</tag>">
<!ENTITY file "<tag>file</tag>">
<!ENTITY read-cookie "<tag>read-cookie</tag>">
+<!ENTITY subtotal "<tag>subtotal</tag>">
<!ENTITY uc-attr-list "<tag>uc-attr-list</tag>">
<!ENTITY tmp "<tag>tmp</tag>">
<!ENTITY loop "<tag>loop</tag>">
+<!ENTITY strip "<tag>strip</tag>">
<!ENTITY row "<tag>row</tag>">
<!ENTITY shipping "<tag>shipping</tag>">
<!ENTITY warnings "<tag>warnings</tag>">
<!ENTITY soap_entity "<tag>soap_entity</tag>">
-<!ENTITY setlocale "<tag>setlocale</tag>">
+<!ENTITY sql "<tag>sql</tag>">
<!ENTITY input-filter "<tag>input-filter</tag>">
+<!ENTITY setlocale "<tag>setlocale</tag>">
+<!ENTITY cgi "<tag>cgi</tag>">
<!ENTITY deliver "<tag>deliver</tag>">
<!ENTITY region "<tag>region</tag>">
<!ENTITY accessories "<tag>accessories</tag>">
@@ -94,9 +38,10 @@
<!ENTITY fly-list "<tag>fly-list</tag>">
<!ENTITY options "<tag>options</tag>">
<!ENTITY area "<tag>area</tag>">
-<!ENTITY time "<tag>time</tag>">
<!ENTITY harness "<tag>harness</tag>">
+<!ENTITY time "<tag>time</tag>">
<!ENTITY unpack "<tag>unpack</tag>">
+<!ENTITY currency "<tag>currency</tag>">
<!ENTITY error "<tag>error</tag>">
<!ENTITY set "<tag>set</tag>">
<!ENTITY banner "<tag>banner</tag>">
@@ -115,8 +60,8 @@
<!ENTITY attr-list "<tag>attr-list</tag>">
<!ENTITY update "<tag>update</tag>">
<!ENTITY profile "<tag>profile</tag>">
-<!ENTITY tmpn "<tag>tmpn</tag>">
<!ENTITY page "<tag>page</tag>">
+<!ENTITY tmpn "<tag>tmpn</tag>">
<!ENTITY flag "<tag>flag</tag>">
<!ENTITY shipping-desc "<tag>shipping-desc</tag>">
<!ENTITY record "<tag>record</tag>">
@@ -127,13 +72,14 @@
<!ENTITY field "<tag>field</tag>">
<!ENTITY calcn "<tag>calcn</tag>">
<!ENTITY salestax "<tag>salestax</tag>">
+<!ENTITY value "<tag>value</tag>">
<!ENTITY default "<tag>default</tag>">
<!ENTITY data "<tag>data</tag>">
<!ENTITY discount "<tag>discount</tag>">
<!ENTITY process "<tag>process</tag>">
<!ENTITY checked "<tag>checked</tag>">
-<!ENTITY accounting "<tag>accounting</tag>">
<!ENTITY price "<tag>price</tag>">
+<!ENTITY accounting "<tag>accounting</tag>">
<!ENTITY search-region "<tag>search-region</tag>">
<!ENTITY item-list "<tag>item-list</tag>">
<!ENTITY dump "<tag>dump</tag>">
@@ -143,8 +89,8 @@
<!ENTITY scratch "<tag>scratch</tag>">
<!ENTITY levy-list "<tag>levy-list</tag>">
<!ENTITY control-set "<tag>control-set</tag>">
-<!ENTITY log "<tag>log</tag>">
<!ENTITY mail "<tag>mail</tag>">
+<!ENTITY log "<tag>log</tag>">
<!ENTITY value-extended "<tag>value-extended</tag>">
<!ENTITY cart "<tag>cart</tag>">
<!ENTITY control "<tag>control</tag>">
@@ -154,8 +100,8 @@
<!ENTITY userdb "<tag>userdb</tag>">
<!ENTITY import "<tag>import</tag>">
<!ENTITY nitems "<tag>nitems</tag>">
-<!ENTITY selected "<tag>selected</tag>">
<!ENTITY catch "<tag>catch</tag>">
+<!ENTITY selected "<tag>selected</tag>">
<!ENTITY handling "<tag>handling</tag>">
<!ENTITY image "<tag>image</tag>">
<!ENTITY fcounter "<tag>fcounter</tag>">
@@ -203,10 +149,10 @@
<!ENTITY list_pages "<tag>list_pages</tag>">
<!ENTITY reconfig "<tag>reconfig</tag>">
<!ENTITY row-edit "<tag>row-edit</tag>">
-<!ENTITY substitute_file "<tag>substitute_file</tag>">
<!ENTITY newer "<tag>newer</tag>">
-<!ENTITY list-databases "<tag>list-databases</tag>">
+<!ENTITY substitute_file "<tag>substitute_file</tag>">
<!ENTITY filters "<tag>filters</tag>">
+<!ENTITY list-databases "<tag>list-databases</tag>">
<!ENTITY display "<tag>display</tag>">
<!ENTITY if-mm "<tag>if-mm</tag>">
<!ENTITY run-profile "<tag>run-profile</tag>">
@@ -215,8 +161,8 @@
<!ENTITY file-navigator "<tag>file-navigator</tag>">
<!ENTITY table-editor "<tag>table-editor</tag>">
<!ENTITY list-keys "<tag>list-keys</tag>">
-<!ENTITY write-shipping "<tag>write-shipping</tag>">
<!ENTITY dump_session "<tag>dump_session</tag>">
+<!ENTITY write-shipping "<tag>write-shipping</tag>">
<!ENTITY reconfig-time "<tag>reconfig-time</tag>">
<!ENTITY diffmerge "<tag>diffmerge</tag>">
<!ENTITY write-relative-file "<tag>write-relative-file</tag>">
@@ -224,22 +170,23 @@
<!ENTITY get-gpg-keys "<tag>get-gpg-keys</tag>">
<!ENTITY return_to "<tag>return_to</tag>">
<!ENTITY diff "<tag>diff</tag>">
-<!ENTITY quick_table "<tag>quick_table</tag>">
<!ENTITY export-database "<tag>export-database</tag>">
+<!ENTITY quick_table "<tag>quick_table</tag>">
<!ENTITY db_columns "<tag>db_columns</tag>">
<!ENTITY db-hash "<tag>db-hash</tag>">
<!ENTITY file-info "<tag>file-info</tag>">
<!ENTITY backup-file "<tag>backup-file</tag>">
<!ENTITY read-shipping "<tag>read-shipping</tag>">
+<!ENTITY crypt "<tag>crypt</tag>">
<!ENTITY rotate-table "<tag>rotate-table</tag>">
-<!ENTITY mm-value "<tag>mm-value</tag>">
<!ENTITY available_www_shipping "<tag>available_www_shipping</tag>">
+<!ENTITY mm-value "<tag>mm-value</tag>">
<!ENTITY add-gpg-key "<tag>add-gpg-key</tag>">
<!ENTITY list_glob "<tag>list_glob</tag>">
<!ENTITY grep-mm "<tag>grep-mm</tag>">
<!ENTITY version "<tag>version</tag>">
-<!ENTITY cp "<tag>cp</tag>">
<!ENTITY check-upload "<tag>check-upload</tag>">
+<!ENTITY cp "<tag>cp</tag>">
<!ENTITY import_fields "<tag>import_fields</tag>">
<!ENTITY uneval "<tag>uneval</tag>">
<!ENTITY directive_value "<tag>directive_value</tag>">
@@ -268,6 +215,7 @@
<!ENTITY xml-generator "<tag>xml-generator</tag>">
<!ENTITY read-ui-page "<tag>read-ui-page</tag>">
<!ENTITY db-date "<tag>db-date</tag>">
+<!ENTITY loc "<tag>loc</tag>">
<!ENTITY with "<tag>with</tag>">
<!ENTITY convert-date "<tag>convert-date</tag>">
<!ENTITY email-raw "<tag>email-raw</tag>">
@@ -539,4 +487,3 @@
<!ENTITY PostURL "<option>PostURL</option>">
<!ENTITY DatabaseAutoIgnore "<option>DatabaseAutoIgnore</option>">
<!ENTITY MoreDB "<option>MoreDB</option>">
-<!ENTITY TaxInclusive "<option>TaxInclusive</option>">
1.9 +221 -199 xmldocs/guides/xmldocs.xml
rev 1.9, prev_rev 1.8
Index: xmldocs.xml
===================================================================
RCS file: /var/cvs/xmldocs/guides/xmldocs.xml,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- xmldocs.xml 20 Oct 2004 21:17:41 -0000 1.8
+++ xmldocs.xml 23 Oct 2004 16:38:30 -0000 1.9
@@ -132,7 +132,7 @@
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)
+ HOW-TOs (quick, on-topic, technical solutions)
</para></listitem>
<listitem><para>
References (quick, on-topic refentry pages describing
@@ -194,7 +194,7 @@
</para>
<sect2>
- <title>Guides</title>
+ <title>Modifying Guides</title>
<para>
To modify an existing guide, simply edit
<filename>guides/<replaceable>name</replaceable>.xml</filename>.
@@ -217,15 +217,15 @@
</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 class='directory'>OUTPUT/<replaceable>name
- </replaceable>/</filename>.
+ saved to
+ <filename class='directory'>OUTPUT/<replaceable>name</replaceable>/</filename>.
</para>
</sect2>
<sect2>
- <title>HOWTOs</title>
+ <title>Modifying HOW-TOs</title>
<para>
- To modify an existing HOWTO item, simply edit
+ To modify an existing HOW-TO item, simply edit
<filename>howtos/<replaceable>name</replaceable>.xml</filename>.
</para>
<para>
@@ -236,25 +236,25 @@
the current standard.
</para>
<para>
- To make the new HOWTO entry build as part of the global
+ To make the new HOW-TO entry build as part of the global
<command>make</command> procedure, you don't have to do anything;
the <filename>howtos/howtos.xml</filename> is automatically regenerated
(by following Makefile dependencies). If you need to trigger .xml file
regeneration manually, invoke <userinput>make howtos/howtos.xml</userinput>.
</para>
<para>
- To build the HOWTO collection,
+ To build the HOW-TO 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
+ unspecified, the chunked HTML version of the HOW-TO collection will be
built and, of course, saved to <filename>OUTPUT/howtos/</filename>.
</para>
</sect2>
<sect2>
<title>
- Symbols (pragmas, globvars, *tags, globconfs, catconfs, filters)
+ Modifying Symbols (pragmas, globvars, *tags, globconfs, catconfs, filters)
</title>
<para>
To modify an existing symbol, simply edit <filename>refs/*</filename>
@@ -279,7 +279,7 @@
use <command>make clean-refs refxmls</command>.
</para>
<para>
- Note that the refentries can (and are) built in manpage format as well.
+ Note that the refentries can be built in manpage format as well.
To generate the manpages, run
<command>make OUTPUT/<replaceable>group</replaceable>.man</command>,
where <literal>group</literal> is one of
@@ -290,7 +290,7 @@
</sect2>
<sect2>
- <title>Glossary</title>
+ <title>Modifying Glossary</title>
<para>
To modify an existing item, simply edit the appropriate
<filename>glossary/*</filename> file.
@@ -301,7 +301,7 @@
(copy the structure from <filename>glossary/pragma</filename>).
</para>
<para>
- To generate the glossary XML source, run
+ To generate the glossary XML source manually, run
<command>make glossary/glossary.xml</command>. To build the glossary,
run <command>make OUTPUT/glossary.<replaceable>format</replaceable>
</command>.
@@ -310,191 +310,6 @@
</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>
@@ -529,7 +344,7 @@
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
+ <filename>docbook/literals.ent</filename> and then just refer to it
using the entity name; like you can write &IC; to produce &IC;.
</para></listitem>
<listitem><para>
@@ -693,6 +508,213 @@
<filename class='directory'>pending/</filename>.
</para>
+</sect1>
+
+
+<sect1 id='FileFormats'>
+ <title>File Formats</title>
+
+ <para>
+ <emphasis role='bold'>
+ This is an irrelevant section. Read it only if the examples from the
+ already written documentation are not enough, and you need some more
+ hints.
+ </emphasis>
+ </para>
+
+ <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/literals.ent</filename> and
+ <filename>docbook/autodefs.ent</filename>. For manual entity definitions,
+ always use the former file; the latter is autogenerated and automaintained.
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>HOW-TOs</title>
+ <para>
+ HOW-TOs 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.
+ Existing HOW-TOs provide excellent quickstarts.
+ </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 can (and, infact, must) omit from your chunks.
+ </para>
+ <para>
+ You can also create more sections that begin with the same name, and
+ are then appended 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, which is available with multi-file
+ method only) 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.
+ ICDEVGROUP members are specified like "&docelic;amp;,
+ &ICDEVGROUP;", where the username and ICDEVGROUP entities expand
+ to a suitable
+ strings (full name, and full team name with link currently - this
+ is defined in <filename>docbook/literals.ent</filename>).
+ If no author is
+ specified, the default shows the team name, not mentioning any
+ individual specifically.<sbr/>
+ 3rd party people need to be specified in the same way (
+ name and email with optional group name), such as in a silly
+ example of "Mirko Star <mstar at aol.com>". If the person
+ is expected to contribute more often, adding an entity in
+ the <filename>literals</filename> for him/her is okay.
+ </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).<sbr/>
+ On items that begin with "<" (that is, on those that seem to be
+ formatted already), no special processing is done and are included
+ verbatim.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </sect3>
+
+ <sect3>
+ <title>synopsis</title>
+ <para>
+ The <filename>synopsis</filename> file needs to contain a block
+ that depends on the symbol type being documented. Just copy an
+ existing one from the same symbol group.
+ </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 (well, at least not without
+ entities).
+ </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>
</article>
More information about the docs
mailing list