[docs] xmldocs - docelic modified 3 files

docs at icdevgroup.org docs at icdevgroup.org
Thu Oct 14 11:54:42 EDT 2004


User:      docelic
Date:      2004-10-14 15:54:42 GMT
Modified:  .        TODO
Modified:  bin      refs-autogen
Modified:  guides   xmldocs.xml
Log:
- Cleaned some TODO items and reorganized TODO a bit

Revision  Changes    Path
1.34      +23 -37    xmldocs/TODO


rev 1.34, prev_rev 1.33
Index: TODO
===================================================================
RCS file: /var/cvs/xmldocs/TODO,v
retrieving revision 1.33
retrieving revision 1.34
diff -u -r1.33 -r1.34
--- TODO	12 Oct 2004 09:41:24 -0000	1.33
+++ TODO	14 Oct 2004 15:54:42 -0000	1.34
@@ -4,14 +4,10 @@
   <cmdsynopsis> is verbatim and <screen> still renders comments without
   newlines! I mean, what the... (And &copy; is translated to crap instead
   of plain "C"). Will need to write XSLT to fix that, and support tables.
-- not to forget, fix cases where context goes to negative values
 - Contexts: in situation like "symbol \n symbol" where the symbol appears
   multiple times within +- of first occurence, we treat it like one context.
   but the header says 'displaying 2/2 contexts', it doesn't remove
   'duplicates'. fix that.
