NewHelpSystem & man pages

[Rainer Müller]

For everyone who did not notice yet what this is about, I documented my
plans about a new help system based on AsciiDoc at
<http://trac.macports.org/wiki/NewHelpSystem>.

markd at macports.org wrote:
> I just want to restate that there is a current project underway to source
> new man pages out of the guide that has been tested, though the content of
> the port man page has not been composed yet.  I also said my intent is to
> finish the sections of the guide that contain the new man page content
> this summer.
> 
> It seems to me you intend to supercede the new man page sources being
> constructed in doc-new/man/xml/*.  Is that correct?  If so we need to have
> some community consensus on that since it seems to me that would mean our
> projects cannot happen at the same time, and also that my effort with
> simon@ to source the man pages out of the guide and yours to source parts
> of the guide from the man pages would each require a differently
> structured guide.

I know that your long term goal was to integrate man pages and guide
together. But I didn't know yet that work already started on this. Now I
am looking at the man pages in XML format in doc-new/man/xml/* which are
untouched for over a year now and thus outdated as we continued to work
on them in base/doc/. Sorry that I was not aware of these existing man
pages there, but for me this project looks stalled for too long.

The old plain roff format for man pages was just too cryptic and
uncommon, so we are in the need for a new format. My intent with
choosing AsciiDoc as the source for the new man pages is trying to
satisfy both the need for a simple format and still being able to
integrate it into the guide. Simple formats for documentation have been
requested by Florian Ebeling some time ago [1] and I still second that
request.

Let's just compare a little bit of the XML and AsciiDoc format.

XML:

    <refsection>
      <title>GLOBAL OPTIONS</title>

      <variablelist>
        <varlistentry>
          <term><option>-q</option></term>

          <listitem>
            <para>quiet mode (suppress messages)</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>-v</option></term>

          <listitem>
            <para>verbose mode (generate verbose messages)</para>
          </listitem>
        </varlistentry>


AsciiDoc:

    GLOBAL OPTIONS
    --------------

    -v::
        Verbose mode, generates verbose messages

    -d::
        Debug mode, generate debugging messages, implies -v


And now please tell me honestly, which of these two do you find more
intuitive and readable?

For me it is totally the AsciiDoc format which I prefer to write and
edit. XML is just too cumbersome. You may disagree with me, but this is
my point of view. In my opinion it is still the format which stops
people from contributing to the guide.

You can see more at port.1.txt [2], where I already converted the
current port(1) man page to AsciiDoc syntax.

AsciiDoc internally also uses Docbook XML and allows that as output
format, so it will be no problem to integrate these man pages into the
guide. If you want to view that, just checkout the new branch and run
`make xml in` the base/doc directory.

Rainer

[1]
http://lists.macosforge.org/pipermail/macports-dev/2009-January/006953.html
[2]
http://trac.macports.org/browser/branches/new-help-system/base/doc/port.1.txt

PS: Sorry Mark, you may receive this mail twice now, but the list
address in your original mail was wrong, which I only noticed as my
reply bounced.