[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [Groff] Introduction

From: Joerg van den Hoff
Subject: Re: [Groff] Introduction
Date: Sat, 22 Oct 2005 16:21:44 +0200
User-agent: Mozilla Thunderbird 1.0.7 (Macintosh/20050923)

(Ted Harding) wrote:
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,

well, you're not alone with your view.

I'm annoyed as well when 'man some_command' tells me to RTFTID (where TID is 'TexInfoDocumentation' and you know what RTF stands for :-) ).

especially concerning the 'labyrinth' aspect of texinfo docs, this can be a pain in the back for a casual (~= non-EMACS)user of 'info'. I think you made the important point: good (!) concise manpages save time (and even comprehensive ones like "man bash" are OK, if you know a sensible search pattern to enter into 'less'). cross-links and an index are fine, they just don't help always: I have made the experience, that more often than not, I'm looking for information concerning some key word which is not necessarily an index or cross-link term. such a 'string search' across the whole documentation seems not possible in 'info' (seems to be restricted to the current node (or how is it called in info-speak?)) or am I wrong?

luckily enough, groff _has_ useful manpages.


reply via email to

[Prev in Thread] Current Thread [Next in Thread]