-- If usertag MapRoutines, display the routine
-- If See Also item starts with '<', do not perform any scrabmle on it and
-  pass as-is
 
 - In iccattut:
   - make a "translation map" of /etc/interchange/* to RPM-equivs.
@@ -21,9 +17,32 @@
   - Fix ImageDir and include one picture for example
 
 - in source contexts, wrap runaway lines
+- match style (no starting verb or all starting verbs) in all Example titles
+- Makefile: olinkdbs targets need to have literal depends, not $(shell )
+- 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
 
 HOWTOs:
 - how to delete item from cart in all possible ways
+- create a menu bar: see bar_button
+
+- 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 SYSTEM:
 - copy the definition for <example> to a
@@ -34,16 +53,11 @@
 - Read all possible options for tag files from vend/config.pm
   (%tag.* structures) and warn if invalid option is found in any tag file.
 
-- properly wrap examples in xmldocs.xml in mentioned tags so that it's
-  directly visible an example of the tag
-
 iccattut:
 - give examples for the tasks in 'do yourself' section (in progress)
 - give good practices about filtering, security
 - see problems from old docs/TODO notes on iccattut
 
-GLOSSARY:
-tag, interpolation, reparse, symbol types
 
  Mid-term:
 - Think about adding "online example" (role=html in combination with 
@@ -115,32 +129,4 @@
  - new developer howto
 
 ----------
-catalog/global variable, tag,ui,
-action, form,  unix inet socket, values,
-regex, flypage, sku
-
-match style (no starting verb or all starting verbs) in all Example titles
-
-style: leave newline at end of file
-explain version naming.. stable/unstable and how 5.3.0 implies next stable
-
-script to [un]comment debug lines
-Say about accesskeys in html source, for key-based navigation
-
-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
-
-how to:
-- create a menu bar: see bar_button
-- 
-
-check if all Default fields are properly formated (<literal> or none)
-s/a HTML/an HTML/
-
-Makefile:
- - olinkdbs targets need to have literal depends, not $(shell )
 



1.47      +6 -0      xmldocs/bin/refs-autogen


rev 1.47, prev_rev 1.46
Index: refs-autogen
===================================================================
RCS file: /var/cvs/xmldocs/bin/refs-autogen,v
retrieving revision 1.46
retrieving revision 1.47
diff -u -r1.46 -r1.47
--- refs-autogen	14 Oct 2004 15:32:38 -0000	1.46
+++ refs-autogen	14 Oct 2004 15:54:42 -0000	1.47
@@ -251,6 +251,11 @@
 						$cend = $cstart + scalar @{$$ctx{ctx}}-1;
 						$cstart == 1 and $cend -= 1;
 					}
+
+					# General fix, shouldn't break anything
+					$cstart <= 0 and $cstart = 1;
+					$cend > @{ $$ctx{ctx} } and $cend = @{ $$ctx{ctx} }-1;
+
 					$ctxmeta .= " (context shows lines " . ( $cstart . "-" .  $cend );
 					# XXX - eliminate negative numbers in source context spans
 					# ( 0-6 == OK, -4-6 != OK )
@@ -347,6 +352,7 @@
 	# XXX only if it's the symbol from same category, otherwise use
 	# olink to link between documents
 	for my $itm ( @see_items ) {
+		next if $itm =~ /^</;
 		if ( $autogenerated{$itm} ) {
 			my $linktype = "link"; # the default, linking inside the same document
 			my $linkarg = "linkend";



1.7       +24 -21    xmldocs/guides/xmldocs.xml


rev 1.7, prev_rev 1.6
Index: xmldocs.xml
===================================================================
RCS file: /var/cvs/xmldocs/guides/xmldocs.xml,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- xmldocs.xml	9 Oct 2004 20:33:34 -0000	1.6
+++ xmldocs.xml	14 Oct 2004 15:54:42 -0000	1.7
@@ -45,10 +45,13 @@
 		<para>
 		The purpose of this document is to give you a
 		<emphasis>Quick Start</emphasis> on XMLDOCS authoring.
-		Where appropriate (and needed for context reasons), we will discuss the underlying technologies, Interchange sources and the XMLDOCS layer organization.
+		Where appropriate (and needed for context reasons), we will discuss the
+		underlying technologies, Interchange sources and the XMLDOCS layer
+		organization.
 		</para>
 		<para>
-		After this, you might be interested in more technical reading found in <filename>xmldocs/README</filename>.
+		After this, you might be interested in more technical reading found
+		in <filename>xmldocs/README</filename>.
 		</para>
 	</abstract>
 
@@ -501,28 +504,28 @@
 
 		<para>
 		<ulink url="http://www.docbook.org/tdg/en/html/acronym.html">acronym</ulink><sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/application.html">application</ulink> - software program name<sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/arg.html">arg</ulink> - part of the cmdsynopsis element<sbr/>
+		<ulink url="http://www.docbook.org/tdg/en/html/application.html">application</ulink> - software program name, such as <application>QuickBooks</application><sbr/>
+		<ulink url="http://www.docbook.org/tdg/en/html/arg.html">arg</ulink> - part of the cmdsynopsis element, such as <arg>value</arg> (it renders differently depnding on the type of argument - plain, required, or optional*)<sbr/>
 		<ulink url="http://www.docbook.org/tdg/en/html/blockquote.html">blockquote</ulink><sbr/>
 		<ulink url="http://www.docbook.org/tdg/en/html/classname.html">classname</ulink> - Perl module name, such as <classname>Image::Size</classname><sbr/>
 		<ulink url="http://www.docbook.org/tdg/en/html/cmdsynopsis.html">cmdsynopsis</ulink> - the parent element for all synopsis lines<sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/code.html">code</ulink> - chunks of actual code. Use to display ITL/Perl/any-other code examples inline<sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/command.html">command</ulink> - computer command name (usually Unix command)<sbr/>
+		<ulink url="http://www.docbook.org/tdg/en/html/code.html">code</ulink> - chunks of actual code. Use to display ITL/Perl/any-other code examples inline, suc as <code>[scratch tempvar]</code><sbr/>
+		<ulink url="http://www.docbook.org/tdg/en/html/command.html">command</ulink> - computer command name (usually Unix command), such as <command>ls</command><sbr/>
 		<ulink url="http://www.docbook.org/tdg/en/html/computeroutput.html">computeroutput</ulink><sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/constant.html">constant</ulink><sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/database.html">database</ulink> - everything related to a database. See class='' option to it<sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/emphasis.html">emphasis</ulink> - renders as italic text<sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/envar.html">envar</ulink> - environment variable, such as REMOTE_PORT<sbr/>
+		<ulink url="http://www.docbook.org/tdg/en/html/constant.html">constant</ulink>, such as <constant>MAXPATHLEN</constant><sbr/>
+		<ulink url="http://www.docbook.org/tdg/en/html/database.html">database</ulink> - everything related to a database. See class='' option to it; such as field <database class='field'>sku</database><sbr/>
+		<ulink url="http://www.docbook.org/tdg/en/html/emphasis.html">emphasis</ulink> - renders as <emphasis>italic</emphasis> or <emphasis role='bold'>bold with role='bold'</emphasis><sbr/>
+		<ulink url="http://www.docbook.org/tdg/en/html/envar.html">envar</ulink> - environment variable, usually as seen by the web server or IC, such as <envar>REMOTE_PORT</envar><sbr/>
 		<ulink url="http://www.docbook.org/tdg/en/html/errorcode.html">errorcode</ulink><sbr/>
 		<ulink url="http://www.docbook.org/tdg/en/html/errorname.html">errorname</ulink><sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/errortext.html">errortext</ulink> - such as "Page not found"<sbr/>
+		<ulink url="http://www.docbook.org/tdg/en/html/errortext.html">errortext</ulink> - such as <errortext>Page not found</errortext><sbr/>
 		<ulink url="http://www.docbook.org/tdg/en/html/errortype.html">errortype</ulink><sbr/>
 		<ulink url="http://www.docbook.org/tdg/en/html/example.html">example</ulink> - parent element for all examples<sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/filename.html">filename</ulink> - file and directory (class='directory') names<sbr/>
-		filter - Interchange filter name (XMLDOCS extension to DocBook XML)<sbr/>
+		<ulink url="http://www.docbook.org/tdg/en/html/filename.html">filename</ulink> - file and directory (class='directory') names, such as <filename>/etc/syslog.conf</filename><sbr/>
+		filter - Interchange filter name (XMLDOCS extension to DocBook XML), such as <filter>entities</filter><sbr/>
 		<ulink url="http://www.docbook.org/tdg/en/html/firstterm.html">firstterm</ulink> - first occurence of a term. Renders as italic<sbr/>
 		<ulink url="http://www.docbook.org/tdg/en/html/footnote.html">footnote</ulink><sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/function.html">function</ulink> - function name, such as syscall64()<sbr/>
+		<ulink url="http://www.docbook.org/tdg/en/html/function.html">function</ulink> - function name, such as <function>syscall64()</function><sbr/>
 		<ulink url="http://www.docbook.org/tdg/en/html/group.html">group</ulink> - grouping of args inside cmdsynopsis<sbr/>
 		<ulink url="http://www.docbook.org/tdg/en/html/guibutton.html">guibutton</ulink> - identify buttons in the (web) gui, such as <guibutton>Finalize!</guibutton><sbr/>
 		<ulink url="http://www.docbook.org/tdg/en/html/guiicon.html">guiicon</ulink><sbr/>
@@ -530,7 +533,7 @@
 		<ulink url="http://www.docbook.org/tdg/en/html/guimenu.html">guimenu</ulink><sbr/>
 		<ulink url="http://www.docbook.org/tdg/en/html/guimenuitem.html">guimenu</ulink><sbr/>
 		<ulink url="http://www.docbook.org/tdg/en/html/guisubmenu.html">guisubmenu</ulink><sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/hardware.html">hardware</ulink> - piece of hardware<sbr/>
+		<ulink url="http://www.docbook.org/tdg/en/html/hardware.html">hardware</ulink> - piece of hardware, such as <hardware>motherboard</hardware><sbr/>
 		<ulink url="http://www.docbook.org/tdg/en/html/important.html">important</ulink><sbr/>
 		<ulink url="http://www.docbook.org/tdg/en/html/itemizedlist.html">itemizedlist</ulink> - most commonly used type of list<sbr/>
 		<ulink url="http://www.docbook.org/tdg/en/html/keysym.html">keysym</ulink><sbr/>
@@ -541,12 +544,12 @@
 		mv - identify form variable, such as <mv>mv_return_all</mv> (XMLDOCS extension to DocBook XML)<sbr/>
 		<ulink url="http://www.docbook.org/tdg/en/html/note.html">note</ulink><sbr/>
 		<ulink url="http://www.docbook.org/tdg/en/html/olink.html">olink</ulink><sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/option.html">option</ulink> - use it to mark Interchange config directives (like say, MailOrderTo or Variable)<sbr/>
+		<ulink url="http://www.docbook.org/tdg/en/html/option.html">option</ulink> - use it to mark Interchange config directives (like say, <option>MailOrderTo</option> or <option>Variable</option>)<sbr/>
 		<ulink url="http://www.docbook.org/tdg/en/html/para.html">para</ulink> - the standard paragraph element<sbr/>
-		pragma - Interchange pragma name (XMLDOCS extension to DocBook XML)<sbr/>
+		pragma - Interchange pragma name (XMLDOCS extension to DocBook XML), such as <pragma>no_html_comment_embed</pragma><sbr/>
 		<ulink url="http://www.docbook.org/tdg/en/html/productname.html">productname</ulink><sbr/>
 		<ulink url="http://www.docbook.org/tdg/en/html/programlisting.html">programlisting</ulink><sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/prompt.html">prompt</ulink> - computer prompt, such as Login:<sbr/>
+		<ulink url="http://www.docbook.org/tdg/en/html/prompt.html">prompt</ulink> - computer prompt, such as <prompt>Login:</prompt><sbr/>
 		<ulink url="http://www.docbook.org/tdg/en/html/replaceable.html">replaceable</ulink> - identified the replaceable part in the cmdsynopsis element<sbr/>
 		<ulink url="http://www.docbook.org/tdg/en/html/returnvalue.html">returnvalue</ulink><sbr/>
 		<ulink url="http://www.docbook.org/tdg/en/html/sbr.html">sbr</ulink> - starts a newline. Useful in cmdsynopsis or if you don't want to split the paragraph in two, which then generates a wide spacing<sbr/>
@@ -554,12 +557,12 @@
 		<ulink url="http://www.docbook.org/tdg/en/html/subscript.html">subscript</ulink><sbr/>
 		<ulink url="http://www.docbook.org/tdg/en/html/superscript.html">superscript</ulink><sbr/>
 		<ulink url="http://www.docbook.org/tdg/en/html/systemitem.html">systemitem</ulink> - various system items, see possible class='' values<sbr/>
-		tag - Interchange tag name (XMLDOCS extension to DocBook XML)<sbr/>
+		tag - Interchange tag name (XMLDOCS extension to DocBook XML), such as <tag>include</tag> or <tag>data</tag><sbr/>
 		<ulink url="http://www.docbook.org/tdg/en/html/term.html">term</ulink><sbr/>
 		<ulink url="http://www.docbook.org/tdg/en/html/tip.html">tip</ulink><sbr/>
 		<ulink url="http://www.docbook.org/tdg/en/html/ulink.html">ulink</ulink><sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/userinput.html">userinput</ulink> - similar to &lt;command&gt; but here you can also include parameters, actually the complete command line the user would run<sbr/>
-		<ulink url="http://www.docbook.org/tdg/en/html/varname.html">varname</ulink> - global or catalog Interchange variable, such as MV_PAGE or UI_IMAGE_DIR<sbr/>
+		<ulink url="http://www.docbook.org/tdg/en/html/userinput.html">userinput</ulink> - similar to &lt;command&gt; but here you can also include parameters, actually the complete command line the user would run, such as <userinput>ls /etc</userinput><sbr/>
+		<ulink url="http://www.docbook.org/tdg/en/html/varname.html">varname</ulink> - global or catalog Interchange variable, such as <varname>MV_PAGE</varname> or <varname>UI_IMAGE_DIR</varname><sbr/>
 		<ulink url="http://www.docbook.org/tdg/en/html/warning.html">warning</ulink><sbr/>
 		<ulink url="http://www.docbook.org/tdg/en/html/wordasword.html">wordasword</ulink><sbr/>
 		<ulink url="http://www.docbook.org/tdg/en/html/xref.html">xref</ulink><sbr/>








More information about the docs mailing list