Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 226 lines (167 sloc) 9.012 kb
eab1131 Davor Ocelic Initial revision
docelic authored
1
2 The Interchange Development Group
3 http://www.icdevgroup.org
4
5 ICDEVGROUP Documentation Set
6 http://www.icdevgroup.org/cgi-bin/cvsweb/xmldocs/
7
a0f2502 Davor Ocelic A large commit with many enhancements:
docelic authored
8 This is a technical look at the XMLDOCS system, and it tells you how to get
9 the documentation generated. For the XMLDOCS authoring QuickStart, see
10 guides/xmldocs.xml (or that is OUTPUT/xmldocs.html after you run 'make').
11
eab1131 Davor Ocelic Initial revision
docelic authored
12
13 INTRODUCTION
14
15 The (new) Interchange XML documentation set is completely self-contained.
16 To build the complete documentation set, run:
17
18 make
19
02466d3 Davor Ocelic MODIFIED:
docelic authored
20 To build specific targets, see Makefile for target names. Few useful
21 targets would include:
22
23 make guides
24 make refs
09c6b9a Davor Ocelic - bin/stattree and bin/refs-autogen:
docelic authored
25
7b35729 Davor Ocelic - Makefile: added support for howtos
docelic authored
26 make OUTPUT/iccattut.html
27 make OUTPUT/iccattut
28 make OUTPUT/iccattut.man
09c6b9a Davor Ocelic - bin/stattree and bin/refs-autogen:
docelic authored
29
02466d3 Davor Ocelic MODIFIED:
docelic authored
30 make OUTPUT/xmldocs.css
7b35729 Davor Ocelic - Makefile: added support for howtos
docelic authored
31 make tmp/olinkdbs
a0f2502 Davor Ocelic A large commit with many enhancements:
docelic authored
32 make tmp/stattrees (same as 'make cache')
33 make tmp/refs-autogen (same as 'make refxmls')
eab1131 Davor Ocelic Initial revision
docelic authored
34
35
36 PREREQUISITES
37
0130e5c Davor Ocelic - Make Makefile targets that depend on IC_VERSIONS non-fatal (eliminate ...
docelic authored
38 To perform a successful build, the following programs and modules
39 must be available:
eab1131 Davor Ocelic Initial revision
docelic authored
40
41 - Perl
42 - Shell commands: mkdir, cp, tar, gzip, bzip2
0130e5c Davor Ocelic - Make Makefile targets that depend on IC_VERSIONS non-fatal (eliminate ...
docelic authored
43 - docbook-xml
44 - docbook-xsl
eab1131 Davor Ocelic Initial revision
docelic authored
45 - xsltproc
02466d3 Davor Ocelic MODIFIED:
docelic authored
46 - xmlto
7b35729 Davor Ocelic - Makefile: added support for howtos
docelic authored
47 - exuberant-ctags
48 - passivetex (for FO output - ps, pdf, ...) (not used yet)
eab1131 Davor Ocelic Initial revision
docelic authored
49
50
51 FINAL OUTPUT
52
53 During the invocation of 'make', few files will be created:
54
09c6b9a Davor Ocelic - bin/stattree and bin/refs-autogen:
docelic authored
55 tmp/*.db - OLink DB files generated from source .xml files,
56 and other temporary files.
02466d3 Davor Ocelic MODIFIED:
docelic authored
57
eab1131 Davor Ocelic Initial revision
docelic authored
58 cache/<ver>/* - Various Interchange source tree statistics, available
59 over a filesystem interface. (For XInclusion in .xml
60 sources and similar purposes). The files are generated
61 from cache/<ver>/.cache.bin.
02466d3 Davor Ocelic MODIFIED:
docelic authored
62 .cache.bin itself is generated by bin/stattree, the files
63 from it are created by bin/mkreport.
64
65 The cache is Perl's portable Storable dump, and is only
a0f2502 Davor Ocelic A large commit with many enhancements:
docelic authored
66 a convenience. If the binary is incompatible for you
67 (which often happens to be the case), simply get
68 Interchange sources and run bin/stattree yourself.
eab1131 Davor Ocelic Initial revision
docelic authored
69
70 OUTPUT/ - Autogenerated:
71 directory containing the actual completely self-contained
72 and interlinked documentation set. Once it's created, you
73 can move it out of the build tree and package as you see
74 fit.
75
76
77 DEVELOPMENT NOTES
78
79 The directory structure:
80 Makefile - Main Makefile
81 bin - Helper tools
82 cache - Interchange source trees metadata
83 docbook - DocBook XML support files
02466d3 Davor Ocelic MODIFIED:
docelic authored
84 files - Support files, such as downloadable examples etc.
eab1131 Davor Ocelic Initial revision
docelic authored
85 guides - Collection of guides
86 howtos - Collection of howtos
87 refs - Collection of reference pages
a0f2502 Davor Ocelic A large commit with many enhancements:
docelic authored
88 glossary - Collection of glossary items
eab1131 Davor Ocelic Initial revision
docelic authored
89 images - All images
02466d3 Davor Ocelic MODIFIED:
docelic authored
90 tmp - (not in CVS) Scratch and temporary file space
91 pending - A "pending" directory.
eab1131 Davor Ocelic Initial revision
docelic authored
92 If you have a chunk which you'd like to integrate in
93 the docset, but don't have the time to prepare it
94 yourself, just drop it in there and someone will pick
95 it up.
02466d3 Davor Ocelic MODIFIED:
docelic authored
96 sources - (not in CVS). If you create this directory, and fill it
97 in with subdirectories containing Interchange releases
b377a02 Davor Ocelic - Minor improvements
docelic authored
98 (say, 4.8.0/, 5.0.0/, 5.2.0, cvs-head/), then you can run
99 'make tmp/stattrees' to generate the source tree information.
eab1131 Davor Ocelic Initial revision
docelic authored
100
101
102 Updating cache/:
103 The dotfiles found in cache/ can only be generated when the sources/
02466d3 Davor Ocelic MODIFIED:
docelic authored
104 directory is present as described above, and contains Interchange releases
105 in directories named after release numbers (with the exception of
106 "cvs-head").
107
108 Once that's in place, make sure all available versions are mentioned in
109 Makefile's IC_VERSIONS variable, and then run 'make cache'.
110 This will regenerate files for the versions you have.
eab1131 Davor Ocelic Initial revision
docelic authored
111
02466d3 Davor Ocelic MODIFIED:
docelic authored
112 It is important to have as many releases as possible in sources/, because
113 when you generate the documentation (reference pages most notably), the
114 symbols there are considered "added" the first time they're encountered
115 in the sources (so they'll appear more recent than they actually are).
eab1131 Davor Ocelic Initial revision
docelic authored
116
117 As this is only rarely done (only when the release changes due to an
118 important backport or something - and even then it probably doesn't
0130e5c Davor Ocelic - Make Makefile targets that depend on IC_VERSIONS non-fatal (eliminate ...
docelic authored
119 change any figures because the updates are small), the generated dotfiles
eab1131 Davor Ocelic Initial revision
docelic authored
120 *are* kept in the CVS because they can be considered static.
121
0130e5c Davor Ocelic - Make Makefile targets that depend on IC_VERSIONS non-fatal (eliminate ...
docelic authored
122 When bin/mkreport runs later, it parses the .cache.bin file and produces
123 number of output files (interesting "leaf nodes" in a hash). Those
124 files are filesystem interface to tree-level statistics, and can be
125 used in numerous ways, XInclude for example.
b377a02 Davor Ocelic - Minor improvements
docelic authored
126 Like: Interchange consists of <xi:include file='.../total.files'> files.
a0f2502 Davor Ocelic A large commit with many enhancements:
docelic authored
127 (Currently this is not enabled).
0130e5c Davor Ocelic - Make Makefile targets that depend on IC_VERSIONS non-fatal (eliminate ...
docelic authored
128
eab1131 Davor Ocelic Initial revision
docelic authored
129
130 The XML "preprocessor" tool:
a0f2502 Davor Ocelic A large commit with many enhancements:
docelic authored
131 There's bin/pp tool which you can use to write larger blocks of
132 XML more conveniently. See the script itself for usage notes.
eab1131 Davor Ocelic Initial revision
docelic authored
133
134
02466d3 Davor Ocelic MODIFIED:
docelic authored
135 Autogeneration of the reference pages: ** IMPORTANT **
136 Creation of new documentation parts: ** IMPORTANT **
137
b377a02 Davor Ocelic - Minor improvements
docelic authored
138 When bin/stattree runs, it collects information about all the "symbols"
02466d3 Davor Ocelic MODIFIED:
docelic authored
139 in the source it can find (symbols are anything: pragmas, global variables,
140 functions, tags, ...). It collects the symbol names together with all files
141 and line numbers (and few lines of context around them) where they
142 appear. This is the first step of reference pages autogeneration.
143
144 Some of the symbol information is derived from the source automatically;
145 other parts must be added manually by us.
146
147 Let's take an example of "post_page" pragma (but the principle is the same
a0f2502 Davor Ocelic A large commit with many enhancements:
docelic authored
148 for any symbol). User-supplied information is found in either:
149
150 o refs/<symbol>/ directory, or
151 o refs/<symbol> file, where multiple sections are defined using the
152 __NAME__ <section> and __END__ tokens (similar to IC profiles ;-).
153
154 Regardless of the way you document an item, the following information
155 is needed to consider the symbol documentation complete:
02466d3 Davor Ocelic MODIFIED:
docelic authored
156
157 - autogenerated:
158 id, name, symbol type, availability, source occurences
159 - could be user-supplied but has meaningful default:
160 notes, bugs, authors, copyright
161 - must be user-supplied because it only has placeholder defaults:
162 purpose, synopsis, description, examples, see also
163
164 All of those fields can both be overriden or appended with user-supplied
a0f2502 Davor Ocelic A large commit with many enhancements:
docelic authored
165 information:
02466d3 Davor Ocelic MODIFIED:
docelic authored
166
a0f2502 Davor Ocelic A large commit with many enhancements:
docelic authored
167 o refs/<symbol>/* method (one-directory, multiple-files):
168
02466d3 Davor Ocelic MODIFIED:
docelic authored
169 To unconditionally override values and/or provide one-liner contents, use
170 refs/<symbol>/control file. It has pretty much inflexible "field: content"
171 line format, but # comments can be used.
172
173 To append with information, you use refs/<symbol>/<X>, where <X> is
174 the name of an existing section, maybe followed by an arbitrary string.
175 With the exception of example files, you generally only create one
176 file for each section.
177 To supply more examples, you could keep them in an informal structure
178 like this:
7b35729 Davor Ocelic - Makefile: added support for howtos
docelic authored
179 refs/post_page/example
180 refs/post_page/example2
b377a02 Davor Ocelic - Minor improvements
docelic authored
181 refs/post_page/example-relative_pages
182 refs/post_page/example:used-often
183 refs/post_page/example.something
02466d3 Davor Ocelic MODIFIED:
docelic authored
184
185 (also, nothing prevents you from having more <example>s in the same file
186 if you like).
187
188 You can't use # comments in the non-control files (they'd be left as-is),
189 but you can use XML comments <!-- commented section -->.
190 To avoid having to escape all HTML entities and everything, simply
191 enclose "dirty" blocks in <![CDATA[ ... ]]>.
192
a0f2502 Davor Ocelic A large commit with many enhancements:
docelic authored
193 o refs/<symbol> method (one-file):
194
195 All rules apply as above, except that instead of creating a new file
196 (say, refs/post_page/description), you add it to refs/post_page this way:
197
198 __NAME__ description
199 ...anything...
200 __END__
201
202 Over time it appeared we only want to append information and never
203 override it, so this method does not have a way to override a value
204 like refs/<symbol>/control file can do.
205
206
02466d3 Davor Ocelic MODIFIED:
docelic authored
207 ** To create the documentation for a yet non-existant item or modify an
208 ** existing item, simply run bin/editem <name>. It will create all the
209 ** skeleton files, auto-let you edit the important files and do basic checks.
210
211 ** When adding documentation entries, please favor QUALITY over QUANTITY.
212 ** That means you should grep the whole CVS for ALL information about a
213 ** symbol (and supplement that with your own invaluable historical and
214 ** technical information), and then write the item documentation that
215 ** includes all that information.
216
c8b5f11 Davor Ocelic - Makefile: make distclean is now quiet as it should be
docelic authored
217 ** After you build the documentation, there will be a file named
218 ** tmp/missing autogenerated, and it will contain a list of symbols with all
219 ** the parts of the documentation they still miss for the item to be
220 ** considered complete. Clearing out this list is a priority;
221 ** given that the new system is so convenient and cool, you have no excuse ;-)
222
eab1131 Davor Ocelic Initial revision
docelic authored
223
224 Davor Ocelic, docelic@icdevgroup.org
225
Something went wrong with that request. Please try again.