Skip to content

HTTPS clone URL

Subversion checkout URL

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