on Tue, Dec 25, 2001 at 03:54:36AM -0200, Christoph Simon (ciccio@kiosknet.com.br) wrote:
> On Mon, 24 Dec 2001 20:38:49 -0800
> "Karsten M. Self" <kmself@ix.netcom.com> wrote:
>
> > - It attempts to replace, not augment, an existing, established,
> > viable, useful, and effective standard. This is almost always a bad
> > idea. The far better tack: provided augmented functionality. If
> > your solution is compelling enough, people will transition.
>
> Right, but doesn't apply here.
Wrong.
If your explicit policy is "deprecate manpages in favor of info pages",
you're replacing functionality. I've documented this from the gcc
manpage, it's a typical example.
GNU Info is used to replace manpages. It leaves packages with
incomplete, outdated, or missing man pages. This is a Bad Thing®.
> > - It's (largely) bound to a specific viewer. Which, if you don't use
<...>
> Inconsequent. Man requires groff and a pager.
A pager is a non-specific reader.
> I can't read SGML or XML (but hate them), specially when created by
> some `intelligent tool' with no human digestable linebreaks.
I'm not talking about the composition tools, I'm talking about the
_viewing_ tools. Non sequitur.
<...>
> Man pages stop being useful when they get too long. Try locating a
> short word in man bash.
/\<at\>
Or, for a context search:
man bash | col | grep -w at
...returns 81 lines, which can then be looked at fairly readily or
searched with additional context:
/character at point
> Also, IMHO, I don't think a slash for searching forward and a question
> mark for back is intuitive, at least not more than Ctrl-S (search)
> Ctrl-R (reverse search).
It's not intuitive, that's somewhat my point. But it *is* learned,
particularly if you're using more/less and/or a vi clone frequently, or
other tools (e.g.: w3m) which use vi keys.
As it happens, info allows use of vi keys (didn't know this until
today), and the C-s and C-r keys are among the emacs bindings I do
recall more readily. FWIW, I use emacs mode for command line editing in
bash. I'm not fully locked into one mode of thinking. _But_, what I
_don't_ know are multi-line and multi-buffer navigation keystrokes,
which are necessary in info.
The point isn't which mode is "more intuitive", it's whether or not the
commonly used tools allow the option to select an environment that's
comfortable to the user. Info perforce constrains this choice. It
doesn't matter if you prefer searching with '/', with C-s, or by
touching your tongue to your nose, Info restricts the tools available
to you.
> > - It fragments the documentation effort. GNU favors info. Debian
> > favors manpages (I've written on this in the past, references
> > supporting both claims are available).
>
> Probably true, but people still can choose, unless they get
> consistently bashed for it.
You can only choose if you're writing the documentation on your system.
As it is, Debian prefers manpages:
Debian Policy, 13.1, Manual Pages:
Each program, utility, and function should have an associated manpage
included in the same package. It is suggested that all configuration
files also have a manual page included as well.
<...>
Even though the GNU Project do not in general consider the lack of
a manpage to be a bug, we do.
> > - Info and man serve different functions. Man is meant to be a quick
> Both, man and info have a learning curve.
***ACCESSING*** a man page -- the task of opening and navigating the
document itself -- doesn't have a _separate_ learning process.
Accessing an info page does.
_Understanding_ a man page is admittedly an art. Ditto an Info page.
Info throws two hurdles at the user, man only one.
> One of the declared aims of info is to provide a frame to write
> introductions or tutorials which wouldn't fit well into a man page,
> because that is limited to a reference manual.
This is a supplemental function. This documentation shouldn't attempt
to replace something it can't: a basic usage reference.
> > This man page is not kept up to date except when volunteers want
> > to maintain it. If you find a discrepancy between the man page
> > and the software, please check the Info file, which is the
> > authoritative documentation.
>
> This is the choice of the program's authors.
For someone crowing over the advantages of Info and its benefits in
conveying information, you seem to have a fundamental comprehension
problem:
This is _NOT_ a statement of author's choice, it's _GNU's POLICY_.
> > ...followed by dire warnings that the manpage may not be updated,
> > etc., etc. At which point the pitiless reader turns to the info
> > document...which in many cases is a copy of the same manpage (now
> > presented in an unfamiliar document viewer). Houston, we've got a
> > problem.
>
> This is the choice of debian maintainers.
Looks to me more like someone dropped the ball. "Gee...GNU doesn't do
man pages, so we'll note that in the man page, but I don't feel like
writing an info page....".
If you want to press the point, I'll try to raise examples, others are
similarly welcome to provide same.
> > The basic concept [of Info] is valid. However, what seems to have
> > happened in the world is that we got several rival document and
> > hypertext languages in about the same five minute period of 1987.
> > Tim Berners-Lee happened to win the race. Ironically, man pages
> > translate quite well to HTML, and DocBook / LDP has largely filled
> > the niche Info is more suited to: providing a more substantial,
> > book-styled, document suitable for browsing rather than a quick
> > reference.
>
> If I can open info on any terminal, I do prefer it over lynx and would
> never want to have to wait for mozilla starting up
Shared perspective. Though you've other alternatives for text-mode
browsing: links, and w3m (latter is my pref).
> It is obvious that man pages translate easy to HTML: they are so
> simple and limited, that they translate well to anything, including
> info.
Yeah. Funny, when I was a kid, we called that KISS....
> > Info _was_ a really good idea at its time. Binding it to an
> > emacs-style editor made a bit of sense. But things have changed,
> > the computing audience has exploded beyond Richard's dreams (both in
> > general, and for GNU/Linux specifically), and I'd venture to suggest
> > that most people using GNU/Linux either don't know emacsen or don't
> > use them as their principle editing environment. This is no longer
> > a principally technical community, even on the "techincal" platform.
>
> I'm happy belonging to a minority.
How about providing choices to the rest of us.
IIRC, there's a web browser built into emacs. You can also browse
various files from within emacs. I'm not asking for access modes to
tools such as info to disappear. I'm asking that the more fundamental,
open, convention of the Unix manual pages be respected by FSF.
> > I've got _no_ idea how to access this search function. The _only_ time
<...>
> Try Ctrl-H to get help in info.
Thanks.
> Oh, and info info works as well as man man.
Yes. But 'man info' is rather useless (a neutered manpage is presented),
while 'info man' provides a full-featured explanation, in a single page,
of the 'man' command.
> > There is _one_ problem I consistently see with manpages: a lack of
> > examples. A manpage should explain _what_ the function does,
> > provide a brief synopsis of _why_ (e.g.: when do you want to use
> > foo), and then ***SHOW YOU HOW***. See my earlier comment today WRT
> > setting the system clock with 'date'. Syntax isn't presented in the
> > manpage. Remedying this single failing of man pages would do no end
> > of good.
>
> Some manpages do, but they have not been designed for that, nor is it
> their purpose. Manpages with examples miss their basic aim: to should
> provide a quick but complete reference.
You are grossly misinformed.
Traditionally, man pages, particularly for complex commands, would
include a few examples drawn from tasks commonly (or usefully) performed
with the command. Debian lacks strongly in this regard. I also keep an
OpenBSD box here, and would point to, for instance, man (1) find as an
example of a well-written manpage with some good examples.
OpenBSD's manpages area available online at:
http://www.openbsd.org/cgi-bin/man.cgi
> No space for examples
I'm sorry. You're absolutely right. We simply must save that virtual
paper by keeping manpages as short as possible.
<cough>bollux<cough>
> (nor is there a traditional secion for examples).
EXAMPLES
> It would render the pages much longer and more difficult to get an
> overview.
And somehow this isn't a problem for Info?
The synopsis and description (options summary) comes first. Examples
come later.
> There is no index in man.
/^[A-Z]
> Info is designed to deal well with this.
The man page format is a loosely structured, but nonetheless structured,
document. The user is welcome to use available tools of her choosing to
parse, search, scan, summarize, or simply read, the document.
> Using several levels of indices, references and cross-references,
...which I, and the newbie, frankly find confusing.
> you can [...] quickly
...get utterly and completely lost in the Info hierarchy...?
Oh, I'm sorry. I'm afraid I interrupted. You were saying?....
> any information you are looking for without reading the whole thing
> once more (you did read it the first time, did you?)
No. I'm scanning for data. The structure of the Info document, the
"indices, references, and cross references" frankly get in the way. I
_can't scan the document quickly, in one sweep_. Instead, I've got to
navigate multiple pages, which _always_ gets me lost.
> OTOH, often I try --help before using man, if I just need a reminder.
Ditto. See my starting post in this thread.
> > > So what is it that makes you (and others) react so vehemently?
> >
> > Um. Answered? ;-)
>
> No.
My $DEITY! I've just spent thirty minutes talking to the wall!!
Peace.
--
Karsten M. Self <kmself@ix.netcom.com> http://kmself.home.netcom.com/
What part of "Gestalt" don't you understand? Home of the brave
http://gestalt-system.sourceforge.net/ Land of the free
We freed Dmitry! Boycott Adobe! Repeal the DMCA! http://www.freesklyarov.org
Geek for Hire http://kmself.home.netcom.com/resume.html
Attachment:
pgpxzjlTbxucw.pgp
Description: PGP signature