Permalink
Browse files

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
  • Loading branch information...
docelic committed Sep 24, 2004
1 parent 322e4c6 commit a0f2502a32e5115e272ec6f7a9f350532313cf1e
View
49 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,
- simply get Interchange sources and run bin/stattree yourself.
+ a convenience. If the binary is incompatible for you
+ (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.
- See the script itself for usage notes.
+ There's bin/pp tool which you can use to write larger blocks of
+ 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>/
- directory. Information which is needed to consider a symbol documentation
- complete includes:
+ for any symbol). User-supplied information is found in either:
+
+ 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.
View
4 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
View
@@ -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'>
-<title>DESCRIPTION</title>
-<para>$ag{"description"}</para>
+<refsect1 id='$ag{"name"}_notes'>
+<title>NOTES</title>
+<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>
View
@@ -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>-->
View
@@ -1,2 +0,0 @@
-<!-- List bugs here. Environment is <para>.
- Delete those two lines. -->
@@ -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>
View
@@ -1,11 +1,21 @@
-<!-- Where applicable, show syntax in a way which is opposite of the
- default value.
+<!-- Syntax section appears to be very complex. The convention follows:
- Describe various options inside 'description' file, not here.
- Delete those comment lines.
+1. pragmas/globvars (context is <cmdsynopsis>):
+ <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,
- syntax line for tags is autogenerated ** -->
+2. any kind of tags (context is <table> with all headers etc.):
+ <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. -->
View
@@ -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;
+}
+
@@ -1,6 +1,4 @@
-<cmdsynopsis>
<group choice='req'>
<arg choice='plain'>0</arg>
<arg choice='plain'>1</arg>
</group>
-</cmdsynopsis>
@@ -1,6 +1,4 @@
-<cmdsynopsis>
<group choice='req'>
<arg choice='plain'>0</arg>
<arg choice='plain'>1</arg>
</group>
-</cmdsynopsis>
@@ -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>
View
@@ -1,3 +1 @@
-<cmdsynopsis>
@@MV_FILE@@
-</cmdsynopsis>
@@ -1,6 +1,4 @@
-<cmdsynopsis>
<group choice='req'>
<arg choice='plain'>0</arg>
<arg choice='plain'>1</arg>
</group>
-</cmdsynopsis>
View
@@ -1,3 +1 @@
-<cmdsynopsis>
<arg choice='req'><replaceable>host name</replaceable></arg>
-</cmdsynopsis>
@@ -1,6 +1,4 @@
-<cmdsynopsis>
<group choice='req'>
<arg choice='plain'>0</arg>
<arg choice='plain'>1</arg>
</group>
-</cmdsynopsis>
@@ -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>
@@ -1,6 +1,4 @@
-<cmdsynopsis>
<group choice='req'>
<arg choice='plain'>0</arg>
<arg choice='plain'>1</arg>
</group>
-</cmdsynopsis>
View
@@ -1,3 +1 @@
-<cmdsynopsis>
@@MV_PAGE@@
-</cmdsynopsis>
@@ -1,3 +1 @@
-<cmdsynopsis>
@@MV_PREV_PAGE@@
-</cmdsynopsis>
@@ -1,3 +1 @@
-<cmdsynopsis>
<arg choice='req'><replaceable>count</replaceable></arg>
-</cmdsynopsis>
@@ -1,3 +1 @@
-<cmdsynopsis>
<arg choice='req'><replaceable>host name</replaceable></arg>
-</cmdsynopsis>
View
@@ -1,3 +1 @@
-<cmdsynopsis>
@@MV_SUBJECT@@
-</cmdsynopsis>
Oops, something went wrong.

0 comments on commit a0f2502

Please sign in to comment.