NewHelpSystem & man pages

[Rainer Müller]

C. Florian Ebeling wrote:
> On Fri, Apr 10, 2009 at 10:42 PM, Rainer Müller <raimue at macports.org> wrote:
>> 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>.
> 
> Really good to see an initiative to shape in the doc area! The current
> state of affairs was not really satisfying. Mark has probably good
> reasons why he couldn't bring in more time, but we shouldn't stay in
> write-lock mode for too long on that.
> 
> Do I get it correct that the guide will be maintained separately for
> now, after the new help system plan?

My plan is to present help right when you need it - while running port
commands. So if you are unsure what a port command does exactly, you
simply run 'port help <command>' and get a description with additional
usage examples.

One option would have been to just print help texts to stdout, but this
is not really satisfying. For long texts, you would have to scroll up
again in the terminal or use a pipe with less. This is not very comfortable.

I am not about to comment on git version control itself, but I really
like the way the git command line utility offers help by opening man
pages from 'git help'. This is both unintrusive (does not clutter your
scrollback buffer) and is easily accessible (no need to search the web
or long text documents for the right section describing this command).

While these man pages target documentation of the individual port
commands, The Guide is a different resource for help. It is available
online as comprehensive documentation of the port system. I turn there
to understand how the port system or Portfile development works and
to find out which policies are in place.

> In which ways can people help the effort? (Maybe that would be a good
> additional note on the wiki page to point out.)

I added the list of man pages I have thought of currently to the wiki
page. I already converted port.1.txt now to AsciiDoc syntax and did some
small revise.

Also I have written port-install.1.txt, which can already be used as
example for other man pages. So to help with the new man pages, just
pick any from the list (maybe even mark it as taken to avoid conflicts?)
and write something up and commit it to the branch or submit it per Trac
and assign it to me. Of course you can also extend existing man pages to
add additional aspects.

As reference you can use the two man pages I have finished so far and
git man pages [1] as examples. If you want to help but have problems
with the AsciiDoc syntax, just submit what you can come up with so far.
Fine adjustment can still take place. AsciiDoc is also new to me, so I
can't recommend any best practices yet.

The new-help-system branch is not limited to me, of course anybody is
invited to help! :-)

Rainer

[1] http://git.kernel.org/?p=git/git.git;a=tree;f=Documentation