Re: Be insane.

[Ingo Schwarze <schwarze@usta.de>]

Hi Kristaps,

Kristaps Dzonsons wrote on Sun, Apr 15, 2012 at 06:35:30PM +0200:

> For that matter, mandoc(1) itself is a poster child of being
> non-UNIX-ish, discarding `tbl | eqn | nroff' for the sake of
> efficiency and simplicity at considerable benefit.

I do consider "format a manual" as one single task (i don't worry
much whether the author used tbl(7) or .Bl -column when reading
documentation), and i don't like when i need multiple tools in
concert to solve one single task that can already be considered
elemental, so from the point of view of man page usability,
traditional roff went somewhat overboard with its piping.
Don't worry, i fully agree that mandoc(1) is decisively better
in that respect.

> 1. Calls to apropos(1) and whatis(1) are overwhelmingly followed
> by a call to man(1).
> Point 1. is significant.  We currently use apropos(1) to find a
> manual, then man(1) to look at it.  apropos(1) as a standalone tool
> makes no sense, no?  I rarely just want to know whether a manual
> exists:  I want to read it.  Why not stop pretending
> apropos(1)/man(1) serve independent purposes?  Isn't this bloat?

I can't confirm that usage pattern, at all.

Almost always, i know exactly which manual i want, type "man",
and be done with it.  Needing apropos(1) is already rare, and
when it happens, i'm already in deep trouble: I don't even know
which tool i need!  Getting out of that trouble will take time,
and trying to economize a single call to man(1) is not going to
be helpful.

Then, most searches need multiple attempts, and the first
few attempts are usually too broad or too narrow such that they
do *not* result in a call to man(1).  Again, being directed from
apropos(1) to man(1) doesn't help.

Searching for manuals and reading manuals are different matters.
Sure, often enough, when the search has been successful and i have
*finally* found a candidate manual that might explain what i need,
i will have a look inside.  But following *each* call to apropos
by a prompt to look at one of the results is something completely
different.

Often, i do not find anything useful installed, do not read any
of the manuals i found, but proceed to search the ports tree
or even the Web instead.

> 2. I barely use whatis(1).
> As for point 2., why do we have two tools that do pretty much the
> same thing?  Isn't this also bloat?

Yes it is, it is (a mild form of) user interface bloat.
The whatis(1) predecessor manwhere(1) appeared in 1BSD.  
Then apropos(1) appeared in 2BSD.  Given that whatis(1) is a
special case of apropos(1), it is mostly obsolete since around
2BSD.  Probably, it would have been better if Bill Joy would
have built one tool, apropos(1), instead of two, right there,
in 2BSD.

Today, providing whatis(1) is mostly a matter of tradition;
nothing much is to be gained by deleting it now.  Similarly,
deleting chgrp(1) because it's just a pointless special case
of chown(8) would probably come a bit late by now.

> 3. man(1) is ill-equipped to handle multiple pages by the same
> name (or "identity", broadly speaking).
> Point 3., for me, is quite annoying.  I have several local trees of
> manuals whose names and sections clobber those of installed
> utilities. man(1) came from a time when all manuals were in one
> directory and there was an assumption that foo1/foo.1 was unique.
> This is no longer the case, but nobody's stepped forward to say "how
> do I ask for the SECOND foo1/foo.1"?  From OpenBSD's `man -a', what
> is the "first" manpage anyway?  Once multiple manpaths came into
> play, the assumption of uniqueness was violated.  Trying to ignore
> this is silly.

When i type "man foo", i want the system "foo(1)".  When there are
multiple system "foo(1)"s, likely my system is broken.  When i have
non-system manual trees and want to look at them, that's what "-M"
is for.

You know, i'm forced to use SuSE now and then.  They have multiple
copies of almost all manuals in multiple paths, and all of them
are in the system search path.  So each time i type "man", i don't
get the manual right away, but instead a prompt to select one of
the alternatives.  I call that broken:  Both that a prompt is
implemented at all and that the system manuals are not well-defined.

Multiple manual trees is something for people working on manuals,
like us, not for normal users.  Normal users (including myself,
when not working on manuals) just need one tree of manuals.

> Thus, I've settled---this isn't checked in yet because my time's so
> insanely limited these days---on the mandocdb.c re-write and a
> single library function, manpage_search(), passing a search
> expression and getting back results.  I built the search-ask-display
> behaviour into a new manpage(1) utility, then an apropos(1) and
> whatis(1) doing their current silly dance.

I don't understand.  What you call manpage(1) now is nothing
but apropos(1) itself, or what is the difference?

Anyway, if you want to do anything with interactive prompting,
i would be grateful if you could keep the code separate so that
it can easily be skipped when merging, just like i'm skipping
the Linux compatibility stuff for strlcpy and friends etc.
Ideally, any interactive prompting would be confined to its
own file and not have tentacles into other files.  I plainly
don't want any of it, and i don't think it has any place in
the man(1) suite tools.

> In the same way, if you want to stick with Berkeley DB,
> then by all means be my guest.

Actually, no - the sqlite stuff may well be promising.
It is easier to get machine-independent, it is more flexible
and powerful, probably without being less efficient.
Besides, people wanted sqlite in the OpenBSD base system for
a long time, and just today, Marc Espie has imported it.
So i hope to become one of his first users, with mandocdb.

And since we had to back out completely, changing the format
of the database again is no problem at all.

Yours,
  Ingo
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv