[docs] xmldocs - docelic modified 5 files
docs at icdevgroup.org
docs at icdevgroup.org
Sat Nov 13 19:30:01 EST 2004
User: docelic
Date: 2004-11-14 00:30:00 GMT
Modified: . Makefile TODO
Modified: bin generic-autogen refs-autogen
Modified: docbook literals.ent
Log:
Evening commit
- Makefile: added some dependencies on bin/generic-autogen
- TODO: rearranged, cleaned up
- bin/generic-autogen:
- skip CVS dir
- Do not generate all-lowercase entities, (&glos-ITL; leaves ITL in uppercase)
- bin/refs-autogen:
- Added %tagname hash so it knows which actual XML tag corresponds to a symbol
- !Prettifyied the "Tag Structure" field! Awesome automatic interlinking
- docbook/literals.ent: some entities
Revision Changes Path
1.42 +2 -2 xmldocs/Makefile
rev 1.42, prev_rev 1.41
Index: Makefile
===================================================================
RCS file: /var/cvs/xmldocs/Makefile,v
retrieving revision 1.41
retrieving revision 1.42
diff -u -r1.41 -r1.42
--- Makefile 12 Nov 2004 23:47:44 -0000 1.41
+++ Makefile 14 Nov 2004 00:29:59 -0000 1.42
@@ -200,9 +200,9 @@
#############################################################
# One-shot targets
-glossary/glossary.xml: $(shell find glossary/ -regex '.+[^(\.xml)]$$')
+glossary/glossary.xml: $(shell find glossary/ -regex '.+[^(\.xml)]$$') bin/generic-autogen
bin/generic-autogen glossary
-howtos/howtos.xml: $(shell find howtos/ -regex '.+[^(\.xml)]$$')
+howtos/howtos.xml: $(shell find howtos/ -regex '.+[^(\.xml)]$$') bin/generic-autogen
bin/generic-autogen howtos
1.46 +52 -101 xmldocs/TODO
rev 1.46, prev_rev 1.45
Index: TODO
===================================================================
RCS file: /var/cvs/xmldocs/TODO,v
retrieving revision 1.45
retrieving revision 1.46
diff -u -r1.45 -r1.46
--- TODO 9 Nov 2004 23:16:16 -0000 1.45
+++ TODO 14 Nov 2004 00:29:59 -0000 1.46
@@ -1,31 +1,23 @@
-Interpolate/reparse are two options? adjust ROW_INTERPOLATE_0/1
+Outstanding:
+- Interpolate/reparse are two options; adjust ROW_INTERPOLATE/REPARSE_0/1
+- Online examples only have to be standard examples, with actual work in
+ practice if condition=online
+ Code to do that is: <programlisting><textobject><textdata fileref="pathto.xml"/></textobject></programlisting>
-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.
+- Ask ndw about including [NEW!] and [TODO!] in titles in TOC.
-ADD ROLES FOR OPERATING SYSTEMS/LINUX DISTRIBUTIONS. Documentation
-from Debian package should directly have all proper paths and names.
-
-<Racke>I name three things that IC users often didn't acknowledge:
- namespaces (CGI, Values, Scratch)
- parsing order ([L], variables, lists) - interpolation
- inventing syntax doesn't buy you anything
- IC is _not_ a programming language
-
-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.
+ NEWS: New guy took over xslt maintenance and is interested in improved
+ manpage support - he's interested in my problems, and is willing to
+ do xslt work himself.
+
- ./files/ directory is not properly referenced from chunked documents.
-- Double-linked SeeAlso doesn't work. ConfigAllBefore points to ConfigAllAfter,
- but the latter doesn't return love.
+ This will be done by prefixing links from chunked documents with ../
+ "Code" for this is done, I just need to get it from ndw.
- In iccattut:
- make a "translation map" of /etc/interchange/* to RPM-equivs.
@@ -33,6 +25,17 @@
( This is ok, docbook 4.4 will have <package> element )
- explain syntax accepted in profile files
- Fix ImageDir and include one picture for example
+ - <Racke>I name three things that IC users often didn't acknowledge:
+ namespaces (CGI, Values, Scratch)
+ parsing order ([L], variables, lists) - interpolation
+ inventing syntax doesn't buy you anything
+ IC is _not_ a programming language
+ - how to delete item from cart in all possible ways
+ - 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.
- in source contexts, wrap runaway lines
- match style (no starting verb or all starting verbs) in all Example titles
@@ -45,11 +48,7 @@
tag, interpolation, reparse, symbol types
catalog/global variable, tag,ui,
action, form, unix inet socket, values,
-regex, flypage, sku, ad, weighted display
-
-HOWTOs:
-- how to delete item from cart in all possible ways
-- create a menu bar: see bar_button
+regex, flypage, sku
- More:
Programming guidelines doc - integrate with programming style. Advise
@@ -65,20 +64,11 @@
- PRODUCE PATCH TO RECOMPILE OFFICIAL DISTRIBUTION PERL without threads.
DOCUMENTATION SYSTEM:
-- copy the definition for <example> to a
- new name so we'll be able to differentiate between source chunks and
- examples.
- Add support to document tags which are NOT found in separate files
(like [restrict] or [subject]).
- Read all possible options for tag files from vend/config.pm
(%tag.* structures) and warn if invalid option is found in any tag file.
-iccattut:
-- 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:
@@ -90,86 +80,47 @@
say, 15 lines of context, but it'll come great when you have a copy
of a 300-lines usertag. Example for this could be taken directly out of
mwforum demo on mwforum.org
-- In refs-autogen at a few places we keep both the hash/array representation
- of values, and their string representation. (We always generate string
- 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 mark obsolete items (those not present in cvs-head)
-- Visually mark undocumented items
- Generate leaf nodes (put bin/mkreport back in action)
-- Make script which would be like: vim `our.script usertags synopsis`.
- our.script would find all usertags and where their synopsis is defined,
- somewhere in refs/.
-- In howtos, include CVS date of items
-
- Long-term:
-- filenames in Source contexts should also be clickable. this is longterm
- because it'll involve perltidy and other stuff I have in mind ...
-
-DOCUMENTATION ITSELF:
-- Resolve items from tmp/missing file. (You need to run 'make' in your tree
- first, to get that file generated). I did what I could, now the list only
- contains items which don't even exist in the old docs, so I can't copy/paste;
- someone who is able to write the description/examples from scratch should
- do that.
-
-
-<epigraph>
-<attribution>William Safire</attribution>
-<para>
-Knowing how things work is the basis for appreciation, and is
-thus a source of civilized delight.
-</para>
-</epigraph>
-
-
-"In times of universal deceit, telling the truth becomes
- a revolutionary act." -- George Orwell.
-
-
-For a successful technology, reality must take precedence over public
-relations, for Nature cannot be fooled. -- Dick Feynman
-
-######################################################################
Tags:
- parameters
- positional list
- invalidates cache
aliases
tag call / perl call / mvasp
container
has subtags
nests
-----
-New docs:
- - promotional
- - new developer howto
-----------
----------------------------------------------------------------
-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>
+Ideas:
+- In db_columns: add exlude_columns= parameter?
+- New docs:
+ - promotional
+ - new developer howto
+- filenames in Source contexts should also be clickable. this is longterm
+ because it'll involve perltidy and other stuff I have in mind ...
+Notes:
+- say that code is colorful collection of time and people, so docs try to fill
+the gap.
+- say that even though sometimes the code looks ugly/unreadable, check 3 times before thinking it's a bug
+- ** 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.
+- "In times of universal deceit, telling the truth becomes
+ a revolutionary act." -- George Orwell.
+- For a successful technology, reality must take precedence over public
+ relations, for Nature cannot be fooled. -- Dick Feynman
+- <epigraph>
+ <attribution>William Safire</attribution>
+ <para>
+ Knowing how things work is the basis for appreciation, and is
+ thus a source of civilized delight.
+ </para>
+ </epigraph>
-Code problems:
-- In db_columns: add exlude_columns= parameter?
+Misc:
+- Mike We are short on chiefs and heavy on Indians here
----
-say that code is colorful collection of time and people, so docs try to fill
-the gap.
1.6 +3 -4 xmldocs/bin/generic-autogen
rev 1.6, prev_rev 1.5
Index: generic-autogen
===================================================================
RCS file: /var/cvs/xmldocs/bin/generic-autogen,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- generic-autogen 9 Nov 2004 23:16:16 -0000 1.5
+++ generic-autogen 14 Nov 2004 00:30:00 -0000 1.6
@@ -80,19 +80,18 @@
readdir DIR; readdir DIR;
while ( my $file = readdir DIR ) {
- next if $file =~ /^\.|\.xml$/;
+ next if $file =~ /^\.|^CVS|\.xml$/;
open IN, "< $cat/$file" or die "Can't read-open $cat/$file ($!)\n";
$items{$file} = [ <IN> ];
$alphabet{ lc(substr($file, 0, 1)) }++;
push @loaded, $file;
my $lcfile = lc $file;
+ my $link = "<olink targetdoc='$cat' targetptr='$file'/>";
##### Should be lowercase ****
- ##### Uppercase is temporary only
print ENT <<ENDO;
-<!ENTITY $sn{$cat}-$lcfile "$file">
-<!ENTITY $sn{$cat}-$file "$file">
+<!ENTITY $sn{$cat}-$file "$link">
ENDO
print "Added $file\n" if $verbose;
1.65 +21 -2 xmldocs/bin/refs-autogen
rev 1.65, prev_rev 1.64
Index: refs-autogen
===================================================================
RCS file: /var/cvs/xmldocs/bin/refs-autogen,v
retrieving revision 1.64
retrieving revision 1.65
diff -u -r1.64 -r1.65
--- refs-autogen 12 Nov 2004 23:47:44 -0000 1.64
+++ refs-autogen 14 Nov 2004 00:30:00 -0000 1.65
@@ -43,7 +43,7 @@
my $autopath = "docbook/autorefs.ent";
my %dups; # List of symbols names that are not unique
-my @page_order = (qw/purpose default structure synopsis description online example notes bugs/, "symbol type", "source", "author", "copyright", "see also");
+my @page_order = (qw/purpose default structure synopsis description structure online example notes bugs/, "symbol type", "source", "author", "copyright", "see also");
unless ( GetOptions (
"verbosedb|dumpdb|d!" => \$dumpdb,
@@ -77,6 +77,18 @@
filter => "Filter",
);
+my %tagname = (
+ globvar => "varname",
+ catvar => "varname",
+ pragma => "pragma",
+ usertag => "tag",
+ uitag => "tag",
+ systemtag => "tag",
+ globconf => "option",
+ catconf => "option",
+ filter => "filter",
+);
+
# Default fields
my %defaults = (
synopsis => "&DEF_SYNOPSIS;",
@@ -90,6 +102,7 @@
copyright => "&DEF_COPYRIGHT;",
'see also' => "&DEF_SEEALSO;",
purpose => "&DEF_PURPOSE;",
+ structure => "&DEF_STRUCTURE;",
);
my @mandatory = (qw/synopsis example description purpose/);
@@ -446,9 +459,15 @@
# The 'structure' field will show which other symbols the current
# symbol uses. Fill it:
if ( $hash{uses}{$group}{$ag{name}} ) {
+ $ag{structure} = "<para>This tag appears to be affected by, or affects, the following:</para>\n";
while (my($k,$v)=each %{ $hash{uses}{$group}{$ag{name}} }) {
- $ag{structure} .= "$k: @$v<sbr/>\n";
+ s/^(.+)$/<$tagname{lc $k}>$1<\/$tagname{lc $k}>/ for @$v;
+ local $" = ", ";
+ $k = $longname{$k};
+ $ag{structure} .= "${k}s: @$v<sbr/>\n";
}
+ } else {
+ $ag{structure} = "<para>This tag does not appear to be affected by, or affect, the rest of Interchange.</para>\n";
}
1.14 +16 -9 xmldocs/docbook/literals.ent
rev 1.14, prev_rev 1.13
Index: literals.ent
===================================================================
RCS file: /var/cvs/xmldocs/docbook/literals.ent,v
retrieving revision 1.13
retrieving revision 1.14
diff -u -r1.13 -r1.14
--- literals.ent 9 Nov 2004 23:16:16 -0000 1.13
+++ literals.ent 14 Nov 2004 00:30:00 -0000 1.14
@@ -12,6 +12,21 @@
<!ENTITY APACHE "<ulink url='http://www.apache.org/'>Apache</ulink>">
<!ENTITY W3 "<ulink url='http://www.w3c.org/'>W3C</ulink>">
<!ENTITY W3C "<ulink url='http://www.w3c.org/'>W3C</ulink>">
+<!ENTITY PERL "<ulink url='http://www.perl.org/'>Perl</ulink>">
+
+
+
+<!-- ENTITIES TO AVOID A LOT OF REPETITION -->
+<!ENTITY gcf "<filename>interchange.cfg</filename>">
+<!ENTITY ccf "<filename>catalog.cfg</filename>">
+<!ENTITY gcfs "<filename>interchange.cfg</filename> or <filename>catalog.cfg</filename>">
+<!ENTITY cgfs "<filename>catalog.cfg</filename> or <filename>interchange.cfg</filename>">
+<!ENTITY ICROOT "<olink targetdoc='glossary' targetptr='ICROOT'>ICROOT</olink>">
+<!-- Current and previous default catalog name -->
+<!ENTITY Std-catalog "Standard">
+<!ENTITY std-catalog "standard">
+<!ENTITY Prev-catalog "Foundation">
+<!ENTITY prev-catalog "foundation">
@@ -37,6 +52,7 @@
option) any later version.</para>">
<!ENTITY DEF_SEEALSO "No information.">
<!ENTITY DEF_PURPOSE "description line missing">
+<!ENTITY DEF_STRUCTURE "None.">
@@ -52,15 +68,6 @@
<!-- GLOSSARY LINKS ARE AUTOMATIC -->
-
-
-<!-- ENTITIES TO AVOID A LOT OF REPETITION -->
-<!ENTITY gcf "<filename>interchange.cfg</filename>">
-<!ENTITY ccf "<filename>catalog.cfg</filename>">
-<!ENTITY gcfs "<filename>interchange.cfg</filename> or <filename>catalog.cfg</filename>">
-<!ENTITY cgfs "<filename>catalog.cfg</filename> or <filename>interchange.cfg</filename>">
-
-<!ENTITY ICROOT "<olink targetdoc='glossary' targetptr='ICROOT'>ICROOT</olink>">
<!-- ENTITIES TO EASIER CONSTRUCT TAG PARAMETERS LIST -->
More information about the docs
mailing list