Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

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
  • Loading branch information...
commit 8a8fb4077963fdaae3a48c82e4a18ca59182cf67 1 parent abea0cb
@docelic docelic authored
Showing with 67 additions and 36 deletions.
  1. +27 −34 TODO
  2. +38 −2 bin/refs-autogen
  3. +2 −0  docbook/literals.ent
View
61 TODO
@@ -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 @@ Stuff:
- 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 @@ Stuff:
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
View
40 bin/refs-autogen
@@ -46,7 +46,7 @@ my %dups; # List of symbols names that are not unique
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 @@ my %defaults = (
'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 @@ while ( $path = shift @paths) { # For each version specified
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 @@ while ( my($k,$v) = each %{ $autogenerated{$group} } ) {
# 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 @@ ENDD
$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 @@ if ( $compounds ) {
%{ $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 @@ $templates{filter} = <<'__ENDP__';
<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"}
@@ -1241,6 +1272,11 @@ $ag{"synopsis"}
<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'>
<title>EXAMPLES</title>
$ag{"example"}
View
2  docbook/literals.ent
@@ -64,6 +64,8 @@ option) any later version.</para>">
<!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">
Please sign in to comment.
Something went wrong with that request. Please try again.