NewHelpSystem

[markd at macports.org]

>First I want to apologize for being inactive in the last months.
>I only have sporadic access to a Mac at the moment (I switched to
>Linux with my main machine) so my activity was very low. But I
>like the MacPorts project and will continue to update my ports
>when I have time and access to my Mac. But as I will not be very
>active feel free to take over my ports.
>
>Regarding the guide. I think for now the guide should use DocBook
>at least until it's finished. Then we can decide if we want to
>switch. But the duplication pointed out by Mark is an important
>factor. So I think we should make a quick decision if the man
>pages should be written in DocBook or Asciidoc. And after the
>decision all other documents should be merged and removed so we
>only have one source and no duplication.
>
>If we switch the man pages to Asciidoc then all man pages in
>base/doc/ should only be generated through Asciidoc so we have a
>single format.
>
>The only problematic man page is portfile.7 as it is directly
>wired into the guide. I would like to remove it (or generate it
>through DocBook) and instead install the guide in
>/opt/local/share/doc/port/ so the user can access it.
>
>We should really remove all duplication and move documentation
>either to base/doc or doc, but not in both places.


Hi Simon,

Sorry to take so long to reply.  The first step I had in mind with the new
guide was to get into it at least all knowledge that the old guide had,
and then midway into it decided to add the content from the man pages too.
 Though I really think it is a serious mistake to split the man page
content from the guide because of the overlap, the reasons for it seem
selfevident enough to me that I really don't want to waste any more time
arguing this.

So basically I am saying that for those who consider rewriting the man
page *content* a separate project (though as I said I do not) then the
guide could be considered more or less complete if we've incorporated all
the useful information from the old guide.  I can do a quick scan of the
old guide and see.

I think it is fine to start writing man pages in asciidoc - I was never
really comfortable with man pages sourced from DocBook.  The way the XML
had to be formatted for man pages was kludgy and the processing it took to
generate the output was too.  I think asciidoc is an intriguing
possibility and I'll be taking a look at it soon.  If it made the task of
integrating the man page content into the guide easier it would be great,
and that is a goal of mine if no one else's goal.  I think people are
confusing the man pages with the man page content in this discussion.

So basically I'm saying that I think we should get on with doc projects,
whether they compete or not.  We've had enough of discusson already.  If
and when one of us has produced something real that is more complete or
better in some way than what we have now then we can discuss it at that
time.

Mark