Re: Be insane.

Re: Be insane.

[Ingo Schwarze]

Hi Kristaps,

kristaps@mdocml.bsd.lv wrote on Fri, Mar 23, 2012 at 09:46:25PM -0400:

> Log Message:
> -----------
> Be insane.  Make apropos(1) subsume man(1).

I strongly detest this change and am definitely not going to merge it
to OpenBSD.

This is very un-UNIXish.  We want small tools doing one thing well,
not monsters gobbling up all functionality everywhere, asking us
stupid questions.  I consider this bloat seriously reducing usability.
When a utility has done what i asked for, i want my shell prompt back,
not some other prompt i first have to cut out of before i can type
my next command.  I'm not even willing to accept that as an option.

Yours,
  Ingo


> Modified Files:
> --------------
>     mdocml:
>         cgi.c
>         apropos_db.c
>         apropos_db.h
>         apropos.1
>         apropos.c
> 
> Revision Data
> -------------
[...]
> Index: apropos.1
> ===================================================================
> RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/apropos.1,v
> retrieving revision 1.16
> retrieving revision 1.17
> diff -Lapropos.1 -Lapropos.1 -u -p -r1.16 -r1.17
> --- apropos.1
> +++ apropos.1
[...]
> @@ -44,11 +44,11 @@ searches for
>  databases in the default paths stipulated by
>  .Xr man 1 ,
>  parses terms as case-sensitive regular expressions
> -.Pq the Li \&~ operator
> -over manual names and descriptions
> -.Pq the Li \&Nm No and Li \&Nd No macro keys .
> +over manual names and descriptions.
>  Multiple terms imply pairwise
>  .Fl o .
> +If standard output is a TTY, a result may be selected from a list and
> +its manual displayed with the pager.
>  .Pp
>  Its arguments are as follows:
>  .Bl -tag -width Ds
> @@ -156,13 +156,21 @@ If an architecture is specified for the 
>  .Pp
>  .D1 title(cat/arch) \- description
>  .Pp
> -Resulting manuals may be accessed as
> +If on a TTY, results are prefixed with a numeric identifier.
>  .Pp
> -.Dl $ man \-s sec title
> +.D1 [index] title(cat) \- description
>  .Pp
> -If an architecture is specified in the output, use
> -.Pp
> -.Dl $ man \-s sec \-S arch title
> +One may choose a manual be entering the index at the prompt.
> +Valid choices are displayed using
> +.Ev MANPAGER ,
> +or failing that ,
> +.Ev PAGER
> +or just
> +.Xr more 1 .
> +Source pages are formatted with
> +.Xr mandoc 1 ;
> +preformatted pages with
> +.Xr cat 1 .
>  .Ss Macro Keys
>  Queries evaluate over a subset of
>  .Xr mdoc 7
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

Re: Be insane.

[Kristaps Dzonsons]

> I strongly detest this change and am definitely not going to merge it
> to OpenBSD.
>
> This is very un-UNIXish.  We want small tools doing one thing well,
> not monsters gobbling up all functionality everywhere, asking us
> stupid questions.  I consider this bloat seriously reducing usability.
> When a utility has done what i asked for, i want my shell prompt back,
> not some other prompt i first have to cut out of before i can type
> my next command.  I'm not even willing to accept that as an option.

Hi Ingo,

While re-writing mandocdb.c (I'd posted an early version a few weeks ago 
and will properly checkin soon, with the apropos_db.c re-write in tow), 
I've taken the opportunity to critically examine the man(1), apropos(1), 
and whatis(1) tools.

While I understand your opposition, I beg you to approach these tools 
from a position of curiosity and cool-headed analysis instead of 
painting with broad strokes: I certainly didn't spend these many hours 
simplifying, restructuring, and asking "what if..." to have them 
discarded as being "not UNIX-ish", no questions asked!

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.  This was possible because of 
the intended usage of mandoc(1).

I claim the current behaviour is in this same spirit of efficiency and 
simplicity.  In short, I'm not concerned with how quickly my 
command-prompt returns to me: I'm concerned with getting the information 
that I want as quickly as possible.  I've observed the following, in my 
own personal usage:

   1.  Calls to apropos(1) and whatis(1) are overwhelmingly followed by 
a call to man(1).
   1a. It sometimes takes a few calls to apropos(1) as I fool around 
with "Gaussian" versus "gaussian" versus "standard normal".
   2.  I barely use whatis(1).
   3.  man(1) is ill-equipped to handle multiple pages by the same name 
(or "identity", broadly speaking).

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?

As for point 2., why do we have two tools that do pretty much the same 
thing?  Isn't this also bloat?

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.

I think there's room for improvement.  Don't you?

I've not entirely gone off the deep end: regardless of whether I think 
whatis(1) is useless, I'll build in support for it.

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.

Thus, if one chooses to stay with the "UNIX" way, one can do so.  But to 
be honest, I'm happy as a clam running manpage(1) and having it ask me 
when it encounters multiple manuals corresponding to my search.  I don't 
think I've run apropos(1) since.  Certainly none of my time-wasting 
grep(1)ing and locate(1)ing.

Please bear with me: it will take a little while to get all of this put 
in, but in the meantime, it's alright to try new things, then back them 
off (or not!).  The bsd.lv repository, after all, is a good place to do 
that: Bill Joy isn't exactly calling me to denounce my transgressions.

If OpenBSD doesn't want it downstream, so be it---that's ok, it can 
stick with the apropos and whatis.  In the same way, if you want to 
stick with Berkeley DB, then by all means be my guest.  There's no 
reason why we can't push forward and try new things, but despising 
something and calling it monstrous is plain silly.

Best,

Kristaps
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

Re: Be insane.

[Ingo Schwarze]

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