[docs] xmldocs - docelic modified 9 files
docs at icdevgroup.org
docs at icdevgroup.org
Mon Aug 23 13:38:42 EDT 2004
User: docelic
Date: 2004-08-23 17:38:42 GMT
Modified: . TODO
Modified: bin refs-autogen stattree
Modified: cache/cvs-head .cache.bin
Modified: docbook xmldocs.css
Modified: refs/safe_data control notes
Added: refs/safe_data example-blockwide example-pagewide
Log:
- bin/refs-autogen:
- added comments
- minor fixes
- bin/stattree:
- added comments
- minor fixes
- cache/cvs-head/.cache.bin:
- new version
- docbook/xmldocs.css:
- added body background-color definition
- refs/safe_data/*:
- added examples
- added seeAlso item
- clarified notes
- TODO: items
Revision Changes Path
1.10 +8 -6 xmldocs/TODO
rev 1.10, prev_rev 1.9
Index: TODO
===================================================================
RCS file: /var/cvs/xmldocs/TODO,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- TODO 13 Aug 2004 21:09:15 -0000 1.9
+++ TODO 23 Aug 2004 17:38:41 -0000 1.10
@@ -2,12 +2,17 @@
DOCUMENTATION SYSTEM:
- Make docbook/symbol-type-skel/* contents of a glossary, and display a
glossary entry instead of those files.
-- For tags documentation, have a field if it's a container or not
+- For tags documentation, have a field if it's a container or not (and
+ also honor other tag details found in tag files)
- bin/stattree, in format_ctx(), see how many spacings all the lines have
- in common, and trim that.
+ in common, and trim that from the beginning.
- why in manpage format, comments at the top of the file are messed up (no
linebreaks)
-- remember which tag had _ instead of - in first UserTag line (email-raw)
+- Seems like there's no CSS selector to make a difference between an Example
+ element title, and Screen element title. (This causes source contexts
+ to be prefixed with "Example: ", although they're technically not).
+- Add support to document tags which are NOT found in separate files
+ (like [restrict]).
Mid-term:
- Think about adding "online example" (role=html in combination with
@@ -43,6 +48,3 @@
</para>
</epigraph>
-
-Old docs:
-docs/retired/icintro.sdf - history, intro, typical user session, security
1.20 +8 -15 xmldocs/bin/refs-autogen
rev 1.20, prev_rev 1.19
Index: refs-autogen
===================================================================
RCS file: /var/cvs/xmldocs/bin/refs-autogen,v
retrieving revision 1.19
retrieving revision 1.20
diff -u -r1.19 -r1.20
--- refs-autogen 14 Aug 2004 08:23:47 -0000 1.19
+++ refs-autogen 23 Aug 2004 17:38:41 -0000 1.20
@@ -43,12 +43,13 @@
my %longname = (
globvar => "Global Variable",
pragma => "Pragma",
- usertag => "User tag",
- uitag => "UI tag",
- systemtag => "System tag",
+ usertag => "User Tag",
+ uitag => "User Interface Tag",
+ systemtag => "System Tag",
);
# General description of symbol types
+# Move to docbook/docbookxi.dtd entities
my %general_desc;
opendir DIR, "docbook/symbol-type-skel";
while ( my $file = readdir DIR ) {
@@ -63,25 +64,15 @@
# Default fields
my %defaults = (
synopsis => "&DEF_SYNOPSIS;",
-
description => "&DEF_DESCRIPTION;",
-
example => "&DEF_EXAMPLE;",
-
notes => "&DEF_NOTES;",
-
bugs => "&DEF_BUGS;",
-
'symbol type' => "&DEF_SYMBOLTYPE;",
-
source => '&DEF_SOURCE;',
-
author => "&DEF_AUTHOR;",
-
copyright => "&DEF_COPYRIGHT;",
-
'see also' => "&DEF_SEEALSO;",
-
purpose => "&DEF_PURPOSE;",
);
@@ -176,13 +167,15 @@
my %ag = %$v;
# Do temporary-only modifications to %ag
+ # At the end of the whole block, save completely generated XML to
+ # %symbols hash.
# Double check
$ag{name} ||= $ag{id} || $k;
$ag{name} = $hash{specific}{$ag{name}}{_name} if
$hash{specific}{$ag{name}}{_name};
- # See Also "bidirectional" linking
+ # _See Also_ section: "bidirectional" linking
if ( defined @{ $ag{'_see also'} } ) {
my $list = $ag{'_see also'};
@$list = grep {$autogenerated{$_} and $_ ne $ag{name}} @$list;
@@ -256,7 +249,7 @@
}
-# Produce reference sets
+# Produce reference sets (docbook element Reference contains RefEntries)
while (my ($k,$v) = each %symbol_lists ) {
# Prepare reference page
1.13 +20 -24 xmldocs/bin/stattree
rev 1.13, prev_rev 1.12
Index: stattree
===================================================================
RCS file: /var/cvs/xmldocs/bin/stattree,v
retrieving revision 1.12
retrieving revision 1.13
diff -u -r1.12 -r1.13
--- stattree 13 Aug 2004 21:09:15 -0000 1.12
+++ stattree 23 Aug 2004 17:38:41 -0000 1.13
@@ -25,12 +25,13 @@
# Vars
my $verbose = 0;
my $cachedir = $ENV{CACHE} || "cache";
-my %hash;
+my %hash; # Will contain data to be dumped
my $cpath = $ENV{PWD};
+# Source contexts
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
+# All file types should be listed here or the stats wont. It should be
# reported if an unknown file is found in the archive
# Order is important. First match wins.
my %binary_types = (
@@ -58,12 +59,12 @@
variable => [qw|/vars/.+ /variables/.+|],
);
+
+# A general overview: how many different contents do we have
my $binary_types;
my $ascii_types;
for ( keys %binary_types ) { $binary_types += scalar @{ $binary_types{$_} } }
for ( keys %ascii_types ) { $ascii_types += scalar @{ $ascii_types{$_} } }
-
-# A general overview: how many different contents do we have
$hash{total}{known_types} = $binary_types + $ascii_types;
$hash{total}{known_binary_types} = $binary_types;
$hash{total}{known_ascii_types} = $ascii_types;
@@ -76,14 +77,12 @@
@ARGV == 1 or die "Usage: $0 path[/] \n";
-# $path is the dir to process, $dumppath is relocated name, say
+# $path is the directory to process, $dumppath is relocated name, say
# sources/cvs-head becomes output/cvs-head/cache
my $path = shift;
( my $dumppath = $path ) =~ s#.+?/##;
my $dumpdir = $dumppath;
-my %i = (
- ver => $dumpdir,
-);
+my %i = ( ver => $dumpdir );
$i{ver} =~ s/\/$//;
`mkdir -p $cachedir/$dumpdir` unless -e "$cachedir/$dumpdir";
$dumppath .= "/.cache.bin";
@@ -158,13 +157,17 @@
}
}
}
- # Unknown // TODO pay more attention to this
+ # Unknown // TODO pay more attention to this, this should rarely happen,
+ # even if we're not interested in some files, they *should* be matched
+ # in %ascii_types/%binary_types above to provide accurate statistics.
print STDERR "$file UNKNOWN\n" if $verbose;
return; # We're not interested in handling that
EXTDONE:
- # ftype, fsubtype and fext are known here
+ # file, ftype, fsubtype and fext are known here.
+ # file is filename, ftype is binary/ascii, fsubtype is key in
+ # %ascii_types/%binary_types hash, fext is extension
$hash{total}{$ftype."_files"}++;
$hash{total}{filetypes}{$fsubtype}++;
$hash{total}{matches}{$fext}++;
@@ -209,7 +212,8 @@
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";
+ "./configure script. Will use one from directory name. " .
+ "(This is OK for pre-5.0 versions).\n";
$hash{version} = $i{ver};
}
@@ -220,6 +224,7 @@
$hash{tree}{$file}{comments}++ ;
$hash{total}{perl_comments}++;
# TODO check if the comment contains ::log[A-Z]\w+
+ # to discover calls to logGlobal/logDebug
} elsif ( $line =~ /\s+#/ ) {
$hash{tree}{$file}{gray}++ ;
$hash{total}{perl_gray}++;
@@ -260,6 +265,7 @@
push @{ $hash{symbols}{globvar}{$5} },
[ "$i{ver}/$file", $lnum, "$gfunc[0]:$gfunc[1] $ctx_p\:$ctx_n", [format_ctx(@file[$lnum-$ctx_p..$lnum+$ctx_n])] ];
}
+ # A little catch
if ( $line =~ /\$Tag->var\s*\(\s*(["'])(\S+?)\1(\s*,\s*(\d))?/ ) {
push @{ $hash{symbols}{globvar}{$5} },
[ "$i{ver}/$file", $lnum, "$gfunc[0]:$gfunc[1] $ctx_p\:$ctx_n", [format_ctx(@file[$lnum-$ctx_p..$lnum+$ctx_n])] ];
@@ -297,7 +303,10 @@
[ "$i{ver}/$file", scalar @file, "1:" . scalar @file, [ format_ctx(@file) ] ];
# Now, try to autoconstruct tag synopsis
my %specific;
+
#my $warned;
+ # This is where we parse the tag file. We should discover settings like
+ # HasEndTag, Order, and so on.
for my $_l (@file) {
next unless $_l =~ /^usertag\s/i;
my @lis = split /\s+/, $_l;
@@ -312,19 +321,6 @@
#};
my $tn = shift @lis;
- # Unfortunately this sucks. Some files contain more tags defined
- # in them.
- # code/SystemTag/attr_list.coretag,
- # code/SystemTag/counter.coretag,
- # code/SystemTag/counter.coretag,
- # code/SystemTag/soap.coretag,
- # code/UI_Tag/jsq.coretag,
- # code/UserTag/email_raw.tag,
- # code/UserTag/forum.tag,
- # code/UserTag/loc.tag,
- # We'll deal with them later even though it will cause a small
- # incaccuracy. Either split to files, or to hack in support for this
- # in xmldocs tools, that would require more work.
#if ( $specific{_name} and ( $specific{_name} ne $tn )) {
# warn "HA! $file, managed to err on $specific{_name}/$tn)\n"
#}
1.10 +34304 -1949xmldocs/cache/cvs-head/.cache.bin
rev 1.10, prev_rev 1.9
Index: .cache.bin
===================================================================
RCS file: /var/cvs/xmldocs/cache/cvs-head/.cache.bin,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
Binary files /tmp/cvsFUChJd and /tmp/cvs3psiut differ
1.11 +1 -0 xmldocs/docbook/xmldocs.css
rev 1.11, prev_rev 1.10
Index: xmldocs.css
===================================================================
RCS file: /var/cvs/xmldocs/docbook/xmldocs.css,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -r1.10 -r1.11
--- xmldocs.css 13 Aug 2004 21:09:15 -0000 1.10
+++ xmldocs.css 23 Aug 2004 17:38:41 -0000 1.11
@@ -6,6 +6,7 @@
/* General */
+body { background-color: #fff; }
a { text-decoration: none; }
1.2 +1 -1 xmldocs/refs/safe_data/control
rev 1.2, prev_rev 1.1
Index: control
===================================================================
RCS file: /var/cvs/xmldocs/refs/safe_data/control,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- control 23 Jul 2004 13:32:02 -0000 1.1
+++ control 23 Aug 2004 17:38:42 -0000 1.2
@@ -8,7 +8,7 @@
# Just name the related symbols. The system will work everything out.
# (Note that if you link some item from here, that item will auto-point
# back here (under "indirect links" section))
-see also:
+see also: restrict
# Usually not needed to modify below
1.3 +1 -1 xmldocs/refs/safe_data/notes
rev 1.3, prev_rev 1.2
Index: notes
===================================================================
RCS file: /var/cvs/xmldocs/refs/safe_data/notes,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- notes 8 Aug 2004 20:05:25 -0000 1.2
+++ notes 23 Aug 2004 17:38:42 -0000 1.3
@@ -1 +1 @@
-Watch out for parse order with <tag>tag pragma</tag> or <tag>restrict</tag> when used with lists that retrieve data from the database (such as <tag>PREFIX-*</tag> or the flypage). Loops parse before regular tags like <tag>tag</tag> or <tag>restrict</tag>, and are thus not affected by it.
+Watch out for parse order with <tag>tag pragma</tag> or <tag>restrict</tag> when used with lists that retrieve data from the database (such as <tag>PREFIX-*</tag>, <tag>loop</tag>, or the flypage). Loops parse before regular tags like <tag>tag</tag>, and are thus not affected by them (so you must include the whole loop code in the "critical section").
1.1 xmldocs/refs/safe_data/example-blockwide
rev 1.1, prev_rev 1.0
Index: example-blockwide
===================================================================
<example>
<title>
Enabling safe_data block-wide
</title>
<para>
We'll restrict the available tags to <tag>area</tag> and <tag>page</tag>, and
enclose the critical section in <code>[tag pragma ...]</code>:
</para>
<programlisting><![CDATA[
[tag pragma safe_data]1[/tag]
...critical section...
[restrict area page]
...critical section...
[/restrict]
...critical section...
[tag pragma safe_data]0[/tag]
]]></programlisting>
</example>
1.1 xmldocs/refs/safe_data/example-pagewide
rev 1.1, prev_rev 1.0
Index: example-pagewide
===================================================================
<example>
<title>
Enabling safe_data page-wide
</title>
<para>
Add the following <emphasis>anywhere</emphasis> on an Interchange page:
</para>
<programlisting><![CDATA[
[pragma safe_data]
]]></programlisting>
</example>
More information about the docs
mailing list