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