on Fri, Dec 05, 2003 at 12:00:10PM -0500, Bijan Soleymani (bijan@psq.com) wrote:
> "Karsten M. Self" <kmself@ix.netcom.com> writes:
>
> > on Fri, Dec 05, 2003 at 11:17:04AM -0500, Bijan Soleymani (bijan@psq.com) wrote:
> > RTFL.
> >
> > It's not just the reader. It's the document structure.
>
> I read the damn thing!
May I suggest toggling reading-with-comprehension mode next time?
I wrote that abstract as outcome of a rather involved thread on d-u
previously. Curiously there was a participant with gross comprehension
problems that time 'round too....
> 2) It's (largely) bound to a specific viewer.
>
> It requires an info viewer (not true note my comment).
To view a manpage:
man foo
...which dumps user into $PAGER, or system default, or 'more'. Which
the user uses for any other file. I use such pagers.... dozens of
times a day. They're relatively simple. They're highly familiar. And
I can chose any of several (less, more, most, w3m) which works for me.
With zero functionality loss vis-a-vis the others, in terms of gross
functionality of man.
info foo
...dumps the user into, well, info. Unless you type 'pinfo'. In both
cases, you've essentially got a special-purpose hypertext viewer. There
is no way generally know to access info documents, from the command
line, in a commonly used viewer familiar to the user.
Yes, it's possible
> 3) It fragments the documentation effort.
>
> Bah. Whatever.
You appear to think this is an insignificant point. It's not.
Reading, and I quote:
The GNU folks, in general, abhor man pages, and create info
documents instead....If you really want to understand tar, then you
should run info and read the tar info pages, or use the info mode in
emacs.
...in a manpage is simply unacceptable. Kudos to the Debian project for
filling in manpages where they are missing.
Worse, like other annoyances, the attitude that "we don't do manpages"
becomes "we don't do documentation" for some entire projects, such as
GNOME. I was involved in an extremely disheartening discussion with a
key GNOME developer, and the release manager, earlier this year, in
which I was told to "read the manpage" for gconftool documentation. As
it turns out, there simply _is none_. Despite a 2+ year old outstanding
bug filed against the package.
The discussion revolved around, variously:
- Why gconf is a horrible kluge.
- Why GNOME is geared to end-users, not traditional Unix folks, who
aren't its constituency.
- Why end-users aren't qualified to comment on technical software
issues.
- How gconftool is a traditional Unix admin folks tool...
- ...and much, much dissembling over why in two years nobody had
thought to write a manpage (it's finally starting to happen -- the
contents are largely what you'd see when typing "gconftool --help").
Again: there's a major difference between being able to:
- Type 'apropos foo'
- Type 'man foo' and '/<regexp>' to find a topic.
- Type 'man foo -T<format>' and output the manpage in any desired
format.
...and fussing through either a very rarely used, single-purpose
hypertext browser with unfamiliar features, or hunting and poking
through a set of disjoint webpages if you've installed dwww.
> 5) It splits a programs docs into multiple pages.
>
> Again you can convert it to html all on one page.
You brilliantly miss the somewhat minor point that the info document
*isn't* a single page, readily searchable, and accessible via a single
command-line statement, by default, and that the user has to go through
several nontrivial steps (particularly for the novice or naive user) to
extract another, more useful, format. I certainly went years without
knowing of such options.
> 6) GNU project manpages frequently deprecate manpages
>
> Ok is that a problem with the format? or the GNU project?
Given the inherent and highly visible faults of the format, it is a
fault of the GNU Project.
> 7) Info viewers have usability problems
>
> Again convert to html or pdf.
See 5.
> 8) Info as extended documentation
>
> Ok so Docbook is better than Texinfo.
You betchya.
> 9) The learning curve argument
>
> Yeah learning to read html or a pdf or a physical book is tough.
RTFL. info/pinfo are specialized, single-purpose tools. Vs. _either_ a
general-purpose pager (less / more / most / w3m) or a web browser.
> 12) Thou shalt render content and presentation asunder.
>
> I don't get what this means.
I'm not surprised.
man pages generate slightly formatted text output, which can be dumped
straight to terminal or printer, captured to file, or viewed in any
standard text pager or viewer. With the '-T' option, additional
formats, including postscript, can be generated. With tools such as dwww
or man2html, man pages are accessible as webpages. And, I might add,
tend to render better than info pages.
By contrast, info is a format tied to a specific viewer (by default, and
by most convenient access). It's not tied to the system 'apropos'
command. And the structure of the documents means that translation to
other forms makes for significant loss of utility. The upshot is that I
use an info viewer once every few months, don't know its features, curse
it, and feel very much that I'm not alone.
Info is, in this regard, not entirely unlike MS Word, as a document
which is almost wholly associated with a single tool. With the
concomitant disadvantages this entails.
> 13) Remedy the problem
>
> Ok whatever.
Richard is wrong, sometimes. Ubersoft notwithstanding. He should own
up to this one.
> 14) And yes, manpages have their problems. Example...
>
> Ok so man pages aren't perfect.
>
>
> So I missed the whole part where you explained that Texinfo can be
> converted into info, html, ps or pdf.
I didn't think you were reading with comprehension. Seems I was right:
It is searchable from within info, it has several output formats as
it is LaTeX? based. And the basic concept seems valid.
> And in any case it isn't unreasonable to put the basic documentation
> in a section of the extended documentation. Especially for really
> complicated programs.
You'll find that this is actually a standard practice in Debian
packages.
Basic command references are in a manpage.
Extended documentation is found in /usr/share/doc/<packagename>/, in the
form of manuals, references, programmers references, FAQs, or entire
HTML documents (say, for r-base, exim, or apache).
[Perl and Python discussion elided]: both are presented in man page,
and HTML format. No need to use info. Point of contention above being
that several packages deprecate manpages entirely in favor of info.
_That_ is the specific practice I detest and would prefer corrected.
Preparing docs which can be presented in multiple formats, _including_
manpages, and whatever other silly format(s) are desired, is acceptable.
Peace.
--
Karsten M. Self <kmself@ix.netcom.com> http://kmself.home.netcom.com/
What Part of "Gestalt" don't you understand?
Bush/Cheney '04: Four More Wars!
Attachment:
pgp0mZpz7CxI4.pgp
Description: PGP signature