NewHelpSystem & man pages

[markd at macports.org]

Forgot to send this to the list ...

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

Yes, but I'm just skeptical of this translation and basically assumed it
won't work very well.  That could be wrong, but it is the norm for
translation to fail without extensive manual tweaking.

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

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

Here is the problem.  This will mean duplicate information and
instructions in the man pages and in the guide.  I think this is
unsupportable.  That is why I stopped writing content to work out a
strategy to merge in man pages and manage the content as a whole. rather
than provide similar information in two places and why the guide was
delayed when I was on the task.  It is impossible to have accuracy without
a single source, and I am confident that no one here has the time or
inclination to reconcile two sets of similar text.  There are doc tickets
that say "need to merge web site install section with guide install
section" that illustrate how people react to multiple sources.

Bottom line is that the sources for the man pages need to be the bases for
the relevant guide sections (currently the reference section) on a given
topic.  The guide and the man pages need to be designed together, and that
is what was being done.  I know development stalled, but that was not for
lack of interest.

>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"?

Yes I know is is hacky.  The fact is I don't know that using XML source is
the best way to do on the man pages.  It could be that asiidoc is a better
way in the end.  I am not committed to any technology per se, despite the
impression I may have given by defending DocBook.  If asciidoc can be made
to do the job I'm fine with that, I am just skeptical.  I would be
entirely open to using something else as long as the principles I think
that are necessary for good docs overall are maintained, and the principle
of treating the guide and man pages (and other docs) comprehensively
(accomplished mostly by using a single source) is one of them.  It might
well be that asciidoc has a place, but I'm not sure.

But look, even the GNU coding standards (sect 6.9) show that man pages are
secondary and the problems that can result from man page contributions:
http://www.gnu.org/prep/standards/standards.html and multiple sources.  I
know it may sound ungrateful to question work before is is done, and I
appreciate your willingness to put in time improving the usability of
MacPorts, but it isn't a crazy idea to hash some things out up front so
there won't be any bitterness later on.  I"m not opposed at all to
anyone's work, but how would you like it if I waited until you got
something working before I jump in with my concerns?  That would wasting
your time (assuming my arguments had merit and were persuasive to the
community) and be pretty rude.  So don't think my early objections are
trying to stop you from doing beta work or whatever.

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

I don't think I am taking it personally.  I think the main difference here
is that I take a content writer's perspective, whereas I think you are
taking a developer's perspective.  I am all about content and experience
overall, and that structure and style only matters as far as it support
the goals of knowledge management (content) and usability (experience). 
If asciidoc does it better then I could easily support that.  I think I've
shown that my concerns are on principles, right or wrong.

I think your point of view is all about delivery, and not so much what
gets delivered if I may say so.  And I'm not sure you are aware that you
seem to be ignoring my rewritten man pages that contain extensive content
that is not in the current man pages.  I was confused by the wandering
among several topics related to asciidoc advocacy recently and I didn't
realize you might be doing that until just now.

It seems to me you are doing what is normally called "context sensitive
help", and I think that is another reason to consider the docs as a whole.
 Maybe there is a way that we could work together on this.  Is there a
decent way to have a particular 'port help foo' command spit out a section
of a man page?  Or it could be that each port command could be treated as
a separate topic thatt get included in a file of similar topics together
as man pages, which could then be included in the guide one way or
another.  If they are written with their inclusion with the guide in mind
that would be fine.   I just don't think it is good to write them based on
the needs of the delivery system, the outdated man pages, or anything
other than a comprehensive point of view on the docs as a whole.

Mark