[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 &copy; 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