[docs] xmldocs - docelic modified 15 files

docs at icdevgroup.org docs at icdevgroup.org
Wed Jul 21 16:13:31 EDT 2004


User:      docelic
Date:      2004-07-21 20:13:31 GMT
Modified:  .        Makefile README
Modified:  bin      mkreport stattree
Modified:  cache/cvs-head .cache.bin
Modified:  docbook  common.xsl html-chunks.xsl olinkdb.xml xmldocs.css
Added:     bin      editem refs-autogen
Added:     cache/4.6.0 .cache.bin
Added:     cache/4.8.0 .cache.bin
Added:     cache/5.0.0 .cache.bin
Added:     cache/5.2.0 .cache.bin
Log:
MODIFIED:

- Makefile: largely rewritten
- README: added notes

- bin/mkreport: when dumping to files, toplevel elements have the starting
  dot removed (previous .version file is now version).

- bin/stattree:
  - 10:4 context lines instead of previous 4:4
  - determine $hash{version} from ICVERSION= in configure
  - introduced helper variable $i{ver} back in because pre-5.0 versions
    don't have ICVERSION= in the configure file
  - now picks up old Pragma invocation syntax when determining pragmas
    in the source ($Vend::Cfg->{Pragma}{name}).

- docbook/common.xsl: turned off section.autolabel

- docbook/html-chunks.xsl: removed hardcoded 'iccattut' value

- docbook/xmldocs.css: changed colors, added refentry selectors

- docbook/olinkdb.xml: adjusted to a new naming scheme

ADDED:

- .cache.bin files: Added stattree information for more IC releases

- bin/editem: Helps writing new documentation items; see README for information

- bin/refs-autogen: Produces complete reference sets by autogenerating them.
  see README file.

Revision  Changes    Path
1.5       +126 -155  xmldocs/Makefile


rev 1.5, prev_rev 1.4
Index: Makefile
===================================================================
RCS file: /var/cvs/xmldocs/Makefile,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- Makefile	13 Jul 2004 11:58:57 -0000	1.4
+++ Makefile	21 Jul 2004 20:13:30 -0000	1.5
@@ -7,182 +7,153 @@
 # Base definitions
 SHELL = /bin/sh
 export OUTPUT = OUTPUT
-export CACHE  = cache
-export XML_CATALOG_FILES = $(DOCBOOKDIR)/catalog.xml
-DOCBOOKDIR = docbook
+export LTMPDIR = tmp
+export XML_CATALOG_FILES = docbook/catalog.xml
+DEFAULT_CATALOG = "/etc/xml/catalog"
 XSLT = xsltproc
-XSLT_FLAGS = --xinclude
-IC_VERSIONS = cvs-head
+XSLT_FLAGS = --xinclude --nonet
+XMLTO = xmlto
+XMLTO_FLAGS = --skip-validation
+IC_VERSIONS = 4.6.0 4.8.0 5.0.0 5.2.0 cvs-head
+
+VPATH = guides refs
 .SILENT:
 
-VPATH = guides
+############## No need to modify below ##############
 
-## ## ##
-# Future updates (as documentation expands) go here:
-GUIDES = $(OUTPUT)/iccattut.html $(OUTPUT)/iccattut
-OLINKDBS_UNCHUNKED = $(DOCBOOKDIR)/iccattut-nochunks-targets.db
-OLINKDBS_CHUNKED = $(DOCBOOKDIR)/iccattut-chunks-targets.db
-
-BASE_OUTPUT = output-skel image-files support-files css
-TREE_STATS = tree-cache tree-reports
-# END
-## ## ##
-#
-# Plain "make" cleans up and builds everything. To invoke targets 
-# manually, use names from the section above.
-# 
-# The targets not autobuilt are tree-stats, tags and objlists. They generate
-# files in cache/. cache/ contains information derived from IC
-# releases.
-# When you want to re-generate the cache information (because say,
-# CVS update happends), make sure the "sources" directory or symlink
-# points to a directory with the release you wish to update (for 
-# example, "cvs-head" or "5.2.0"), then run 'make cache'.
-# And don't forget to commit updated cache/ files (if any) to docs CVS.
+.PHONY: all guides refs %.man
 
-############## No need to modify below ##############
+all: guides refs
+	echo 'all' done
 
