[docs] xmldocs - docelic modified 4 files

docs at icdevgroup.org docs at icdevgroup.org
Fri Dec 17 08:39:23 EST 2004


User:      docelic
Date:      2004-12-17 13:39:23 GMT
Modified:  .        README TODO
Modified:  bin      refs-autogen
Added:     .        WRITING
Log:
- README: updates
- WRITING: new file that will replace guides/xmldocs.xml
- bin/refs-autogen: Fix some stuff that prevented generated XML
   from validating (double <para><para>s and excess "} in section IDs.
- TODO: items

Revision  Changes    Path
1.13      +61 -48    xmldocs/README


rev 1.13, prev_rev 1.12
Index: README
===================================================================
RCS file: /var/cvs/xmldocs/README,v
retrieving revision 1.12
retrieving revision 1.13
diff -u -r1.12 -r1.13
--- README	20 Nov 2004 14:40:39 -0000	1.12
+++ README	17 Dec 2004 13:39:22 -0000	1.13
@@ -6,8 +6,7 @@
 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').
+the documentation generated. For XMLDOCS authoring, see file WRITING.
 
 
 INTRODUCTION
@@ -53,6 +52,7 @@
   - docbook-xsl
   - xsltproc
   - exuberant-ctags
+  - passivetex (not yet)
 
 
 FINAL OUTPUT
@@ -105,6 +105,12 @@
                    directory with all needed contents. 'make cvs' is not
                    part of the global 'make' run, but 'make caches', which
                    needs to run after 'make cvs', is.
+   whatsnew      - A directory containing whatsnew.xml, continuously updated
+                   what's new list. The items are added automatically; just
+                   place copies of the CVS commit messages in the whatsnew/
+                   directory; every time you run bin/whatsnew-update, it will
+                   process the files and update whatsnew.xml, which you can
+                   then check-in (or update) in CVS.
 
 
  Updating cache/:
@@ -131,7 +137,8 @@
    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; bin/mkreport is outdated).
+   (Currently this is not available; bin/mkreport is outdated and broken, and
+   will be fixed when I come to needing it).
 
 
  The XML "preprocessor" tool:
@@ -166,7 +173,7 @@
       Everything outside __NAME__ <name> ... __END__ blocks is discarded
       and can effectively be used as a comment area.
 
