[docs] xmldocs - docelic modified 3 files

docs at icdevgroup.org docs at icdevgroup.org
Wed Dec 15 17:34:05 EST 2004


User:      docelic
Date:      2004-12-15 22:34:05 GMT
Modified:  .        TODO
Modified:  bin      refs-autogen
Modified:  docbook  literals.ent
Log:
As usual, I am wonderful ;-) Here's the reason this time:

- bin/refs-autogen:
  With global and catalog configuration directives, which we show in a single
  file since not long ago, there was a problem that a refentry page for the
  catalog directive always overwrote the refentry of the global directive
  (if the directive was both global and catalog).

  This is not a big problem per-se, because the documentation in both is
  the same anyway, but we lose at least one source context each time;
  the source contexts belonging to the global variant of the directive were
  always overwritten.

  Now, this is all properly handled, and a field has been added which
  indicates what type of directive (global, catalog, or both) each directive is.

- docbook/literals.ent: supported above functionality
- TODO: rearranged todo items, removed solved ones

Revision  Changes    Path
1.57      +27 -34    xmldocs/TODO


rev 1.57, prev_rev 1.56
Index: TODO
===================================================================
RCS file: /var/cvs/xmldocs/TODO,v
retrieving revision 1.56
retrieving revision 1.57
diff -u -r1.56 -r1.57
--- TODO	15 Dec 2004 13:34:34 -0000	1.56
+++ TODO	15 Dec 2004 22:34:05 -0000	1.57
@@ -1,47 +1,16 @@
 
 Outstanding:
-- For filters: add field which says whether filter's main purpose is to 
-  add or remove text (or combined): subtypes: filter, add, transform.
-  (this needs to come between description and example, just like 
-  tags have BEHAVIOR field there, and confs will have global or catalog
-  directive indication in that place).
-- See why email and email-raw produce some errors about usertags olink ID
-- Since directives are in the same file, catconfs and globconfs which 
-  are common need to have 2 source contexts instead of one.
+- filters/confs: fill $ag{structure}, automatic for confs, manual for filters
+- why email, email-raw, SendMailProgram produce errors about usertags olink ID
 - Add docbook element to reference mailing list posts. Something like
   <ml list='users'>2004-December/041539</ml>, it expands to:
 	<ulink url="http://www.icdevgroup.org/pipermail/interchange-users/2004-December/041539.html">2004-December/041539</ulink>.
-
-Later:
 - Ask ndw about including [NEW!] and [TODO!] in titles in TOC.
-- Image tag, sort out mgkpath thing
-
-- in source contexts, wrap runaway lines
 - match style (no starting verb or all starting verbs) in all Example titles
 - check if all Default fields are properly formated (<literal> or none)
 - s/a HTML/an HTML/
 - script to [un]comment debug lines!!
 
-GLOSSARY:
-Say about accesskeys in html source, for key-based navigation
-tag, interpolation, reparse, symbol types
-catalog/global variable, tag,ui,
-action, form,  unix inet socket, values,
-regex, flypage, sku
-
-- More:
-Programming guidelines doc - integrate with programming style. Advise
-programmers of choices to make in order to make their code play well with
-IC - for example, if they want to have a field in the DB for images,
-advise them to name the column 'image' because other tags (they might or
-might not later use) take that as default value. etc...
-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:
 - Add support to document tags which are NOT found in separate files
   (like [restrict] or [subject]).
@@ -113,7 +82,7 @@
 - How to deal with Safe
 
 