+guides: $(OUTPUT)/images $(OUTPUT)/files \
+  $(patsubst guides/%.xml,OUTPUT/%.html,$(wildcard guides/*.xml))  \
+  $(patsubst guides/%.xml,OUTPUT/%,$(wildcard guides/*.xml))
 
-.PHONY: $(BASE_OUTPUT) $(TREE_STATS) cache distclean clean FORCE
+refs: tmp/refs-autogen $(OUTPUT)/images $(OUTPUT)/files
+	make $(OUTPUT)/pragmas.html $(OUTPUT)/pragmas $(OUTPUT)/pragmas.man
+	make $(OUTPUT)/globvars.html $(OUTPUT)/globvars $(OUTPUT)/globvars.man
 
-all: distclean $(BASE_OUTPUT) $(TREE_STATS) \
-	$(OLINKDBS_UNCHUNKED) $(OLINKDBS_CHUNKED) \
-	$(GUIDES) final
-
-#
-# XML documentation
-#
-#@echo GOT $*-shortname / $?-all prereqs / $@-output.html / $<-first prereq
-$(OUTPUT)/%.html: %.xml $(DOCBOOKDIR)/* OUTPUT
-	# Unchunked document
-	$(XSLT) $(XSLT_FLAGS) \
-	        --stringparam current.docid $* \
-	        --stringparam target.database.document ../$(DOCBOOKDIR)/olinkdb.xml \
-	        -o $@ \
-	        $(DOCBOOKDIR)/html-nochunks.xsl $<
-
-$(OUTPUT)/%: %.xml $(DOCBOOKDIR)/* OUTPUT
-	# Chunked document
-	$(XSLT) $(XSLT_FLAGS) \
-	        --stringparam current.docid $* \
-	        --stringparam target.database.document ../$(DOCBOOKDIR)/olinkdb.xml \
-	        -o $(OUTPUT)/ \
-	        $(DOCBOOKDIR)/html-chunks.xsl $<
-
-#
-# OLink databases
-#
-$(DOCBOOKDIR)/%-nochunks-targets.db: %.xml
-	# Generate olink databases for unchunked html files
-	$(XSLT) $(XSLT_FLAGS) \
-	        --stringparam collect.xref.targets only \
-	        --stringparam targets.filename $@ \
-	        $(DOCBOOKDIR)/html-nochunks.xsl \
-	        $<
-
-$(DOCBOOKDIR)/%-chunks-targets.db: %.xml
-	# Generate olink databases for chunked html files
-	$(XSLT) $(XSLT_FLAGS) \
-	        --stringparam collect.xref.targets only \
-	        --stringparam targets.filename $@ \
-	        $(DOCBOOKDIR)/html-chunks.xsl \
-	        $<
-
-#
-# Support files
-#
-OUTPUT: $(BASE_OUTPUT)
-
-cache: tree-stats objlists tags
-
-objlists:
-	# Generate human-readable ctags information
-	-for p in $(IC_VERSIONS); do \
-		ctags -R -x --languages=perl --perl-kinds=cls sources/$$p/ \
-		> $(CACHE)/$$p/.objectlist.perl.txt; \
-		ctags -R -x --languages=c --c-kinds=cdf sources/$$p/ \
-		> $(CACHE)/$$p/.objectlist.c.txt; \
-		cd sources \
-	; done
 
-tags:
-	# Generate ctags information
-	-for p in $(IC_VERSIONS); do \
-		ctags -f $(CACHE)/$$p/.tags -R --extra=fq --fields=afikKlmnsSz --line-directives sources/$$p; \
-		cd sources \
-	; done
+#
+# All documents
+#
 
-tree-stats:
-	# Generate stats to bin dump 
-	# Only do that when sources/ is populated
-	-for p in $(IC_VERSIONS); do \
-		mkdir -p $(CACHE)/$$p; \
-		./bin/stattree sources/$$p \
-	; done
+# Unchunked documents
+$(OUTPUT)/%.html: %.xml $(OUTPUT)/xmldocs.css
+	$(XSLT) $(XSLT_FLAGS)                                          \
+	--stringparam current.docid $*                                 \
+	--stringparam target.database.document ../docbook/olinkdb.xml  \
+	-o $@ docbook/html-nochunks.xsl $<
 
-tree-reports:
-	# Make report from $(OUTPUT)/<ver>/.cache.bin
-	for p in $(IC_VERSIONS); do \
-		mkdir -p $(CACHE)/$$p; \
-		./bin/mkreport cache/$$p \
-	; done
+# Man pages
+$(OUTPUT)/%.man: %.xml
+	mkdir -p $(OUTPUT)/man
+	XML_CATALOG_FILES="$(DEFAULT_CATALOG)" $(XMLTO) $(XMLTO_FLAGS)    \
+	-o $(OUTPUT)/man/                                              \
+	man $<
 
-tree-cache:
-	# Copy tree stats to $(OUTPUT)
-	-for p in $(IC_VERSIONS); do \
-		cp -a $(CACHE)/$$p $(OUTPUT) \
-	; done
+# Chunked documents
+$(OUTPUT)/%: %.xml $(OUTPUT)/xmldocs.css
+	$(XSLT) $(XSLT_FLAGS)                                          \
+	--stringparam current.docid $*                                 \
+	--stringparam target.database.document ../docbook/olinkdb.xml  \
+	-o $@/ docbook/html-chunks.xsl $<
+	touch $@
+
+#
+# Support targets
+#
 
-output-skel:
-	# Mirror cache/ structure in output (actually, determine releases)
+tmp/mkreport: $(LTMPDIR)
+	./bin/mkreport $(IC_VERSIONS)
+	touch $@
+
+tmp/refs-autogen: $(LTMPDIR) bin/refs-autogen
+	./bin/refs-autogen $(IC_VERSIONS)
+	touch $@
+
+$(OUTPUT): $(LTMPDIR)
 	mkdir -p $(OUTPUT)
-	for p in $(IC_VERSIONS); do \
-	  mkdir -p $(OUTPUT)/$$p \
-	; done
-	mkdir -p $(OUTPUT)/images
-	mkdir -p $(OUTPUT)/files
 
-image-files: $(OUTPUT)/images
-	# Images
-	#cp images/*.{png,gif,jpg,jpeg} $(OUTPUT)/images/
-	-cp images/*.png $(OUTPUT)/images/
-
-support-files:
-	# Copy support files
-	cp -a files/* $(OUTPUT)/files/
+$(OUTPUT)/xmldocs.css: docbook/xmldocs.css $(OUTPUT)
+	cp docbook/xmldocs.css $(OUTPUT)/xmldocs.css
+
+$(OUTPUT)/images: $(wildcard images/*.jpg images/*.png images/*.gif)
+	mkdir -p $(OUTPUT)/images/
+	cp $(wildcard images/*.jpg images/*.png images/*.gif) $(OUTPUT)/images/
+
+$(OUTPUT)/files: files/*
+	rm -rf $(OUTPUT)/files
+	mkdir -p $(OUTPUT)/files/
 	cp bin/dbgen $(OUTPUT)/files/
-	cd files; for p in *; do \
-		if test "$$p" != "CVS"; then \
-			if test -d "$$p"; then \
-				tar cf ../$(OUTPUT)/files/$$p.tar $$p; \
-				tar zcf ../$(OUTPUT)/files/$$p.tgz $$p; \
-				tar jcf ../$(OUTPUT)/files/$$p.tbz2 $$p \
-			; fi \
-		; fi \
+	cd files; for p in *; do                                      \
+		if test "$$p" != "CVS"; then                              \
+			if test -d "$$p"; then                                \
+				cp -a $$p ../$(OUTPUT)/files/;                    \
+				tar cf ../$(OUTPUT)/files/$$p.tar $$p;            \
+				tar zcf ../$(OUTPUT)/files/$$p.tgz $$p;           \
+				tar jcf ../$(OUTPUT)/files/$$p.tbz2 $$p           \
+			; fi                                                  \
+		; fi                                                      \
 	; done
+	rm -rf `find $(OUTPUT)/files/ -name CVS`
 
-css:
-	# Copy css definitions
-	cp $(DOCBOOKDIR)/*.css $(OUTPUT)/
+$(LTMPDIR):
+	mkdir -p $(LTMPDIR)
 
-#
-# sources/ directory related
-# TODO Make target that conveniently checks out all IC releases from CVS,
-# sets them in appropriate directories under cache/ and runs the tree
-# statistics generator.
 
 #
+# Cleanup
 #
-#
-distclean clean:
-	-rm -rf $(OUTPUT)
-	-rm -f $(DOCBOOKDIR)/*.db
-	-for p in $(IC_VERSIONS); do \
-	  rm -f $(CACHE)/$$p/* \
-	; done
-
-final:
-	-rm -r `find $(OUTPUT) -name CVS`
 
-FORCE: ;
+clean:
+	-rm -rf $(OUTPUT)
 
+distclean: clean
+	-rm -rf $(LTMPDIR)
+	-rm -rf refs/*.xml
+	-for p in $(IC_VERSIONS); do rm cache/$$p/*; done
+
+
+# OLD
+#
+# OlinkDBs
+#
+# TODO OlinkDB targets get properly called implicitly by 
+# the above targets, but SOMEHOW the tmp/*.db files are not created.
+# Everything works fine if you run it manually. I really don't know
+# the problem here.
+# OlinkDB information for unchunked parts
+#$(LTMPDIR)/%-nc.db: %.xml $(LTMPDIR)
+#	$(XSLT) $(XSLT_FLAGS)                                          \
+#	--stringparam collect.xref.targets only                        \
+#	--stringparam targets.filename $@                              \
+#	docbook/html-nochunks.xsl $<
+#
+## OlinkDB information for chunked parts
+#$(TMPDIR)/%-c.db: %.xml $(TMPDIR)
+#	$(XSLT) $(XSLT_FLAGS)                                          \
+#	--stringparam collect.xref.targets only                        \
+#	--stringparam targets.filename $@                              \
+#	docbook/html-chunks.xsl $<
+#
+#
+#	# Generate human-readable ctags information
+#	-for p in $(IC_VERSIONS); do \
+#		ctags -R -x --languages=perl --perl-kinds=cls sources/$$p/ \
+#		> $(CACHE)/$$p/.objectlist.perl.txt; \
+#		ctags -R -x --languages=c --c-kinds=cdf sources/$$p/ \
+#		> $(CACHE)/$$p/.objectlist.c.txt; \
+#		cd sources \
+#	; done
+#
+#tags:
+#	# Generate ctags information
+#	-for p in $(IC_VERSIONS); do \
+#		ctags -f $(CACHE)/$$p/.tags -R --extra=fq --fields=afikKlmnsSz --line-directives sources/$$p; \
+#		cd sources \
+#	; done
+#
+## TODO Make target that conveniently checks out all IC releases from CVS
+#



1.3       +97 -14    xmldocs/README


rev 1.3, prev_rev 1.2
Index: README
===================================================================
RCS file: /var/cvs/xmldocs/README,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- README	12 Jul 2004 10:20:03 -0000	1.2
+++ README	21 Jul 2004 20:13:30 -0000	1.3
@@ -13,7 +13,12 @@
 
   make
 
-To build specific targets, see Makefile for target names.
+To build specific targets, see Makefile for target names. Few useful
+targets would include:
+
+  make guides
+  make refs
+  make OUTPUT/xmldocs.css
 
 
 PREREQUISITES
@@ -26,18 +31,26 @@
   - docbook-xml
   - docbook-xsl
   - xsltproc
+  - xmlto
 
 
 FINAL OUTPUT
 
 During the invocation of 'make', few files will be created:
   
-  docbook/*.db   - OLink DB files generated from source .xml files
-  
+  tmp/*.db       - OLink DB files generated from source .xml files
+                   (currently disabled), and other temporary files.
+
   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,
+                   simply get Interchange sources and run bin/stattree yourself.
   
   OUTPUT/        - Autogenerated:
                    directory containing the actual completely self-contained
@@ -48,34 +61,43 @@
 
 DEVELOPMENT NOTES
 
-
  The directory structure:
    Makefile      - Main Makefile
    bin           - Helper tools
    cache         - Interchange source trees metadata
    docbook       - DocBook XML support files
-   files         - Support files, such as examples etc.
+   files         - Support files, such as downloadable examples etc.
    guides        - Collection of guides
    howtos        - Collection of howtos
    refs          - Collection of reference pages
    images        - All images
-   tmp           - A scratch space and a kind of a pending/ directory.
+   tmp           - (not in CVS) Scratch and temporary file space
+   pending       - A "pending" directory.
                    If you have a chunk which you'd like to integrate in
                    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 
+                   use bin/stattree to generate the source tree information.
+                   Both sources/ and its subdirectories can be symlinks.
 
 
  Updating cache/:
    The dotfiles found in cache/ can only be generated when the sources/
-   directory is present, and contains Interchange releases in directories
-   named after release numbers (with the exception of "cvs-head").
-   (Or the "sources" file can be a symlink to the right location where
-   you keep such directory structure).
-
-   Once that's in place, add the appropriate version under IC_VERSIONS 
-   in the Makefile and run "make cache". This will regenerate files for
-   the versions you have.
+   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).
 
    As this is only rarely done (only when the release changes due to an
    important backport or something - and even then it probably doesn't 
@@ -92,6 +114,67 @@
    There's bin/pp tool which you can use to write XML more conveniently.
    See the script itself for usage notes.
 
+
+ Autogeneration of the reference pages: ** IMPORTANT **
+ Creation of new documentation parts:   ** IMPORTANT **
+
+   When bin/stattree runs, it also collects information about all the "symbols"
+   in the source it can find (symbols are anything: pragmas, global variables,
+   functions, tags, ...). It collects the symbol names together with all files
+   and line numbers (and few lines of context around them) where they
+   appear. This is the first step of reference pages autogeneration.
+
+   Some of the symbol information is derived from the source automatically;
+   other parts must be added manually by us. 
+   
+   Let's take an example of "post_page" pragma (but the principle is the same
+   for any symbol). User-supplied information is found in refs/<symbol>/
+   directory. Information which is needed to consider a symbol documentation
+   complete includes:
+
+     - 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
+
+   All of those fields can both be overriden or appended with user-supplied
+   information.
+   
+   To unconditionally override values and/or provide one-liner contents, use
+   refs/<symbol>/control file. It has pretty much inflexible "field: content"
+   line format, but # comments can be used.
+
+   To append with information, you use refs/<symbol>/<X>, where <X> is
+   the name of an existing section, maybe followed by an arbitrary string.
+   With the exception of example files, you generally only create one
+   file for each section.
+   To supply more examples, you could keep them in an informal structure
+   like this:
+	 refs/post_page/example
+	 refs/post_page/example2
+     refs/post_page/example-relative_pages
+     refs/post_page/example:used-often
+     refs/post_page/example.something
+
+   (also, nothing prevents you from having more <example>s in the same file
+   if you like).
+
+   You can't use # comments in the non-control files (they'd be left as-is),
+   but you can use XML comments <!-- commented section -->.
+   To avoid having to escape all HTML entities and everything, simply
+   enclose "dirty" blocks in <![CDATA[ ... ]]>.
+
+** 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.
+
+** When adding documentation entries, please favor QUALITY over QUANTITY.
+** That means you should grep the whole CVS for ALL information about a 
+** symbol (and supplement that with your own invaluable historical and
+** technical information), and then write the item documentation that
+** includes all that information.
 
 
 Davor Ocelic, docelic at icdevgroup.org



1.5       +4 -1      xmldocs/bin/mkreport


rev 1.5, prev_rev 1.4
Index: mkreport
===================================================================
RCS file: /var/cvs/xmldocs/bin/mkreport,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- mkreport	13 Jul 2004 11:58:58 -0000	1.4
+++ mkreport	21 Jul 2004 20:13:30 -0000	1.5
@@ -222,7 +222,10 @@
 	unless (ref $val eq 'HASH') {
 		$val = join("\n", @$val) if ( ref $val eq 'ARRAY' );
 		local $" = ".";
-		open OUT, "> $cachedir/$dumpdir/@$stack.$key" or
+		# Handle cases like $hash{version}, where it's a toplevel element
+		# without anything on @$stack.
+		( my $fout = "@$stack.$key" ) =~ s/^\.//;
+		open OUT, "> $cachedir/$dumpdir/$fout" or
 			die "Can't dump $dumpdir/@$stack.$key ($!)\n";
 		print OUT $val;
 		close OUT;



1.5       +37 -5     xmldocs/bin/stattree


rev 1.5, prev_rev 1.4
Index: stattree
===================================================================
RCS file: /var/cvs/xmldocs/bin/stattree,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- stattree	13 Jul 2004 11:58:58 -0000	1.4
+++ stattree	21 Jul 2004 20:13:30 -0000	1.5
@@ -27,8 +27,8 @@
 my $cachedir = $ENV{CACHE} || "cache";
 my %hash;
 my $cpath = $ENV{PWD};
-my $ctx_p = 1; # How much context lines to show before
-my $ctx_n = 1; #                                after
+my $ctx_p = 10; # How much context lines to show before
+my $ctx_n = 4; #                                after
 
 # All types should be listed here or the stats wont. It should be
 # reported if an unknown file is found in the archive
@@ -81,6 +81,11 @@
 my $path = shift;
 ( my $dumppath = $path ) =~ s#.+?/##;
 my $dumpdir = $dumppath;
+my %i = (
+	ver => $dumpdir,
+);
+$i{ver} =~ s/\/$//;
+`mkdir -p $cachedir/$dumpdir` unless -e "$cachedir/$dumpdir";
 $dumppath .= "/.cache.bin";
 
 # Convenient routine to just discover all files in a module
@@ -181,7 +186,31 @@
 		$hash{tree}{$file}{lines}++ ;
 		$hash{total}{lines}++ ;
 
-		if ( $fsubtype eq 'perl' ) {
+		# It's the main configure file, pick up the ICVERSION variable
+		if ( $file eq 'configure' ) {
+			for $_ (@file) {
+				if ( /^ICVERSION=(['"])(\d+\.\d+\.\d+)\1/ ) {
+					if ( !$hash{version} or "$hash{version}" eq "$2" ) {
+						$hash{version} = $2
+					} else {
+						die "I got inconsistent ^ICVERSION= information: " .
+							"existing is $hash{version}, new is $2. " . 
+							"Not continuing, fix manually\n";
+					}
+					# break; # We *could* stop processing here,
+					         # but we won't.
+				}
+			}
+			# ICVERSION must be known here, or someone's playing
+			unless ( $hash{version} ) {
+				warn "Wasn't able to determine " .
+					'^ICVERSION=([\'"])(\d+\.\d+\.\d+)\1 from the main ' .
+					"./configure script. Will use one from directory name.\n";
+				$hash{version} = $i{ver};
+			}
+
+		# Perl program file
+		} elsif ( $fsubtype eq 'perl' ) {
 			my $pod = 0;
 			if ( $line =~ /^\s*#/ ) {
 				$hash{tree}{$file}{comments}++ ;
@@ -209,8 +238,11 @@
 				# Discover pragmas
 				# Ph33r, PH33R my MaD R3G3X skiLLz! ;-)
 				# This matches $::Pragma->{} or $$::Pragma{}
-				if ( $line =~ /(()|\$())\$::Pragma(->\2|\3){(\w+?)}/ ) {
-					push @{ $hash{symbols}{pragma}{$5} },
+				#if ( $line =~ /(()|\$())\$::Pragma(->\2|\3){(\w+?)}/ ) {
+				if ( $line =~ /\$::Pragma->{(\w+?)}/ or 
+					$line =~ /\$Vend::Cfg->{Pragma}{(\w+?)}/ ) {
+					#push @{ $hash{symbols}{pragma}{$5} }, <- for use with above
+					push @{ $hash{symbols}{pragma}{$1} },
 						# TODO Here, and 2 places below: make sure if ctx is say, 5:5,
 						# it always shows that much (that is, workaround file beginning/
 						# file end problems).



1.1                  xmldocs/bin/editem


rev 1.1, prev_rev 1.0
Index: editem
===================================================================
#!/bin/sh

if test -z "$1"; then
	echo "No-go. Supply item to add/modify: $0 <name>"
fi

EDPROG="$EDITOR";
if test -z "$EDPROG"; then
	EDPROG=vim
fi

echo Creating/updating item $1
mkdir -p "refs/$1"
cp -i --reply=no docbook/item-skel/* "refs/$1"

echo Editing all item files
sleep 1
$EDPROG refs/$1/*

echo Removing empty files
rm `find "refs/$1" -size 0`

echo Done.




1.1                  xmldocs/bin/refs-autogen


rev 1.1, prev_rev 1.0
Index: refs-autogen
===================================================================
#!/usr/bin/perl

use warnings;
use strict;
use Fatal qw/chdir/;
use File::Find;
use Data::Dumper;
use Getopt::Long;
use Storable qw/nstore_fd fd_retrieve/;
use Fcntl qw/:DEFAULT :flock/;

{ no warnings;
$Data::Dumper::Indent = 1;
$Data::Dumper::Terse++;
$Data::Dumper::Sortkeys++;
}

my $force_regenerate = 1; # Rebuild pages even if they exist
my $dumpdb = 0;
my $verbose = 0;
my $OUTPUT = "OUTPUT";
my %refcache; # memory cache of Storable files. Not really needed but I 
              # copied old code which had it, so ...
my %hash; # complete tree data
my $cachedir = $ENV{CACHE} || "cache";
my %i; # internally derived data
my %autogenerated; # Data for symbols autogenerated in this run
my %invalid; # Information about missing documentation
my %covered; # Weed out duplicate context reports
my %symbol_lists; # symbols listed in categories
my %symbols; # FINAL symbol refentries
my @template = <DATA>;

my @page_order = (qw/purpose synopsis description example notes bugs/, "symbol type", "source", "author", "copyright", "see also");

unless ( GetOptions ( 
	"verbosedb|dumpdb|d!" => \$dumpdb,
	"verbose|v!" => \$verbose,
)) { die "Error parsing options\n" }

@ARGV > 0 or die "Usage: $0 version[s]\n";

my %longname = (
	globvar => "Global Variable",
	pragma => "Pragma",
);

# General description of symbol types
my %general_desc = (
	pragma => "Pragmas are.</para><para>Starting with Interchange 5.0, the \$Vend::Cfg->{Pragma}{name} syntax is abandoned in favor of \$::Pragma->{name}.",
	globvar => "Global variables are too.",
);

# Default fields
my %defaults = (
	synopsis => "No synopsis line",

	description => "No more specific information 
	was supplied. Interchange documentation is being reorganized, and
	we're also trying to fill in the missing pieces along the way.
	We appologize for inconvenience.",

	example => "No examples are available at this time. We do consider this a problem and will try to supply some.",

	notes => "None.",
	
	bugs => "There are no known bugs.</para><para>If you believe you've found a bug, please write to interchange-users\@icdevgroup.org or use <application>reportbug</application> to submit bugs in Debian GNU.",

	'symbol type' => "No symbol type information, this is strange.",

	source => '',

	author => "Interchange Development Group",
	
	copyright => "2004  Interchange Development Group
	</para><para>
	This documentation is free; you can redistribute it and/or modify it
	under the terms of the GNU General Public License as published by the
	Free Software Foundation; either version 2 of the License, or (at your
	option) any later version.",
	
	'see also' => "No information.",

	purpose => "description line missing",
);

my @mandatory = (qw/synopsis example description purpose/, "symbol type");


my $path;
my $dumppath;
my $dumpdir;
my @paths = @ARGV;
my $latest = $paths[$#paths];

while ( $path = shift @paths) {
	$dumppath = $path;
	$i{ver} = $dumppath;
	$dumpdir = "$dumppath/";
	$dumppath .= "/.cache.bin";

	# Load DB
	loaddb( "$cachedir/$dumppath" );

	# This fills %autogenerated
	# Outer loop: symbol types (pragmas, globvars, ...)
	# Inner loop: actual symbols
	while ( my ($gkey,$gval) = each %{ $hash{symbols} } ) {
		while ( my ($key,$val) = each %{ $gval } ) {
			push @{ $symbol_lists{$gkey} }, $key
			# ADDER
				unless grep {/^$key$/} @{ $symbol_lists{$gkey} };
			process_symbol($gkey, $key, $val);
			push @{ $autogenerated{$key}{"_available in"} }, $hash{version};
			$autogenerated{$key}{"available in"} =
				join ", ", @{ $autogenerated{$key}{"_available in"} };
		}
	}

	# Final entry. That's where we add source information and examples
	# (which don't have version-specific data, they're always "latest")
	if ( $path eq $latest ) {
		while ( my($k,$v) = each %autogenerated ) {
			my %ag = %$v;

			$ag{name} ||= $ag{id} || $k;

			for my $field (@page_order) {
				if ( ! $ag{$field} ) {
					if ( grep {/$field/} @mandatory) {
						push @{ $invalid{$k} },
							"Missing field '$field', using default";
					}
					$ag{$field} = $defaults{$field};
				}
			}

			# Do temporary-only modifications to %ag
			$ag{latest} = $hash{version};

			# Prepare source contexts, avoiding those cases
			# where a symbol appears multiple times inside the same
			# context lines span, but by stattree it gets counted
			# as a new context. (which is correct technically, but not
			# suitable for display).
			my $ar = $hash{symbols}{ $ag{"_symbol type"} }{$k};
			for my $ctx ( @$ar ) {
				my ($fi, $ln, $ctxsize, $ctxdata) = @$ctx;
				my $loc = "$fi:$ln";
				for my $arr ( @{ $covered{$k}{$fi} } ) {
					goto DONELOOP if $ln > $$arr[0] and $ln < $$arr[1];
				}
				my $ctxsdata = join "", @$ctxdata;
				$ag{source} .= <<ENDD;
<example>
	<title>$loc ($ctxsize)</title>
	
	<programlisting><![CDATA[
$ctxsdata
	]]></programlisting>
</example>

ENDD
				my ($less,$more) = split /:/, $ctxsize;
				push @{ $covered{$k}{$fi} }, [ $ln-$less, $ln+$more ];
				DONELOOP:
			}

			# Expand template
			my $template = join "", @template;
			{ no warnings;
			# I simply hate this, I can't find out which field
			# is undefined
			while ( $template =~ s/(\$ag{.*?})/$1/eem ) {};
			}

			# Save
			$symbols{$k} = $template;
		}
	}
}

# Produce reference sets
while (my ($k,$v) = each %symbol_lists ) {
	# Prepare reference page

	my $refpage = <<ENDD;
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DocBook-Interchange XML V4.2//EN"
	"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">

<reference>
	<title>Interchange Reference Pages: $longname{$k}s</title>
ENDD

	## Add items
	for my $item (@$v) {
		$refpage .= $symbols{$item}
	}

	## Close up
	$refpage .= "\n" . '</reference>';

	# Dump page
	open OUT, "> refs/${k}s.xml" or
		die "Can't produce reference refs/$k.xml ($!)\n";
	print OUT $refpage;
	close OUT;
}

# Output the 'invalid' list
open INVOUT, "> tmp/missing" or
	die "Can't open tmp/missing ($!)\n";
print INVOUT Dumper \%invalid;
close INVOUT;

exit 0;

#################################################################
# Helpers below

sub process_symbol {
	my ($group, $name, $ref) = @_;

	return if ref $autogenerated{$name};

	# Make skel
	$autogenerated{$name} = {
		name => $name,
		id => $name,
		"_symbol type" => $group,
		"symbol type" => $general_desc{$group},
	};

	# Suplement with information from a control file
	populate($autogenerated{$name}, $name, 'control', 'override');
	populate($autogenerated{$name}, $name, '', 'append');
}

sub populate {
	my ($ref, $name, $file, $mode) = @_;

	# From one specific file (control file usually)
	if ( $file ) {
		open IN, "< refs/$name/$file" or do {
			push @{ $invalid{$name} }, "Requested file '$file' ($!)";
			return;
		};
		if ( $file eq 'control' ) {
			while (my $line = <IN>) {
				next if $line =~ /^\s*#/;
				chomp $line;
				my ($sect,$text) = split /\s*:\s*/, $line, 2;
				goto SDONE if (!( defined $text and length $text ));
				if ( $mode eq 'override' ) {
					$$ref{lc $sect} = $text;
				} else {
					$$ref{lc $sect} .= '</para><para>' . $text;
				}
				SDONE:
			}
		}
		close IN;

	# From other file sets
	} elsif (! length $file) { # all files
		opendir INDIR, "refs/$name/" or do {
			push @{ $invalid{$name} }, "Missing directory";
			return;
		};
		while (my $fn = readdir INDIR) {
			next if $fn =~ /^\./;
			next if $fn eq 'control';
			open INF, "< refs/$name/$fn" or
				die "Can't open refs/$name/$fn ($!)\n";

			( my $sect = $fn ) =~ s/[\-\.\+_:\d].*//;
			$sect =~ s/([a-z])([A-Z])/$1 $2/g;
			$sect = lc $sect;

			if (!( grep {/^$sect/} @page_order )) {
				push @{ $invalid{$name} }, "Section '$sect' from file '$fn' won't be used (name not recognized)";
			}
			
			my $content = join "", <INF>;
			close INF;

			if ( $mode eq 'override' ) {
				$$ref{$sect} = $content;
			} elsif ( $mode eq 'append' ) {
				$$ref{$sect} .= $content;
			}
		}
		closedir INDIR;

	} else {
		die "Parsing of specific, non-control files not implemented\n";
	}
}