-   The refs/<symbol> file-based approach is now preferred. It's more
+   The refs/<symbol> single-file-based approach is now preferred. It's more
    convenient and keeps the number of files in CVS at minimum. The bin/editem
    script advises to use it.
    Use refs/<symbol>/* only if you have special requirements.
@@ -174,54 +181,58 @@
    Regardless of the way you document an item, the following information
    is needed to consider the symbol documentation complete:
 
-     - must be user-supplied because it only has placeholder defaults:
+     - Pieces that must be user-supplied because defaults are only placeholders:
         purpose, synopsis, description, examples, see also
-     - could be user-supplied but has meaningful default:
-        notes, bugs, authors, copyright
-     - autogenerated (can be overriden if really neccesary):
-        id, name, symbol type, availability, source occurences
-
-   All of above fields can both be overriden or appended with user-supplied
-   information:
-
-   o  refs/<symbol> method (one-file):
 
-     To fill the template of the reference page, you add content to sections
-     in the following way:
-
-     __NAME__ section name
-     section content
-     __END__
+     - Pieces that could be user-supplied but have meaningful default:
+        notes, bugs, authors, copyright
 
-     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 (in multi-file method) can do.
-   
-   o  refs/<symbol>/* method (one-directory, multiple-files):
+     - Autogenerated (can be overriden if really neccesary):
+        id, name, symbol type, availability, source occurences
 
-     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.
-
-     To append with information, you use refs/<symbol>/<X>, where <X> is
-     the name of an existing section, maybe followed by an arbitrary string.
-     With the exception of example files, you generally only create one
-     file for each section.
-     To supply more examples, you could keep them in an informal structure
-     like this:
-     refs/post_page/example
-     refs/post_page/example2
-     refs/post_page/example-relative_pages
-     refs/post_page/example:used-often
-     refs/post_page/example.something
-
-     (also, nothing prevents you from having more <example>s in the same file
-     if you like).
-
-     You can't use # comments in the non-control files (they'd be left as-is),
-     but you can use XML comments <!-- commented section -->.
-     To avoid having to escape all HTML entities and everything, simply
-     enclose "dirty" blocks in <![CDATA[ ... ]]>.
+   *** Obscure information START /// Not needed in general ***
+   * All of above fields can both be overriden or appended with user-supplied
+   * information:
+   *
+   * o  refs/<symbol> method (one-file):
+   *
+   *   To fill the template of the reference page, you add content to sections
+   *   in the following way:
+   *
+   *   __NAME__ section name
+   *   section content
+   *   __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 (in multi-file method) can do.
+   * 
+   * 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.
+   *
+   *   To append with information, you use refs/<symbol>/<X>, where <X> is
+   *   the name of an existing section, maybe followed by an arbitrary string.
+   *   With the exception of example files, you generally only create one
+   *   file for each section.
+   *   To supply more examples, you could keep them in an informal structure
+   *   like this:
+   *   refs/post_page/example
+   *   refs/post_page/example2
+   *   refs/post_page/example-relative_pages
+   *   refs/post_page/example:used-often
+   *   refs/post_page/example.something
+   *
+   *   (also, nothing prevents you from having more <example>s in the same file
+   *   if you like).
+   *
+   *   You can't use # comments in the non-control files (they'd be left as-is),
+   *   but you can use XML comments <!-- commented section -->.
+   *   To avoid having to escape all HTML entities and everything, simply
+   *   enclose "dirty" blocks in <![CDATA[ ... ]]>.
+   *** Obscure information END /// Not needed in general ***
 
 
 ** To create the documentation for a yet non-existant item or modify an 
@@ -233,6 +244,8 @@
 ** symbol (and supplement that with your own invaluable historical and
 ** technical information), and then write the item documentation that
 ** includes all that information.
+** Also make sure to check the actual symbol source; at many places I've
+** found undocumented options being present, and variables used or checked.
 
 ** After you build the documentation, there will be a file named
 ** tmp/missing autogenerated, and it will contain a list of symbols with all



1.58      +1 -0      xmldocs/TODO


rev 1.58, prev_rev 1.57
Index: TODO
===================================================================
RCS file: /var/cvs/xmldocs/TODO,v
retrieving revision 1.57
retrieving revision 1.58
diff -u -r1.57 -r1.58
--- TODO	15 Dec 2004 22:34:05 -0000	1.57
+++ TODO	17 Dec 2004 13:39:22 -0000	1.58
@@ -10,6 +10,7 @@
 - check if all Default fields are properly formated (<literal> or none)
 - s/a HTML/an HTML/
 - script to [un]comment debug lines!!
+- use Interchange.pm to make an Interchange shell
 
 DOCUMENTATION SYSTEM:
 - Add support to document tags which are NOT found in separate files



1.1                  xmldocs/WRITING


rev 1.1, prev_rev 1.0
Index: WRITING
===================================================================

The Interchange Development Group
http://www.icdevgroup.org

ICDEVGROUP Documentation Set
http://www.icdevgroup.org/cgi-bin/cvsweb/xmldocs/

Documentation writing/authoring QuickStart.


INTRODUCTION

- The new documentation system (XMLDOCS) is based on DocBook XML
  (http://www.docbok.org/, http://www.sagehill.net/), and includes a
  custom processing layer to extenda DocBook set of elements and perform
  other tuning specific to our needs.

- To naturally understand why XMLDOCS looks the way it looks, and how the
  design decision were made, let's quote the ultimate goals of XMLDOCS:

  1) Use custom scripts to auto-generate *every possible bit* of documentation
     that can be autogenerated.
  2) At places where no autogeneration is possible, keep the ammount of
     manual documentation work required at an absolute minimum.

  The first point effectively makes the documentation base follow Interchange
  source code development effort in a timely manner with no user intervention.
  The second point makes writing documentation so easy and convenient that it
  becomes a natural part of the development, without any annyonying or time-
  consuming overhead.


BASICS

We use DocBook XML tools to transform our DocBook XML documentation sources
into a number of output formats. When the appropriate DocBook processor is
invoked[1], the XML source files must already be put together and wait ready
to be processed.

As we've said that our goal is to autogenerate as much XML as possible, it's
obvious that we do not keep the XML sources in the CVS. (That would be pretty
inflexible, make larger changes very inconvenient, and require daily fixes and
updates to the CVS).

Instead of the above, what we keep in the CVS are a number of documentation
snippets (only those parts that need to be written manually). We first rely on
the bin/stattree script to extract information from Interchange sources[2],
then on bin/*-autogen scripts to combine templates, mentioned stattree
information and our snippets into complete, valid XML sources.


The system separates documentation contents into 5 major groups:

 1 guides: prose-based documents that explain concepts and are intended to
 . be read from top to bottom.
 . Autogeneration of contents is obviously of little use here, so we directly
 . keep .xml sources in the CVS.
 . At (many) places where the external content needs to be included, we use
   xi:include, native DocBook feature.

 2 howto collection: relatively short documents that contain practical examples
 . and supporting technical explanation.
 . Some templating is possible here, so we keep individual HOW-TO snippets
 . (in XML format, minus standard headings which are included in the templates)
 . in the CVS, while they are put together in a single howtos.xml file by the
   bin/generic-autogen script.

 3 reference pages: short, completely on-topic and focused pages documenting
 . all types of symbols. (Symbols are "units" seen in Interchange source - 
 . tags, filters, pragmas, global/catalog variables, Perl functions, ...).
 . Enormous ammount of autogeneration and templating is possible here, and
 . we keep snippets in CVS (format is, again, XML with all kinds of headers
   and containers already included in templates so you can just focus on text).

 4 glossary: prose-based collection of glossary items.
 . Some templating is possible here, so we keep individual glossary snippets
 . (in XML format, minus standard headings which are included in the templates)
 . in the CVS, while they are put together in a single glossary.xml file by the
   bin/generic-autogen script.

 5 whatsnew file: there's a bin/whatsnew-update script that takes care of
 . automatic whatsnew file updates.
 . The .xml file is directly kept in the CVS, while bin/whatsnew-update knows
 . how to update it; you only need to check in to CVS.
 . More information on this can be found in bin/whatsnew-update and
   whatsnew/whatsnew.xml.


Davor Ocelic, docelic at icdevgroup.org


[ 1]: We use xsltproc, a C-based implementation of the XSL processor.
      It is much faster than any of the two alternatives, which are both
      written in Java. Unfortunately, due to the nature of DocBook, processing
      is still visually slow.

[ 2]: Read about the intention and structure of the sources/ directory in the
      README file.




1.76      +8 -7      xmldocs/bin/refs-autogen


rev 1.76, prev_rev 1.75
Index: refs-autogen
===================================================================
RCS file: /var/cvs/xmldocs/bin/refs-autogen,v
retrieving revision 1.75
retrieving revision 1.76
diff -u -r1.75 -r1.76
--- refs-autogen	15 Dec 2004 22:34:05 -0000	1.75
+++ refs-autogen	17 Dec 2004 13:39:23 -0000	1.76
@@ -46,7 +46,7 @@
 my $last_path; # Last version we want docs generated for (say, 5.2.0).
 my $compounds = 1; # Summarize similar symbol groups to single page?
 
-my @page_order = (qw/purpose default structure synopsis description structure online example notes bugs/, "symbol type", "source", "author", "copyright", "see also", "directive type", "filter type");
+my @page_order = (qw/purpose default structure synopsis description online example notes bugs/, "symbol type", "source", "author", "copyright", "see also", "directive type", "filter type");
 
 unless ( GetOptions ( 
 	"verbosedb|dumpdb|d!" => \$dumpdb,
@@ -385,13 +385,14 @@
 
 
 					{ no warnings; # XXX If someone can figure out which of the used vars here is undefined...
+#<screen linenumbering='numbered' startinglinenumber='$ls'>
 					$$ag{source} .= <<ENDD;
 <para>
 </para>
 <figure>
 <title>$loc $revinfo$ctxmeta</title>
 
-<screen linenumbering='numbered' startinglinenumber='$ls'>
+<screen>
 <![CDATA[$ctxsdata]]>
 </screen>
 </figure>
@@ -567,7 +568,7 @@
 	# The 'structure' field will show which other symbols the current
 	# symbol uses. Fill it:
 	if ( $hash{uses}{$group}{$ag{name}} ) {
-		$ag{structure} = "<para>This tag appears to be affected by, or affects, the following:</para>\n";
+		$ag{structure} = "This tag appears to be affected by, or affects, the following:\n";
 		while (my($k,$v)=each %{ $hash{uses}{$group}{$ag{name}} }) {
 			s/^(.+)$/<$tagname{lc $k}>$1<\/$tagname{lc $k}>/ for @$v;
 			local $" = ", ";
@@ -575,7 +576,7 @@
 			$ag{structure} .= "${k}s: @$v<sbr/>\n";
 		}
 	} else {
-		$ag{structure} = "<para>This tag does not appear to be affected by, or affect, the rest of Interchange.</para>\n";
+		$ag{structure} = "This tag does not appear to be affected by, or affect, the rest of Interchange.\n";
 	}
 
 	# Expand template
@@ -1114,7 +1115,7 @@
 <para>$ag{"description"}</para>
 </refsect1>
 
-<refsect1 id='$ag{"name"}_type"}'>
+<refsect1 id='$ag{"name"}_type'>
 <title>FILTER TYPE</title>
 <para>$ag{"filter type"}</para>
 </refsect1>
@@ -1203,7 +1204,7 @@
 <para>$ag{"description"}</para>
 </refsect1>
 
-<refsect1 id='$ag{"name"}_structure"}'>
+<refsect1 id='$ag{"name"}_structure'>
 <title>BEHAVIOR</title>
 <para>$ag{"structure"}</para>
 </refsect1>
@@ -1272,7 +1273,7 @@
 <para>$ag{"description"}</para>
 </refsect1>
 
-<refsect1 id='$ag{"name"}_type"}'>
+<refsect1 id='$ag{"name"}_type'>
 <title>DIRECTIVE TYPE</title>
 <para>$ag{"directive type"}</para>
 </refsect1>








More information about the docs mailing list