OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

docbook-apps message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]


Subject: DOCBOOK-APPS: "Abbreviated" DocBook



I am strongly considering using DocBook for documentation of Aspell
however there is one major problem. DocBook is too dam verbose,
providing an entry for just about everything under the sun.  Although you
may disagree with me, it is so verbose that just reading a DocBook source
document becomes rather difficult.  So, I was wondering if there exists
any tools which will allow me to enter in documents in a more terse and
human readable form with the minimal amount of tags and then have it
expand it into full DocBook form with all the special purpose tags in
place. For example I would like to be able to enter this:

  <refentry>

  <title>printf (3S)
  <for>printf, fprintf, sprintf

  <purpose>print formatted output

  <refsynopsis>

  <code>
  #include &lt;stdio.h&gt;
  int printf(const char * format, ...)
  int fprintf(FILE * strm, const char * format, ...)
  int sprintf (char * s, const char * format, ...)
  </code>

  <refsect1>Description

  printf places output on the standard output stream stdout.

  </refentry>

And have the utility convert it to this:

  <refmeta>
  <refentrytitle>printf</refentrytitle>
  <manvolnum>3S</manvolnum>
  </refmeta>

  <refnamediv>
  <refname>printf</refname>
  <refname>fprintf</refname>
  <refname>sprintf</refname>
  <refpurpose>print formatted output</refpurpose>
  </refnamediv>

  <refsynopsisdiv>

  <funcsynopsis>
  <funcsynopsisinfo>
  #include &lt;stdio.h&gt;
  </funcsynopsisinfo>
  <funcprototype>
  <funcdef>int <function>printf</function></funcdef>
  <paramdef>const char *<parameter>format</parameter></paramdef>
  <paramdef>...</paramdef>
  </funcprototype>

  <funcprototype>
  <funcdef>int <function>fprintf</function></funcdef>
  <paramdef>FILE *<parameter>strm</parameter></paramdef>
  <paramdef>const char *<parameter>format</parameter></paramdef>
  <paramdef>...</paramdef>
  </funcprototype>

  <funcprototype>
  <funcdef>int <function>sprintf</function></funcdef>
  <paramdef>char *<parameter>s</parameter></paramdef>
  <paramdef>const char *<parameter>format</parameter></paramdef>
  <paramdef>...</paramdef>
  </funcprototype>
  </funcsynopsis>

  </refsynopsisdiv>

  <refsect1><title>Description</title>
  <para>
  <function>printf</function> places output on the standard
  output stream stdout.
  </para>
  <para>&hellip;</para>
  </refsect1>
  </refentry>

At least to me the former is far easier to read and to enter in than
the latter.  So do you guys know of any utilities.  I looked all over the
net, but came up empty.  If none exists it is highly likely that I whip up
something myself.  I honestly would like to know how people can stand
editing raw DocBook.  Even with emacs help it is still a bitch to both
read and edit.

Thanks in advance.





[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]


Powered by eList eXpress LLC