Re: master f82f3d6: ; Improve recently added documentation

Re: master f82f3d6: ; Improve recently added documentation

[Stefan Kangas]

eliz@gnu.org (Eli Zaretskii) writes:

> +@noindent
> +The Info documentation is always preferable to man pages, so be sure
> +to link to an Info manual where available.  For example,
> +@command{chmod} is documented in the GNU Coreutils manual, so it is
> +better to link to that instead of the man page.

This is a good change, in general.  One small issue though:

chmod is a good example of where you might want to link to its man page
instead of the info manual, because there is information in the former
that is not in the latter.

So perhaps we could put some other example in the quoted paragraph
above.  How about gcc, for example?

Re: master f82f3d6: ; Improve recently added documentation

[Eli Zaretskii]

> From: Stefan Kangas <stefankangas@gmail.com>
> Date: Sat, 25 Sep 2021 06:19:20 -0700
> 
> chmod is a good example of where you might want to link to its man page
> instead of the info manual, because there is information in the former
> that is not in the latter.

There is?  Which information is missing in the Info manual?

> So perhaps we could put some other example in the quoted paragraph
> above.  How about gcc, for example?

Then we'd have to have 2 examples, because by using "chmod(1)", I also
hint on the issue with the section number.

Re: master f82f3d6: ; Improve recently added documentation

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

>> chmod is a good example of where you might want to link to its man page
>> instead of the info manual, because there is information in the former
>> that is not in the latter.
>
> There is?  Which information is missing in the Info manual?

chmod(1) goes into great detail on how to specify file permissions, but
I thought that was missing from `(coreutils) chmod invocation'.  Now I
see that linked on that page is `(coreutils) File permissions', a page
that goes into even greater depth.

So this point is moot, and the example is fine.

It is still sometimes reasonable to link to the chmod man page, as the
coreutils info manual might be missing on some machines, for example
because of a missing package or because the system does not use GNU
coreutils.  So this examples is actually very good in both cases, with
your addition.

Re: master f82f3d6: ; Improve recently added documentation

[Eli Zaretskii]

> From: Stefan Kangas <stefankangas@gmail.com>
> Date: Sat, 25 Sep 2021 07:53:47 -0700
> Cc: emacs-devel@gnu.org
> 
> It is still sometimes reasonable to link to the chmod man page, as the
> coreutils info manual might be missing on some machines, for example
> because of a missing package or because the system does not use GNU
> coreutils.  So this examples is actually very good in both cases, with
> your addition.

Yes, perhaps we should say something like

  See Info node ... or man page ..., for more details.