Permalink
Browse files

- Cleaned some TODO items and reorganized TODO a bit

  • Loading branch information...
1 parent 51b4050 commit 9cc5ea79bc1b4d8ec514309f619920929b9dac8d @docelic docelic committed Oct 14, 2004
Showing with 53 additions and 58 deletions.
  1. +23 −37 TODO
  2. +6 −0 bin/refs-autogen
  3. +24 −21 guides/xmldocs.xml
View
60 TODO
@@ -4,14 +4,10 @@ PRIMARY:
<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 @@ PRIMARY:
- 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 @@ DOCUMENTATION SYSTEM:
- 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 docs:
- 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 )
View
@@ -251,6 +251,11 @@ while ( $path = shift @paths) { # For each version specified
$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 @@ while ( my($k,$v) = each %autogenerated ) {
# 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";
View
@@ -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,36 +504,36 @@
<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/>
<ulink url="http://www.docbook.org/tdg/en/html/guilabel.html">guilabel</ulink><sbr/>
<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,25 +544,25 @@
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/>
<ulink url="http://www.docbook.org/tdg/en/html/screen.html">screen</ulink> - used as element in which you display existing interchange source (this is mostly in autogenerated pages but can be used manually)<sbr/>
<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/>

0 comments on commit 9cc5ea7

Please sign in to comment.