sub loaddb {
	my $dbpath = shift;

	unless ( exists $refcache{$dbpath} ) {
		open( IN, "< $dbpath") or
			die "Can't open database ($dbpath) ($!).\n";
		flock( IN, LOCK_SH ) or
			die "Can't shared-lock database ($dbpath) ($!).\n";
		$refcache{$dbpath} = fd_retrieve( \*IN );
		close IN or
			die "Can't properly close database ($dbpath) ($!).\n";
	}

	%hash = %{ $refcache{$dbpath} };

	if ( $dumpdb ) {
		print STDERR Dumper \%hash;
		exit 0;
	}
}

sub O { print "@_\n"; print STDOUT "@_\n" if $verbose }

__DATA__
<!--
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook-Interchange XML V4.2//EN"
	"/usr/share/xml/docbook/schema/dtd/4.2/docbookx.dtd">
-->

<refentry id="$ag{id}">

<refmeta>
<refentrytitle>$ag{"name"}</refentrytitle>
<manvolnum>7interchange</manvolnum>
<!--
<refmiscinfo class="date"></refmiscinfo>
<refmiscinfo class="source">Interchange</refmiscinfo>
-->
<refmiscinfo class="title">$ag{"name"}</refmiscinfo>
</refmeta>

<refnamediv>
<refname>$ag{"name"}</refname>
<refpurpose>$ag{"purpose"}</refpurpose>
</refnamediv>

