A large commit with many enhancements:

- README: update to current - TODO: items - bin/refs-autogen: restructured the order of sections in generated refentries - docbook/common.xsl: turned use.extensions to 0 (it prevented <table>s from working) - docbook/xmldocs.css: definitions for table elements (needs more tuning) - docbook/item-skel/*: adjusted - refs/*/synopsis: adjusted to new scheme
interchange · Sep 24, 2004 · a0f2502 · a0f2502
1 parent 322e4c6
commit a0f2502
Show file tree

Hide file tree

Showing 34 changed files with 410 additions and 102 deletions.
diff --git a/README b/README
@@ -5,6 +5,10 @@ http://www.icdevgroup.org
 ICDEVGROUP Documentation Set
 http://www.icdevgroup.org/cgi-bin/cvsweb/xmldocs/
 
+This is a technical look at the XMLDOCS system, and it tells you how to get
+the documentation generated. For the XMLDOCS authoring QuickStart, see
+guides/xmldocs.xml (or that is OUTPUT/xmldocs.html after you run 'make').
+
 
 INTRODUCTION
 
@@ -24,9 +28,9 @@ targets would include:
   make OUTPUT/iccattut.man
 
   make OUTPUT/xmldocs.css
-  make tmp/stattrees
-  make tmp/refs-autogen
   make tmp/olinkdbs
+  make tmp/stattrees      (same as 'make cache')
+  make tmp/refs-autogen   (same as 'make refxmls')
 
 
 PREREQUISITES
@@ -59,8 +63,9 @@ During the invocation of 'make', few files will be created:
                    from it are created by bin/mkreport.
 
                    The cache is Perl's portable Storable dump, and is only
-                   a convenience. If the binary is incompatible for you,
+                   a convenience. If the binary is incompatible for you
-                   simply get Interchange sources and run bin/stattree yourself.
+                   (which often happens to be the case), simply get
+                   Interchange sources and run bin/stattree yourself.
 
   OUTPUT/        - Autogenerated:
                    directory containing the actual completely self-contained
@@ -80,6 +85,7 @@ DEVELOPMENT NOTES
    guides        - Collection of guides
    howtos        - Collection of howtos
    refs          - Collection of reference pages
+   glossary      - Collection of glossary items
    images        - All images
    tmp           - (not in CVS) Scratch and temporary file space
    pending       - A "pending" directory.
@@ -91,7 +97,6 @@ DEVELOPMENT NOTES
                    in with subdirectories containing Interchange releases
                    (say, 4.8.0/, 5.0.0/, 5.2.0, cvs-head/), then you can run
                    'make tmp/stattrees' to generate the source tree information.
-                   Both sources/ and its subdirectories can be symlinks.
 
 
  Updating cache/:
@@ -119,11 +124,12 @@ DEVELOPMENT NOTES
    files are filesystem interface to tree-level statistics, and can be
    used in numerous ways, XInclude for example.
    Like: Interchange consists of <xi:include file='.../total.files'> files.
+   (Currently this is not enabled).
 
 
  The XML "preprocessor" tool:
-   There's bin/pp tool which you can use to write XML more conveniently.
+   There's bin/pp tool which you can use to write larger blocks of
-   See the script itself for usage notes.
+   XML more conveniently. See the script itself for usage notes.
 
 
  Autogeneration of the reference pages: ** IMPORTANT **
@@ -139,9 +145,14 @@ DEVELOPMENT NOTES
    other parts must be added manually by us. 
 
    Let's take an example of "post_page" pragma (but the principle is the same
-   for any symbol). User-supplied information is found in refs/<symbol>/
+   for any symbol). User-supplied information is found in either:
-   directory. Information which is needed to consider a symbol documentation
+
-   complete includes:
+   o  refs/<symbol>/ directory, or
+   o  refs/<symbol> file, where multiple sections are defined using the 
+      __NAME__ <section> and __END__ tokens (similar to IC profiles ;-).
+
+   Regardless of the way you document an item, the following information
+   is needed to consider the symbol documentation complete:
 
      - autogenerated:
         id, name, symbol type, availability, source occurences
