[docs] xmldocs - docelic modified 10 files

docs at icdevgroup.org docs at icdevgroup.org
Tue Aug 31 10:58:36 EDT 2004

User:      docelic
Date:      2004-08-31 14:58:36 GMT
Modified:  .        TODO
Modified:  bin      refs-autogen
Modified:  refs/safe_data example-blockwide
Added:     refs/area control description example example2 example3
Added:              example4 synopsis
 - documented the [area] tag

 - replace TABs with spaces in code example
   (XML tolerates but doesn't like TABs)

 - include id="" parameter in autogenerated sections (to make links/jumps
   between sections of the html manpage possible)

 - sorted items, highlighted primary tasks

Revision  Changes    Path
1.14      +23 -16    xmldocs/TODO

rev 1.14, prev_rev 1.13
Index: TODO
RCS file: /var/cvs/xmldocs/TODO,v
retrieving revision 1.13
retrieving revision 1.14
diff -u -r1.13 -r1.14
--- TODO	29 Aug 2004 20:55:36 -0000	1.13
+++ TODO	31 Aug 2004 14:58:36 -0000	1.14
@@ -1,9 +1,17 @@
+- agree on rules for writing Synopsis lines (should be flexible enough to
+  support all symbol types in an uniform way)
+- rewrite bin/refs-autogen
 - Make docbook/symbol-type-skel/* contents of a glossary, and display a 
   glossary entry instead of those files.
-- For tags documentation, have a field if it's a container or not (and
-  also honor other tag details found in tag files)
+- Under availability, if applicable, display cvs line (modification time,
+  username and version (cvs line)).
+- Support using refs/<filename> with all the documentation for a symbol
+  instead of refs/<directory>/<files>.
 - bin/stattree, in format_ctx(), see how many spacings all the lines have
   in common, and trim that from the beginning.
 - why in manpage format, comments at the top of the file are messed up (no
@@ -12,15 +20,16 @@
   element title, and Screen element title. (This causes source contexts
   to be prefixed with "Example: ", although they're technically not).
 - Add support to document tags which are NOT found in separate files
-  (like [restrict]).
-- Under availability, if applicable, display cvs line (modification time,
-  username and version).
+  (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.
+- give examples for the tasks in 'do yourself' section
+- give good practices about filtering, security
-tag, interpolation, reparse
+tag, interpolation, reparse, symbol types
 - Think about adding "online example" (role=html in combination with 
@@ -35,8 +44,6 @@
   mwforum demo on mwforum.org
-- Support using refs/<filename> with all the documentation for a symbol
-  instead of refs/<directory>/<files>.
 - filenames in Source contexts should also be clickable. this is longterm
   because it'll involve perltidy and other stuff I have in mind ...
@@ -64,11 +71,11 @@
-	positional list
-	invalidates cache
-	aliases
-	tag call / perl call
-	container
-	has subtags
-	nests
+  positional list
+  invalidates cache
+  aliases
+  tag call / perl call / mvasp
+  container
+  has subtags
+  nests

1.25      +12 -12    xmldocs/bin/refs-autogen

rev 1.25, prev_rev 1.24
Index: refs-autogen
RCS file: /var/cvs/xmldocs/bin/refs-autogen,v
retrieving revision 1.24
retrieving revision 1.25
diff -u -r1.24 -r1.25
--- refs-autogen	25 Aug 2004 10:14:54 -0000	1.24
+++ refs-autogen	31 Aug 2004 14:58:36 -0000	1.25
@@ -412,66 +412,66 @@
+<refsect1 id='$ag{"name"}_synopsis'>
+<refsect1 id='$ag{"name"}_$ag{"_first section"}'>
 <title>$ag{"_first section"}</title>
+<refsect1 id='$ag{"name"}_description'>
+<refsect1 id='$ag{"name"}_examples'>
+<refsect1 id='$ag{"name"}_notes'>
+<refsect1 id='$ag{"name"}_symbolType'>
 <title>SYMBOL TYPE</title>
 $ag{"symbol type"}
+<refsect1 id='$ag{"name"}_availability'>
 <para>$ag{"name"} is available in Interchange versions:
 $ag{"available in"}</para>
+<refsect1 id='$ag{"name"}_source'>
 <para>Interchange $ag{"source ver"}:
+<refsect1 id='$ag{"name"}_authors'>
+<refsect1 id='$ag{"name"}_bugs'>
+<refsect1 id='$ag{"name"}_copyright'>
+<refsect1 id='$ag{"name"}_seeAlso'>
 <title>SEE ALSO</title>
 <para>$ag{"see also"}</para>

1.1                  xmldocs/refs/area/control

rev 1.1, prev_rev 1.0
Index: control
purpose: produce a hypertext link
see also: page

1.1                  xmldocs/refs/area/description

rev 1.1, prev_rev 1.0
Index: description
The <tag>area</tag> tag expands to a proper hypertext URL which
preserves the Interchange session information and arguments passed onto
the targeted page. The target page argument you supply is treated relatively
to the <filename class='directory'>pages/</filename> directory inside your
catalog root directory (CATROOT).
The enclosing &lt;a href=""&gt;&lt;/a&gt; HTML tag is not included. This makes
<tag>area</tag> suitable for use in custom &lt;a&gt; links,
Javascript constructs and elsewhere.
This tag was named <literal>area</literal>, because it was first planned to
be used in client side Image-maps.
The <tag>area</tag> and <tag>page</tag> tags are similar; the following two
constructs are identical:
[page href="dir/page" arg="mv_arg"]Target Name</a>
<a href="[area href='dir/page' arg='mv_arg']">Target Name</a>
Besides just producing hypertext links to specific pages, you can also
"embed" complete HTML forms in the target link (for say, one-click ordering
or searches); see <xref linkend="area_examples"/>.

1.1                  xmldocs/refs/area/example

rev 1.1, prev_rev 1.0
Index: example

Produce the basic hypertext link

Add the following to an Interchange page:

Please visit our <a href="[area index]">Welcome</a> page.


1.1                  xmldocs/refs/area/example2

rev 1.1, prev_rev 1.0
Index: example2

Pass arguments onto the target page

Add the following link to an Interchange page:

Visit the <a href="[area href='index' arg='arg1=value1/arg2=value2']">test</a> page.


1.1                  xmldocs/refs/area/example3

rev 1.1, prev_rev 1.0
Index: example3

Simple item ordering using the area tag

Order a <a href="[area order TK112]" target='newframe'>Toaster</a> today.


1.1                  xmldocs/refs/area/example4

rev 1.1, prev_rev 1.0
Index: example4

Embedding HTML forms in the area tag

<A HREF="[area form="
]">Order T-shirt in Large size</A>

Or another example:

<a href="[area form="
  mv_order_fly=description=An on-the-fly item|price=100.01
"]">Order item 000101</a>

Which is equivalent to the usual HTML form:

<form action="[area process]" method=post>
  <input type='hidden' name='mv_todo' VALUE="refresh">
  <input type='hidden' name='mv_order_item' value="000101">
  Qty: <input size='2' name='mv_order_quantity' value="1">
  <input type='hidden' name='mv_order_fly' value="description=An on-the-fly item|price=100.00">
  <input type='submit' value="Order button">


1.1                  xmldocs/refs/area/synopsis

rev 1.1, prev_rev 1.0
Index: synopsis
[area href=<replaceable>page</replaceable> arg=<replaceable>argument</replaceable>]

1.2       +2 -2      xmldocs/refs/safe_data/example-blockwide

rev 1.2, prev_rev 1.1
Index: example-blockwide
RCS file: /var/cvs/xmldocs/refs/safe_data/example-blockwide,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- example-blockwide	23 Aug 2004 17:38:42 -0000	1.1
+++ example-blockwide	31 Aug 2004 14:58:36 -0000	1.2
@@ -12,9 +12,9 @@
 [tag pragma safe_data]1[/tag]
   ...critical section...
-	[restrict area page]
+  [restrict area page]
   ...critical section...
-	[/restrict]
+  [/restrict]
   ...critical section...
 [tag pragma safe_data]0[/tag]

More information about the docs mailing list