Fix wrong directive reference
[xmldocs.git] / README
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=tree
7
8 This is a technical look at the XMLDOCS system, and it tells you how to get
9 the documentation generated. For XMLDOCS authoring, see file WRITING.
10
11
12 INTRODUCTION
13
14 The (new) Interchange XML documentation set is completely self-contained.
15 To build the complete documentation set, just run:
16
17   make git
18   make
19
20 Sometimes you want to build multiple versions of documentation at once
21 (for example, one online, one offline, one profiled for Debian GNU etc.).
22 It is possible to change OUTPUT/ directory to something else (named
23 OUTPUT<yourstring>) to achieve this effect. However, places where I
24 couldn't have inserted variables have OUTPUT/ hardcoded, so OUTPUT is still
25 made a symbolic link to the output dir of your choice. 
26
27 Here's an example:
28
29   OUTPUT=-std make skel
30
31 After that point, you can omit OUTPUT= from subsequent calls to "make"
32 and things will still clap together nicely.
33
34 Also, it is possible to generate documentation for a specific Interchange
35 release, such as 5.0.0 or 5.2.0. To do so, use TARGET env variable:
36
37   TARGET="5.2.0" make refxmls
38
39 Just make sure to have TARGET defined on each 'make' invocation.
40
41 **  -- -- --   -- -- -- --   -- -- -- --   -- -- -- --   -- -- -- --  **
42
43 To build specific targets, see Makefile for target names. Few useful
44 targets would include:
45
46  -- Those that are not part of 'make' routine:
47   make git          (to create complete sources/ directory, or update existing)
48   make clean        (removes OUTPUT/)
49   make distclean    (remove OUTPUT/ and tmp/)
50   make look-clean   (clean + 'mv tmp tmp.temporary'. Useful to only make
51                     the tree as if it is clean (to perform Git operations
52                     without errors), but then automatically rename
53                     the directory back to 'tmp/' and avoid the overhead of
54                     regenerating OlinkDB files).
55
56  -- And those that are part of 'make':
57   make skel
58   make cache
59   make refxmls
60   make olinkdbs-nc olinkdbs-c
61   make OUTPUT/xmldocs.css
62   make tmp/iccattut-nc.db tmp/iccattut-c.db
63   make OUTPUT/iccattut.html OUTPUT/iccattut
64   ...
65
66 See Makefile for a complete list, of course.
67
68
69 PREREQUISITES
70
71 To perform a successful build, the following programs and modules
72 must be available:
73
74   - Perl
75   - Shell commands: mkdir, cp, ln, find, tar, gzip, bzip2, make
76   - git-core
77   - docbook-xml
78   - docbook-xsl
79   - xsltproc
80   - tetex-extra (and actually, packages it depends on)
81
82 Optional Perl modules:
83
84   - XML::Twig
85
86 (Install the Twig module if if you want to syntax-check your additions by
87 calling i.e. "bin/refs-autogen --validate git-head").
88
89 RedHat setups
90
91 If running on Red Hat and not Debian GNU, apply this patch:
92 http://icdevgroup.org/~docelic/xmldocs-rh.diff . It allows you to get
93 usable results, although it's flaky and Debian GNU is really the preferred
94 platform. (I suppose with a better patch, by someone know knows Red Hat
95 and its DocBook XML setup, Red Hat would produce completely good results
96 too - patches welcome).
97
98 On Gentoo GNU/Linux systems, the prerequisite ebuild packages are as follows:
99
100   - dev-lang/perl
101   - dev-util/git
102   - app-arch/gzip
103   - app-arch/bzip2
104   - app-text/docbook-xml-dtd
105   - app-text/docbook-xsl-stylesheets
106   - dev-libs/libxslt
107   - dev-util/ctags
108   - app-text/tetex
109   - dev-perl/XML-Twig
110
111 If running on Gentoo GNU/Linux then you will need to apply the following
112 patch to correct the hard-coded, Debian-specific file locations:
113
114     http://icdevgroup.org/~kwalsh/xmldocs-gentoo.diff
115
116 FINAL OUTPUT
117
118 During the invocation of 'make', few files will be created:
119
120   docbook/auto*.ent - Files containing XML entities that we can use in our
121                    sources. For example, configuration directive Include is
122                    referenced simply as &conf-Include;, tag [include] is 
123                    referenced simply as &tag-include;.
124   
125   tmp/*.db       - OLink DB files generated from source .xml files,
126                    and other, on-the-fly .xmls. 
127
128   cache/<ver>/*  - Various Interchange source tree statistics, available
129                    over a filesystem interface. (For XInclusion in .xml
130                    sources and similar purposes). The files are generated
131                    by bin/mkreport which depends on cache/<ver>/.cache.bin.
132                    cache/<ver>/.cache.bin is generated by bin/stattree.
133
134                    The cache is Perl's portable Storable dump. It was
135                    originally kept in Git (so others could re-use it),
136                    but that didn't play out well in practice so now everyone
137                    building the docs needs to have the sources/ directory
138                    ready and run 'make caches' himself to get the .bin
139                    files generated.
140   
141   OUTPUT/        - Autogenerated:
142                    directory containing the actual completely self-contained
143                    and interlinked documentation set. Once it's created, you
144                    can move it out of the build tree and package as you see
145                    fit.
146                    
147                    This can also be OUTPUT<yourprefix>, if you pass e.g.
148                    OUTPUT=-std in a call to make (as already shown above).
149
150   tmp/missing[2] - After you build the documentation, there will be a file
151                    named tmp/missing autogenerated, and it will contain a list
152                    of symbols with all the parts of the documentation they
153                    still miss for the item to be considered complete.
154                    tmp/missing2 will also be created that will list HOWTO
155                    items and glossary entries that need work.
156
157
158 DEVELOPMENT NOTES
159
160  The directory structure:
161    Makefile      - Main Makefile
162    bin           - Helper tools
163    cache         - Interchange source trees metadata
164    docbook       - DocBook XML support files
165    files         - Support files, such as downloadable examples etc.
166    guides        - Collection of guides
167    refs          - Collection of reference pages
168    glossary      - Collection of glossary items
169    images        - All images
170    tmp           - Scratch and temporary file space
171    pending       - A "pending" directory.
172                    If you have a chunk which you'd like to integrate in
173                    the docset, but don't have the time to prepare it
174                    yourself, just drop it in there and someone will pick
175                    it up.
176    sources       - (Not in Git.) run 'make git' to auto-create this 
177                    directory with all needed contents. 
178    whatsnew      - A directory containing whatsnew.xml, continuously updated
179                    what's new list. The items are added automatically; just
180                    place copies of the Git commit messages in the whatsnew/
181                    directory; every time you run bin/whatsnew-update, it will
182                    process the files and update whatsnew.xml, which you can
183                    then push in Git.
184
185
186  Updating cache/:
187    The dotfiles found in cache/ can only be generated when the sources/
188    directory is present as described above, and contains Interchange releases
189    in directories named after release numbers (with the exception of
190    "git-head"). Run 'make git' to create that sources/ directory with
191    all the contents. Run 'make up-all' to invoke git update on all
192    versions (or 'make up-<ver>' for specific). ('make git' can also be used
193    to update repositories).
194
195
196    ** Leftover information, not important for standard procedure: ************
197    * Once sources/ is in place, make sure all available versions are mentioned
198    * in Makefile's IC_VERSIONS variable, and then run 'make cache'.
199    * This will regenerate files for the versions you have.
200    *
201    * It is important to have as many releases as possible in sources/, because
202    * when you generate the documentation (reference pages most notably), the
203    * symbols there are considered "added" the first time they're encountered
204    * in the sources (so they'll appear more recent than they actually are).
205    ** End of leftover information ********************************************
206
207
208    When bin/mkreport runs later, it parses the .cache.bin file and produces
209    number of output files (interesting "leaf nodes" in a hash). Those 
210    files are filesystem interface to tree-level statistics, and can be
211    used in numerous ways, XInclude for example.
212    Like: "Interchange consists of <xi:include file='.../total.files'> files".
213    (Currently this is not available; bin/mkreport is outdated and broken, and
214    will be fixed when I come to needing it).
215
216
217  The XML "preprocessor" tool:
218    There's bin/pp tool which you can use to write larger blocks of
219    XML more conveniently. See the script itself for usage notes.
220
221  The "CVS CO/UP" script:
222    There's bin/coup tool that helps you manage sources/ directory.
223    See the script or the Makefile for invocation examples.
224    ('make git' and 'make up-<ver|all>' invoke bin/coup).
225
226
227
228  Autogeneration of the reference pages: ** IMPORTANT **
229  Creation of new documentation parts:   ** IMPORTANT **
230
231    When bin/stattree runs, it collects information about all the "symbols"
232    in the source it can find (symbols are anything: pragmas, global variables,
233    functions, tags, config directives ...).
234    It collects the symbol names together with all files
235    and line numbers (and few lines of context around them) where they
236    appear. This is the first step of reference pages autogeneration.
237
238    Some of the symbol information is derived from the source automatically;
239    other parts must be added manually by us. 
240
241    Please note that the symbol name must match the symbol used in the source,
242    although tags allowed to be used with two forms (dash and underscore).
243    
244    Let's take an example of "post_page" pragma (but the principle is the same
245    for any symbol). User-supplied information is found in either:
246    
247    o  refs/<symbol>/ directory, or
248    o  refs/<symbol> file, where multiple sections are defined using the 
249       __NAME__ <section> and __END__ tokens (similar to IC profiles ;-).
250       Everything outside __NAME__ <name> ... __END__ blocks is discarded
251       and can effectively be used as a comment area.
252
253    The refs/<symbol> single-file-based approach is now preferred. It's more
254    convenient, and keeps the number of files in Git to a minimum. The bin/editem
255    script advises to use it.
256    Use refs/<symbol>/* only in special cases (which is never, or close to it).
257    
258    Regardless of the way you document an item, the following information
259    is needed to consider the symbol documentation complete:
260
261      - Pieces that must be user-supplied because defaults are only placeholders:
262         purpose, synopsis, description, examples, see also
263
264      - Pieces that could be user-supplied but have meaningful default:
265         notes, bugs, authors, copyright
266
267      - Autogenerated (can be overriden if really neccesary):
268         id, name, symbol type, availability, source occurences
269
270
271    *** Obscure information START /// Not needed in general ***
272    * All of above fields can both be overriden or appended with user-supplied
273    * information:
274    *
275    *oo  refs/<symbol> method (one-file, the preferred way):
276    *
277    *   To fill the template of the reference page, you add content to sections
278    *   in the following way:
279    *
280    *   __NAME__ section name
281    *   section content
282    *   __END__
283    *
284    *   Over time it appeared we only want to append information and never
285    *   override it, so this method does not have a way to override a value
286    *   like refs/<symbol>/control (in multi-file method) can do.
287    * 
288    *oo  refs/<symbol>/* method (one-directory, multiple-files):
289    *
290    *   To unconditionally override values and/or provide one-liner contents, use
291    *   refs/<symbol>/control file. It has pretty much inflexible
292    *   "field: content" line format, but # comments can be used.
293    *
294    *   To append with information, you use refs/<symbol>/<X>, where <X> is
295    *   the name of an existing section, maybe followed by an arbitrary string.
296    *   With the exception of example files, you generally only create one
297    *   file for each section.
298    *   To supply more examples, you could keep them in an informal structure
299    *   like this:
300    *   refs/post_page/example
301    *   refs/post_page/example2
302    *   refs/post_page/example-relative_pages
303    *   refs/post_page/example:used-often
304    *   refs/post_page/example.something
305    *
306    *   (also, nothing prevents you from having more <example>s in the same file
307    *   if you like).
308    *
309    *   You can't use # comments in the non-control files (they'd be left as-is),
310    *   but you can use XML comments <!-- commented section -->.
311    *   To avoid having to escape all HTML entities and everything, simply
312    *   enclose "dirty" blocks in <![CDATA[ ... ]]>.
313    *** Obscure information END /// Not needed in general ***
314
315
316 ** To create the documentation for a yet non-existent item, your best bet
317 ** is to start off by copying an existing item over.
318
319 ** When adding documentation entries, please favor QUALITY over QUANTITY.
320 ** That means you should grep the whole Git repo for ALL information about a 
321 ** symbol (and supplement that with your own invaluable historical and
322 ** technical information), and then write the item documentation that
323 ** includes all that information.
324 ** Also make sure to check the actual symbol source; at many places I've
325 ** found undocumented options being present, and variables used or checked.
326
327 ** After you build the documentation, there will be a file named
328 ** tmp/missing autogenerated, and it will contain a list of symbols with all
329 ** the parts of the documentation they still miss for the item to be
330 ** considered complete. tmp/missing2 will also be created that will list
331 ** HOWTO items and glossary entries that need work.
332 ** Clearing out this list is a priority;
333 ** given that the new system is so convenient and cool, you have no excuse ;-)
334
335
336 Davor Ocelic, docelic@icdevgroup.org
337