Re: "full" man pages, please?

[Reuti]

Am 21.03.2017 um 17:27 schrieb Mike Hodson:

> ---------- Forwarded message ----------
> From: "Mike Hodson" <address@hidden>
> Date: Mar 21, 2017 12:26 PM
> Subject: Re: "full" man pages, please?
> To: "Bernhard Voelker" <address@hidden>
> Cc:
> 
> I third this, and have mentioned it in the past at least once if not more
> than...
> 
> Why is it so hard to textdump _both_ --help _and_ the texinfo _into a
> manpage_?!?!
> 
> We need one single source of all information. Not 1 half useful one which I
> can get from --help _anyway_ but it is incomplete, and another complete one
> that requires more tooling to properly view and has been impossible for me
> in my 20 years of using Linux to understand how to navigate.

I wrote man pages, and in the beginning also info pages, for the tools I 
programmed for my users. My experience was: it's quite easy to navigate inside 
the info tree when you are aware of its structure. Most likely, as you 
programmed it yourself. But in other info pages I got lost too often: is it the 
next next node on the same level or in the document?

Looking for the option "maxdepth" in `info find`: do I have to use "i" or "s"? 
Not to mention that curly braces to search forth and back need (again) a 
modifier key on a German keyboard. I understand that it might be easier to 
navigate inside the document with an US keyboard.

-- Reuti


> This is a bug if people take time out of their day to explain why it is not
> useful.
> 
> If your only answer is to just use texinfo, you are being blinded by
> historical 'the way it is stupidity when the public is definitely not
> satisfied with the answer.
> 
> Mike
> 
> On Mar 21, 2017 11:55 AM, "Bernhard Voelker" <address@hidden>
> wrote:
> 
> On 03/21/2017 09:24 AM, Harald Dunkel wrote:
>> Hi folks,
>> 
>> I highly appreciate your work to provide excellent tools for
>> decades.
>> 
>> There is one thing I would like to ask for, though: Would you
>> mind to support "full" man pages instead of the "full-docu-can-
>> be-found-in-info-or-on-the-web-only" pages (e.g. dd(1), cpio(1))?
>> 
>> Advantages:
>> 
>> - no break in your regular workflow, regardless on which
>>  unix-like system you are logged in or which man page you
>>  try to access
>> 
>> - no page breaks, but full documentation on a single page.
>>  Its very easy to navigate.
>> 
>> - focused on providing the information. The user interface
>>  is provided by more or less, common to other tools.
>> 
>> I am not asking you to drop the info pages, of course, but IMHO
>> keeping things simple and the DOTADIW approach should still be
>> considered as a major feature of Unix-like systems.
> 
> First of all, the Texinfo manual is the primary way for documentation
> in GNU projects:
> 
> https://www.gnu.org/prep/standards/html_node/GNU-Manuals.html#GNU-Manuals
> 
> Second, maintaining the same as man pages is redundant work.
> Therefore, we choose to generate the man pages from "--help"
> output.
> 
> https://www.gnu.org/prep/standards/html_node/Man-Pages.html
> 
> Re. "nice" and "printouts" (mentioned by Reuti): what's wrong with
> the HTML (one page or single node format), ASCII, DVI or PDF formats?
> 
> https://www.gnu.org/software/coreutils/manual/
> 
> So after all: while the advantages may be tempting, the effort to keep
> texinfo and man in sync is too high for coreutils.
> 
> Consider the mess in findutils: some information exists in the man page,
> while other is in the Texinfo manual.  Not useful either.
> 
> Have a nice day,
> Berny