[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
- 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
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 @@
 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:
-   ^
-** ^  -- -- --   -- -- -- --   -- -- -- --   -- -- -- --   -- -- -- --  **
-** ^-- 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
 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
+                   This can also be OUTPUT<yourprefix>, if you pass e.g.
+                   OUTPUT=-std in a call to make (as shown near the top).
@@ -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