[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/,,[email protected])
 $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 [email protected] $(BOTH) $(IC_VERSIONS)
 	bin/refs-autogen -o [email protected] $(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 &lt;chapter&gt; 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 &lt;mstar at aol.com&gt;; 
-					ICDEVGROUP members are specified like "Davor Ocelic,
-					&amp;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
-			&lt;cmdsynopsis&gt; 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 &lt;para&gt; tag. If, for the purpose of your description, you
-			need new paragraphs, simply use &lt;/para&gt;&lt;para&gt; to 
-			separate them, but always omit the starting &lt;para&gt; and 
-			ending &lt;/para&gt;.
-			</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 &lt;example&gt; element (which 
-			usually contains the &lt;title&gt;, short &lt;para&gt; with description
-			and &lt;programlisting&gt; 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 &lt;glossentry&gt; 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 &amp;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 &lt;chapter&gt; 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 "&amp;docelic;amp;,
+					&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 &lt;mstar at aol.com&gt;". 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 "&lt;" (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 &lt;para&gt; tag. If, for the purpose of your description, you
+			need new paragraphs, simply use &lt;/para&gt;&lt;para&gt; to 
+			separate them, but always omit the starting &lt;para&gt; and 
+			ending &lt;/para&gt;.
+			</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 &lt;example&gt; element (which 
+			usually contains the &lt;title&gt;, short &lt;para&gt; with description
+			and &lt;programlisting&gt; 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 &lt;glossentry&gt; element. See <filename>glossary/pragma</filename>
+		for an example.
+		</para>
+	</sect2>
+	
 </sect1>
 
 </article>








More information about the docs mailing list