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