-- In iccattut (CHECK why revert to old version didn't get to cvs ?!):
+- In iccattut:
   - Check if redhat/tarball paths are correct
   - explain syntax accepted in profile files
   - Fix ImageDir and include one picture for example
@@ -130,3 +99,27 @@
     from current "excercise for readers" section, and also many more things.
   - files/tutorial*: s/tutorial-*.log/tutorial.*.log/
 
+GLOSSARY:
+Say about accesskeys in html source, for key-based navigation
+tag, interpolation, reparse, symbol types
+catalog/global variable, tag,ui,
+action, form,  unix inet socket, values,
+regex, flypage, sku
+
+- More:
+Programming guidelines doc - integrate with programming style. Advise
+programmers of choices to make in order to make their code play well with
+IC - for example, if they want to have a field in the DB for images,
+advise them to name the column 'image' because other tags (they might or
+might not later use) take that as default value. etc...
+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.
+
+
+
+NON DOCS RELATED
+- Image tag, sort out mgkpath thing



1.75      +38 -2     xmldocs/bin/refs-autogen


rev 1.75, prev_rev 1.74
Index: refs-autogen
===================================================================
RCS file: /var/cvs/xmldocs/bin/refs-autogen,v
retrieving revision 1.74
retrieving revision 1.75
diff -u -r1.74 -r1.75
--- refs-autogen	15 Dec 2004 17:27:04 -0000	1.74
+++ refs-autogen	15 Dec 2004 22:34:05 -0000	1.75
@@ -46,7 +46,7 @@
 my $last_path; # Last version we want docs generated for (say, 5.2.0).
 my $compounds = 1; # Summarize similar symbol groups to single page?
 
-my @page_order = (qw/purpose default structure synopsis description structure 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", "directive type", "filter type");
 
 unless ( GetOptions ( 
 	"verbosedb|dumpdb|d!" => \$dumpdb,
@@ -112,6 +112,8 @@
 	'see also' => "&DEF_SEEALSO;",
 	purpose => "&DEF_PURPOSE;",
 	structure => "&DEF_STRUCTURE;",
+	'directive type' => "&DEF_DIRECTIVE_TYPE;",
+	'filter type' => "&DEF_FILTER_TYPE;",
 );
 
 my @mandatory = (qw/synopsis example description purpose/);
@@ -262,6 +264,26 @@
 			my $ag = $autogenerated{$gkey}{$key};
 			my $ar = $hash{symbols}{ $$ag{"_symbol type"} }{$key};
 
+			# Do one silly thing (again, compound docs are tearing me apart).
+			if ( $gkey eq 'globconf' ) {
+
+				@{ $$ag{'_directive type'} } = ("Global directive");
+				# For config directives, we can't simply do as above because catconf
+				# would then overrides globconf, and that's not okay! (We need to
+				# preserve the source contexts from globconfs, so we must handle
+				# this with some brains in the process).
+				# Here's what we do:
+				# For each globconf, we add catconf source contexts to it (if
+				# catconf variant exists), and we delete it from catconfs hash. Then
+				# what is left in catconfs are only catconf directives, and are simply
+				# added to final $symbols{conf} because they wont overwrite anything.
+				if ( $hash{symbols}{catconf}{$key} ) {
+					push @{ $ar }, @{ $hash{symbols}{catconf}{$key} };
+					delete $hash{symbols}{catconf}{$key};
+					push @{ $$ag{'_directive type'} }, "Catalog directive";
+				}
+			}
+
 			if ( $ar ) {
 				$$ag{source} = "";
 				$covered{$gkey}{$key} = {}; # This one was though to find ;-)
@@ -505,6 +527,9 @@
 	# Compress 4.6.0, 4.8.0, 5.0.0 to 4.6.0-5.0.0
 	$ag{'available in'} = compress_availability($ag{'_available in'});
 
+	$ag{"_directive type"} and 
+	$ag{"directive type"} = join "<sbr/>\n", @{ $ag{"_directive type"} };
+
 
 	# DONE
 	$ag{latest} = $hash{version};
@@ -553,7 +578,6 @@
 		$ag{structure} = "<para>This tag does not appear to be affected by, or affect, the rest of Interchange.</para>\n";
 	}
 
-
 	# Expand template
 	my $template = $templates{ $ag{"_symbol type"} };
 	$template or warn "No template $ag{'_symbol type'} ?\n";
@@ -582,10 +606,12 @@
 		%{ $symbols{usertag} },
 		%{ $symbols{uitag} },
 	};
+
 	$symbols{conf} = {
 		%{ $symbols{globconf} },
 		%{ $symbols{catconf} },
 	};
+
 	delete @symbols{qw/systemtag usertag uitag/};
 	delete @symbols{qw/globconf catconf/};
 }
@@ -1088,6 +1114,11 @@
 <para>$ag{"description"}</para>
 </refsect1>
 
+<refsect1 id='$ag{"name"}_type"}'>
+<title>FILTER TYPE</title>
+<para>$ag{"filter type"}</para>
+</refsect1>
+
 <refsect1 id='$ag{"name"}_examples'>
 <title>EXAMPLES</title>
 $ag{"example"}
@@ -1239,6 +1270,11 @@
 <refsect1 id='$ag{"name"}_description'>
 <title>DESCRIPTION</title>
 <para>$ag{"description"}</para>
+</refsect1>
+
+<refsect1 id='$ag{"name"}_type"}'>
+<title>DIRECTIVE TYPE</title>
+<para>$ag{"directive type"}</para>
 </refsect1>
 
 <refsect1 id='$ag{"name"}_examples'>



1.21      +2 -0      xmldocs/docbook/literals.ent


rev 1.21, prev_rev 1.20
Index: literals.ent
===================================================================
RCS file: /var/cvs/xmldocs/docbook/literals.ent,v
retrieving revision 1.20
retrieving revision 1.21
diff -u -r1.20 -r1.21
--- literals.ent	8 Dec 2004 00:11:17 -0000	1.20
+++ literals.ent	15 Dec 2004 22:34:05 -0000	1.21
@@ -64,6 +64,8 @@
 <!ENTITY DEF_SEEALSO "No information.">
 <!ENTITY DEF_PURPOSE "description line missing">
 <!ENTITY DEF_STRUCTURE "None.">
+<!ENTITY DEF_FILTER_TYPE "Unspecified.">
+<!ENTITY DEF_DIRECTIVE_TYPE "Catalog directive">
 
 
 








More information about the docs mailing list