Re: coreutils/man/rm.x - fails to mention POSIX "Refuse to remove path/. and path/.., as well as `.' and `..'

[Arsen Arsenović]

Mike Hodson <mystica@gmail.com> writes:

> On Sat, Sep 23, 2023, 12:47 Arsen Arsenović <arsen@aarsen.me> wrote:
>
>> Hi,
>>
>> James Feeney <james@nurealm.net> writes:
>>
>> > coreutils 9.3
>> > coreutils/man/rm.x
>> >
>> > Even though "rm" was modified,
>
>
>> the rm(1) man page completely fails to mention this particular POSIX
>> > promise.
>
>
>> Language should be added to the GNU rm man page explicitly stating the
>> > POSIX behavior:
>
>
>
> This is specified in the manual:
>
>
>
>> See (coreutils)rm invocation, paragraph 5.
>>
>
> ... but this is not the 'manual', its the 'info' page. 'infopage' ? is that
> a term?
> But I digress over semantics..

No, the correct term is 'manual'.  The info format is one of the output
formats for Texinfo manuals.

> This brings up once again a problem I have had, and I believe is in fact
> the reason that I subscribed to this mailing list in the first place years
> ago.
> The info pages, quite unfortunately, DO NOT match the man pages.

Quite the opposite, if man pages, which are unstructured flat pages with
some convention on headings, matched the manuals, they'd be hard to
access.  See, for instance, the ffmpeg manuals.

> There is at the same time both more, and less verbosity in certain sections
> between the two. For one, I appreciate that the 'manpage' directs you to
> other related 'see also' pages.  It also contains full copyright and
> authorship information.  I have not yet figured out where these
> corresponding values exist in 'info' for the individual 'rm' command.

Hmm, normally these are contained in a node in the manual, but they do,
indeed, seem to be missing from (coreutils).  Strange.

SEE ALSO is simply not a useful construct in any documentation system
but 'man', as all other documentation systems (that I am aware of) have
marked-up inline links.

> I suspect [and history keeps indicating this to me] that a rather small
> group of people understand how to [properly] use the GNU 'info' command, or
> even know of its existence, vs the UNIX standard 'man' command.
>
> The Unix 'man' command is well known and understood, and has been the
> defacto standard since 1971. 15 years prior to GNU Info.

Many standards come and go.

Note that I agree that a better info viewer (and a better info on-disk
format) are necessary, but groff -Tutf8 -mtty-char | less -R is not
better.  It lacks the ability to navigate or reflow (the latter '.info'
also lacks today, unfortunately).

The solution to this is not to downgrade to man-pages, but to make the
'info' format better (the source material, i.e. the .texi, for that is
already there) and to provide a better browser.  Texinfo developers have
toyed with the idea of using HTML for that, but I'm personally more
partial to a simpler format that's a 'lossless' encoding that could
instead quickly be translated either to '-Tutf8 -mtty-chars'-style
output *or* to HTML, for GUI viewers like the KDE help center (which
currently uses info2html, which isn't too effective due to the on-disk
format).

(FWIW, I also think man could use more purpose-made pagers.. but there
are intrinsic difficulties due to the source format)

> This one case seems particularly egregious, considering that the POSIX
> specific information is likely not understood by someone trying to
> understand why their command does not work, and this same person likely
> will neither know of 'info' nor read to the very bottom of the manpage to
> see there is indeed a second (info) manual.
>
> In the particular case of 'rm', (albeit on an older ubuntu version of
> coreutils, 9.1, as an example) there is only 16 80-column textual lines
> difference between 'man' and 'info' outputs. [infopage is 16 lines longer]
> 'man' output furthermore resizes to the size of my terminal, making its
> actual vertical output less if the terminal is > 80 columns.
> 'info' output does not seem to resize, which to me makes it harder to read.
>
> Furthermore, between 'info' and 'man' the output of the pages seems to be
> nicer in 'manpage' format as the different sections are all nicely
> indented, have proper section headers, and it is visually less bothersome
> without having so many single quotes everywhere.

This is another unfortunate quirk of the on-disk format.  I have a low
priority task of replacing it (overridden by various other projects
sadly).  I intended to do that this summer, but could not fit it into
schedule.  Contributions welcome (feel free to ask for context on the
Texinfo ML).

However, I don't see the benefit of the left margin.  I suppose that it
could be added with a format that's not, essentially, indexed catpages.

> Until there can be some sort of proper synchronization of all information
> between 'man' and 'info' for coreutils commands, It is my personal feeling
> that every single manpage is invalid because it does not contain the full
> information required to utilize a command.

man pages are brief overviews, not dissimilar to --help output.  Their
current format achieves that end.

> Perhaps to force the issue to redirect people to 'info' pages consistently
> manpages should simply be converted to ONLY contain:
>
> Full documentation <https://www.gnu.org/software/coreutils/rm>
> or available locally via: info '(coreutils) rm invocation'
>
> ?

This would mean that --help has to suffer (the manpages are produced via
help2man, with some templates, as you discovered).

> Or, perhaps there should be an effort to come up with a way to
> automatically synchronize all the information contained within 1, to the
> other?

GCC does this, resulting in an unwieldy man-page.  The mechanism could
be borrowed (and slightly reworked) for coreutils, though I'm unsure if
the result would be worth the effort.  I imagine it'd be better than the
GCC one simply due to scale, though.

> Mike

Have a lovely night.
-- 
Arsen Arsenović

signature.asc
Description: PGP signature