Fix wrong directive reference
[xmldocs.git] / WRITING
1
2 The Interchange Development Group
3 http://www.icdevgroup.org
4
5 ICDEVGROUP Documentation Set
6 http://git.icdevgroup.org/?p=xmldocs.git;a=summary
7
8 Documentation writing/authoring QuickStart.
9
10
11 INTRODUCTION
12
13 - The new documentation system (XMLDOCS) is based on DocBook XML
14   (http://www.docbok.org/, http://www.sagehill.net/), and includes a
15   custom processing layer to extend the DocBook set of elements and perform
16   other tuning to our specific needs.
17
18 - To naturally understand why XMLDOCS looks the way it looks, and how the
19   design decision were made, let's quote the ultimate goals of XMLDOCS:
20
21   1) Use custom scripts to auto-generate *every possible bit* of documentation
22      that can be autogenerated.
23   2) At places where no autogeneration is possible, keep the ammount of
24      manual documentation work required at an absolute minimum.
25
26   The first point effectively makes the documentation base follow Interchange
27   source code development effort in a timely manner with no user intervention.
28   The second point makes writing documentation so easy and convenient that it
29   becomes a natural part of the development, without any annoying or time-
30   consuming overhead.
31
32
33 BASICS
34
35 We use DocBook XML tools to transform our DocBook XML documentation sources
36 into a number of output formats. When the appropriate DocBook processor is
37 invoked[1], the XML source files must already be put together and wait ready
38 to be processed.
39
40 As we've said that our goal is to autogenerate as much XML as possible, it's
41 obvious that we do not keep the XML sources in Git. (That would be pretty
42 inflexible, make larger changes very inconvenient, and require daily fixes and
43 updates to the Git repo.)
44
45 Instead of the above, what we keep in Git are a number of documentation
46 snippets (only those parts that need to be written manually). We first rely on
47 the bin/stattree script to extract information from Interchange sources[2],
48 then on bin/*-autogen scripts to combine templates, mentioned stattree
49 information and our snippets into complete, valid XML sources.
50
51
52 The system separates documentation contents into 5 major groups:
53
54  1 guides: prose-based documents that explain concepts and are intended to
55  . be read from top to bottom.
56  . Autogeneration of contents is obviously of little use here, so we directly
57  . keep .xml sources in Git.
58  . At (many) places where the external contents need to be included, we use
59    xi:include, native DocBook feature.
60
61  2 howto collection: direct answers to direct questions; relatively short
62  . documents that contain working examples and supporting technical explanation.
63  . In the past, those were small snippets in howtos/* which were put together
64  . by bin/generic-autogen script, but in the meantime we moved directly to
65  . guides/howtos.xml, as howtos started looking much like regular guides.
66
67  3 reference pages: short, completely on-topic and focused pages documenting
68  . all types of symbols. (Symbols are "units" seen in Interchange source - 
69  . tags, filters, pragmas, global/catalog variables, Perl functions, ...).
70  . Enormous ammount of autogeneration and templating is possible here, and
71  . we keep snippets in Git (format is, again, XML with all kinds of headers
72    and containers already included in templates so you can just focus on text).
73
74  4 glossary: prose-based collection of glossary items.
75  . Some templating is possible here, so we keep individual glossary snippets
76  . (in XML format, minus standard headings which are included in the templates)
77  . in Git, while they are put together in a single glossary.xml file by the
78    bin/generic-autogen script.
79
80  5 whatsnew file: there's a bin/whatsnew-update script that takes care of
81  . automatic whatsnew file updates.
82  . The .xml file is directly kept in Git, while bin/whatsnew-update knows
83  . how to update it; you only need to check-in the updated whatsnew file to Git.
84  . More information on this can be found in bin/whatsnew-update and
85    whatsnew/whatsnew.xml.
86
87 [ 1]: We use xsltproc, a C-based implementation of the XSL processor.
88       It is much faster than any of the two alternatives, which are both
89       written in Java. Unfortunately, due to the nature of DocBook, processing
90       is still visually slow.
91
92 [ 2]: Read about the intention and structure of the sources/ directory in the
93       README file.
94
95
96 WRITING
97
98 Not to waste words, and to give practical examples, best see the existing
99 documentation for reference on how to write new or update existing material.
100
101 You also need to look at docbook/*.ent files, they contain XML entities
102 that you are encouraged to use instead of writing common symbols, words and
103 phrases manually over and over. For example, instead of ever mentioning
104 "Interchange", simply write "⁣". That entity would expand to a proper
105 name ("Interchange") and also provide a link to the website.
106
107 What follows are pieces from one obsolete xmldocs intro document. Some of
108 this was already said, but we better repeat than omit it:
109
110
111
112
113 *** OLD INFO / Usable for more clarification ***
114
115 GENERATING FINAL OUTPUT
116
117 bin/refs-autogen is used to generate the reference pages
118 (containing many individual refentries). bin/generic-autogen is used for
119 the glossary.
120 The whole autogeneration story comes from the observation that enormous
121 piece of the final XML source can be produced automatically, with insertions
122 and templating. So, every chunk you write still has to be XML-conformant
123 (of course), but you no longer have to write all those repetitive blocks
124 of XML.
125
126 The documentation writing procedure is not always the same, it depends
127 on the actual part of the content you want to write/update.
128 The procedure could be the same in theory, but in practice it is mostly
129 symbol type-dependent, so that more of XML can be autogenerated.
130
131
132 * Modifying Guides
133
134 To modify an existing guide, simply edit
135 guides/name.xml.
136
137 To start a new guide, create a new guides/name.xml file. For a quickstart,
138 copy the exact structure as you see in the existing iccattut guide. The
139 iccattut guide will always reflect the current standard.
140
141 To make the new guide build as part of the global make procedure, open the
142 Makefile and simply add the guide .xml name under the GUIDES = section.
143
144 To build a guide manually, invoke "make OUTPUT/name.format", where 'format'
145 represents typical filename extensions (such as .html or .ps). If you leave
146 ".format" unspecified, the chunked HTML version will be built
147 and, of course, saved to OUTPUT/name/.
148
149
150 * Modifying Symbols (pragmas, globvars, *tags, globconfs, catconfs, filters)
151
152 To modify an existing symbol, simply edit refs/* or refs/*/* (depending on
153 whether the symbol documentation was saved in one-file or multi-file format).
154 Multi-file format was used in the beginning, and although is still normally
155 supported, it seems to be less convenient, and should not be used.
156
157 To document a new symbol using one-file format, run 'bin/editem name'.
158 This will create skeleton file (refs/name) and load it in your editor.
159 Before you get the grip, carefully read the embedded comments in the file
160 that will guide you through (Delete the comments as you go).
161
162 After you've added a symbol, you need to regenerate the refs/*.xml files
163 which it affected. This should happen as part of the standard Make dependency
164 resolution, but if you need to invoke unconditional manual regeneration, 
165 use 'make clean-refs refxmls'.
166
167 Note that the refentries can be built in manpage format as well. To generate
168 the manpages, run 'make OUTPUT/group.man', where group is one of
169 pragmas, globvars, usertags, systemtags, uitags etc. The output manpages
170 will be placed to a common manpage directory, OUTPUT/man/.
171
172
173 * Modifying Glossary
174
175 To modify an existing item, simply edit the appropriate glossary/* file.
176
177 To add a new glossary entry, create the glossary/name file
178 (copy the structure from say, glossary/ITL).
179
180 To generate the glossary XML source manually, run 'make glossary/glossary.xml'.
181 To build the glossary, run make OUTPUT/glossary.format.
182
183
184
185 Davor Ocelic, docelic@icdevgroup.org
186