<refsect1>
<title>SYNOPSIS</title>
$ag{"synopsis"}
</refsect1>

<refsect1>
<title>DESCRIPTION</title>
<para>$ag{"description"}</para>
</refsect1>

<refsect1>
<title>EXAMPLES</title>
$ag{"example"}
</refsect1>

<refsect1>
<title>NOTES</title>
<para>$ag{"notes"}</para>
</refsect1>

<refsect1>
<title>BUGS</title>
<para>$ag{"bugs"}</para>
</refsect1>

<refsect1>
<title>SYMBOL TYPE</title>
<para>$ag{"symbol type"}</para>
</refsect1>

<refsect1>
<title>AVAILABILITY</title>
<para>$ag{"name"} is available in the following Interchange 
versions (including intermediates):
</para><para>
$ag{"available in"}</para>
</refsect1>

<refsect1>
<title>SOURCE</title>
<para>A list of all the places the symbol appears in
in the current Interchange (cvs-head = $ag{"latest"})
development tree:</para>
$ag{source}
</refsect1>

<refsect1>
<title>AUTHORS</title>
<para>$ag{"author"}</para>
</refsect1>

<refsect1>
<title>COPYRIGHT</title>
<para>$ag{"copyright"}</para>
</refsect1>

<refsect1>
<title>SEE ALSO</title>
<para>$ag{"see also"}</para>
</refsect1>

