NewHelpSystem & man pages

[markd at macports.org]

I sent this to the wrong list address by mistake, so I'm sending it again.

>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/. For me this project looks stalled for too long.

Hi Rainer,

If you can produce better docs than what I've done it doesn't matter what
has already been done.  I would naturally want to use the simplest method
that can produce acceptable output.  If you can't with the method you have
proposed, then it doesn't matter if it has been stalled too long or not as
long as it continues before a better plan arrives.

I only raised the issue that I have already started on man pages only to
say that no one should modify the guide for a new purpose without
consulting the community.  That would be disturbing an ongoing project
that I am working on now, no matter what are one's personal judgements on
what counts as stalled.  It also wouldn't be necessary since if you need
to demonstrate issues related to your project having to do with the guide,
you could always make a copy in your branch.
>
>If Rainer's effort with new manpages using asciidoc is successful, we 
>could of course discuss the idea of migrating the Guide over to that 
>format as well.

The problem from my perspective is that as far as I've been able to tell,
what would count as success seems to have surprisingly little to do with
structure or style (control over which docbook and CSS give to the current
guide), and it appears from the last few messages that a commitment to
using a single source has been dropped or probably soon will be too. 
Aside from the absolute necessity in my opinion to use a single source
(eliminate duplicated effort), the main problem I see, as I've already
said before, is that without a defined structure and style the docs will
not be very consistent and will have no resistance to entropy in any case.

>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.

We all know asciidoc is simpler; the question is whether or not the
criteria for success can be met.  I looked at alternatives to XML before I
started the guide (because I want the simplest solution that meets the
goals too) and rejected them as not meeting my criteria for success. 
You've defined the success as the ability to edit bits easily and that is
an easy target to hit, but has nothing to say about product quality and I
think most users have greater expectations for docs than that.  I think
having something like NewHelpSystem is fine, but adding features doesn't
mean ignoring previous design goals or dictating changes unrelated to such
features.

I haven't even seen where you have warned anyone or commented on the
completely generic look of asciidos generated html and the lack of control
for adding future format additions and changes.  Are we ok with a guide
that looks like Git man pages?  I'm not.  Is the communty satisfied with
that?  Or has that been discussed somewhere and I've missed it?  That
would be the first question I would ask, even though the other questions
I've raised would still hold.  If everybody is satisfied with poorly
formatted and structured docs, then I really need to know that.  Because I
am not interested in producing documents that ugly (poorly formatted) or
unsustainable (poorly structured) or the massively error-prone process of
reconciling text manually between guide and man (no single doc source). 
In the case of the former two, it isn't worthy of a product that runs on a
Mac, and in the case of the latter I just have better things to do, and
I'd hope we all do.

I mean no rudeness whatever, I'm just trying to get my point across.  And
I've said it all before and you are quite unimpressed.  That is why I
suppose that we should continue on parallel courses and let the community
decide which is better overall.  This is assuming that the community does
want docs that aspire to have a good design; if not then it is time for me
to retire.  :)

Mark