[docs] xmldocs - docelic modified README
docs at icdevgroup.org
docs at icdevgroup.org
Wed Oct 20 17:31:10 EDT 2004
User: docelic
Date: 2004-10-20 21:31:09 GMT
Modified: . README
Log:
- Updated README
Revision Changes Path
1.11 +36 -32 xmldocs/README
rev 1.11, prev_rev 1.10
Index: README
===================================================================
RCS file: /var/cvs/xmldocs/README,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -r1.10 -r1.11
--- README 9 Oct 2004 20:33:34 -0000 1.10
+++ README 20 Oct 2004 21:31:09 -0000 1.11
@@ -20,17 +20,17 @@
To build specific targets, see Makefile for target names. Few useful
targets would include:
- - Those that you would have to run manually:
+ -- Those that you would have to run manually:
make cvs (to auto-create complete sources/ directory)
make clean (removes OUTPUT/)
make distclean (remove OUTPUT/ and tmp/)
- make look-clean (clean + mv tmp tmp.temporary. Useful to only make
+ make look-clean (clean + 'mv tmp tmp.temporary'. Useful to only make
the tree as if it is clean (to perform CVS operations
without errors), but then automatically rename
the directory back to 'tmp/' and avoid the overhead of
regenerating OlinkDB files).
- - And those covered by 'make':
+ -- And those covered by 'make':
make skel
make OUTPUT/xmldocs.css
make caches
@@ -65,14 +65,15 @@
cache/<ver>/* - Various Interchange source tree statistics, available
over a filesystem interface. (For XInclusion in .xml
sources and similar purposes). The files are generated
- from cache/<ver>/.cache.bin.
- .cache.bin itself is generated by bin/stattree, the files
- from it are created by bin/mkreport.
-
- The cache is Perl's portable Storable dump, and is only
- a convenience. If the binary is incompatible for you
- (which often happens to be the case), simply get
- Interchange sources and run bin/stattree yourself.
+ by bin/mkreport which depends on cache/<ver>/.cache.bin.
+ cache/<ver>/.cache.bin is generated by bin/stattree.
+
+ The cache is Perl's portable Storable dump. It was
+ originally kept in the CVS (so others could re-use it),
+ but that didn't play out well in practice so now everyone
+ building the docs needs to have the sources/ directory
+ ready and run 'make caches' himself to get the .bin
+ files generated.
OUTPUT/ - Autogenerated:
directory containing the actual completely self-contained
@@ -100,28 +101,30 @@
the docset, but don't have the time to prepare it
yourself, just drop it in there and someone will pick
it up.
- sources - (not in CVS). If you create this directory, and fill it
- in with subdirectories containing Interchange releases
- (say, 4.8.0/, 5.0.0/, 5.2.0, cvs-head/), then you can run
- 'make caches' to generate the source tree information.
- Now that we don't keep pre-generated cache files in the CVS,
- this will be automatically called during standard 'make'.
+ sources - (not in CVS). run 'make cvs' to auto-create this
+ directory with all needed contents. 'make cvs' is not
+ part of the global 'make' run, but 'make caches', which
+ needs to run after 'make cvs', is.
Updating cache/:
The dotfiles found in cache/ can only be generated when the sources/
directory is present as described above, and contains Interchange releases
in directories named after release numbers (with the exception of
- "cvs-head").
-
- Once that's in place, make sure all available versions are mentioned in
- Makefile's IC_VERSIONS variable, and then run 'make cache'.
- This will regenerate files for the versions you have.
-
- It is important to have as many releases as possible in sources/, because
- when you generate the documentation (reference pages most notably), the
- symbols there are considered "added" the first time they're encountered
- in the sources (so they'll appear more recent than they actually are).
+ "cvs-head"). Run 'make cvs' to create that sources/ directory with
+ all the contents. Run 'make up-all' to invoke cvs update on all
+ versions (or 'make up-<ver>' for specific).
+
+ ** Leftover information, not important for standard procedure: **
+ * Once that's in place, make sure all available versions are mentioned in
+ * Makefile's IC_VERSIONS variable, and then run 'make cache'.
+ * This will regenerate files for the versions you have.
+ *
+ * It is important to have as many releases as possible in sources/, because
+ * when you generate the documentation (reference pages most notably), the
+ * symbols there are considered "added" the first time they're encountered
+ * in the sources (so they'll appear more recent than they actually are).
+ ** End of leftover information **
When bin/mkreport runs later, it parses the .cache.bin file and produces
number of output files (interesting "leaf nodes" in a hash). Those
@@ -138,6 +141,7 @@
The "CVS CO/UP" script:
There's bin/coup tool that helps you manage sources/ directory.
See the script or the Makefile for invocation examples.
+ ('make cvs' and 'make up-<ver|all>' invoke bin/coup).
Autogeneration of the reference pages: ** IMPORTANT **
@@ -170,14 +174,14 @@
Regardless of the way you document an item, the following information
is needed to consider the symbol documentation complete:
- - autogenerated:
- id, name, symbol type, availability, source occurences
- - could be user-supplied but has meaningful default:
- notes, bugs, authors, copyright
- must be user-supplied because it only has placeholder defaults:
purpose, synopsis, description, examples, see also
+ - could be user-supplied but has meaningful default:
+ notes, bugs, authors, copyright
+ - autogenerated (can be overriden if really neccesary):
+ id, name, symbol type, availability, source occurences
- All of those fields can both be overriden or appended with user-supplied
+ All of above fields can both be overriden or appended with user-supplied
information:
o refs/<symbol> method (one-file):
More information about the docs
mailing list