[docs] xmldocs - docelic modified 3 files
docs at icdevgroup.org
docs at icdevgroup.org
Tue Feb 1 16:30:12 EST 2005
User: docelic
Date: 2005-02-01 21:30:11 GMT
Modified: guides iccattut.xml xmldocs.xml
Added: guides programming-style.xml
Log:
- programming-style: new guide. Basically programming-style document that
was seen flying around in CVS/-core list
- iccattut: cosmetic
- xmldocs: little tuning
Revision Changes Path
1.31 +0 -1 xmldocs/guides/iccattut.xml
rev 1.31, prev_rev 1.30
Index: iccattut.xml
===================================================================
RCS file: /var/cvs/xmldocs/guides/iccattut.xml,v
retrieving revision 1.30
retrieving revision 1.31
diff -u -r1.30 -r1.31
--- iccattut.xml 14 Dec 2004 21:07:31 -0000 1.30
+++ iccattut.xml 1 Feb 2005 21:30:11 -0000 1.31
@@ -9,7 +9,6 @@
<articleinfo>
<title>Interchange Guides: the Catalog Building Tutorial</title>
<titleabbrev>iccattut</titleabbrev>
- <edition>version xml2.0pre</edition>
<copyright>
<year>2003</year><year>2004</year>
1.11 +0 -309 xmldocs/guides/xmldocs.xml
rev 1.11, prev_rev 1.10
Index: xmldocs.xml
===================================================================
RCS file: /var/cvs/xmldocs/guides/xmldocs.xml,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -r1.10 -r1.11
--- xmldocs.xml 27 Dec 2004 01:06:11 -0000 1.10
+++ xmldocs.xml 1 Feb 2005 21:30:11 -0000 1.11
@@ -1,312 +1,3 @@
-<?xml version="1.0" standalone="no"?>
-
-<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook-Interchange XML V4.2//EN"
- "../docbook/docbookxi.dtd">
-
-<article id='xmldocs'>
-
-<articleinfo>
- <title>Interchange Guides: the XMLDOCS Documentation System</title>
- <titleabbrev>xmldocs</titleabbrev>
-
- <copyright>
- <year>2004</year>
- <holder>Davor Ocelic</holder>
- </copyright>
- <copyright>
- <year>2004</year>
- <holder>Interchange Development Group</holder>
- </copyright>
-
- <authorgroup>
- <author>
- <firstname>Davor</firstname><surname>Ocelic</surname>
- <email>docelic at icdevgroup.org</email>
- </author>
- </authorgroup>
-
- <legalnotice>
- <para>
- This documentation is free; you can redistribute it and/or modify
- it under the terms of the &GNU; General Public License as published by
- the Free Software Foundation; either version 2 of the License, or
- (at your option) any later version.
- </para>
- <para>
- It is distributed in the hope that it will be useful,
- but WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- GNU General Public License for more details.
- </para>
- </legalnotice>
-
- <abstract>
- <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.
- </para>
- <para>
- After this, you might be interested in more technical reading found
- in <filename>xmldocs/README</filename>.
- </para>
- </abstract>
-
-</articleinfo>
-
-
-<sect1 id='Introduction'>
- <title>Introduction</title>
-
- <!-- <para>
- Before I officially joined the &ICDEVGROUP;, I have already identified the
- weak points in the documentation system used. I found that:
- </para>
-
- <itemizedlist>
- <listitem><para>
- The SDF/POD format caused too much "overhead" every time you wanted to
- add a piece of information (and everything had to be added manually). Also,
- the available SDF/POD tools and output formats were inflexible and not
- up to today's open documentation standards.
- </para></listitem>
- <listitem><para>
- The documentation itself didn't (quite) keep up with the development;
- a lot of items were never documented. The parts that were, were more or
- less valid but did not include details and insights, and did not
- <emphasis>feel</emphasis> current.
- </para></listitem>
- </itemizedlist> -->
-
- <para>
- </para>
-
- <para>
- At first (after joining the ICDEVGROUP), I wasn't openly suggesting a
- complete documentation redesign because I thought I wasn't in position
- to propose bigger procedural changes. However, I was encouraged by
- Stefan "Racke" Hornburg to investigate this possibilty ;-)
- </para>
-
- <para>
- My general idea was to link the documentation to the Interchange sources,
- and use <emphasis>auto-generation</emphasis> where ever possible.
- In a private e-mail thread, Stefan suggested using XML as the base. As XML
- is definitely better than any custom system I can come up with, this was a
- push in the right direction.
- </para>
-
- <para>
- The main Interchange XMLDOCS goals (as mentioned in my first -core post from Tue Jul 6 17:59:25 EDT 2004) are:
- <itemizedlist>
- <listitem><para>
- Minimizing the documentation writing overhead (clean and easy authoring
- system <emphasis>and</emphasis> autogeneration of all information the
- computer can derive with no human intervention),
- </para></listitem>
- <listitem><para>
- Standard, flexible format for good readability and easy contribution,
- </para></listitem>
- <listitem><para>
- Increase in overall documentation accuracy and completeness,
- </para></listitem>
- <listitem><para>
- Higher-quality output formats.
- </para></listitem>
- </itemizedlist>
- </para>
-
-</sect1>
-
-<sect1 id='DocumentationStructure'>
- <title>Documentation Structure</title>
-
- <para>
- So, the current system is split into the following categories:
- </para>
- <itemizedlist>
- <listitem><para>
- Guides (easy reading, mostly prose and not overly technical documents serving as an "illustrated introduction" to the subject, take iccattut for example)
- </para></listitem>
- <listitem><para>
- HOW-TOs (quick, on-topic, technical solutions)
- </para></listitem>
- <listitem><para>
- References (quick, on-topic refentry pages describing
- Interchange "symbols" - global variables, pragmas, user tags, system
- tags, filters, ...).
- </para></listitem>
- <listitem><para>
- Glossary
- </para></listitem>
- </itemizedlist>
- <para>
- It is important to note that only Guides are directly edited in-place
- (that is, by opening and editing <filename>guides/*.xml</filename>).
- Generation of any output format can be invoked on those files without
- additional preparation.
- </para>
- <para>
- All other source XML files (reference pages, the HOW-TO collection and the
- glossary) first need to be generated by appropriate
- <command>bin/*-autogen</command> script, and then such complete XML
- files can be used for the production of final output.
- </para>
- <para>
- The autogen scripts combine autodiscovered information (gathered by
- <command>bin/stattree</command>), a lot of Interchange-specific
- documentation logic, and the user-supplied documentation chunks, into
- complete source .xml files.
- </para>
- <para>
- The user-supplied chunks are kept in obvious places,
- <filename>glossary/*</filename>,
- <filename>howtos/*</filename> and
- <filename>refs/*</filename>.
- </para>
- <para>
- <command>bin/refs-autogen</command> is used to generate the reference
- pages (containing many individual refentries).
- <command>bin/generic-autogen</command> is used for the glossary and
- the HOW-TO collection.
- </para>
- <para>
- The whole autogeneration story comes from the observation that
- <emphasis>enormous</emphasis> piece of the final XML source can be
- produced automatically, with insertions and templating. So, every chunk
- you write still has to be XML-conformant (of course), but you no longer
- have to write all those repetitive blocks of XML.
- </para>
-</sect1>
-
-<sect1 id='AuthoringQuickStart'>
- <title>Authoring QuickStart</title>
-
- <para>
- The documentation writing procedure is not always the same, it depends
- on the actual part of the content you want to write/update.
- The procedure <emphasis>could</emphasis> be the same in theory, but in
- practice it is mostly symbol type-dependent, so that more of XML can
- be autogenerated.
- </para>
-
- <sect2>
- <title>Modifying Guides</title>
- <para>
- To modify an existing guide, simply edit
- <filename>guides/<replaceable>name</replaceable>.xml</filename>.
- </para>
- <para>
- To start a new guide, create a new
- <filename>guides/<replaceable>name</replaceable>.xml</filename> file.
- For a quickstart, copy the exact structure as you see in the existing
- <literal>iccattut</literal> guide. The iccattut guide will always reflect
- the current standard.
- </para>
- <para>
- To make the new guide build as part of the global <command>make</command>
- procedure, open the <filename>Makefile</filename> and simply add the
- guide .xml name under the <literal>GUIDES = </literal> section.
- </para>
- <para>
- To build it manually, invoke <command>make
- OUTPUT/<replaceable>name</replaceable>.<replaceable>format</replaceable>
- </command>, where 'format' represents typical filename extensions (such
- as .html or .ps). If you leave ".<replaceable>format</replaceable>"
- unspecified, the chunked HTML version will be built and, of course,
- saved to
- <filename class='directory'>OUTPUT/<replaceable>name</replaceable>/</filename>.
- </para>
- </sect2>
-
- <sect2>
- <title>Modifying HOW-TOs</title>
- <para>
- To modify an existing HOW-TO item, simply edit
- <filename>howtos/<replaceable>name</replaceable>.xml</filename>.
- </para>
- <para>
- To start a new HOWTO item, create a new
- <filename>howtos/<replaceable>name</replaceable>.xml</filename> file.
- For a quickstart, copy the exact structure as you see in the existing
- <literal>custom-sendmail-routine.xml</literal>. It will always reflect
- the current standard.
- </para>
- <para>
- To make the new HOW-TO entry build as part of the global
- <command>make</command> procedure, you don't have to do anything;
- the <filename>howtos/howtos.xml</filename> is automatically regenerated
- (by following Makefile dependencies). If you need to trigger .xml file
- regeneration manually, invoke <userinput>make howtos/howtos.xml</userinput>.
- </para>
- <para>
- To build the HOW-TO collection,
- invoke <command>make OUTPUT/howtos.<replaceable>format</replaceable>
- </command>, where 'format' represents typical filename extensions (such
- as .html or .ps). If you leave ".<replaceable>format</replaceable>"
- unspecified, the chunked HTML version of the HOW-TO collection will be
- built and, of course, saved to <filename>OUTPUT/howtos/</filename>.
- </para>
- </sect2>
-
- <sect2>
- <title>
- Modifying Symbols (pragmas, globvars, *tags, globconfs, catconfs, filters)
- </title>
- <para>
- To modify an existing symbol, simply edit <filename>refs/*</filename>
- or <filename>refs/*/*</filename> (depending on whether the symbol
- documentation was saved in one-file or multi-file format). Multi-file
- format was used in the beginning, and although is still normally
- supported, it seems to be less convenient.
- </para>
- <para>
- To document a new symbol using one-file format, run <command>bin/editem
- <replaceable>name</replaceable></command>. This will create skeleton
- file (<filename>refs/<replaceable>name</replaceable></filename>) and
- load it in your editor. Before you get the grip, <emphasis>carefully
- read the embedded comments in the file</emphasis> that will guide you
- through.
- </para>
- <para>
- After you've added a symbol, you need to regenerate the
- <filename>refs/*.xml</filename> file(s) which
- it affected. This should happen as part of the standard Make dependency
- resolution, but if you need to invoke unconditional manual regeneration,
- use <command>make clean-refs refxmls</command>.
- </para>
- <para>
- Note that the refentries can be built in manpage format as well.
- To generate the manpages, run
- <command>make OUTPUT/<replaceable>group</replaceable>.man</command>,
- where <literal>group</literal> is one of
- pragmas, globvars, usertags, systemtags, uitags etc. The output manpages
- will be placed to a common manpage directory,
- <filename class='directory'>OUTPUT/man/</filename>.
- </para>
- </sect2>
-
- <sect2>
- <title>Modifying Glossary</title>
- <para>
- To modify an existing item, simply edit the appropriate
- <filename>glossary/*</filename> file.
- </para>
- <para>
- To add a new glossary entry, create the
- <filename>glossary/<replaceable>name</replaceable></filename> file
- (copy the structure from <filename>glossary/pragma</filename>).
- </para>
- <para>
- To generate the glossary XML source manually, run
- <command>make glossary/glossary.xml</command>. To build the glossary,
- run <command>make OUTPUT/glossary.<replaceable>format</replaceable>
- </command>.
- </para>
- </sect2>
-
</sect1>
<sect1 id='XMLGuidelines'>
1.1 xmldocs/guides/programming-style.xml
rev 1.1, prev_rev 1.0
Index: programming-style.xml
===================================================================
<?xml version="1.0" standalone="no"?>
<!-- catalog not working ? -->
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook-Interchange XML V4.2//EN"
"../docbook/docbookxi.dtd">
<article id='programming-style'>
<articleinfo>
<title>Interchange Guides: Official Programming Style</title>
<titleabbrev>programming-style</titleabbrev>
<copyright>
<year>2003</year><year>2004</year><year>2005</year>
<holder>Interchange Development Group</holder>
</copyright>
<authorgroup>
<author>
<firstname>Davor</firstname><surname>Ocelic</surname>
<email>docelic at icdevgroup.org</email>
</author>
<author><firstname>Mike</firstname><surname>Heins</surname>
<email>mike at perusion.com</email>
</author>
<author><firstname>Jeff</firstname><surname>Barr</surname>
<!-- <email></email> -->
</author>
<author>
<firstname>Eric</firstname><surname>Zarko</surname>
<!--<email></email>-->
</author>
<author>
<firstname>Jon</firstname><surname>Jensen</surname>
<email>jon at endpoint.com</email>
</author>
<author><firstname>Sonny</firstname><surname>Cook</surname>
<email>sonny at endpoint.com</email>
</author>
</authorgroup>
<legalnotice>
<para>
This documentation is free; you can redistribute it and/or modify
it under the terms of the &GNU; General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
</para>
<para>
It is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
</para>
</legalnotice>
<abstract>
<para>
The purpose of this document is present the officially encouraged &IC; programming style.
</para>
</abstract>
</articleinfo>
<sect1 id='GeneralProgrammingStyle'>
<title>General Programming Style</title>
<para>
&IC; programming style is <literal>perlstyle</literal>, with few
additions. Most of the following was decided in a meeting held on
November 14, 2000.
</para>
<para>
We agreed that it is good to have a programming style, and
that the existing style of code should be preserved. We agreed that making
global changes to impose a consistent style is not worth doing. Instead,
we will make revisions as we rewrite code. We will generally follow the
published &PERL; style <ulink url="http://www.perl.com/doc/manual/html/pod/perlstyle.html">guidelines</ulink>.
</para>
<!-- TODO check out http://perlmonks.thepen.com/209555.html -->
</sect1>
<sect1 id="Additions">
<title>Interchange-specific additions</title>
<itemizedlist>
<listitem><para>
<emphasis role='bold'>if / else</emphasis> - we accept, but do not
encourage the use of <emphasis>cuddled else</emphasis> constructs
(those with <literal>} else {</literal> on the same line). Use:
<programlisting>
}
else {
</programlisting>
</para></listitem>
<listitem><para>
<emphasis role='bold'>Lexical Issues</emphasis> - white space is free,
and white space around operators increases readability.
Lining up <literal>=</literal>s in a series of assignments can be
used to emphasize the parallel structure.
</para></listitem>
<listitem><para>
<emphasis role='bold'>Naming</emphasis> - package globals
should start with a capital letter. In other
situations, avoid <emphasis>StudlyCaps</emphasis> where names begin
with a capital letter.
Items in the main package should be referenced as
<literal>$::<replaceable>Foo</replaceable></literal>, not
<literal>$main::<replaceable>Foo</replaceable></literal>.
</para></listitem>
<listitem><para>
<emphasis role='bold'>Globals</emphasis> - global variables and subs
should be used very sparingly.
Occasionally it is necessary to use global variables as implicit arguments
to certain subs for efficiency purposes. We should not add more globals,
and we should consider removing existing ones. An important exception are
certain subs such as <function>logGlobal</function>,
<function>logDebug</function>, <function>errmsg</function>, and
<function>logError</function>.
</para></listitem>
<listitem><para>
<emphasis role='bold'>CVS</emphasis> - CVS comments should be meaningful.
As a matter of good programming
practice, we encourage a careful review of all diffs before committing
changes to CVS. When committing a large number of files (possibly
containing changes and fixes to multiple areas) it is best to create
file-specific comments addressing individual fixes. Using blank
comments is not encouraged.
</para></listitem>
<listitem><para>
<emphasis role='bold'>Loops</emphasis> - we prefer to declare loop
control variables immediately prior to the beginning of the loop:
<programlisting>
my $var;
foreach $var () {
...
}
</programlisting>
</para></listitem>
<listitem><para>
<emphasis role='bold'>HTML</emphasis> - in late 2004, it was agreed to
make the HTML code as XHTML-compliant as possible, but without using
XHTML constructs that could cause problems for older browsers.
</para>
<para>
In essence, all &glos-HTML; tag and argument names should be lowercased,
and all argument values should be quoted, using double quotes if not
particularly unsuitable. &PERL; gives us the nice <literal>qq{}</literal>
operator that eliminates the problem of quotes clashing with Perl syntax:
<programlisting><![CDATA[
my $buf = qq{<a href="http://google.com/">Visit Google!</a>};
]]></programlisting>
</para>
<para>
XHTML also mandates that all
tags are treated as containers. This is easy to follow for container tags
such as <p> — simply remember not to omit the closing tag.
With non-container tags, such as <input>, <br> or <hr>,
a new &glos-pragma; will be introduced to automatically replace the
closing <literal>></literal> with <literal>/></literal>.
</para></listitem>
<!--
Bugzilla - We encourage the use of Bugzilla as a work queuing tool.
Entering and tracking all bugs, even those you find and then fix yourself,
is a good practice. Creating a relationship between a CVS commit and a
Bugzilla entry by listing the bug number in the CVS log message and the
file names in the Bugzilla entry is encouraged.
-->
</itemizedlist>
</sect1>
</article>
More information about the docs
mailing list