@@ -151,8 +162,10 @@ DEVELOPMENT NOTES
         purpose, synopsis, description, examples, see also
 
    All of those fields can both be overriden or appended with user-supplied
-   information.
+   information:
 
+   o  refs/<symbol>/* method (one-directory, multiple-files):
+
    To unconditionally override values and/or provide one-liner contents, use
    refs/<symbol>/control file. It has pretty much inflexible "field: content"
    line format, but # comments can be used.
@@ -177,6 +190,20 @@ DEVELOPMENT NOTES
    To avoid having to escape all HTML entities and everything, simply
    enclose "dirty" blocks in <![CDATA[ ... ]]>.
 
+   o  refs/<symbol> method (one-file):
+
+   All rules apply as above, except that instead of creating a new file
+   (say, refs/post_page/description), you add it to refs/post_page this way:
+
+   __NAME__ description
+   ...anything...
+   __END__
+
+   Over time it appeared we only want to append information and never
+   override it, so this method does not have a way to override a value
+   like refs/<symbol>/control file can do.
+
+
 ** To create the documentation for a yet non-existant item or modify an 
 ** existing item, simply run bin/editem <name>. It will create all the
 ** skeleton files, auto-let you edit the important files and do basic checks.

diff --git a/TODO b/TODO
@@ -7,6 +7,7 @@ PRIMARY:
 - See why the autogenerated navigation links are so retarded (just home/up,
   no next/prev)
 - not to forget, fix cases where context goes to negative values
+- Source contexts get some weird values reported in header information
 
 - In iccattut:
   - under important file and directories, mention default username,
@@ -23,6 +24,9 @@ PRIMARY:
   bin/editem
 - in source contexts, wrap runaway lines
 
+HOWTOs:
+- how to delete item from cart in all possible ways
+
 DOCUMENTATION SYSTEM:
 - copy the definition for <example> to a
   new name so we'll be able to differentiate between source chunks and 

diff --git a/bin/refs-autogen b/bin/refs-autogen
@@ -607,8 +607,10 @@ $templates{pragma} = <<'__ENDP__';
 </refnamediv>
 
 <refsect1 id='$ag{"name"}_synopsis'>
-<title>SYNOPSIS</title>
+<title>VALUE</title>
+<cmdsynopsis>
 $ag{"synopsis"}
+</cmdsynopsis>
 </refsect1>
 
 <refsect1 id='$ag{"name"}_default'>
@@ -677,31 +679,55 @@ $templates{usertag} = <<'__ENDP__';
 <refpurpose>$ag{"purpose"}</refpurpose>
 </refnamediv>
 
+<refsect1 id='$ag{"name"}_description'>
+<title>DESCRIPTION</title>
+<para>$ag{"description"}</para>
+</refsect1>
+
 <refsect1 id='$ag{"name"}_synopsis'>
-<title>SYNOPSIS</title>
+<title>PARAMETERS</title>
+
+<informaltable cellspacing='4' cellpadding='2' pgwide='1'>
+<tgroup cols='5' align='left' colsep='1' rowsep='1'>
+<colspec colname='arg'/>
+<colspec colname='pos'/>
+<colspec colname='req'/>
+<colspec colname='def'/>
+<colspec colname='dsc'/>
+
+<thead>
+<row>
+<entry>Argument</entry>
+<entry>Pos.</entry>
+<entry>Req.</entry>
+<entry>Default</entry>
+<entry>Description</entry>
+</row>
+</thead>
+<tbody>
 $ag{"synopsis"}
+</tbody>
+</tgroup>
+</informaltable>
 </refsect1>
 
+<!-- Disabled. I could remove it unless I do something useful with it.
 <refsect1 id='$ag{"name"}_structure"}'>
 <title>TAG STRUCTURE</title>
 <para>$ag{"structure"}</para>
 </refsect1>
+-->
 
-<refsect1 id='$ag{"name"}_description'>
+<refsect1 id='$ag{"name"}_notes'>
-<title>DESCRIPTION</title>
+<title>NOTES</title>
-<para>$ag{"description"}</para>
+<para>$ag{"notes"}</para>
 </refsect1>
 
 <refsect1 id='$ag{"name"}_examples'>
 <title>EXAMPLES</title>
 $ag{"example"}
 </refsect1>
 
-<refsect1 id='$ag{"name"}_notes'>
-<title>NOTES</title>
-<para>$ag{"notes"}</para>
-</refsect1>
-
 <refsect1 id='$ag{"name"}_availability'>
 <title>AVAILABILITY</title>
 <para>$ag{"name"} is available in Interchange versions:
@@ -721,10 +747,13 @@ $ag{source}
 <para>$ag{"author"}</para>
 </refsect1>
 
+<!-- Removed because copyright is seen in Source (first few lines),
+     and the generated document starts with copyright notice
 <refsect1 id='$ag{"name"}_copyright'>
 <title>COPYRIGHT</title>
 $ag{"copyright"}
 </refsect1>
+-->
 
 <refsect1 id='$ag{"name"}_seeAlso'>
 <title>SEE ALSO</title>

diff --git a/docbook/common.xsl b/docbook/common.xsl
@@ -18,7 +18,7 @@
 	<xsl:param name="callout.graphics">1</xsl:param>
 	<xsl:param name="callout.graphics.path">./images/</xsl:param>
 
-	<xsl:param name="use.extensions">1</xsl:param>
+	<xsl:param name="use.extensions">0</xsl:param>
 	<xsl:param name="textinsert.extension">1</xsl:param>
 
 	<!--<xsl:template match="tag"><xsl:text>[</xsl:text><xsl:call-template name="inline.monoseq"/><xsl:text>]</xsl:text></xsl:template>-->

diff --git a/docbook/item-skel/bugs b/docbook/item-skel/bugs
diff --git a/docbook/item-skel/example b/docbook/item-skel/example
@@ -1,5 +1,5 @@
 <!-- Template example. Fill in the title (in title), short description
-     (in para) and actual program chunk (inside listing/cdata).
+     (in para) and actual program chunk (inside programlisting/cdata).
      Delete those 3 lines of comments.                             -->
 
 <example>

diff --git a/docbook/item-skel/synopsis b/docbook/item-skel/synopsis
@@ -1,11 +1,21 @@
-<!-- Where applicable, show syntax in a way which is opposite of the
+<!-- Syntax section appears to be very complex.  The convention follows:
-     default value.
 
-     Describe various options inside 'description' file, not here.
+1. pragmas/globvars (context is <cmdsynopsis>):
-     Delete those comment lines.
+  <group choice='req'>
+    <arg choice='plain'>0</arg>
+    <arg choice='plain'>1</arg>
+    <arg choice='plain'><replaceable>string</replaceable></arg>
+  </group>
 
-     ** If you're documenting a TAG, leave this file completely empty,
+2. any kind of tags (context is <table> with all headers etc.):
-        syntax line for tags is autogenerated **                     -->
+  <row>
+    <entry>SYMBOL_ARGUMENT_NAME</entry>
+    <entry>POSITIONAL ('Yes' or empty)</entry>
+    <entry>REQUIRED ('Yes' or empty)</entry>
+    <entry>DEFAULT (number, description or <literal>value</literal>)</entry>
+    <entry>DESCRIPTION</entry>
+  </row>
 
-<cmdsynopsis>
+
-</cmdsynopsis>
+Take out the template that suits you best, edit it and delete all other
+comments.                                                               -->
diff --git a/docbook/xmldocs.css b/docbook/xmldocs.css
@@ -300,3 +300,14 @@ a {
 	color: #208cbd;
 }
 
+
+thead {
+	background-color: black;
+	color: white; 
+} 
+
+table, tbody,thead,tfoot, tr,td {
+	border-color: #8F8F8F;
+	border: dotted 1px;
+} 
+
diff --git a/refs/CGIWRAP_WORKAROUND/synopsis b/refs/CGIWRAP_WORKAROUND/synopsis
@@ -1,6 +1,4 @@
-<cmdsynopsis>
   <group choice='req'>
     <arg choice='plain'>0</arg>
     <arg choice='plain'>1</arg>
   </group>
-</cmdsynopsis>
diff --git a/refs/MV_BAD_LOCK/synopsis b/refs/MV_BAD_LOCK/synopsis
@@ -1,6 +1,4 @@
-<cmdsynopsis>
   <group choice='req'>
     <arg choice='plain'>0</arg>
     <arg choice='plain'>1</arg>
   </group>
-</cmdsynopsis>
diff --git a/refs/MV_DOLLAR_ZERO/synopsis b/refs/MV_DOLLAR_ZERO/synopsis
@@ -1,7 +1,5 @@
-<cmdsynopsis>
   <group choice='req'>
     <arg choice='plain'>0</arg>
     <arg choice='plain'>1</arg>
     <arg choice='plain'><replaceable>string</replaceable></arg>
   </group>
-</cmdsynopsis>
diff --git a/refs/MV_FILE/synopsis b/refs/MV_FILE/synopsis
@@ -1,3 +1 @@
-<cmdsynopsis>
 @@MV_FILE@@
-</cmdsynopsis>
diff --git a/refs/MV_GETPPID_BROKEN/synopsis b/refs/MV_GETPPID_BROKEN/synopsis
@@ -1,6 +1,4 @@
-<cmdsynopsis>
   <group choice='req'>
     <arg choice='plain'>0</arg>
     <arg choice='plain'>1</arg>
   </group>
-</cmdsynopsis>
diff --git a/refs/MV_HELO/synopsis b/refs/MV_HELO/synopsis
@@ -1,3 +1 @@
-<cmdsynopsis>
   <arg choice='req'><replaceable>host name</replaceable></arg>
-</cmdsynopsis>
diff --git a/refs/MV_HTML4_COMPLIANT/synopsis b/refs/MV_HTML4_COMPLIANT/synopsis
@@ -1,6 +1,4 @@
-<cmdsynopsis>
   <group choice='req'>
     <arg choice='plain'>0</arg>
     <arg choice='plain'>1</arg>
   </group>
-</cmdsynopsis>
diff --git a/refs/MV_MAILFROM/synopsis b/refs/MV_MAILFROM/synopsis
@@ -1,6 +1,4 @@
-<cmdsynopsis>
 	<group choice='req'>
 		<arg choice='plain'><replaceable>user name</replaceable></arg>
 		<arg choice='plain'><replaceable>e-mail address</replaceable></arg>
 	</group>
-</cmdsynopsis>
diff --git a/refs/MV_NO_CRYPT/synopsis b/refs/MV_NO_CRYPT/synopsis
@@ -1,6 +1,4 @@
-<cmdsynopsis>
   <group choice='req'>
     <arg choice='plain'>0</arg>
     <arg choice='plain'>1</arg>
   </group>
-</cmdsynopsis>
diff --git a/refs/MV_PAGE/synopsis b/refs/MV_PAGE/synopsis
@@ -1,3 +1 @@
-<cmdsynopsis>
 @@MV_PAGE@@
-</cmdsynopsis>
diff --git a/refs/MV_PREV_PAGE/synopsis b/refs/MV_PREV_PAGE/synopsis
@@ -1,3 +1 @@
-<cmdsynopsis>
 @@MV_PREV_PAGE@@
-</cmdsynopsis>
diff --git a/refs/MV_SESSION_READ_RETRY/synopsis b/refs/MV_SESSION_READ_RETRY/synopsis
@@ -1,3 +1 @@
-<cmdsynopsis>
   <arg choice='req'><replaceable>count</replaceable></arg>
-</cmdsynopsis>
diff --git a/refs/MV_SMTPHOST/synopsis b/refs/MV_SMTPHOST/synopsis
@@ -1,3 +1 @@
-<cmdsynopsis>
   <arg choice='req'><replaceable>host name</replaceable></arg>
-</cmdsynopsis>
diff --git a/refs/MV_SUBJECT/synopsis b/refs/MV_SUBJECT/synopsis
@@ -1,3 +1 @@
-<cmdsynopsis>
 @@MV_SUBJECT@@
-</cmdsynopsis>