Permalink
Browse files

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
  • Loading branch information...
docelic committed Aug 31, 2004
1 parent fbf7c6b commit 81e9a5e10bf27474f2bcd87522cc9e9c2ec1a7ac
Showing with 150 additions and 30 deletions.
  1. +23 −16 TODO
  2. +12 −12 bin/refs-autogen
  3. +2 −0 refs/area/control
  4. +24 −0 refs/area/description
  5. +15 −0 refs/area/example
  6. +15 −0 refs/area/example2
  7. +11 −0 refs/area/example3
  8. +43 −0 refs/area/example4
  9. +3 −0 refs/area/synopsis
  10. +2 −2 refs/safe_data/example-blockwide
View
39 TODO
@@ -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 @@ DOCUMENTATION SYSTEM:
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 @@ tag, interpolation, reparse
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 @@ Pragmas, globvars:
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
View
@@ -412,66 +412,66 @@ __DATA__
<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>
View
@@ -0,0 +1,2 @@
+purpose: produce a hypertext link
+see also: page
View
@@ -0,0 +1,24 @@
+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"/>.
View
@@ -0,0 +1,15 @@
+<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>
View
@@ -0,0 +1,15 @@
+<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>
View
@@ -0,0 +1,11 @@
+<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>
View
@@ -0,0 +1,43 @@
+<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>
View
@@ -0,0 +1,3 @@
+<synopsis>
+[area href=<replaceable>page</replaceable> arg=<replaceable>argument</replaceable>]
+</synopsis>
@@ -12,9 +12,9 @@ enclose the critical section in <code>[tag pragma ...]</code>:
<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>

0 comments on commit 81e9a5e

Please sign in to comment.