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