[docs] xmldocs - docelic modified 2 files
docs at icdevgroup.org
docs at icdevgroup.org
Wed May 25 18:28:58 EDT 2005
User: docelic
Date: 2005-05-25 22:28:58 GMT
Modified: . Makefile README
Log:
- Improved Makefile completely now, for this turn
- Reflected README with current facts
Revision Changes Path
1.61 +3 -4 xmldocs/Makefile
rev 1.61, prev_rev 1.60
Index: Makefile
===================================================================
RCS file: /var/cvs/xmldocs/Makefile,v
retrieving revision 1.60
retrieving revision 1.61
diff -u -r1.60 -r1.61
--- Makefile 24 May 2005 21:42:18 -0000 1.60
+++ Makefile 25 May 2005 22:28:58 -0000 1.61
@@ -42,10 +42,9 @@
#############################################################
# Complete build
-all: $(foreach icver,$(IC_VERSIONS),cache/$(icver)/.cache.bin) \
- skel refxmls glossary howtos \
- olinks-nc olinks-c \
- guides symbols
+all: skel cvs cache refxmls \
+ olinkdbs-nc olinkdbs-c \
+ glossary symbols guides howtos
guides: $(foreach doc,$(GUIDES),OUTPUT/$(doc).html ) \
$(foreach doc,$(GUIDES),OUTPUT/$(doc))
1.16 +35 -40 xmldocs/README
rev 1.16, prev_rev 1.15
Index: README
===================================================================
RCS file: /var/cvs/xmldocs/README,v
retrieving revision 1.15
retrieving revision 1.16
diff -u -r1.15 -r1.16
--- README 24 May 2005 20:24:04 -0000 1.15
+++ README 25 May 2005 22:28:58 -0000 1.16
@@ -12,29 +12,14 @@
INTRODUCTION
The (new) Interchange XML documentation set is completely self-contained.
-To build the complete documentation set, run:
+To build the complete documentation set, just run:
make
- ^
-** ^ -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- **
-** ^-- Well, not really ;-| I didn't manage to get this totally right,
-so the (complete) procedure to build the docs is:
-
-( cvs checkout first, then: )
-make cvs cache skel
-make refxmls
-make olinkdbs-nc olinkdbs-c
-( and then the usual targets: )
-make glossary symbols guides howtos
-
-Also the problem is that the whole thing takes enormous time to build, even
-with xsltproc which is like by far the fastest docbook processor ;-)
-But well, on a >2GHz machine, it's bearable.
-It's possible now to change OUTPUT directory to something else, named
+It's also possible to change OUTPUT/ directory to something else, named
OUTPUT<yourstring>. However, places where I couldn't have inserted variables
-have OUTPUT/ hardcoded, so OUTPUT is made a symbolic link to the current
-output dir.
+have OUTPUT/ hardcoded, so OUTPUT is made a symbolic link to the output dir
+of your choice.
Here's an example:
@@ -49,7 +34,7 @@
targets would include:
-- Those that you would have to run manually:
- make cvs (to auto-create complete sources/ directory)
+ make cvs (to create complete sources/ directory, or update existing)
make clean (removes OUTPUT/)
make distclean (remove OUTPUT/ and tmp/)
make look-clean (clean + 'mv tmp tmp.temporary'. Useful to only make
@@ -59,12 +44,12 @@
regenerating OlinkDB files).
-- And those already covered by 'make':
- make caches
+ make skel
+ make cache
make refxmls
make olinkdbs-nc olinkdbs-c
- make tmp/iccattut-nc.db tmp/iccattut-c.db
- make skel
make OUTPUT/xmldocs.css
+ make tmp/iccattut-nc.db tmp/iccattut-c.db
make OUTPUT/iccattut.html OUTPUT/iccattut
See Makefile for a complete list, of course.
@@ -76,17 +61,22 @@
must be available:
- Perl
- - Shell commands: mkdir, cp, tar, gzip, bzip2
+ - Shell commands: mkdir, cp, ln, find, tar, gzip, bzip2
- docbook-xml
- docbook-xsl
- xsltproc
- exuberant-ctags
- - passivetex (not yet)
+ - passivetex
FINAL OUTPUT
During the invocation of 'make', few files will be created:
+
+ docbook/auto*.ent - Files containing XML entities that we can use in our
+ sources. For example, configuration directive Include is
+ referenced simply as &conf-Include;, tag [include] is
+ referenced simply as &tag-include;.
tmp/*.db - OLink DB files generated from source .xml files,
and other, on-the-fly .xmls.
@@ -109,6 +99,9 @@
and interlinked documentation set. Once it's created, you
can move it out of the build tree and package as you see
fit.
+
+ This can also be OUTPUT<yourprefix>, if you pass e.g.
+ OUTPUT=-std in a call to make (as shown near the top).
DEVELOPMENT NOTES
@@ -131,9 +124,7 @@
yourself, just drop it in there and someone will pick
it up.
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.
+ directory with all needed contents.
whatsnew - A directory containing whatsnew.xml, continuously updated
what's new list. The items are added automatically; just
place copies of the CVS commit messages in the whatsnew/
@@ -148,18 +139,21 @@
in directories named after release numbers (with the exception of
"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).
+ versions (or 'make up-<ver>' for specific). ('make cvs' can also be used
+ to update repositories).
- ** 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'.
+
+ ** Leftover information, not important for standard procedure: ************
+ * Once sources/ is 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 **
+ ** 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
@@ -180,6 +174,7 @@
('make cvs' and 'make up-<ver|all>' invoke bin/coup).
+
Autogeneration of the reference pages: ** IMPORTANT **
Creation of new documentation parts: ** IMPORTANT **
@@ -203,9 +198,9 @@
and can effectively be used as a comment area.
The refs/<symbol> single-file-based approach is now preferred. It's more
- convenient and keeps the number of files in CVS at minimum. The bin/editem
+ convenient, and keeps the number of files in CVS at minimum. The bin/editem
script advises to use it.
- Use refs/<symbol>/* only if you have special requirements.
+ Use refs/<symbol>/* only in special cases (which is never, or close to it).
Regardless of the way you document an item, the following information
is needed to consider the symbol documentation complete:
@@ -219,11 +214,12 @@
- Autogenerated (can be overriden if really neccesary):
id, name, symbol type, availability, source occurences
+
*** Obscure information START /// Not needed in general ***
* All of above fields can both be overriden or appended with user-supplied
* information:
*
- * o refs/<symbol> method (one-file):
+ *oo refs/<symbol> method (one-file, the preferred way):
*
* To fill the template of the reference page, you add content to sections
* in the following way:
@@ -236,7 +232,7 @@
* override it, so this method does not have a way to override a value
* like refs/<symbol>/control (in multi-file method) can do.
*
- * o refs/<symbol>/* method (one-directory, multiple-files):
+ *oo refs/<symbol>/* method (one-directory, multiple-files):
*
* To unconditionally override values and/or provide one-liner contents, use
* refs/<symbol>/control file. It has pretty much inflexible
@@ -264,9 +260,8 @@
*** Obscure information END /// Not needed in general ***
-** To create the documentation for a yet non-existant item or modify an
-** existing item, simply run bin/editem <name>. It will create all the
-** skeleton files, auto-let you edit the important files and do basic checks.
+** To create the documentation for a yet non-existant item, your best bet
+** is to start off by copying an existing item over.
** When adding documentation entries, please favor QUALITY over QUANTITY.
** That means you should grep the whole CVS for ALL information about a
More information about the docs
mailing list