</refentry>




1.1                  xmldocs/cache/4.6.0/.cache.bin


<<.cache.bin: data>>


1.1                  xmldocs/cache/4.8.0/.cache.bin


<<.cache.bin: data>>


1.1                  xmldocs/cache/5.0.0/.cache.bin


<<.cache.bin: data>>


1.1                  xmldocs/cache/5.2.0/.cache.bin


<<.cache.bin: data>>


1.5       +4371 -2425xmldocs/cache/cvs-head/.cache.bin


<<.cache.bin: data>>


1.3       +1 -1      xmldocs/docbook/common.xsl


rev 1.3, prev_rev 1.2
Index: common.xsl
===================================================================
RCS file: /var/cvs/xmldocs/docbook/common.xsl,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- common.xsl	12 Jul 2004 10:20:04 -0000	1.2
+++ common.xsl	21 Jul 2004 20:13:30 -0000	1.3
@@ -6,7 +6,7 @@
 	xmlns:xi="http://www.w3.org/2003/XInclude"
 	version="1.0">
 
-	<xsl:param name="section.autolabel">1</xsl:param>
+	<xsl:param name="section.autolabel">0</xsl:param>
 
 	<xsl:param name="admon.graphics">1</xsl:param>
 	<xsl:param name="admon.graphics.path">./images/</xsl:param>



