[docs] xmldocs - docelic modified 8 files
docs at icdevgroup.org
docs at icdevgroup.org
Fri Aug 13 17:09:16 EDT 2004
User: docelic
Date: 2004-08-13 21:09:16 GMT
Modified: . TODO
Modified: bin refs-autogen stattree
Modified: docbook common.xsl docbookxi.dtd xmldocs.css
Modified: docbook/item-skel synopsis
Modified: docbook/symbol-type-skel pragma
Log:
- bin/refs-autogen:
- turn default text into xml entities so they can be used from within
refs/*/* files. (simply call &DEF_name; )
- enable generation of tags (which was disabled)
- make possible for bin/stattree to override item name
(over $hash{specific}{...} fields. this comes handy when tag name is not
the same as filename it's contained in).
- disable inclusion of autogenerate synopsis line for tags (needs work)
- ENABLE EXCLUSION OF ITEMS from autogenerated list if you simply add
ignore: yes|1|do in their refs/<name>/control file.
- Shorten a lot of text in autogenerated pages; remove all unnecessary
parts (as Jon suggested to remove excessive verbosity)
- bin/stattree:
- EXCLUDE m#^(eg|extra|SPECS|debian|scripts|extensions)/# directories from
parsing
- add $hash{specific}{...} fields where various info can be added to take
precedence later in bin/refs-autogen
- docbook/common.xsl:
- Dont leave examples prefixless, leave "Example: " string visible.
This is good in manpages where otherwise you have no visual indication of
a new example beginning.
- Add xml entities (from bin/refs-autogen)
- docbook/xmldocs.css:
- add bottom margin around example
- docbook/item-skel/synopsis:
- fix a missing bracket
- add more comment
- docbook/symbol-type-skel/pragma:
- fix wording
Revision Changes Path
1.9 +7 -0 xmldocs/TODO
rev 1.9, prev_rev 1.8
Index: TODO
===================================================================
RCS file: /var/cvs/xmldocs/TODO,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- TODO 9 Aug 2004 15:53:57 -0000 1.8
+++ TODO 13 Aug 2004 21:09:15 -0000 1.9
@@ -5,6 +5,9 @@
- For tags documentation, have a field if it's a container or not
- bin/stattree, in format_ctx(), see how many spacings all the lines have
in common, and trim that.
+- 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)
Mid-term:
- Think about adding "online example" (role=html in combination with
@@ -39,3 +42,7 @@
thus a source of civilized delight.
</para>
</epigraph>
+
+
+Old docs:
+docs/retired/icintro.sdf - history, intro, typical user session, security
1.18 +31 -31 xmldocs/bin/refs-autogen
rev 1.18, prev_rev 1.17
Index: refs-autogen
===================================================================
RCS file: /var/cvs/xmldocs/bin/refs-autogen,v
retrieving revision 1.17
retrieving revision 1.18
diff -u -r1.17 -r1.18
--- refs-autogen 8 Aug 2004 20:05:21 -0000 1.17
+++ refs-autogen 13 Aug 2004 21:09:15 -0000 1.18
@@ -1,4 +1,4 @@
-#!/usr/bin/perl
+!/usr/bin/perl
use warnings;
use strict;
@@ -62,36 +62,27 @@
# Default fields
my %defaults = (
- synopsis => "No synopsis line",
+ synopsis => "&DEF_SYNOPSIS;",
- 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.",
+ description => "&DEF_DESCRIPTION;",
- example => "No examples are available at this time. We do consider this a problem and will try to supply some.",
+ example => "&DEF_EXAMPLE;",
- notes => "None.",
+ notes => "&DEF_NOTES;",
- 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.",
+ bugs => "&DEF_BUGS;",
- 'symbol type' => "No symbol type information, this is strange.",
+ 'symbol type' => "&DEF_SYMBOLTYPE;",
- source => '',
+ source => '&DEF_SOURCE;',
- author => "Interchange Development Group",
+ author => "&DEF_AUTHOR;",
- copyright => "2004 Interchange Development Group
- </para><para>
- This documentation and the source code are free; you can redistribute
- them and/or modify them
- 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.",
+ copyright => "&DEF_COPYRIGHT;",
- 'see also' => "No information.",
+ 'see also' => "&DEF_SEEALSO;",
- purpose => "description line missing",
+ purpose => "&DEF_PURPOSE;",
);
my @mandatory = (qw/synopsis example description purpose/, "symbol type");
@@ -117,7 +108,8 @@
# Outer loop: symbol types (pragmas, globvars, ...)
# Inner loop: actual symbols
while ( my ($gkey,$gval) = each %{ $hash{symbols} } ) {
- next unless $gkey =~ /^(globvar|pragma)$/;
+ # Let's include tags now, disable the skip
+ #next unless $gkey =~ /^(globvar|pragma)$/;
for my $key (keys(%$gval)) {
my $val = $gval->{$key};
push @{ $symbol_lists{$gkey} }, $key
@@ -177,6 +169,7 @@
}
}
+### THIS IS LAST RUN ###
# Final entry. That's where we add examples
# (which don't have version-specific data, they're always "latest")
while ( my($k,$v) = each %autogenerated ) {
@@ -186,6 +179,8 @@
# Double check
$ag{name} ||= $ag{id} || $k;
+ $ag{name} = $hash{specific}{$ag{name}}{_name} if
+ $hash{specific}{$ag{name}}{_name};
# See Also "bidirectional" linking
if ( defined @{ $ag{'_see also'} } ) {
@@ -239,6 +234,13 @@
}
}
+
+ # SYNOPSIS LINE
+ #if ( $ag{'_symbol type'} =~ /tag$/ ) {
+ # $ag{synopsis} = "[$ag{name} @{ $hash{specific}{$ag{name}}{order} }]";
+ #}
+
+ # DONE
$ag{latest} = $hash{version};
# Expand template
@@ -250,7 +252,7 @@
}
# Save
- $symbols{$k} = $template;
+ $symbols{$k} = $template unless ( $ag{ignore} and $ag{ignore} =~ /[y1d]/i );
}
@@ -268,7 +270,7 @@
## Add items
for my $item (sort @$v) {
- $refpage .= $symbols{$item}
+ $refpage .= $symbols{$item} if $symbols{$item}
}
## Close up
@@ -451,17 +453,15 @@
<refsect1>
<title>AVAILABILITY</title>
-<para>$ag{"name"} is available in the following Interchange
-versions (including intermediates):
+<para>$ag{"name"} is available in Interchange versions:
</para><para>
$ag{"available in"}</para>
</refsect1>
<refsect1>
<title>SOURCE</title>
-<para>The current Interchange development version (cvs-head) is $ag{"latest"}.
-The symbol last appears in Interchange $ag{"source ver"}, in the
-following contexts:</para>
+<para>Interchange $ag{"source ver"}:
+</para>
$ag{source}
</refsect1>
@@ -472,12 +472,12 @@
<refsect1>
<title>BUGS</title>
-<para>$ag{"bugs"}</para>
+$ag{"bugs"}
</refsect1>
<refsect1>
<title>COPYRIGHT</title>
-<para>$ag{"copyright"}</para>
+$ag{"copyright"}
</refsect1>
<refsect1>
1.12 +94 -43 xmldocs/bin/stattree
rev 1.12, prev_rev 1.11
Index: stattree
===================================================================
RCS file: /var/cvs/xmldocs/bin/stattree,v
retrieving revision 1.11
retrieving revision 1.12
diff -u -r1.11 -r1.12
--- stattree 8 Aug 2004 20:05:21 -0000 1.11
+++ stattree 13 Aug 2004 21:09:15 -0000 1.12
@@ -175,6 +175,10 @@
# No more job with binary files
return if $ftype eq 'binary';
+ # Also ignore some directories (don't parse contents in them)
+ # (following a -core discussion from Aug 2004).
+ return if $file =~ m#^(eg|extra|SPECS|debian|scripts|extensions)/#;
+
# Open text file, parse contents
open IN, "< $file" or die "Can't open $file ($!)\n";
my @file = <IN>;
@@ -288,10 +292,50 @@
$file =~ m#(\w+?)\.(core)?tag$# or
warn "I know $file is a tag but regex doesn't match it\n";
my $tagname = $1;
- # Disable for now.
- #@{ $hash{symbols}{$fsubtype}{$1} } = ();
- # Not this, context info will be provided in html files
- #[ "$i{ver}/$file", scalar @file, "1:" . scalar @file, [ @file ] ];
+ # Add the tag and basic info to the hash
+ push @{ $hash{symbols}{$fsubtype}{$1} },
+ [ "$i{ver}/$file", scalar @file, "1:" . scalar @file, [ format_ctx(@file) ] ];
+ # Now, try to autoconstruct tag synopsis
+ my %specific;
+ #my $warned;
+ for my $_l (@file) {
+ next unless $_l =~ /^usertag\s/i;
+ my @lis = split /\s+/, $_l;
+ shift @lis; # Remove "Usertag" which is first in the list
+
+ # We don't care if filename doesn't match tag name defined in it,
+ # this is solved by saving the name to $specific{_name} which will
+ # then override filename in bin/refs-autogen.
+ #unless ( (my $tn = shift(@lis)) eq "$tagname" ) {
+ #warn "HA! TAGFILE $file, name mismatch ($tagname != $tn)\n"
+ # unless $warned++;
+ #};
+ 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"
+ #}
+
+ $specific{_name} = $tn;
+
+ my $tagopt = lc ( shift @lis );
+ next if $tagopt eq 'routine';
+ $specific{$tagopt} = "@lis";
+ }
+ $hash{specific}{$tagname} = { %specific };
last;
}
}
@@ -356,45 +400,52 @@
# perl_pod # pod lines
#
# perl_empty # number of empty (except whitespace) lines
-#
-# matches => { # files with that extension/selector
-# ...ext...
-# }
-#
-# filetypes => { # files of that type
-# ...ftype...
-# }
-#
-# perl_functions # Total number of Perl functions in the source
-#
-# # Each file's stat() data
-# tree => {
-# ...file... => {
-# size => (stat _)[7],
-# atime => (stat _)[8],
-# mtime => (stat _)[9],
-# ctime => (stat _)[10],
-# type => directory/text/binary
-# (for text only below)
-# subtype> subtype (binary image, text c source, text perl source..)
-# ext => extension as recognized by file matcher
-# lines => number of lines
-# code => lines of code
-# comments => lines of perl-style comments
-# pod => lines of POD
-# gray => mixed, same as above in total{}
-# empty => empty lines (including whitespace)
-# }
-# }
-#
-# # Symbols
-# symbols => {
-# pragma => { # pragma symbols
-# name => { # pragma name
-# file => [ line num ] # file/line-information it occurs in
-# }
-# }
-# }
+#
+# matches => { # files with that extension/selector
+# ...ext...
+# }
+#
+# filetypes => { # files of that type
+# ...ftype...
+# }
+#
+# perl_functions # Total number of Perl functions in the source
+#
+# # Each file's stat() data
+# tree => {
+# ...file... => {
+# size => (stat _)[7],
+# atime => (stat _)[8],
+# mtime => (stat _)[9],
+# ctime => (stat _)[10],
+# type => directory/text/binary
+# (for text only below)
+# subtype> subtype (binary image, text c source, text perl source..)
+# ext => extension as recognized by file matcher
+# lines => number of lines
+# code => lines of code
+# comments => lines of perl-style comments
+# pod => lines of POD
+# gray => mixed, same as above in total{}
+# empty => empty lines (including whitespace)
+# }
+# }
+#
+# # Symbols
+# symbols => {
+# pragma => { # pragma symbols
+# name => { # pragma name
+# file => [ line num ] # file/line-information it occurs in
+# }
+# }
+# }
+#
+# # Item specific data
+# specific => {
+# symbol name => {
+# # something...
+# }
+# }
# )
#
#
1.8 +1 -1 xmldocs/docbook/common.xsl
rev 1.8, prev_rev 1.7
Index: common.xsl
===================================================================
RCS file: /var/cvs/xmldocs/docbook/common.xsl,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- common.xsl 8 Aug 2004 21:04:24 -0000 1.7
+++ common.xsl 13 Aug 2004 21:09:15 -0000 1.8
@@ -29,7 +29,7 @@
<l:i18n xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0">
<l:l10n language="en">
<l:context name="title">
- <l:template name="example" text="%t"/>
+ <l:template name="example" text="Example: %t"/>
</l:context>
</l:l10n>
</l:i18n>
1.6 +23 -0 xmldocs/docbook/docbookxi.dtd
rev 1.6, prev_rev 1.5
Index: docbookxi.dtd
===================================================================
RCS file: /var/cvs/xmldocs/docbook/docbookxi.dtd,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- docbookxi.dtd 9 Aug 2004 15:53:57 -0000 1.5
+++ docbookxi.dtd 13 Aug 2004 21:09:15 -0000 1.6
@@ -9,6 +9,29 @@
<!ENTITY ICCVS "<ulink url='http://www.icdevgroup.org/i/dev/cvs.html'>CVS</ulink>">
<!ENTITY APACHE "<ulink url='http://www.apache.org/'>Apache</ulink>">
+<!-- ENTITIES USED IN AUTOGENERATED DOCS MOSTLY -->
+<!ENTITY DEF_SYNOPSIS "No synopsis line">
+<!ENTITY DEF_DESCRIPTION "No more specific information was supplied. We know
+this piece is missing and we'll try to update it.">
+<!ENTITY DEF_EXAMPLE "No examples are available at this time. We do consider this a problem and will try to supply some.">
+<!ENTITY DEF_NOTES "None.">
+<!ENTITY DEF_BUGS "<para>There are no known bugs.</para><para>If you believe you've found a bug, please write to interchange-users at icdevgroup.org or use <application>reportbug</application> to submit bugs in Debian GNU.</para>">
+<!ENTITY DEF_SYMBOLTYPE "No symbol type information, this is strange.">
+<!ENTITY DEF_SOURCE 'No source information.'>
+<!ENTITY DEF_AUTHOR "The <ulink url='http://www.icdevgroup.org'>Interchange Development Group</ulink>">
+<!ENTITY DEF_COPYRIGHT "
+<para>
+Copyright © 2004 The Interchange Development Group
+</para> <para>
+This documentation and the source code are free; you can redistribute
+them and/or modify them
+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.</para>">
+<!ENTITY DEF_SEEALSO "No information.">
+<!ENTITY DEF_PURPOSE "description line missing">
+
+
<!-- Remove MsgSet -->
<!ENTITY % compound.class "procedure|sidebar">
<!ENTITY % msgset.content.module "IGNORE">
1.10 +4 -0 xmldocs/docbook/xmldocs.css
rev 1.10, prev_rev 1.9
Index: xmldocs.css
===================================================================
RCS file: /var/cvs/xmldocs/docbook/xmldocs.css,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- xmldocs.css 9 Aug 2004 15:53:57 -0000 1.9
+++ xmldocs.css 13 Aug 2004 21:09:15 -0000 1.10
@@ -240,6 +240,10 @@
margin: 0;
}
+.example {
+ margin-bottom: 24px;
+}
+
.screen {
margin-top: 0;
padding: 4px 4px 4px 4px;
1.3 +5 -2 xmldocs/docbook/item-skel/synopsis
rev 1.3, prev_rev 1.2
Index: synopsis
===================================================================
RCS file: /var/cvs/xmldocs/docbook/item-skel/synopsis,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- synopsis 23 Jul 2004 13:32:02 -0000 1.2
+++ synopsis 13 Aug 2004 21:09:16 -0000 1.3
@@ -1,7 +1,7 @@
<!-- Synopsis is a CDATA block (it's <pre>formatted), so you're pretty
much free to construct the synopsis any way you want. Try to keep it
along the lines of (if not describing Tags for which this scheme is
- not usable:
+ not usable):
literal - literal text
<text> - mandatory value
@@ -11,7 +11,10 @@
default value.
Describe various options inside 'description' file, not here.
- Delete those comment lines -->
+ Delete those comment lines.
+
+ ** If you're documenting a TAG, leave this file completely empty,
+ syntax line for tags is autogenerated ** -->
<synopsis><![CDATA[
]]></synopsis>
1.4 +1 -1 xmldocs/docbook/symbol-type-skel/pragma
rev 1.4, prev_rev 1.3
Index: pragma
===================================================================
RCS file: /var/cvs/xmldocs/docbook/symbol-type-skel/pragma,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- pragma 8 Aug 2004 20:05:22 -0000 1.3
+++ pragma 13 Aug 2004 21:09:16 -0000 1.4
@@ -7,4 +7,4 @@
</para><para>
To define a pragma for a small ITL block inside the page, enclose the block in <code>[tag pragma NAME]1[/tag]...[tag pragma NAME]0[/tag]</code>.
</para><para>
-Starting with Interchange 5.0, the <code>$::Pragma->{name}</code> syntax is used instead of the old <code>$Vend::Cfg->{Pragma}{name}</code>.
+Starting with Interchange 5.0, the <code>$::Pragma->{name}</code> syntax is used in the Interchange source instead of the old <code>$Vend::Cfg->{Pragma}{name}</code>.
More information about the docs
mailing list