On 22-Oct-05 Werner LEMBERG wrote:
. Documentation of GNU projects should be in texinfo format.
Err, there are lots of so-called GNU projects that aren't documented
in texinfo.
This is true but very unfortunate IMHO. It isn't very difficult to
write a texinfo file, and there are many benefits to do that.
I would like to dissent (partially) from this.
Granted, writing detailed explanations, examples, etc. in a texinfo
file is a good thing to do, and it's a valuable resource when you
need such things.
However, I have always regretted, even resented, GNU's transition
from "man" to "info" for basic reference. For people who are
accustomed to them, man pages are easy and quick to use, for the
most part. Admittedly, the terseness of some classic Unix man pages,
and the not infrequent need to cross-reference between several
such pages, could make it a trying exercise too.
But, nowadays, many GNU man pages are mere stubs, when they used to
be full summaries, and the reader is told to read the info document.
For all the wonderful opportunities that the GNU project has opened
up for the world, and its impeccable adherence to freedom of software,
nevertheless there is something of "1984" about GNU.
For instance, though are still far from succeeding, I suspect that
the GNU Thought Police really want everyone to use EMACS. And it's
not difficult to see hints of that in texinfo! Where texinfo itself
is concerned, however, it seems they are a bit closer to dominating
how users think and work.
I don't -- and won't -- use EMACS: I can't stand it! I do, and want
to, use vim. I like, and want to have, good man pages which list
all the essentials of the behaviour of commands. I rarely want
to get into the labyrinth of a texinfo document (though I'm pleased
it's there I need the more discursive information it contains).
So I'm not in favour of any trend which would take away what I
like and want. Man pages have a good function, and would better
fulfil that function if comprehensively written. This should
not clash with info documents, which better fill a different
function. And there is plenty of scope for an auxiliary collection
of documentation in a variety of formats to explain and illustrate
the software, and to guide users.
The preferences stated above are mine. I don't expect others to
share them: they should be free -- and enabled -- to adopt their
own preferences. Likewise, so should I be (and anyone else who
happens to share mine).
Best wishes to all,
Ted.