NewHelpSystem & man pages

[Rainer Müller]

markd at macports.org wrote:
> 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.

As I already explained, I do not plan to replace the current guide with
the NewHelpSystem. My effort is to create "hands-on" help available by
using the 'port help' command. And I am also not doing this on trunk, I
created a new branch for it. If it does not work out as expected, then
we can still throw it away and start something else.

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

AsciiDoc still gives control over DocBook and CSS. It is still possible
to change the XSL stylesheet converting the DocBook to HTML and the CSS
is in a separate file. It is even possible to add your own DocBook
elements if that would be necessary.

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

I don't see how you would apply the style and structure of the Guide
being a website to man pages in Terminal. Having the man pages on the
website is a secondary goal and I had the idea only while writing the
NewHelpSystem page. The primary goal is to have a usable 'port help'
which currently is not helpful at all.

I made a call for contributions on macports-users before about writing
more helpful strings for the current implementation, but nobody seems to
be interested. So why should I not be allowed to do something about it
if nobody else cares? And as it is me doing the work, I am going to do
it in a way I like.

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

I didn't warn anybody because your expectations are simply not true. As
AsciiDoc uses DocBook as intermediate format, we can apply the same
customizations as to any document directly written in DocBook. This
includes changing XSLT and CSS.

And as we see in the guide, we are already applying customizations by
hacks. This is a) a sed expression to insert links to the headline
anchors b) a Tcl script to insert the TOC into each page for the chunked
version. Probably it would also be possible to do this with XSLT, but
it's probably too complicated. So there is the point in "having control"?

It was me who lately digged through the XSLT to add attribute
customizations to the single-page and the chunked versions and I also
added links to switch between them.

And how should I ask the community before I have anything to show?
A HTML version of the man pages would not have to look exactly like the
ones on the Git homepage. We can still apply custom CSS or even custom
XSLT. Be aware that AsciiDoc does not only offer writing man pages but
various output formats. But at the moment, my focus are man pages for
the terminal.

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

Sorry, but I don't take the arguments of poorly structure or bad
formatting as serious. As explained above, AsciiDoc offers everything
DocBook does.

My plan is not to offer the Guide as man pages. This is mainly new
content describing the various options of the port commands.

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

If I would have been unimpressed I might not have considered AsciiDoc
which offers compatibility and interaction with DocBook. There are other
ways to write man pages without writing plain roff, like latex2man,
pod2man or any of the various markdown parsers. I am aware of the
concerns you expressed, but maybe I just don't see that as the big issue
as you do or I see ways to accomplish the goals.

Please do not take this discussion too personal. I appreciate your work
and I am looking forward for further contributions by you. It is
probably my fault that I quietly added this wiki page describing my plan
without any announcement on the mailing list. But I was not going to
hold a speech promoting AsciiDoc without having tried if it would work
at all. I also didn't want to do this all in private and come up with a
finished solution in a few months. Rather I am doing everything in
public so others can chime in about it and I can get some feedback if
this concept of 'port help' would be accepted at all.

Rainer