[docs] xmldocs - docelic modified 2 files
docs at icdevgroup.org
docs at icdevgroup.org
Wed Oct 20 17:17:41 EDT 2004
User: docelic
Date: 2004-10-20 21:17:41 GMT
Modified: docbook autodefs.ent
Modified: guides xmldocs.xml
Log:
- Up-to-dating guides/xmldocs.xml (more to come later)
Revision Changes Path
1.3 +185 -124 xmldocs/docbook/autodefs.ent
rev 1.3, prev_rev 1.2
Index: autodefs.ent
===================================================================
RCS file: /var/cvs/xmldocs/docbook/autodefs.ent,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- autodefs.ent 19 Oct 2004 22:38:11 -0000 1.2
+++ autodefs.ent 20 Oct 2004 21:17:41 -0000 1.3
@@ -1,3 +1,188 @@
+<!ENTITY next_sequential "<filter>next_sequential</filter>">
+<!ENTITY encrypt "<filter>encrypt</filter>">
+<!ENTITY date2time "<filter>date2time</filter>">
+<!ENTITY linkdecode "<filter>linkdecode</filter>">
+<!ENTITY qb_safe "<filter>qb_safe</filter>">
+<!ENTITY lc "<filter>lc</filter>">
+<!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 uc-attr-list "<tag>uc-attr-list</tag>">
+<!ENTITY tmp "<tag>tmp</tag>">
+<!ENTITY loop "<tag>loop</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 input-filter "<tag>input-filter</tag>">
+<!ENTITY deliver "<tag>deliver</tag>">
+<!ENTITY region "<tag>region</tag>">
+<!ENTITY accessories "<tag>accessories</tag>">
+<!ENTITY description "<tag>description</tag>">
+<!ENTITY total-cost "<tag>total-cost</tag>">
+<!ENTITY mvasp "<tag>mvasp</tag>">
+<!ENTITY html-table "<tag>html-table</tag>">
+<!ENTITY levies "<tag>levies</tag>">
+<!ENTITY assign "<tag>assign</tag>">
+<!ENTITY seti "<tag>seti</tag>">
+<!ENTITY timed-build "<tag>timed-build</tag>">
+<!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 unpack "<tag>unpack</tag>">
+<!ENTITY error "<tag>error</tag>">
+<!ENTITY set "<tag>set</tag>">
+<!ENTITY banner "<tag>banner</tag>">
+<!ENTITY msg "<tag>msg</tag>">
+<!ENTITY onfly "<tag>onfly</tag>">
+<!ENTITY calc "<tag>calc</tag>">
+<!ENTITY filter "<tag>filter</tag>">
+<!ENTITY either "<tag>either</tag>">
+<!ENTITY perl "<tag>perl</tag>">
+<!ENTITY index "<tag>index</tag>">
+<!ENTITY parse_locale "<tag>parse_locale</tag>">
+<!ENTITY charge "<tag>charge</tag>">
+<!ENTITY try "<tag>try</tag>">
+<!ENTITY counter "<tag>counter</tag>">
+<!ENTITY output-to "<tag>output-to</tag>">
+<!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 flag "<tag>flag</tag>">
+<!ENTITY shipping-desc "<tag>shipping-desc</tag>">
+<!ENTITY record "<tag>record</tag>">
+<!ENTITY order "<tag>order</tag>">
+<!ENTITY debug "<tag>debug</tag>">
+<!ENTITY export "<tag>export</tag>">
+<!ENTITY tag "<tag>tag</tag>">
+<!ENTITY field "<tag>field</tag>">
+<!ENTITY calcn "<tag>calcn</tag>">
+<!ENTITY salestax "<tag>salestax</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 search-region "<tag>search-region</tag>">
+<!ENTITY item-list "<tag>item-list</tag>">
+<!ENTITY dump "<tag>dump</tag>">
+<!ENTITY soap "<tag>soap</tag>">
+<!ENTITY include "<tag>include</tag>">
+<!ENTITY fly-tax "<tag>fly-tax</tag>">
+<!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 value-extended "<tag>value-extended</tag>">
+<!ENTITY cart "<tag>cart</tag>">
+<!ENTITY control "<tag>control</tag>">
+<!ENTITY scratchd "<tag>scratchd</tag>">
+<!ENTITY query "<tag>query</tag>">
+<!ENTITY menu "<tag>menu</tag>">
+<!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 handling "<tag>handling</tag>">
+<!ENTITY image "<tag>image</tag>">
+<!ENTITY fcounter "<tag>fcounter</tag>">
+<!ENTITY MV_FILE "<varname>MV_FILE</varname>">
+<!ENTITY MV_ECML_FIELD_MAP "<varname>MV_ECML_FIELD_MAP</varname>">
+<!ENTITY MV_SESSION_READ_RETRY "<varname>MV_SESSION_READ_RETRY</varname>">
+<!ENTITY UI_BASE "<varname>UI_BASE</varname>">
+<!ENTITY MV_ROBOT_EXPIRE "<varname>MV_ROBOT_EXPIRE</varname>">
+<!ENTITY MV_PAGE "<varname>MV_PAGE</varname>">
+<!ENTITY MV_NO_CRYPT "<varname>MV_NO_CRYPT</varname>">
+<!ENTITY UI_SECURITY_OVERRIDE "<varname>UI_SECURITY_OVERRIDE</varname>">
+<!ENTITY MV_PREV_PAGE "<varname>MV_PREV_PAGE</varname>">
+<!ENTITY GPG_PATH "<varname>GPG_PATH</varname>">
+<!ENTITY MV_HTML4_COMPLIANT "<varname>MV_HTML4_COMPLIANT</varname>">
+<!ENTITY UI_STD_HEAD "<varname>UI_STD_HEAD</varname>">
+<!ENTITY UI_IMAGE_DIR "<varname>UI_IMAGE_DIR</varname>">
+<!ENTITY LANG "<varname>LANG</varname>">
+<!ENTITY UI_STD_FOOTER "<varname>UI_STD_FOOTER</varname>">
+<!ENTITY MV_FORTUNE_COMMAND "<varname>MV_FORTUNE_COMMAND</varname>">
+<!ENTITY MV_MAILFROM "<varname>MV_MAILFROM</varname>">
+<!ENTITY MV_HELO "<varname>MV_HELO</varname>">
+<!ENTITY MV_SMTPHOST "<varname>MV_SMTPHOST</varname>">
+<!ENTITY MV_BAD_LOCK "<varname>MV_BAD_LOCK</varname>">
+<!ENTITY MV_GETPPID_BROKEN "<varname>MV_GETPPID_BROKEN</varname>">
+<!ENTITY CGIWRAP_WORKAROUND "<varname>CGIWRAP_WORKAROUND</varname>">
+<!ENTITY IMAGE_MOGRIFY "<varname>IMAGE_MOGRIFY</varname>">
+<!ENTITY MV_SUBJECT "<varname>MV_SUBJECT</varname>">
<!ENTITY menu-load "<tag>menu-load</tag>">
<!ENTITY su "<tag>su</tag>">
<!ENTITY xfer-catalog "<tag>xfer-catalog</tag>">
@@ -46,7 +231,6 @@
<!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>">
@@ -84,7 +268,6 @@
<!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>">
@@ -126,104 +309,6 @@
<!ENTITY pay-cert "<tag>pay-cert</tag>">
<!ENTITY breadcrumbs "<tag>breadcrumbs</tag>">
<!ENTITY values-space "<tag>values-space</tag>">
-<!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 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 sql "<tag>sql</tag>">
-<!ENTITY setlocale "<tag>setlocale</tag>">
-<!ENTITY input-filter "<tag>input-filter</tag>">
-<!ENTITY cgi "<tag>cgi</tag>">
-<!ENTITY deliver "<tag>deliver</tag>">
-<!ENTITY region "<tag>region</tag>">
-<!ENTITY accessories "<tag>accessories</tag>">
-<!ENTITY description "<tag>description</tag>">
-<!ENTITY total-cost "<tag>total-cost</tag>">
-<!ENTITY mvasp "<tag>mvasp</tag>">
-<!ENTITY html-table "<tag>html-table</tag>">
-<!ENTITY levies "<tag>levies</tag>">
-<!ENTITY assign "<tag>assign</tag>">
-<!ENTITY seti "<tag>seti</tag>">
-<!ENTITY timed-build "<tag>timed-build</tag>">
-<!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 unpack "<tag>unpack</tag>">
-<!ENTITY currency "<tag>currency</tag>">
-<!ENTITY error "<tag>error</tag>">
-<!ENTITY set "<tag>set</tag>">
-<!ENTITY banner "<tag>banner</tag>">
-<!ENTITY msg "<tag>msg</tag>">
-<!ENTITY onfly "<tag>onfly</tag>">
-<!ENTITY calc "<tag>calc</tag>">
-<!ENTITY filter "<tag>filter</tag>">
-<!ENTITY either "<tag>either</tag>">
-<!ENTITY perl "<tag>perl</tag>">
-<!ENTITY index "<tag>index</tag>">
-<!ENTITY parse_locale "<tag>parse_locale</tag>">
-<!ENTITY charge "<tag>charge</tag>">
-<!ENTITY try "<tag>try</tag>">
-<!ENTITY counter "<tag>counter</tag>">
-<!ENTITY output-to "<tag>output-to</tag>">
-<!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 flag "<tag>flag</tag>">
-<!ENTITY shipping-desc "<tag>shipping-desc</tag>">
-<!ENTITY record "<tag>record</tag>">
-<!ENTITY order "<tag>order</tag>">
-<!ENTITY debug "<tag>debug</tag>">
-<!ENTITY export "<tag>export</tag>">
-<!ENTITY tag "<tag>tag</tag>">
-<!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 search-region "<tag>search-region</tag>">
-<!ENTITY item-list "<tag>item-list</tag>">
-<!ENTITY dump "<tag>dump</tag>">
-<!ENTITY soap "<tag>soap</tag>">
-<!ENTITY include "<tag>include</tag>">
-<!ENTITY fly-tax "<tag>fly-tax</tag>">
-<!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 value-extended "<tag>value-extended</tag>">
-<!ENTITY cart "<tag>cart</tag>">
-<!ENTITY control "<tag>control</tag>">
-<!ENTITY scratchd "<tag>scratchd</tag>">
-<!ENTITY query "<tag>query</tag>">
-<!ENTITY menu "<tag>menu</tag>">
-<!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 handling "<tag>handling</tag>">
-<!ENTITY image "<tag>image</tag>">
-<!ENTITY fcounter "<tag>fcounter</tag>">
<!ENTITY AddDirective "<option>AddDirective</option>">
<!ENTITY CheckHTML "<option>CheckHTML</option>">
<!ENTITY AcrossLocks "<option>AcrossLocks</option>">
@@ -455,27 +540,3 @@
<!ENTITY DatabaseAutoIgnore "<option>DatabaseAutoIgnore</option>">
<!ENTITY MoreDB "<option>MoreDB</option>">
<!ENTITY TaxInclusive "<option>TaxInclusive</option>">
-<!ENTITY MV_FILE "<varname>MV_FILE</varname>">
-<!ENTITY MV_ECML_FIELD_MAP "<varname>MV_ECML_FIELD_MAP</varname>">
-<!ENTITY MV_SESSION_READ_RETRY "<varname>MV_SESSION_READ_RETRY</varname>">
-<!ENTITY UI_BASE "<varname>UI_BASE</varname>">
-<!ENTITY MV_ROBOT_EXPIRE "<varname>MV_ROBOT_EXPIRE</varname>">
-<!ENTITY MV_PAGE "<varname>MV_PAGE</varname>">
-<!ENTITY MV_NO_CRYPT "<varname>MV_NO_CRYPT</varname>">
-<!ENTITY UI_SECURITY_OVERRIDE "<varname>UI_SECURITY_OVERRIDE</varname>">
-<!ENTITY MV_PREV_PAGE "<varname>MV_PREV_PAGE</varname>">
-<!ENTITY GPG_PATH "<varname>GPG_PATH</varname>">
-<!ENTITY MV_HTML4_COMPLIANT "<varname>MV_HTML4_COMPLIANT</varname>">
-<!ENTITY UI_STD_HEAD "<varname>UI_STD_HEAD</varname>">
-<!ENTITY UI_IMAGE_DIR "<varname>UI_IMAGE_DIR</varname>">
-<!ENTITY LANG "<varname>LANG</varname>">
-<!ENTITY UI_STD_FOOTER "<varname>UI_STD_FOOTER</varname>">
-<!ENTITY MV_FORTUNE_COMMAND "<varname>MV_FORTUNE_COMMAND</varname>">
-<!ENTITY MV_MAILFROM "<varname>MV_MAILFROM</varname>">
-<!ENTITY MV_HELO "<varname>MV_HELO</varname>">
-<!ENTITY MV_SMTPHOST "<varname>MV_SMTPHOST</varname>">
-<!ENTITY MV_BAD_LOCK "<varname>MV_BAD_LOCK</varname>">
-<!ENTITY MV_GETPPID_BROKEN "<varname>MV_GETPPID_BROKEN</varname>">
-<!ENTITY CGIWRAP_WORKAROUND "<varname>CGIWRAP_WORKAROUND</varname>">
-<!ENTITY IMAGE_MOGRIFY "<varname>IMAGE_MOGRIFY</varname>">
-<!ENTITY MV_SUBJECT "<varname>MV_SUBJECT</varname>">
1.8 +121 -50 xmldocs/guides/xmldocs.xml
rev 1.8, prev_rev 1.7
Index: xmldocs.xml
===================================================================
RCS file: /var/cvs/xmldocs/guides/xmldocs.xml,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- xmldocs.xml 14 Oct 2004 15:54:42 -0000 1.7
+++ xmldocs.xml 20 Oct 2004 21:17:41 -0000 1.8
@@ -126,6 +126,7 @@
<para>
So, the current system is split into the following categories:
+ </para>
<itemizedlist>
<listitem><para>
Guides (easy reading, mostly prose and not overly technical documents serving as an "illustrated introduction" to the subject, take iccattut for example)
@@ -134,27 +135,50 @@
HOWTOs (quick, on-topic, technical solutions)
</para></listitem>
<listitem><para>
- Reference sets (quick, on-topic descriptions and usage examples of
+ References (quick, on-topic refentry pages describing
Interchange "symbols" - global variables, pragmas, user tags, system
- tags, ...).
- </para>
- <para>
- <emphasis role='bold'>The source .xml files for the reference sets are
- autogenerated
- </emphasis>. The <command>bin/stattree</command> script collects all
- needed information from Interchange sources and saves it to cache files.
- <command>bin/refs-autogen</command> reads the cache files, supplements
- that information with data from
- <filename class='directory'>refs/*/*</filename> files and generates the
- final <filename>refs/*.xml</filename> sources.
+ tags, filters, ...).
</para></listitem>
<listitem><para>
- Glossary, where the glossary terms are kept in
- <filename>glossary/*</filename> files. The glossary itself, <filename>
- guides/glossary.xml</filename> is then autogenerated by
- <command>bin/glossary-autogen</command>.
+ Glossary
</para></listitem>
</itemizedlist>
+ <para>
+ It is important to note that only Guides are directly edited in-place
+ (that is, by opening and editing <filename>guides/*.xml</filename>).
+ Generation of any output format can be invoked on those files without
+ additional preparation.
+ </para>
+ <para>
+ All other source XML files (reference pages, the HOW-TO collection and the
+ glossary) first need to be generated by appropriate
+ <command>bin/*-autogen</command> script, and then such complete XML
+ files can be used for the production of final output.
+ </para>
+ <para>
+ The autogen scripts combine autodiscovered information (gathered by
+ <command>bin/stattree</command>), a lot of Interchange-specific
+ documentation logic, and the user-supplied documentation chunks, into
+ complete source .xml files.
+ </para>
+ <para>
+ The user-supplied chunks are kept in obvious places,
+ <filename>glossary/*</filename>,
+ <filename>howtos/*</filename> and
+ <filename>refs/*</filename>.
+ </para>
+ <para>
+ <command>bin/refs-autogen</command> is used to generate the reference
+ pages (containing many individual refentries).
+ <command>bin/generic-autogen</command> is used for the glossary and
+ the HOW-TO collection.
+ </para>
+ <para>
+ The whole autogeneration story comes from the observation that
+ <emphasis>enormous</emphasis> piece of the final XML source can be
+ produced automatically, with insertions and templating. So, every chunk
+ you write still has to be XML-conformant (of course), but you no longer
+ have to write all those repetitive blocks of XML.
</para>
</sect1>
@@ -164,80 +188,123 @@
<para>
The documentation writing procedure is not always the same, it depends
on the actual part of the content you want to write/update.
+ The procedure <emphasis>could</emphasis> be the same in theory, but in
+ practice it is mostly symbol type-dependent, so that more of XML can
+ be autogenerated.
</para>
<sect2>
<title>Guides</title>
<para>
- To modify an existing guide, simply edit <filename>guides/<replaceable>name</replaceable>.xml</filename>.
+ To modify an existing guide, simply edit
+ <filename>guides/<replaceable>name</replaceable>.xml</filename>.
</para>
<para>
- To start a new guide, create a new <filename>guides/<replaceable>name</replaceable>.xml</filename> file. For a quickstart, copy the exact structure as you see in the existing <literal>iccattut</literal> guide. The iccattut guide will always reflect the current standard.
+ To start a new guide, create a new
+ <filename>guides/<replaceable>name</replaceable>.xml</filename> file.
+ For a quickstart, copy the exact structure as you see in the existing
+ <literal>iccattut</literal> guide. The iccattut guide will always reflect
+ the current standard.
</para>
<para>
To make the new guide build as part of the global <command>make</command>
- procedure, nothing needs to be done; the guide is auto-located and built.
- To build it manually, invoke <command>make OUTPUT/<replaceable>name</replaceable>.<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 will be built and, of course, saved to <filename>OUTPUT/<replaceable>name</replaceable>/</filename>.
+ procedure, open the <filename>Makefile</filename> and simply add the
+ guide .xml name under the <literal>GUIDES = </literal> section.
+ </para>
+ <para>
+ To build it manually, invoke <command>make
+ OUTPUT/<replaceable>name</replaceable>.<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 will be built and, of course,
+ saved to<filename class='directory'>OUTPUT/<replaceable>name
+ </replaceable>/</filename>.
</para>
</sect2>
<sect2>
<title>HOWTOs</title>
<para>
- To modify an existing HOWTO item, simply edit <filename>howtos/<replaceable>name</replaceable>.xml</filename>.
+ To modify an existing HOWTO item, simply edit
+ <filename>howtos/<replaceable>name</replaceable>.xml</filename>.
</para>
<para>
- To start a new HOWTO, create a new <filename>howtos/<replaceable>name</replaceable>.xml</filename> file. For a quickstart, copy the exact structure as you see in the existing <literal>custom-sendmail-routine.xml</literal> HOWTO. It will always reflect the current standard.
+ To start a new HOWTO item, create a new
+ <filename>howtos/<replaceable>name</replaceable>.xml</filename> file.
+ For a quickstart, copy the exact structure as you see in the existing
+ <literal>custom-sendmail-routine.xml</literal>. It will always reflect
+ the current standard.
</para>
<para>
To make the new HOWTO entry build as part of the global
- <command>make</command>
- procedure, you need to edit <filename>howtos/howtos.xml</filename>. Search for <literal>custom-sendmail</literal> in it and make your new entries look like the existing ones.
- HOWTOs can't be built separately. To build the HOWTO 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 built and, of course, saved to <filename>OUTPUT/howtos/</filename>.
+ <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,
+ 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
+ built and, of course, saved to <filename>OUTPUT/howtos/</filename>.
</para>
</sect2>
<sect2>
- <title>Symbols (pragmas, globvars, tags, ...)</title>
- <para>
- Symbols are a little different. The XMLDOCS system does an
- investigation and discovers everything about all the symbols and types
- (except for the last part of the prose text that a human needs to write).
- </para>
- <para>
- So the procedure here is different: the system knows which symbols it
- wants to document, all you have to do is put those bits of
- human-information to places where xmldocs will look for.
- </para>
- <para>
- To document a new symbol, run <command>bin/editem <replaceable>name</replaceable></command>. This will create skeleton files (<filename>refs/<replaceable>name</replaceable>/*</filename>) and load them all up in your editor. When you edit all files, the symbol will be documented.
+ <title>
+ Symbols (pragmas, globvars, *tags, globconfs, catconfs, filters)
+ </title>
+ <para>
+ To modify an existing symbol, simply edit <filename>refs/*</filename>
+ or <filename>refs/*/*</filename> (depending on whether the symbol
+ documentation was saved in one-file or multi-file format). Multi-file
+ format was used in the beginning, and although is still normally
+ supported, it seems to be less convenient.
+ </para>
+ <para>
+ To document a new symbol using one-file format, run <command>bin/editem
+ <replaceable>name</replaceable></command>. This will create skeleton
+ file (<filename>refs/<replaceable>name</replaceable></filename>) and
+ load it in your editor. Before you get the grip, <emphasis>carefully
+ read the embedded comments in the file</emphasis> that will guide you
+ through.
</para>
<para>
After you've added a symbol, you need to regenerate the
<filename>refs/*.xml</filename> file(s) which
- it affected: <command>rm tmp/refs-autogen; make tmp/refs-autogen</command>.
- Then run the appropriate generator (like say, <command>make OUTPUT/globvars.html</command>) or the global build routine (<command>make distclean all</command>).
+ it affected. This should happen as part of the standard Make dependency
+ resolution, but if you need to invoke unconditional manual regeneration,
+ use <command>make clean-refs refxmls</command>.
</para>
<para>
Note that the refentries can (and are) built in manpage format as well.
- To generate the manpages, run <command>make OUTPUT/<replaceable>group</replaceable>.man</command>, where <literal>group</literal> is pragmas, globvars, usertags, systemtags, uitags... The output manpages will be placed to <filename class='directory'>OUTPUT/man/</filename>.
- </para>
- <para>
- To modify an existing symbol, simply edit the appropriate files in <filename>refs/<replaceable>name</replaceable>/</filename>.
+ To generate the manpages, run
+ <command>make OUTPUT/<replaceable>group</replaceable>.man</command>,
+ where <literal>group</literal> is one of
+ pragmas, globvars, usertags, systemtags, uitags etc. The output manpages
+ will be placed to a common manpage directory,
+ <filename class='directory'>OUTPUT/man/</filename>.
</para>
</sect2>
<sect2>
<title>Glossary</title>
<para>
- To add a new glossary entry, create the <filename>glossary/<replaceable>name</replaceable></filename> file (copy the structure from <filename>glossary/pragma</filename>).
+ To modify an existing item, simply edit the appropriate
+ <filename>glossary/*</filename> file.
</para>
<para>
- To modify an existing item, edit the appropriate <filename class='directory'>glossary/</filename> file.
+ To add a new glossary entry, create the
+ <filename>glossary/<replaceable>name</replaceable></filename> file
+ (copy the structure from <filename>glossary/pragma</filename>).
</para>
<para>
- To build the glossary source, run <command>make guides/glossary.xml</command>. To build the glossary output, run <command>make OUTPUT/glossary.<replaceable>format</replaceable>.</command>. Otherwise the glossary output would be autogenerated during the overall <command>make</command> procedure (it's source goes to <filename class='directory'>guides/</filename> where it is picked up automatically).
+ To generate the glossary XML source, run
+ <command>make glossary/glossary.xml</command>. To build the glossary,
+ run <command>make OUTPUT/glossary.<replaceable>format</replaceable>
+ </command>.
</para>
</sect2>
@@ -598,8 +665,7 @@
<itemizedlist>
<listitem><para>
- Update the existing files with proper tagging (XML or whatever is
- the document's format), or
+ Update the existing files with proper XML formatting, or
</para></listitem>
<listitem><para>
Update the existing files <emphasis>without</emphasis> properly tagging
@@ -621,6 +687,11 @@
words we can rephrase and enough information to work on.
</para></listitem>
</itemizedlist>
+
+ <para>
+ Also, commit any goodies you might have to
+ <filename class='directory'>pending/</filename>.
+ </para>
</sect1>
More information about the docs
mailing list