[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
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
 - 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 @@
+- &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>
@@ -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>

1.2       +164 -11   xmldocs/WRITING

rev 1.2, prev_rev 1.1
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
-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.
+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:
+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.
+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.
+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.
+	<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>
+	<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>
+	<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>
+	<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>
+Davor Ocelic, docelic at icdevgroup.org

More information about the docs mailing list