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>.
[email protected] 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. _______________________________________________ macports-dev mailing list [email protected] http://lists.macosforge.org/mailman/listinfo.cgi/macports-dev
