[docs] xmldocs - docelic modified 4 files
docs at icdevgroup.org
docs at icdevgroup.org
Fri Nov 5 20:06:46 EST 2004
User: docelic
Date: 2004-11-06 01:06:46 GMT
Modified: . Makefile TODO
Modified: bin stattree refs-autogen
Log:
- bin/stattree:
- **added support for finding Catalog Variables**
- Catalog and Global variables are now detected in all forms they appear
(including @_, __, @@, [var X], [var X, \d] etc..
- added one error check (helps catch errors in line_find*() functions)
- avoid parsing of 4.6.0's Tagref.pm after __DATA__ since it's messy below
- bin/refs-autogen:
- 3 lines added to support 'catvars' symbol group
- if a source context shows say, total of 15 lines, and the symbol is
present there multiple times, it was counted as different contexts, but
bin/refs-autogen removed "overlapping" ones.
In addition to this removal, we properly adjust the line in output which
says "(X of total Y contexts shown)".
- Makefile:
- add 'catvars' to SYMBOL_TYPES
- TODO: items
Revision Changes Path
1.36 +1 -1 xmldocs/Makefile
rev 1.36, prev_rev 1.35
Index: Makefile
===================================================================
RCS file: /var/cvs/xmldocs/Makefile,v
retrieving revision 1.35
retrieving revision 1.36
diff -u -r1.35 -r1.36
--- Makefile 4 Nov 2004 10:08:25 -0000 1.35
+++ Makefile 6 Nov 2004 01:06:46 -0000 1.36
@@ -10,7 +10,7 @@
#############################################################
# Base definitions
IC_VERSIONS = 4.6.0 4.8.0 5.0.0 5.2.0 cvs-head
-SYMBOL_TYPES= pragmas globvars usertags uitags systemtags globconfs catconfs filters
+SYMBOL_TYPES= pragmas globvars usertags uitags systemtags globconfs catconfs filters catvars
GUIDES = iccattut xmldocs
HOWTOS = howtos
GLOSSARY = glossary
1.43 +45 -7 xmldocs/TODO
rev 1.43, prev_rev 1.42
Index: TODO
===================================================================
RCS file: /var/cvs/xmldocs/TODO,v
retrieving revision 1.42
retrieving revision 1.43
diff -u -r1.42 -r1.43
--- TODO 28 Oct 2004 22:46:01 -0000 1.42
+++ TODO 6 Nov 2004 01:06:46 -0000 1.43
@@ -1,18 +1,29 @@
+Great stuff:
+For each symbol: keep a list of other symbols IT uses
+For example, if I knew that, I could have seen I need to set
+DOCROOT for [image] to work.
+
+ADD ROLES FOR OPERATING SYSTEMS/LINUX DISTRIBUTIONS. Documentation
+from Debian package should directly have all proper paths and names.
+
+
+Ask ndw about including [NEW!] in titles in TOC.
+
+
PRIMARY:
- 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
of plain "C"). Will need to write XSLT to fix that, and support tables.
-- Contexts: in situation like "symbol \n symbol" where the symbol appears
- multiple times within +- of first occurence, we treat it like one context.
- but the header says 'displaying 2/2 contexts', it doesn't remove
- 'duplicates'. fix that.
- ./files/ directory is not properly referenced from chunked documents.
- Solve by using entities?
- Double-linked SeeAlso doesn't work. ConfigAllBefore points to ConfigAllAfter,
but the latter doesn't return love.
+- Switch to double-pass document generation. This will make PROPER
+ <glossterm> links work again and will allow for profiles which we must
+ have (for online examples etc..).
+
- In iccattut:
- make a "translation map" of /etc/interchange/* to RPM-equivs.
- item for package names, like interchange-cat-foundation, wenglish, etc..
@@ -22,10 +33,9 @@
- in source contexts, wrap runaway lines
- match style (no starting verb or all starting verbs) in all Example titles
-- Makefile: olinkdbs targets need to have literal depends, not $(shell )
- check if all Default fields are properly formated (<literal> or none)
- s/a HTML/an HTML/
-- script to [un]comment debug lines
+- script to [un]comment debug lines!!
GLOSSARY:
Say about accesskeys in html source, for key-based navigation
@@ -47,6 +57,9 @@
guide on setting complete IC environment
style: leave newline at end of file
explain version naming.. stable/unstable and how 5.3.0 implies next stable
+Documentation on how to create replicated catalog online and at your
+desktop machine for ultimate convenience.
+- PRODUCE PATCH TO RECOMPILE OFFICIAL DISTRIBUTION PERL without threads.
DOCUMENTATION SYSTEM:
- copy the definition for <example> to a
@@ -61,6 +74,8 @@
- give examples for the tasks in 'do yourself' section (in progress)
- give good practices about filtering, security
- see problems from old docs/TODO notes on iccattut
+- ICCATTUT MUST NOT STOP WHERE it stops now. it needs to show all stuff
+ from current "excercise for readers" section, and also many more things.
Mid-term:
@@ -134,3 +149,26 @@
----------
+---------------------------------------------------------------
+Taking on ideas from previous ML posts:
+
+** Dan Browning: clustering howto, tuning tips (by Mike),
+jedit + IC colorization, commit-to-live script,
+Racke: performance docs NEEDED, clustering my mike needs funding or he
+won't do it. CVS howto is browning.
+
+** Mike We are short on chiefs and heavy on Indians here
+
+
+OLINE EXAMPLES:
+ <programlisting><textobject><textdata fileref="pathto.xml"/></textobject></programlisting>
+
+
+
+
+Code problems:
+- In db_columns: add exlude_columns= parameter?
+
+---
+say that code is colorful collection of time and people, so docs try to fill
+the gap.
1.29 +54 -3 xmldocs/bin/stattree
rev 1.29, prev_rev 1.28
Index: stattree
===================================================================
RCS file: /var/cvs/xmldocs/bin/stattree,v
retrieving revision 1.28
retrieving revision 1.29
diff -u -r1.28 -r1.29
--- stattree 20 Oct 2004 16:48:02 -0000 1.28
+++ stattree 6 Nov 2004 01:06:46 -0000 1.29
@@ -244,9 +244,20 @@
$c{line} = $filedata[$lnum];
$c{lnum} = $lnum;
+ # Should never happen. If it does, it's critical problem.
+ defined $c{line} or do {
+ print STDERR "Undefined line: \n";
+ print STDERR Dumper \%c;
+ die;
+ };
+
$hash{tree}{$file}{lines}++ ;
$hash{total}{lines}++ ;
+ # BLEH!
+ last if $i{ver} eq '4.6.0'
+ and $c{file} =~ /Tagref\.pm$/ and $c{line} =~ /^__DATA__$/;
+
# Perl program file
if ( $c{fsubtype} eq 'perl' ) {
my $pod = 0;
@@ -276,6 +287,7 @@
line_findPragmas(\%c);
line_findGlobVars(\%c);
+ line_findCatVars(\%c);
line_findFunctionName(\%c);
} else {
@@ -320,6 +332,7 @@
line_findPragmas(\%c);
# For example, this should find PGP_HOME
line_findGlobVars(\%c);
+ line_findCatVars(\%c);
line_findFunctionName(\%c);
}
next;
@@ -499,13 +512,51 @@
}
}
+sub line_findCatVars {
+ ######################################################
+ # Diskover global variables
+ my %c = %{ (shift) };
+ my $name;
+
+ if (
+ ($c{line} =~ /(()|\$())\$(::)?Variable(->\2|\3){(\w+?)}/ and $name=$6)
+ or ($c{line}=~/\$Tag->var\s*\(\s*(["'])(\S+?)\1(\s*,\s*(2))?/ and $name=$5)
+ or ($c{line} =~ /[^_\/]__([^_]\w+?)__[^_\/]/ and
+ ( $1 !~ /^(END|DIE|MYVAR|PACKAGE|NAME|none|WARN)$/) and $name=$1)
+ or ($c{line} =~ /\[var (\S+?)\]/i and $name=$1)
+ or ($c{line} =~ /\[var (\S+?)\s+2\s*\]/i and $name=$1)
+ ) {
+
+ push @{ $hash{symbols}{catvar}{$name} }, {
+ %c,
+ file => "$i{ver}/$c{file}",
+ lnum => $c{lnum},
+ func => ${$c{gfunc}}[0],
+ funclnum => ${$c{gfunc}}[1],
+ ctxpre => $c{ctx_p},
+ ctxpost => $c{ctx_n},
+ ctxs => $c{lnum} - $c{ctx_p},
+ ctxe => $c{lnum} + $c{ctx_n},
+ ctx => [format_ctx(@{$c{filedata}}[$c{lnum}-$c{ctx_p}..$c{lnum}+$c{ctx_n}])]
+ };
+
+ $hash{total}{catvars}++;
+ }
+}
+
sub line_findGlobVars {
######################################################
# Diskover global variables
my %c = %{ (shift) };
- if ( ( $c{line} =~ /(()|\$())\$Global::Variable(->\2|\3){(\w+?)}/ or
- $c{line} =~ /\$Tag->var\s*\(\s*(["'])(\S+?)\1(\s*,\s*(\d))?/ ) and $5 ) {
- push @{ $hash{symbols}{globvar}{$5} }, {
+ my $name;
+
+ if (
+ ($c{line} =~ /(()|\$())\$Global::Variable(->\2|\3){(\w+?)}/ and $name=$5)
+ or ($c{line}=~/\$Tag->var\s*\(\s*(["'])(\S+?)\1(\s*,\s*(\d))?/ and $name=$5)
+ or ($c{line} =~ /[^\/]\@[_\@](\w+?)[_\@]\@[^\/]/ and $name=$1)
+ or ($c{line} =~ /\[var (\S+?)\s+1\s*\]/i and $name=$1)
+ ) {
+ push @{ $hash{symbols}{globvar}{$name} }, {
%c,
file => "$i{ver}/$c{file}",
lnum => $c{lnum},
1.57 +26 -14 xmldocs/bin/refs-autogen
rev 1.57, prev_rev 1.56
Index: refs-autogen
===================================================================
RCS file: /var/cvs/xmldocs/bin/refs-autogen,v
retrieving revision 1.56
retrieving revision 1.57
diff -u -r1.56 -r1.57
--- refs-autogen 28 Oct 2004 22:46:01 -0000 1.56
+++ refs-autogen 6 Nov 2004 01:06:46 -0000 1.57
@@ -91,6 +91,7 @@
my %longname = (
globvar => "Global Variable",
+ catvar => "Catalog Variable",
pragma => "Pragma",
usertag => "User Tag",
uitag => "User Interface Tag",
@@ -225,20 +226,10 @@
if ( $ar ) {$$ag{source} = "" }
- $$ag{"ctxs total"} = scalar @$ar;
- $$ag{"ctxs shown"} = @$ar < $max_ctxs ? @$ar : $max_ctxs;
-
- my $ctxcount = 0;
+ my $ctxtotal = scalar @$ar;
+ my $ctxshown = 0;
for my $ctx ( @$ar ) {
- # Make sure we don't overdo it with source contexts.
- # MV_PAGE appears on like 31 place. We definitely don't need to
- # see more than 10.
- if ( $ctxcount++ > $max_ctxs ) {
- print STDERR "$$ag{name} has ", scalar @$ar,
- " contexts, limiting to $max_ctxs\n" if $verbose;
- last;
- }
# my $hidden = @$ar - $max_ctxs;
# $$ag{source} .= <<ENDD;
#<para>
@@ -254,8 +245,22 @@
# Support item types with only context info in this field
for my $arr ( @{ $covered{$key}{$fi} } ) {
next if !$ln or !$$arr[0] or !$$arr[1];
- goto DONELOOP if $ln > $$arr[0] and $ln < $$arr[1];
+ if ($ln > $$arr[0] and $ln < $$arr[1]) {
+ $ctxtotal--;
+ goto DONELOOP;
+ }
+ }
+
+
+ # Make sure we don't overdo it with source contexts.
+ # MV_PAGE appears on like 31 place. We definitely don't need to
+ # see more than 10.
+ if ( $ctxshown++ > 10 ) {
+ print STDERR "$$ag{name} has ", scalar @$ar,
+ " contexts, limiting to $max_ctxs\n" if $verbose;
+ goto DONELOOP;
}
+
# We 'shift' here because we unshifted 1 row to match line
# numbers with array indexes
my $ctxsdata = join "\n", @{ $$ctx{ctx} };
@@ -314,6 +319,8 @@
$revinfo = "(rev. $r from $d)";
}
}
+
+
{ no warnings; # XXX If someone can figure out which of the used vars here is undefined...
$$ag{source} .= <<ENDD;
<para>
@@ -333,6 +340,9 @@
push @{ $covered{$key}{$fi} }, [ $$ctx{ctxs}, $$ctx{ctxe} ];
DONELOOP:
}
+
+ $$ag{"ctxs total"} = $ctxtotal;
+ $$ag{"ctxs shown"} = $ctxshown < $max_ctxs ? $ctxshown : $max_ctxs;
}
}
}
@@ -646,7 +656,8 @@
$dups{$name} and # Symbol name is non-unique
-e $genpath and # Generic file exists (refs/<name>)
!-e $specpath and # But special files don't (refs/<name>.<group>)
- $group !~ /conf$/ ) {# And it's not a config directive for which we tolerate
+ $group !~ /conf|var$/ ) {# And it's not a cfg directive or globvar/catvar
+ #for which we tolerate
local $" = " AND ";
die "Symbol '$name' is: @{ $dups{$name} }. Must have refs/<name>.<type>\n";
}
@@ -1088,6 +1099,7 @@
__ENDP__
$templates{globvar} = $templates{pragma};
+$templates{catvar} = $templates{pragma};
$templates{uitag} = $templates{usertag};
$templates{systemtag} = $templates{usertag};
$templates{catconf} = $templates{globconf};
More information about the docs
mailing list