Skip to content

HTTPS clone URL

Subversion checkout URL

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