1.3       +1 -1      xmldocs/docbook/html-chunks.xsl


rev 1.3, prev_rev 1.2
Index: html-chunks.xsl
===================================================================
RCS file: /var/cvs/xmldocs/docbook/html-chunks.xsl,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- html-chunks.xsl	11 Jul 2004 23:58:18 -0000	1.2
+++ html-chunks.xsl	21 Jul 2004 20:13:30 -0000	1.3
@@ -37,7 +37,7 @@
 
 	<xsl:param name="use.id.as.filename"/>
 	<xsl:param name="root.filename">index</xsl:param>
-	<xsl:param name="base.dir">iccattut/</xsl:param>
+	<!--<xsl:param name="base.dir">iccattut/</xsl:param>-->
 	<xsl:param name="chunk.fast">1</xsl:param>
 	<xsl:param name="chunk.section.depth">1</xsl:param>
 	<xsl:param name="chunker.output.encoding">ISO8859-1</xsl:param>



1.2       +2 -2      xmldocs/docbook/olinkdb.xml


rev 1.2, prev_rev 1.1
Index: olinkdb.xml
===================================================================
RCS file: /var/cvs/xmldocs/docbook/olinkdb.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- olinkdb.xml	11 Jul 2004 21:06:33 -0000	1.1
+++ olinkdb.xml	21 Jul 2004 20:13:30 -0000	1.2
@@ -7,8 +7,8 @@
 
 	<sitemap>
 		<dir name="OUTPUT"> 
