[docs] xmldocs - docelic modified 10 files

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
Log:
refs/area:
 - documented the [area] tag

refs/safe_data/example-blockwide:
 - replace TABs with spaces in code example
   (XML tolerates but doesn't like TABs)

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

TODO:
 - 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 @@
 
-DOCUMENTATION SYSTEM:
+PRIMARY:
+- 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>.
+
+
+DOCUMENTATION SYSTEM:
 - 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.
 
+iccattut:
+- give examples for the tasks in 'do yourself' section
+- give good practices about filtering, security
 
 GLOSSARY:
-tag, interpolation, reparse
+tag, interpolation, reparse, symbol types
 
  Mid-term:
 - Think about adding "online example" (role=html in combination with 
@@ -35,8 +44,6 @@
   mwforum demo on mwforum.org
 
  Long-term:
-- 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 @@
 
 Tags:
   parameters
-	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 @@
 <refpurpose>$ag{"purpose"}</refpurpose>
 </refnamediv>
 
-<refsect1>
+<refsect1 id='$ag{"name"}_synopsis'>
 <title>SYNOPSIS</title>
 $ag{"synopsis"}
 </refsect1>
 
-<refsect1>
+<refsect1 id='$ag{"name"}_$ag{"_first section"}'>
 <title>$ag{"_first section"}</title>
 <para>$ag{"default"}</para>
 </refsect1>
 
-<refsect1>
+<refsect1 id='$ag{"name"}_description'>
 <title>DESCRIPTION</title>
 <para>$ag{"description"}</para>
 </refsect1>
 
-<refsect1>
+<refsect1 id='$ag{"name"}_examples'>
 <title>EXAMPLES</title>
 $ag{"example"}
 </refsect1>
 
-<refsect1>
+<refsect1 id='$ag{"name"}_notes'>
 <title>NOTES</title>
 <para>$ag{"notes"}</para>
 </refsect1>
 
-<refsect1>
+<refsect1 id='$ag{"name"}_symbolType'>
 <title>SYMBOL TYPE</title>
 $ag{"symbol type"}
 </refsect1>
 
-<refsect1>
+<refsect1 id='$ag{"name"}_availability'>
 <title>AVAILABILITY</title>
 <para>$ag{"name"} is available in Interchange versions:
 </para><para>
 $ag{"available in"}</para>
 </refsect1>
 
-<refsect1>
+<refsect1 id='$ag{"name"}_source'>
 <title>SOURCE</title>
 <para>Interchange $ag{"source ver"}:
 </para>
 $ag{source}
 </refsect1>
 
-<refsect1>
+<refsect1 id='$ag{"name"}_authors'>
 <title>AUTHORS</title>
 <para>$ag{"author"}</para>
 </refsect1>
 
-<refsect1>
+<refsect1 id='$ag{"name"}_bugs'>
 <title>BUGS</title>
 $ag{"bugs"}
 </refsect1>
 
-<refsect1>
+<refsect1 id='$ag{"name"}_copyright'>
 <title>COPYRIGHT</title>
 $ag{"copyright"}
 </refsect1>
 
-<refsect1>
+<refsect1 id='$ag{"name"}_seeAlso'>
 <title>SEE ALSO</title>
 <para>$ag{"see also"}</para>
 </refsect1>



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).
</para><para>
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.
</para><para>
This tag was named <literal>area</literal>, because it was first planned to
be used in client side Image-maps.
</para><para>
The <tag>area</tag> and <tag>page</tag> tags are similar; the following two
constructs are identical:
</para>
<programlisting><![CDATA[
[page href="dir/page" arg="mv_arg"]Target Name</a>
<a href="[area href='dir/page' arg='mv_arg']">Target Name</a>
]]></programlisting>
<para>
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
===================================================================
<example>

<title>
Produce the basic hypertext link
</title>

<para>
Add the following to an Interchange page:
</para>

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

</example>



1.1                  xmldocs/refs/area/example2


rev 1.1, prev_rev 1.0
Index: example2
===================================================================
<example>

<title>
Pass arguments onto the target page
</title>

<para>
Add the following link to an Interchange page:
</para>

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

</example>



1.1                  xmldocs/refs/area/example3


rev 1.1, prev_rev 1.0
Index: example3
===================================================================
<example>

<title>
Simple item ordering using the area tag
</title>

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

</example>



1.1                  xmldocs/refs/area/example4


rev 1.1, prev_rev 1.0
Index: example4
===================================================================
<example>

<title>
Embedding HTML forms in the area tag
</title>

<programlisting><![CDATA[
<A HREF="[area form="
  mv_order_item=99-102
  mv_order_size=L
  mv_order_quantity=1
  mv_separate_items=1
  mv_todo=refresh"
]">Order T-shirt in Large size</A>
]]></programlisting>

<para>
Or another example:
</para>

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

<para>
Which is equivalent to the usual HTML form:
</para>

<programlisting><![CDATA[
<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">
</form>
]]></programlisting>

</example>



1.1                  xmldocs/refs/area/synopsis


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



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 @@
 <programlisting><![CDATA[
 [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]
 ]]></programlisting>






