C. Florian Ebeling wrote: > On Fri, Apr 10, 2009 at 10:42 PM, Rainer Müller <[email protected]> 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 _______________________________________________ macports-dev mailing list [email protected] http://lists.macosforge.org/mailman/listinfo.cgi/macports-dev
