[docs] xmldocs - docelic modified 2 files
docs at icdevgroup.org
docs at icdevgroup.org
Tue Feb 1 16:37:47 EST 2005
User: docelic
Date: 2005-02-01 21:37:47 GMT
Modified: . TODO WRITING
Log:
The usual accompanying improvements
Revision Changes Path
1.62 +10 -11 xmldocs/TODO
rev 1.62, prev_rev 1.61
Index: TODO
===================================================================
RCS file: /var/cvs/xmldocs/TODO,v
retrieving revision 1.61
retrieving revision 1.62
diff -u -r1.61 -r1.62
--- TODO 3 Jan 2005 20:48:34 -0000 1.61
+++ TODO 1 Feb 2005 21:37:47 -0000 1.62
@@ -1,11 +1,10 @@
- See that if 'crypt' is put in see also, all symbols of that name appear
in see also line and their type is distinguished visually.
-- Finish proper formatting for online examples
- Add ROW_REPARSE along ROW_INTERPOLATE in tag refs
- TAXAREA is not discovered in source by bin/stattree
- toc in glossary
-- &gloss-hello-world needs to give "hello world", not "hello-world" as text
+- Make MapRoutined source contexts have Line: x-y instead of Lines: z header.
- make glossary,howto items also appear as symbols, so that you can put
their names in See Also and get generated links
- find out where on denali did I misplace a "port" of icvariables?
@@ -13,13 +12,18 @@
first example does not see the other, but the other sees the first becase
of 10 lines of pre-context. (example is IMAGE_MOGRIFY refentry). In those
cases, resize area of the context report so that it appears as one
+- With confs, also include source context where it is being used
+- Enhance stuff with acronyms
+- Under AUTHORS, include cvs line where appropriate (guides, howtos, gloss... )
+- In vars.html, include line if it appears in variable.txt
Outstanding:
- why email, email-raw, SendMailProgram produce errors about usertags olink ID
- Add docbook element to reference mailing list posts. Something like
<ml list='users'>2004-December/041539</ml>, it expands to:
<ulink url="http://www.icdevgroup.org/pipermail/interchange-users/2004-December/041539.html">2004-December/041539</ulink>.
-- Ask ndw about including [NEW!] and [TODO!] in titles in TOC.
+- Ask ndw about including [NEW!] and [TODO!] in titles in TOC. --> This is a
+ bug and it will work when they fix it.
- match style (no starting verb or all starting verbs) in all Example titles
- check if all Default fields are properly formated (<literal> or none)
- s/a HTML/an HTML/
@@ -38,6 +42,7 @@
Mid-term:
+- &glos-hello-world needs to give "hello world", not "hello-world" as text
- List of mv_s, descriptions and shortcuts
- for "online" docs, also provide a form where users can add comments or
ask for clarification. (this could be done with either pure IC (forum?), or
@@ -51,7 +56,6 @@
- If filter returns Vend::xxx::something(), include that function in context
reports, and try to determine the "Uses" field (which also needs to be
added to filter refentry template or something)
-- icsdf2xml.pl -> =item/=back should be <listitem><para> not, just <para>
Tags:
aliases
@@ -79,17 +83,12 @@
- jedit + IC colorization, commit-to-live script,
- Racke: performance docs NEEDED, clustering my mike needs funding or he
won't do it. CVS howto is browning.
+
+
- "In times of universal deceit, telling the truth becomes
a revolutionary act." -- George Orwell.
- For a successful technology, reality must take precedence over public
relations, for Nature cannot be fooled. -- Dick Feynman
-- <epigraph>
- <attribution>William Safire</attribution>
- <para>
- Knowing how things work is the basis for appreciation, and is
- thus a source of civilized delight.
- </para>
- </epigraph>
Misc:
1.2 +164 -11 xmldocs/WRITING
rev 1.2, prev_rev 1.1
Index: WRITING
===================================================================
RCS file: /var/cvs/xmldocs/WRITING,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- WRITING 17 Dec 2004 13:39:22 -0000 1.1
+++ WRITING 1 Feb 2005 21:37:47 -0000 1.2
@@ -12,8 +12,8 @@
- 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.
+ custom processing layer to extend the DocBook set of elements and perform
+ other tuning to our specific 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:
@@ -26,7 +26,7 @@
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-
+ becomes a natural part of the development, without any annoying or time-
consuming overhead.
@@ -55,11 +55,11 @@
. 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
+ . At (many) places where the external contents need to be included, we use
xi:include, native DocBook feature.
- 2 howto collection: relatively short documents that contain practical examples
- . and supporting technical explanation.
+ 2 howto collection: direct answers to direct questions; relatively short
+ . documents that contain working 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
@@ -81,14 +81,10 @@
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.
+ . how to update it; you only need to check-in the updated whatsnew file 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
@@ -96,4 +92,161 @@
[ 2]: Read about the intention and structure of the sources/ directory in the
README file.
+
+
+WRITING
+
+Not to waste words, and to give practical examples, best see the existing
+documentation for reference how to write new or fix existing pieces.
+
+You also need to look at docbook/*.ent files, they contain XML entities
+that you are encouraged to use instead of writing common symbols, words and
+phrases manually over and over.
+
+What follows are pieces from one obsolete xmldocs intro document. Some of
+this was already said, but better repeat than omit it:
+
+
+
+GENERATING FINAL OUTPUT
+
+
+bin/refs-autogen 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>
+
+
+
+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>Modifying Guides</title>
+ <para>
+ 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.
+ </para>
+ <para>
+ To make the new guide build as part of the global <command>make</command>
+ 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>Modifying HOW-TOs</title>
+ <para>
+ To modify an existing HOW-TO item, simply edit
+ <filename>howtos/<replaceable>name</replaceable>.xml</filename>.
+ </para>
+ <para>
+ 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 HOW-TO entry build as part of the global
+ <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 HOW-TO 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 HOW-TO collection will be
+ built and, of course, saved to <filename>OUTPUT/howtos/</filename>.
+ </para>
+</sect2>
+
+<sect2>
+ <title>
+ Modifying 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. 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 be built in manpage format as well.
+ 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>Modifying Glossary</title>
+ <para>
+ To modify an existing item, simply edit the appropriate
+ <filename>glossary/*</filename> file.
+ </para>
+ <para>
+ 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 generate the glossary XML source manually, run
+ <command>make glossary/glossary.xml</command>. To build the glossary,
+ run <command>make OUTPUT/glossary.<replaceable>format</replaceable>
+ </command>.
+ </para>
+</sect2>
+
+
+Davor Ocelic, docelic at icdevgroup.org
More information about the docs
mailing list