-			<document targetdoc="iccattut" baseuri="docbook">
-				<xi:include href="iccattut-nochunks-targets.db"  
+			<document targetdoc="iccattut" baseuri="tmp">
+				<xi:include href="iccattut-nc.db"  
 					xmlns:xi="http://www.w3.org/2001/XInclude"/>
 			</document>
 		</dir>



1.2       +70 -0     xmldocs/docbook/xmldocs.css


rev 1.2, prev_rev 1.1
Index: xmldocs.css
===================================================================
RCS file: /var/cvs/xmldocs/docbook/xmldocs.css,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- xmldocs.css	11 Jul 2004 21:06:31 -0000	1.1
+++ xmldocs.css	21 Jul 2004 20:13:30 -0000	1.2
@@ -16,9 +16,74 @@
 	background-repeat: no-repeat;
 }
 
+h3.title {
+	/*background-color: #d5e1ff;*/
+	background-color: #e5ecff;
+	font-weight: normal;
+}
+
+
+/* Refentry */
+.refentry .refnamediv {
+	border: dotted 1px #ffcc66;
+	margin-top: 40px;
+	margin-bottom: 20px;
+}
+
+.refentry .refnamediv h2 {
+	background-color: #ffcc66;
+	margin: 0 0 0 0;
+	/*font-size: 0px;*/
+	padding-left: 10px;
+	font-size: small;
+	font-variant: small-caps;
+	border-top: dotted 1px #208cbd;
+	border-left: dotted 1px #208cbd;
+	border-right: dotted 1px #208cbd;
+	/*visibility: hidden;*/
+}
+
+.refentry .refnamediv p {
+	margin: 0 0 0 0;
+	padding: 2px 0px 2px 10px;
+	background-color: #ffcc66;
+	border: dotted 1px #208cbd;
+	border-top: none;
+	font-weight: bold;
+	/*font-stretch: semi-condensed;*/
+}
+
+.refsect1 h2 {
+	/*background-color: #ffcc66;*/
+	/*background-color: #d5e1ff;*/
+	background-color: #e5ecff;
+	padding: 2px 0px 2px 10px;
+	font-size: 90%;
+	/*font-variant: small-caps;*/
+	font-weight: bold;
+	/*font-stretch: semi-condensed;*/
+	/*font-size: small;*/
+	border: dotted 1px #208cbd;
+	/*border-right: none;
+	border-bottom: none;*/
+}
+
+.refsect1 p {
+	padding-left: 10px;
+}
+
+/* Refentry end */
+
+
 .toc {
 	border: dotted 1px #208cbd;
 	padding: 14px;
+	margin-bottom: 40px;
+}
+
+.example .title {
+	/*background-color: #d5e1ff;*/
+	background-color: transparent;
 }
 
 .programlisting, .screen {
@@ -30,6 +95,11 @@
 	background-image: url(images/example2.png);
 	background-position: top left;
 	background-repeat: no-repeat;
+}
+
+.refsect1 .example .programlisting {
+	background-image: none;
+	border: none;
 }
 
 hr {








More information about the docs mailing list