Re: Document for + seems to be missing in ls' document

[Eric Blake]

On 03/12/2015 01:46 PM, Mike Hodson wrote:

[please don't top-post on technical lists]

> "We prefer the full documentation in the info page for a reason."
> 

I probably should have said: "We prefer maintaining the full
documentation in texinfo for a reason".  We want the --help output to be
concise.  We also want to minimize effort - maintaining full
documentation by hand in both texinfo and roff formats would be too much
effort, so we have to generate the man page from something.  It's easy
to use help2man to generate man pages from --help output, but I don't
know of any good conversion from texinfo to man.  So the man page ends
up being as concise as --help output, while including a pointer to the
full documentation.

> Can you either point me to an already elaborated mention of this reason, on
> some web page, or elaborate a bit more here?

Yes - the GNU Coding Standards:

https://www.gnu.org/software/autoconf/manual/standards.html#GNU-Manuals

"The preferred document format for the GNU system is the Texinfo
formatting language. Every GNU package should (ideally) have
documentation in Texinfo both for reference and for learners. Texinfo
makes it possible to produce a good quality formatted book, using TeX,
and to generate an Info file. It is also possible to generate HTML
output from Texinfo source. See the Texinfo manual, either the hardcopy,
or the on-line version available through info or the Emacs Info
subsystem (C-h i).

Nowadays some other formats such as Docbook and Sgmltexi can be
converted automatically into Texinfo. It is ok to produce the Texinfo
documentation by conversion this way, as long as it gives good results.
...

Don’t use Unix man pages as a model for how to write GNU documentation;
most of them are terse, badly structured, and give inadequate
explanation of the underlying concepts. (There are, of course, some
exceptions.) Also, Unix man pages use a particular format which is
different from what we use in GNU manuals."

> 
> I _hate_ texinfo.

I have to wonder if you actually hate 'info', rather than 'texinfo'.
(and to be honest, I seldom use 'info' myself, preferring to get at the
documentation in other formats, because of how much I dislike 'info')

The texinfo source is also the source of a web page.  In fact, the next
coreutils release will update the man pages to point to the web page,
rather than info:

http://git.savannah.gnu.org/gitweb/?p=coreutils.git;a=commitdiff;h=e8715100cb2824fbd8ec724728a21fffdbcdb9f5


> Now, you're correct that the information for "that star character listed in
> 'ls' permission output" IS somewhere in the middle of coreutils' texinfo
> manual, in the 'What information is listed' section.
> 
> It is however _not_ part of "info coreutils 'ls invocation'" pointed to by
> the manpage, and unless one is fully cognizant of how to navigate texinfo
> for the information they are looking for, it is not immediately apparent
> that subsections exist.

That's one of the reasons that I _like_ the 'html' version of the
manuals MUCH more than the 'info' version - you can choose to view the
entire manual at once, at which point, a simple 'ctrl-f' will let your
browser find the relevant text within the manual regardless of the
'texinfo's division of information into sections.

https://www.gnu.org/software/coreutils/manual/coreutils.html is the full
manual; although I will admit that the text added to 'ls --help' will
only take you to
https://www.gnu.org/software/coreutils/manual/coreutils.html which in
turn redirects to the paginated html manual at
https://www.gnu.org/software/coreutils/manual/html_node/ls-invocation.html#ls-invocation.

>  Once you scroll 'ls invocation' to the bottom, an
> entirely new section pops into view, an action which has never once in my
> life indicated to me that what I was now looking at, was in any way
> connected to the previous.

That is a shortfall of 'info', not 'texinfo'.  In the html rendering,
even in the paginated link mentioned above, it's a bit more obvious that
there are several sub-pages all associated with 'ls', and you have to
click on a link to get to that sub-page, rather than just hit 'space'
and move to the next page without an idea of whether the successor page
is a child of the current page.

> I ask, for sanity of everyone who wants to find quick yet COMPLETE
> information about a command, that the entirety of what you put into the
> texinfo docs should be duplicated in the per-tool manualpages.

While you are entitled to that opinion, it will probably not happen
unless you can convince rms to change the GNU Coding Standards to
request that all GNU projects comply.  For now, you may have to just be
content with the fact that the man pages point to the full manual.

-- 
Eric Blake   eblake redhat com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org

signature.asc
Description: OpenPGP digital signature