On Wed, Aug 1, 2012 at 6:59 AM, Roland Mainz <roland.ma...@nrubsig.org> wrote:
> On Wed, Jul 18, 2012 at 3:37 PM, David Korn <d...@research.att.com> wrote:
>> cc: ast-developers@research.att.com
>> Subject: Re: Re: AST busybox ... / was: Re: [ast-developers] Patch for
>> seamless grep.c integration into libcmd
>>> Well... I have plans for that... but I need to probe carefully whether
>>> you and Glenn like the idea (which is basically to use DocBook/XML as
>>> "master source" for all manpage/getopts stuff and build the
>>> _ast_getopts strings at build time... with options for full coverage
>>> (the default), reduced builtin documentation or only the minimal set
>>> for short and long options (the advantage would be that DocBook/XML is
>>> an industry standard which would _VASTLY_ simplify many things...
>>> including promo material generation and the translation of the
>>> manpages (there have been significant complains from the
>>> Sun^H^H^HOracle documentation folks because they were not able to
>>> handle the situation (e.g. "alien" tools, non-standard procedures and
>>> no clue how to handle that even after many explanations) ... instead
>>> they dumped the output of somebuiltin --html and translated that and
>>> leaving the other options etc. untranslated))).
>>
>> If the translation is reversable it is a good idea. I should be
>> able to edit the getopts string, and then have DocBook/XML updated
>> as well as update DocBook/XML and have getopts strings updated.
>
> Erm... the DocBook/XML----> _ast_getopts string translation is lossy
> because DocBook can contain much more information (for beginners:
> DocBook/XML is not like (X)HTML and describes the layout (e.g. which
> fonts or color is being used or whether something should be bold,
> italic or not) ... instead DocBook "tags" the information on a
> per-purpose information.
>
> For example a fragment for a AST mkdir(1) man page would look like
> this (<para> means "paragraph"):
> -- snip --
> <variablelist>
> <varlistentry>
> <term><option>-m</option></term>
> <term><option>--mode</option>=<replaceable>mode</replaceable></term>
> <listitem>
> <para>Set the mode of created directories to mode. mode is
> symbolic or octal mode as in <citerefentry>
> <refentrytitle>chmod</refentrytitle>
> <manvolnum>1</manvolnum>
> </citerefentry>. Relative modes assume an initial mode of
> <literal>a=rwx</literal>.
> </para>
> </listitem>
> </varlistentry>
> <!-- Add more varlistentrys with the same structure -->
> </variablelist>
> -- snip --
>
> So the conversion _ast_optget would be more or less a one-time event
> and then we would use a simple utility which fetches the DocBook/XML
> input to generate the _ast_getopts string.
> The hard part is that I previously crafted such utilities using ksh93
> (to make use of .sh.match and other pattern matching facilities). But
> this won't work because we want to build ksh93 itself. The other
> (XML-traditional) option is to use "xsltproc" ... but that is not an
> option because it depends on libxml2 which drags-in quazillion of
> other shared libraries as dependicies (like Windows dependicy hell^2)
> ...
> ... which leaves me stuck with implemeting a tool myself... by hand
> ... in ANSI C (not hard... just work...). The only "happyness" I can
> see that I can (hopefully) use libast (basically I need a XML tag
> tokeniser like
> http://svn.nrubsig.org/svn/people/gisburn/scripts/xmlfragmentparse.sh
> written in C... the remainder is just the funny
> "hack-the-logic-until-it-works"-game) ...
>
> ... but before I do that I need feedback from David&&Glenn whether
> they like the idea (e.g. for ksh93 it means the getopts strings in
> src/cmd/ksh93/data/builtins.c will be converted into DocBook/XML and
> stored in this format in the source (e.g. the DocBook/XML manpages
> would be the master file) ... and during built time we build a C file
> with _ast_getopts strings)
Here is another sample manpage from
http://anonscm.debian.org/viewvc/debian-xml-sgml/packages/docbook-xsl/debian/examples/foo.1.example_manpage.xml?view=co&revision=1.1&content-type=text%2Fplain
which demonstrates the power of Docbook :)
As starting step, could ksh93v shup ksh93(1) as Docbook/XML?
Simon
<?xml version='1.0' encoding='ISO-8859-1'?>
<?xml-stylesheet type="text/xsl"
href="http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl";?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"; [
<!-- Process this file with an XSLT processor, e.g. xsltproc: -->
<!-- `xsltproc \
-''-nonet \
-''-param man.charmap.use.subset "0" \
-''-param make.year.ranges "1" \
-''-param make.single.year.ranges "1" \
manpage.xml' -->
<!-- Fill in your name for FIRSTNAME and SURNAME. -->
<!ENTITY dhfirstname "Daniel">
<!ENTITY dhsurname "Leidert">
<!ENTITY dhemail "daniel.leid...@wgdd.de">
<!-- dhusername could also be set to "&firstname; &surname;". -->
<!ENTITY dhusername "&dhfirstname; &dhsurname;">
<!-- The version information can also be suppressed (just -->
<!-- remove it or comment it out. -->
<!ENTITY dhrelease "0.1.2">
<!-- Please adjust the date whenever revising the manpage. -->
<!ENTITY dhdate "2006-08-27">
<!-- TITLE should be something like "User commands", -->
<!-- "&dhpackage; command-line reference" or similar (see e.g. -->
<!-- http://www.tldp.org/HOWTO/Man-Page/q2.html). But limit -->
<!-- the length to 30 chars. -->
<!ENTITY dhtitle "User Manuals">
<!ENTITY dhucpackage "FOO">
<!ENTITY dhpackage "foo">
<!-- If the application e.g. belongs to a package like X.org, -->
<!-- this should be set to the its name instead. -->
<!ENTITY dhproduct "&dhpackage;">
<!-- SECTION should be 1-8, maybe w/ subsection other -->
<!-- parameters are allowed: see man(7), man(1) and -->
<!-- http://www.tldp.org/HOWTO/Man-Page/q2.html. -->
<!ENTITY dhsection "1">
]>
<refentry>
<refentryinfo>
<title>&dhtitle;</title>
<productname>&dhpackage;</productname>
<releaseinfo role="version">&dhrelease;</releaseinfo>
<date>&dhdate;</date>
<authorgroup>
<author>
<firstname>Jens</firstname>
<surname>Schweikhardt</surname>
<contrib>Wrote this example manpage for the
"Linux Man Page Howto", available at <ulink
url="http://www.schweikhardt.net/man_page_howto.html"/> or <ulink
url="http://www.faqs.org/docs/Linux-mini/Man-Page.html"/>.</contrib>
<address>
<email>schwe...@schweikhardt.net</email>
</address>
</author>
<author>
<firstname>&dhfirstname;</firstname>
<surname>&dhsurname;</surname>
<contrib>Rewrote and extended the example
manpage in DocBook XML for the Debian distribution.</contrib>
<address>
<email>&dhemail;</email>
</address>
</author>
</authorgroup>
<copyright>
<year>1995</year>
<year>1996</year>
<year>1997</year>
<year>1998</year>
<year>1999</year>
<year>2000</year>
<year>2001</year>
<year>2002</year>
<year>2003</year>
<holder>Jens Schweikhardt</holder>
</copyright>
<copyright>
<year>2006</year>
<holder>&dhusername;</holder>
</copyright>
<legalnotice>
<para>The Howto containing this example, was offered
under the following conditions:</para>
<para>Redistribution and use in source and binary
forms, with or without modification, are permitted provided that the following
conditions are met:</para>
<orderedlist>
<listitem>
<para>Redistributions of source code
must retain the above copyright notice, this list of conditions and the
following disclaimer.</para>
</listitem>
<listitem>
<para>Redistributions in binary form
must reproduce the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials provided with
the distribution.</para>
</listitem>
</orderedlist>
<para>THIS SOFTWARE IS PROVIDED BY THE AUTHOR "AS
IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.</para>
</legalnotice>
</refentryinfo>
<refmeta>
<refentrytitle>&dhucpackage;</refentrytitle>
<manvolnum>&dhsection;</manvolnum>
</refmeta>
<refnamediv>
<refname>&dhpackage;</refname>
<refpurpose>frobnicate the bar library</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>&dhpackage;</command>
<arg choice="opt"><option>-bar</option></arg>
<group choice="opt">
<arg choice="plain"><option>-b</option></arg>
<arg
choice="plain"><option>--busy</option></arg>
</group>
<group choice="opt">
<arg choice="plain"><option>-c
<replaceable>config-file</replaceable></option></arg>
<arg
choice="plain"><option>--config=<replaceable>config-file</replaceable></option></arg>
</group>
<arg choice="opt">
<group choice="req">
<arg
choice="plain"><option>-e</option></arg>
<arg
choice="plain"><option>--example</option></arg>
</group>
<replaceable class="option">this</replaceable>
</arg>
<arg choice="opt">
<group choice="req">
<arg
choice="plain"><option>-e</option></arg>
<arg
choice="plain"><option>--example</option></arg>
</group>
<group choice="req">
<arg
choice="plain"><replaceable>this</replaceable></arg>
<arg
choice="plain"><replaceable>that</replaceable></arg>
</group>
</arg>
<arg choice="plain"
rep="repeat"><replaceable>file(s)</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>&dhpackage;</command>
<!-- Normally the help and version options make the programs stop
right after outputting the requested information.
-->
<group choice="opt">
<arg choice="plain">
<group choice="req">
<arg
choice="plain"><option>-h</option></arg>
<arg
choice="plain"><option>--help</option></arg>
</group>
</arg>
<arg choice="plain">
<group choice="req">
<arg
choice="plain"><option>-v</option></arg>
<arg
choice="plain"><option>--version</option></arg>
</group>
</arg>
</group>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1 id="description">
<title>DESCRIPTION</title>
<para><command>&dhpackage;</command> frobnicates the
<application>bar</application> library by tweaking internal symbol tables. By
default it parses all baz segments and rearranges them in reverse order by time
for the
<citerefentry><refentrytitle>xyzzy</refentrytitle><manvolnum>1</manvolnum></citerefentry>
linker to find them. The symdef entry is then compressed using the
<abbrev>WBG</abbrev> (Whiz-Bang-Gizmo) algorithm. All files are processed in
the order specified.</para>
</refsect1>
<refsect1 id="options">
<title>OPTIONS</title>
<variablelist>
<!-- Use the variablelist.term.separator and the
variablelist.term.break.after parameters to
control the term elements. -->
<varlistentry>
<term><option>-b</option></term>
<term><option>--busy</option></term>
<listitem>
<para>Do not write <quote>busy</quote>
to <filename class="devicefile">stdout</filename> while processing.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-c <replaceable
class="parameter">config-file</replaceable></option></term>
<term><option>--config=<replaceable
class="parameter">config-file</replaceable></option></term>
<listitem>
<para>Use the alternate system wide
<replaceable>config-file</replaceable> instead of the
<filename>/etc/foo.conf</filename>. This overrides any <envar>FOOCONF</envar>
environment variable.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-a</option></term>
<listitem>
<para>In addition to the baz segments,
also parse the
<citerefentry><refentrytitle>blurfl</refentrytitle><manvolnum>3</manvolnum></citerefentry>
headers.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-r</option></term>
<listitem>
<para>Recursive mode. Operates as fast
as lightning at the expense of a megabyte of virtual memory.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="files">
<title>FILES</title>
<variablelist>
<varlistentry>
<term><filename>/etc/foo.conf</filename></term>
<listitem>
<para>The system-wide configuration
file. See
<citerefentry><refentrytitle>foo.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
for further details.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>${HOME}/.foo.conf</filename></term>
<listitem>
<para>The per-user configuration file.
See
<citerefentry><refentrytitle>foo.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
for further details.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="environment">
<title>ENVIONMENT</title>
<variablelist>
<varlistentry>
<term><envar>FOOCONF</envar></term>
<listitem>
<para>The full pathname for an
alternate system wide configuration file
<citerefentry><refentrytitle>foo.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
(see also <xref linkend="files"/>). Overridden by the <option>-c</option>
option.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="diagnostics">
<title>DIAGNOSTICS</title>
<para>The following diagnostics may be issued on <filename
class="devicefile">stderr</filename>:</para>
<variablelist>
<varlistentry>
<term><quote><errortext>Bad magic
number.</errortext></quote></term>
<listitem>
<para>The input file does not look like
an archive file.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><quote><errortext>Old style baz
segments.</errortext></quote></term>
<listitem>
<para><command>&dhpackage;</command>
can only handle new style baz segments. <acronym>COBOL</acronym> object
libraries are not supported in this version.</para>
</listitem>
</varlistentry>
</variablelist>
<para>The following return codes can be used in scripts:</para>
<segmentedlist>
<segtitle>Errorcode</segtitle>
<segtitle>Errortext</segtitle>
<segtitle>Diagnostic</segtitle>
<seglistitem>
<seg><errorcode>0</errorcode></seg>
<seg><errortext>Program exited
normally.</errortext></seg>
<seg>No error. Program ran successfully.</seg>
</seglistitem>
<seglistitem>
<seg><errorcode>1</errorcode></seg>
<seg><errortext>Bad magic
number.</errortext></seg>
<seg>The input file does not look like an
archive file.</seg>
</seglistitem>
<seglistitem>
<seg><errorcode>2</errorcode></seg>
<seg><errortext>Old style baz
segments.</errortext></seg>
<seg><command>&dhpackage;</command> can only
handle new style baz segments. <acronym>COBOL</acronym> object libraries are
not supported in this version.</seg>
</seglistitem>
</segmentedlist>
</refsect1>
<refsect1 id="bugs">
<!-- Or use this section to tell about upstream BTS. -->
<title>BUGS</title>
<para>The command name should have been chosen more carefully
to reflect its purpose.</para>
<para>The upstreams <acronym>BTS</acronym> can be found at
<ulink url="http://bugzilla.foo.tld"/>.</para>
</refsect1>
<refsect1 id="see_also">
<title>SEE ALSO</title>
<!-- In alpabetical order. -->
<para><citerefentry>
<refentrytitle>bar</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>, <citerefentry>
<refentrytitle>foo</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>, <citerefentry>
<refentrytitle>foo.conf</refentrytitle>
<manvolnum>5</manvolnum>
</citerefentry>, <citerefentry>
<refentrytitle>xyzzy</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry></para>
<para>The programs are documented fully by <citetitle>The Rise
and Fall of a Fooish Bar</citetitle> available via the
<application>Info</application> system.</para>
</refsect1>
</refentry>
_______________________________________________
ast-developers mailing list
ast-developers@research.att.com
https://mailman.research.att.com/mailman/listinfo/ast-developers
