[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