Permalink
Browse files

- 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
  • Loading branch information...
1 parent 8a8fb40 commit 3e701cc62cf2f1e59aa598aeeb5ac29ad3ec5288 @docelic docelic committed Dec 17, 2004
Showing with 169 additions and 55 deletions.
  1. +61 −48 README
  2. +1 −0 TODO
  3. +99 −0 WRITING
  4. +8 −7 bin/refs-autogen
View
109 README
@@ -6,8 +6,7 @@ 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').
+the documentation generated. For XMLDOCS authoring, see file WRITING.
INTRODUCTION
@@ -53,6 +52,7 @@ must be available:
- docbook-xsl
- xsltproc
- exuberant-ctags
+ - passivetex (not yet)
FINAL OUTPUT
@@ -105,6 +105,12 @@ DEVELOPMENT NOTES
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 @@ 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; 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,62 +173,66 @@ DEVELOPMENT NOTES
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.
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__
-
- 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
+ - Pieces that could be user-supplied but have meaningful default:
+ notes, bugs, authors, copyright
- (also, nothing prevents you from having more <example>s in the same file
- if you like).
+ - Autogenerated (can be overriden if really neccesary):
+ id, name, symbol type, availability, source occurences
- 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 @@ DEVELOPMENT NOTES
** 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
View
1 TODO
@@ -10,6 +10,7 @@ Outstanding:
- 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
View
99 WRITING
@@ -0,0 +1,99 @@
+
+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@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.
+
View
15 bin/refs-autogen
@@ -46,7 +46,7 @@ my %dups; # List of symbols names that are not unique
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 @@ while ( $path = shift @paths) { # For each version specified
{ 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,15 +568,15 @@ ENDD
# 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 $" = ", ";
$k = $longname{$k};
$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 @@ $templates{filter} = <<'__ENDP__';
<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 @@ $ag{"synopsis"}
<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 @@ $ag{"synopsis"}
<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>

0 comments on commit 3e701cc

Please sign in to comment.