Skip to content
Newer
Older
100644 188 lines (140 sloc) 7.48 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
8
9 INTRODUCTION
10
11 The (new) Interchange XML documentation set is completely self-contained.
12 To build the complete documentation set, run:
13
14 make
15
02466d3 @docelic MODIFIED:
docelic authored Jul 21, 2004
16 To build specific targets, see Makefile for target names. Few useful
17 targets would include:
18
19 make guides
20 make refs
21 make OUTPUT/xmldocs.css
eab1131 @docelic Initial revision
docelic authored Jul 11, 2004
22
23
24 PREREQUISITES
25
0130e5c @docelic - Make Makefile targets that depend on IC_VERSIONS non-fatal (elimina…
docelic authored Jul 12, 2004
26 To perform a successful build, the following programs and modules
27 must be available:
eab1131 @docelic Initial revision
docelic authored Jul 11, 2004
28
29 - Perl
30 - 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
31 - docbook-xml
32 - docbook-xsl
eab1131 @docelic Initial revision
docelic authored Jul 11, 2004
33 - xsltproc
02466d3 @docelic MODIFIED:
docelic authored Jul 21, 2004
34 - xmlto
eab1131 @docelic Initial revision
docelic authored Jul 11, 2004
35
36
37 FINAL OUTPUT
38
39 During the invocation of 'make', few files will be created:
40
02466d3 @docelic MODIFIED:
docelic authored Jul 21, 2004
41 tmp/*.db - OLink DB files generated from source .xml files
42 (currently disabled), and other temporary files.
43
eab1131 @docelic Initial revision
docelic authored Jul 11, 2004
44 cache/<ver>/* - Various Interchange source tree statistics, available
45 over a filesystem interface. (For XInclusion in .xml
46 sources and similar purposes). The files are generated
47 from cache/<ver>/.cache.bin.
02466d3 @docelic MODIFIED:
docelic authored Jul 21, 2004
48 .cache.bin itself is generated by bin/stattree, the files
49 from it are created by bin/mkreport.
50
51 The cache is Perl's portable Storable dump, and is only
52 a convenience. If the binary is incompatible for you,
53 simply get Interchange sources and run bin/stattree yourself.
eab1131 @docelic Initial revision
docelic authored Jul 11, 2004
54
55 OUTPUT/ - Autogenerated:
56 directory containing the actual completely self-contained
57 and interlinked documentation set. Once it's created, you
58 can move it out of the build tree and package as you see
59 fit.
60
61
62 DEVELOPMENT NOTES
63
64 The directory structure:
65 Makefile - Main Makefile
66 bin - Helper tools
67 cache - Interchange source trees metadata
68 docbook - DocBook XML support files
02466d3 @docelic MODIFIED:
docelic authored Jul 21, 2004
69 files - Support files, such as downloadable examples etc.
eab1131 @docelic Initial revision
docelic authored Jul 11, 2004
70 guides - Collection of guides
71 howtos - Collection of howtos
72 refs - Collection of reference pages
73 images - All images
02466d3 @docelic MODIFIED:
docelic authored Jul 21, 2004
74 tmp - (not in CVS) Scratch and temporary file space
75 pending - A "pending" directory.
eab1131 @docelic Initial revision
docelic authored Jul 11, 2004
76 If you have a chunk which you'd like to integrate in
77 the docset, but don't have the time to prepare it
78 yourself, just drop it in there and someone will pick
79 it up.
02466d3 @docelic MODIFIED:
docelic authored Jul 21, 2004
80 sources - (not in CVS). If you create this directory, and fill it
81 in with subdirectories containing Interchange releases
82 (say, 4.8.0/, 5.0.0/, 5.2.0, cvs-head/), then you can
83 use bin/stattree to generate the source tree information.
84 Both sources/ and its subdirectories can be symlinks.
eab1131 @docelic Initial revision
docelic authored Jul 11, 2004
85
86
87 Updating cache/:
88 The dotfiles found in cache/ can only be generated when the sources/
02466d3 @docelic MODIFIED:
docelic authored Jul 21, 2004
89 directory is present as described above, and contains Interchange releases
90 in directories named after release numbers (with the exception of
91 "cvs-head").
92
93 Once that's in place, make sure all available versions are mentioned in
94 Makefile's IC_VERSIONS variable, and then run 'make cache'.
95 This will regenerate files for the versions you have.
eab1131 @docelic Initial revision
docelic authored Jul 11, 2004
96
02466d3 @docelic MODIFIED:
docelic authored Jul 21, 2004
97 It is important to have as many releases as possible in sources/, because
98 when you generate the documentation (reference pages most notably), the
99 symbols there are considered "added" the first time they're encountered
100 in the sources (so they'll appear more recent than they actually are).
eab1131 @docelic Initial revision
docelic authored Jul 11, 2004
101
102 As this is only rarely done (only when the release changes due to an
103 important backport or something - and even then it probably doesn't
0130e5c @docelic - Make Makefile targets that depend on IC_VERSIONS non-fatal (elimina…
docelic authored Jul 12, 2004
104 change any figures because the updates are small), the generated dotfiles
eab1131 @docelic Initial revision
docelic authored Jul 11, 2004
105 *are* kept in the CVS because they can be considered static.
106
0130e5c @docelic - Make Makefile targets that depend on IC_VERSIONS non-fatal (elimina…
docelic authored Jul 12, 2004
107 When bin/mkreport runs later, it parses the .cache.bin file and produces
108 number of output files (interesting "leaf nodes" in a hash). Those
109 files are filesystem interface to tree-level statistics, and can be
110 used in numerous ways, XInclude for example.
111
eab1131 @docelic Initial revision
docelic authored Jul 11, 2004
112
113 The XML "preprocessor" tool:
114 There's bin/pp tool which you can use to write XML more conveniently.
115 See the script itself for usage notes.
116
117
02466d3 @docelic MODIFIED:
docelic authored Jul 21, 2004
118 Autogeneration of the reference pages: ** IMPORTANT **
119 Creation of new documentation parts: ** IMPORTANT **
120
121 When bin/stattree runs, it also collects information about all the "symbols"
122 in the source it can find (symbols are anything: pragmas, global variables,
123 functions, tags, ...). It collects the symbol names together with all files
124 and line numbers (and few lines of context around them) where they
125 appear. This is the first step of reference pages autogeneration.
126
127 Some of the symbol information is derived from the source automatically;
128 other parts must be added manually by us.
129
130 Let's take an example of "post_page" pragma (but the principle is the same
131 for any symbol). User-supplied information is found in refs/<symbol>/
132 directory. Information which is needed to consider a symbol documentation
133 complete includes:
134
135 - autogenerated:
136 id, name, symbol type, availability, source occurences
137 - could be user-supplied but has meaningful default:
138 notes, bugs, authors, copyright
139 - must be user-supplied because it only has placeholder defaults:
140 purpose, synopsis, description, examples, see also
141
142 All of those fields can both be overriden or appended with user-supplied
143 information.
144
145 To unconditionally override values and/or provide one-liner contents, use
146 refs/<symbol>/control file. It has pretty much inflexible "field: content"
147 line format, but # comments can be used.
148
149 To append with information, you use refs/<symbol>/<X>, where <X> is
150 the name of an existing section, maybe followed by an arbitrary string.
151 With the exception of example files, you generally only create one
152 file for each section.
153 To supply more examples, you could keep them in an informal structure
154 like this:
155 refs/post_page/example
156 refs/post_page/example2
157 refs/post_page/example-relative_pages
158 refs/post_page/example:used-often
159 refs/post_page/example.something
160
161 (also, nothing prevents you from having more <example>s in the same file
162 if you like).
163
164 You can't use # comments in the non-control files (they'd be left as-is),
165 but you can use XML comments <!-- commented section -->.
166 To avoid having to escape all HTML entities and everything, simply
167 enclose "dirty" blocks in <![CDATA[ ... ]]>.
168
169 ** To create the documentation for a yet non-existant item or modify an
170 ** existing item, simply run bin/editem <name>. It will create all the
171 ** skeleton files, auto-let you edit the important files and do basic checks.
172
173 ** When adding documentation entries, please favor QUALITY over QUANTITY.
174 ** That means you should grep the whole CVS for ALL information about a
175 ** symbol (and supplement that with your own invaluable historical and
176 ** technical information), and then write the item documentation that
177 ** includes all that information.
178
c8b5f11 @docelic - Makefile: make distclean is now quiet as it should be
docelic authored Jul 21, 2004
179 ** After you build the documentation, there will be a file named
180 ** tmp/missing autogenerated, and it will contain a list of symbols with all
181 ** the parts of the documentation they still miss for the item to be
182 ** considered complete. Clearing out this list is a priority;
183 ** given that the new system is so convenient and cool, you have no excuse ;-)
184
eab1131 @docelic Initial revision
docelic authored Jul 11, 2004
185
186 Davor Ocelic, docelic@icdevgroup.org
187
Something went wrong with that request. Please try again.