[docs] xmldocs - docelic modified 2 files
docs at icdevgroup.org
docs at icdevgroup.org
Wed Sep 22 04:02:47 EDT 2004
User: docelic
Date: 2004-09-22 08:02:47 GMT
Modified: . TODO
Modified: bin refs-autogen
Log:
- bin/refs-autogen:
- It is now possible to create the FILE refs/SYMBOL_NAME and store
all documentation in it. So you don't have to use a directory
refs/SYBMOL_NAME/ and then create files in it. This is primarily to
reduce the number of files in the CVS.
Use like this (for example, refs/export-database):
__NAME__ description
Anything .. ..
__END__
__NAME__ example
..anything...
__END__
__NAME__ example-2
anything...
__END__
- If an item is completely undocumented, made the messages in tmp/missing
a lot shorter. (simply says "missing all" for an item)
- TODO: clear items
Revision Changes Path
1.20 +3 -11 xmldocs/TODO
rev 1.20, prev_rev 1.19
Index: TODO
===================================================================
RCS file: /var/cvs/xmldocs/TODO,v
retrieving revision 1.19
retrieving revision 1.20
diff -u -r1.19 -r1.20
--- TODO 21 Sep 2004 18:37:31 -0000 1.19
+++ TODO 22 Sep 2004 08:02:47 -0000 1.20
@@ -1,7 +1,5 @@
PRIMARY:
-- Support using refs/<filename> with all the documentation for a symbol
- instead of refs/<directory>/<files>.
- Stinky manpage stylesheets are a disaster. This time it's that
<cmdsynopsis> is verbatim and <screen> still renders comments without
newlines! I mean, what the... (And © is translated to crap instead
@@ -13,12 +11,9 @@
when modifying array/hash). It should be made so that we only modify
array/hash during the whole program, then in the last step before
generating the template they get stringified.
-- Visually identify obsolete items (those not present in cvs-head)
-- Add a note that we're focusing on really basic stuff that won't change
- over time (the criteria we used to determine what's for iccattut and what
- isn't)
-- not to forget, fix cases where context goes to negative values, and make
- cache target in Makefile
+- Visually mark obsolete items (those not present in cvs-head)
+- leaf nodes
+- not to forget, fix cases where context goes to negative values
- In iccattut:
- mention which paths would be valid for /usr/local tarball
@@ -36,9 +31,6 @@
- explain syntax accepted in profile files
DOCUMENTATION SYSTEM:
-- bin/stattree, in format_ctx(), see how many spacings all the lines have
- in common, and trim that from the beginning. [Did that, and the thing
- still doesn't work somehow].
- copy the definition for <example> to a
new name so we'll be able to differentiate between source chunks and
examples.
1.30 +58 -23 xmldocs/bin/refs-autogen
rev 1.30, prev_rev 1.29
Index: refs-autogen
===================================================================
RCS file: /var/cvs/xmldocs/bin/refs-autogen,v
retrieving revision 1.29
retrieving revision 1.30
diff -u -r1.29 -r1.30
--- refs-autogen 22 Sep 2004 06:55:58 -0000 1.29
+++ refs-autogen 22 Sep 2004 08:02:47 -0000 1.30
@@ -57,6 +57,7 @@
my %symbols; # FINAL symbol refentries
my %templates;
my $max_ctxs = 10;
+my @set_missing_all;
my @page_order = (qw/purpose default structure synopsis description example notes bugs/, "symbol type", "source", "author", "copyright", "see also");
@@ -357,6 +358,7 @@
}
# Output the 'invalid' list
+$invalid{$_} = ("Missing all (undocumented)") for @set_missing_all;
open INVOUT, "> tmp/missing" or
die "Can't open tmp/missing ($!)\n";
print INVOUT Dumper \%invalid;
@@ -445,37 +447,70 @@
# From other file sets
} elsif (! length $file) { # all files
- opendir INDIR, "refs/$name/" or do {
- push @{ $invalid{$name} }, "Missing directory (all other errors follow from this)";
- return;
- };
- while (my $fn = readdir INDIR) {
- next if $fn =~ /^\.|^CVS$/;
- 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)";
+ if ( -d "refs/$name" ) {
+ opendir INDIR, "refs/$name/" or do {
+ warn "Can't open refs/$name/ ($!)\n";
+ return
+ };
+ while (my $fn = readdir INDIR) {
+ next if $fn =~ /^\.|^CVS$/;
+ next if $fn eq 'control';
+ open INF, "< refs/$name/$fn" or
+ die "Can't open refs/$name/$fn ($!)\n";
+
+ my $sect = $fn;
+
+ my $content = join "", <INF>;
+ close INF;
+
+ update_field ("append", $name, $ref, $fn, $sect, $content);
}
-
- my $content = join "", <INF>;
- close INF;
+ closedir INDIR;
- if ( $mode eq 'override' ) {
- $$ref{$sect} = $content;
- } elsif ( $mode eq 'append' ) {
- $$ref{$sect} .= $content;
+ } elsif ( -f "refs/$name" ) {
+ open IN, "< refs/$name" or do {
+ warn "Can't open refs/$name ($!)\n";
+ return
+ };
+ my @c = <IN>;
+ close IN;
+
+ my ( $section, $content );
+ for my $line (@c) {
+ if ( $line =~ /^__NAME__ (.+)\s*$/ ) { $section = $1; next }
+ if ( $line =~ /^__END__/ ) {
+ update_field("append", $name, $ref, "refs/$name", $section, $content);
+ $section = "";
+ $content = "";
+ }
+ $content .= $line if $section;
}
+
+ } else {
+ push @set_missing_all, $name;
}
- closedir INDIR;
} else {
die "Parsing of specific, non-control files not implemented\n";
+ }
+}
+
+sub update_field {
+ my ($mode, $name, $sref, $fn, $sect, $content) = @_;
+
+ $sect =~ 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)";
+ }
+
+ if ( $mode eq 'override' ) {
+ $$sref{$sect} = $content;
+ } elsif ( $mode eq 'append' ) {
+ $$sref{$sect} .= $content;
}
}
More information about the docs
mailing list