Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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