Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 338 lines (262 sloc) 14.107 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
a705400 @docelic Further s/cvs/git/ tunings
docelic authored
17 make git
eab1131 @docelic Initial revision
docelic authored
18 make
afb373e @docelic - Improved Makefile completely now, for this turn
docelic authored
19
3c0854c @docelic - three new reference pages
docelic authored
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.
4a1b532 @docelic - Makefile:
docelic authored
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
558a0d6 @docelic - Mention TARGET_RELEASE= to generate docs for specific Interchange
docelic authored
34 Also, it is possible to generate documentation for a specific Interchange
6dca116 @docelic * Few small updates, important is the introduction of manpages
docelic authored
35 release, such as 5.0.0 or 5.2.0. To do so, use TARGET env variable:
558a0d6 @docelic - Mention TARGET_RELEASE= to generate docs for specific Interchange
docelic authored
36
6dca116 @docelic * Few small updates, important is the introduction of manpages
docelic authored
37 TARGET="5.2.0" make refxmls
558a0d6 @docelic - Mention TARGET_RELEASE= to generate docs for specific Interchange
docelic authored
38
6dca116 @docelic * Few small updates, important is the introduction of manpages
docelic authored
39 Just make sure to have TARGET defined on each 'make' invocation.
558a0d6 @docelic - Mention TARGET_RELEASE= to generate docs for specific Interchange
docelic authored
40
c1660ad @docelic More clean build
docelic authored
41 ** -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- **
eab1131 @docelic Initial revision
docelic authored
42
02466d3 @docelic MODIFIED:
docelic authored
43 To build specific targets, see Makefile for target names. Few useful
44 targets would include:
45
4946375 @docelic - An easy commit to break the summer silence.
docelic authored
46 -- Those that are not part of 'make' routine:
a705400 @docelic Further s/cvs/git/ tunings
docelic authored
47 make git (to create complete sources/ directory, or update existing)
059348e @docelic - Makefile: fixes, updates
docelic authored
48 make clean (removes OUTPUT/)
49 make distclean (remove OUTPUT/ and tmp/)
f524dd8 @docelic - Updated README
docelic authored
50 make look-clean (clean + 'mv tmp tmp.temporary'. Useful to only make
059348e @docelic - Makefile: fixes, updates
docelic authored
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
4946375 @docelic - An easy commit to break the summer silence.
docelic authored
56 -- And those that are part of 'make':
afb373e @docelic - Improved Makefile completely now, for this turn
docelic authored
57 make skel
58 make cache
059348e @docelic - Makefile: fixes, updates
docelic authored
59 make refxmls
7d06b33 @docelic Some styling stuff.
docelic authored
60 make olinkdbs-nc olinkdbs-c
61 make OUTPUT/xmldocs.css
afb373e @docelic - Improved Makefile completely now, for this turn
docelic authored
62 make tmp/iccattut-nc.db tmp/iccattut-c.db
7d06b33 @docelic Some styling stuff.
docelic authored
63 make OUTPUT/iccattut.html OUTPUT/iccattut
4946375 @docelic - An easy commit to break the summer silence.
docelic authored
64 ...
059348e @docelic - Makefile: fixes, updates
docelic authored
65
66 See Makefile for a complete list, of course.
eab1131 @docelic Initial revision
docelic authored
67
68
69 PREREQUISITES
70
0130e5c @docelic - Make Makefile targets that depend on IC_VERSIONS non-fatal (elimina…
docelic authored
71 To perform a successful build, the following programs and modules
72 must be available:
eab1131 @docelic Initial revision
docelic authored
73
74 - Perl
22d6b68 @racke added make and cvs to prerequisites
racke authored
75 - Shell commands: mkdir, cp, ln, find, tar, gzip, bzip2, make
a705400 @docelic Further s/cvs/git/ tunings
docelic authored
76 - git-core
0130e5c @docelic - Make Makefile targets that depend on IC_VERSIONS non-fatal (elimina…
docelic authored
77 - docbook-xml
78 - docbook-xsl
eab1131 @docelic Initial revision
docelic authored
79 - xsltproc
3139e04 @docelic - guides/xmldocs.xml: guide about writing XMLDOCS (in progress)
docelic authored
80 - tetex-extra (and actually, packages it depends on)
6f44380 @docelic Comment updates, to test changed git hooks
docelic authored
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
eab1131 @docelic Initial revision
docelic authored
90
d2c6eee @docelic - Makefile: remove dependence on bin/stattree
docelic authored
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
4946375 @docelic - An easy commit to break the summer silence.
docelic authored
96 too - patches welcome).
d2c6eee @docelic - Makefile: remove dependence on bin/stattree
docelic authored
97
86b7c3e * Added some Gentoo-specific notes, such as a list of prerequisite
Kevin Walsh authored
98 On Gentoo GNU/Linux systems, the prerequisite ebuild packages are as follows:
99
100 - dev-lang/perl
a705400 @docelic Further s/cvs/git/ tunings
docelic authored
101 - dev-util/git
86b7c3e * Added some Gentoo-specific notes, such as a list of prerequisite
Kevin Walsh authored
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
eab1131 @docelic Initial revision
docelic authored
116 FINAL OUTPUT
117
118 During the invocation of 'make', few files will be created:
afb373e @docelic - Improved Makefile completely now, for this turn
docelic authored
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;.
eab1131 @docelic Initial revision
docelic authored
124
09c6b9a @docelic - bin/stattree and bin/refs-autogen:
docelic authored
125 tmp/*.db - OLink DB files generated from source .xml files,
059348e @docelic - Makefile: fixes, updates
docelic authored
126 and other, on-the-fly .xmls.
02466d3 @docelic MODIFIED:
docelic authored
127
eab1131 @docelic Initial revision
docelic authored
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
f524dd8 @docelic - Updated README
docelic authored
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 the CVS (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.
eab1131 @docelic Initial revision
docelic authored
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.
afb373e @docelic - Improved Makefile completely now, for this turn
docelic authored
146
147 This can also be OUTPUT<yourprefix>, if you pass e.g.
e4aa17a @docelic - Small fixes/updates to 6 existing files
docelic authored
148 OUTPUT=-std in a call to make (as already shown above).
eab1131 @docelic Initial revision
docelic authored
149
d2c6eee @docelic - Makefile: remove dependence on bin/stattree
docelic authored
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
eab1131 @docelic Initial revision
docelic authored
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
02466d3 @docelic MODIFIED:
docelic authored
165 files - Support files, such as downloadable examples etc.
eab1131 @docelic Initial revision
docelic authored
166 guides - Collection of guides
167 refs - Collection of reference pages
a0f2502 @docelic A large commit with many enhancements:
docelic authored
168 glossary - Collection of glossary items
eab1131 @docelic Initial revision
docelic authored
169 images - All images
059348e @docelic - Makefile: fixes, updates
docelic authored
170 tmp - Scratch and temporary file space
02466d3 @docelic MODIFIED:
docelic authored
171 pending - A "pending" directory.
eab1131 @docelic Initial revision
docelic authored
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.
a705400 @docelic Further s/cvs/git/ tunings
docelic authored
176 sources - (not in CVS). run 'make git' to auto-create this
afb373e @docelic - Improved Makefile completely now, for this turn
docelic authored
177 directory with all needed contents.
3e701cc @docelic - README: updates
docelic authored
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 CVS 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 check-in (or update) in CVS.
eab1131 @docelic Initial revision
docelic authored
184
185
186 Updating cache/:
187 The dotfiles found in cache/ can only be generated when the sources/
02466d3 @docelic MODIFIED:
docelic authored
188 directory is present as described above, and contains Interchange releases
189 in directories named after release numbers (with the exception of
a705400 @docelic Further s/cvs/git/ tunings
docelic authored
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
afb373e @docelic - Improved Makefile completely now, for this turn
docelic authored
193 to update repositories).
194
f524dd8 @docelic - Updated README
docelic authored
195
afb373e @docelic - Improved Makefile completely now, for this turn
docelic authored
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'.
f524dd8 @docelic - Updated README
docelic authored
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).
afb373e @docelic - Improved Makefile completely now, for this turn
docelic authored
205 ** End of leftover information ********************************************
206
eab1131 @docelic Initial revision
docelic authored
207
0130e5c @docelic - Make Makefile targets that depend on IC_VERSIONS non-fatal (elimina…
docelic authored
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.
059348e @docelic - Makefile: fixes, updates
docelic authored
212 Like: "Interchange consists of <xi:include file='.../total.files'> files".
3e701cc @docelic - README: updates
docelic authored
213 (Currently this is not available; bin/mkreport is outdated and broken, and
214 will be fixed when I come to needing it).
0130e5c @docelic - Make Makefile targets that depend on IC_VERSIONS non-fatal (elimina…
docelic authored
215
eab1131 @docelic Initial revision
docelic authored
216
217 The XML "preprocessor" tool:
a0f2502 @docelic A large commit with many enhancements:
docelic authored
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.
eab1131 @docelic Initial revision
docelic authored
220
059348e @docelic - Makefile: fixes, updates
docelic authored
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.
a705400 @docelic Further s/cvs/git/ tunings
docelic authored
224 ('make git' and 'make up-<ver|all>' invoke bin/coup).
059348e @docelic - Makefile: fixes, updates
docelic authored
225
eab1131 @docelic Initial revision
docelic authored
226
afb373e @docelic - Improved Makefile completely now, for this turn
docelic authored
227
02466d3 @docelic MODIFIED:
docelic authored
228 Autogeneration of the reference pages: ** IMPORTANT **
229 Creation of new documentation parts: ** IMPORTANT **
230
b377a02 @docelic - Minor improvements
docelic authored
231 When bin/stattree runs, it collects information about all the "symbols"
02466d3 @docelic MODIFIED:
docelic authored
232 in the source it can find (symbols are anything: pragmas, global variables,
059348e @docelic - Makefile: fixes, updates
docelic authored
233 functions, tags, config directives ...).
234 It collects the symbol names together with all files
02466d3 @docelic MODIFIED:
docelic authored
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.
9d547aa @racke add a warning for a trap i got into
racke authored
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).
02466d3 @docelic MODIFIED:
docelic authored
243
244 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
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 ;-).
059348e @docelic - Makefile: fixes, updates
docelic authored
250 Everything outside __NAME__ <name> ... __END__ blocks is discarded
251 and can effectively be used as a comment area.
252
3e701cc @docelic - README: updates
docelic authored
253 The refs/<symbol> single-file-based approach is now preferred. It's more
afb373e @docelic - Improved Makefile completely now, for this turn
docelic authored
254 convenient, and keeps the number of files in CVS at minimum. The bin/editem
059348e @docelic - Makefile: fixes, updates
docelic authored
255 script advises to use it.
afb373e @docelic - Improved Makefile completely now, for this turn
docelic authored
256 Use refs/<symbol>/* only in special cases (which is never, or close to it).
a0f2502 @docelic A large commit with many enhancements:
docelic authored
257
258 Regardless of the way you document an item, the following information
259 is needed to consider the symbol documentation complete:
02466d3 @docelic MODIFIED:
docelic authored
260
3e701cc @docelic - README: updates
docelic authored
261 - Pieces that must be user-supplied because defaults are only placeholders:
02466d3 @docelic MODIFIED:
docelic authored
262 purpose, synopsis, description, examples, see also
a0f2502 @docelic A large commit with many enhancements:
docelic authored
263
3e701cc @docelic - README: updates
docelic authored
264 - Pieces that could be user-supplied but have meaningful default:
265 notes, bugs, authors, copyright
059348e @docelic - Makefile: fixes, updates
docelic authored
266
3e701cc @docelic - README: updates
docelic authored
267 - Autogenerated (can be overriden if really neccesary):
268 id, name, symbol type, availability, source occurences
059348e @docelic - Makefile: fixes, updates
docelic authored
269
afb373e @docelic - Improved Makefile completely now, for this turn
docelic authored
270
3e701cc @docelic - README: updates
docelic authored
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 *
afb373e @docelic - Improved Makefile completely now, for this turn
docelic authored
275 *oo refs/<symbol> method (one-file, the preferred way):
3e701cc @docelic - README: updates
docelic authored
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 *
afb373e @docelic - Improved Makefile completely now, for this turn
docelic authored
288 *oo refs/<symbol>/* method (one-directory, multiple-files):
3e701cc @docelic - README: updates
docelic authored
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 ***
a0f2502 @docelic A large commit with many enhancements:
docelic authored
314
315
17ab073 @docelic * Some bringing up to date
docelic authored
316 ** To create the documentation for a yet non-existent item, your best bet
afb373e @docelic - Improved Makefile completely now, for this turn
docelic authored
317 ** is to start off by copying an existing item over.
02466d3 @docelic MODIFIED:
docelic authored
318
319 ** When adding documentation entries, please favor QUALITY over QUANTITY.
320 ** That means you should grep the whole CVS 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.
3e701cc @docelic - README: updates
docelic authored
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.
02466d3 @docelic MODIFIED:
docelic authored
326
c8b5f11 @docelic - Makefile: make distclean is now quiet as it should be
docelic authored
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
d2c6eee @docelic - Makefile: remove dependence on bin/stattree
docelic authored
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;
c8b5f11 @docelic - Makefile: make distclean is now quiet as it should be
docelic authored
333 ** given that the new system is so convenient and cool, you have no excuse ;-)
334
eab1131 @docelic Initial revision
docelic authored
335
336 Davor Ocelic, docelic@icdevgroup.org
337
Something went wrong with that request. Please try again.