"We prefer the full documentation in the info page for a reason."
Can you either point me to an already elaborated mention of this reason, on
some web page, or elaborate a bit more here?
I _hate_ texinfo.
Let me wax poetic upon the ways. Should you not wish to read the ways,
please skip to the bottom.
*** skip from here ***
I find it maddening to look through a manual page, (de-facto UNIX
documentation source, since 1971, although sadly not a product of GNU like
Texinfo) and get only partial information.
I'll say it now, and will again, forever, until they change something:
mplayer's monolithic manual page is the most useful manual, as it describes
everything they can think of, and its logically 'all in one place' for me
to pore through.
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. 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.
Things that are "links" within texinfo are not entirely easy to
differentiate from those which are "not links": I tried to go to the 'next'
section by moving my cursor to the "Next: dir invocation" bit of the top
line that states:
"File: coreutils.info, Node: ls invocation, Next: dir invocation, Up:
Directory listing"
Hitting 'enter' on the "next" word above, does nothing of the sort, and
takes me to some unknown place in the document. I have no way to go 'back'
to where i was, 'p'revious only takes me to this new unknown place's
preceding page, and i'm forced to quit out of texinfo and become angry that
what seemed like it should have worked, didn't.
It is IMPOSSIBLE to have _navigational_ errors within a manual page. Up,
or down, top to bottom, you cannot change into some other entirely
unrelated manual, nor can you hit the wrong button and entirely lose your
place...
Further, it is very visually jarring for me to try and read texinfo
documents and keep a sense of coherency and in-order relation due to the
'clear screen and repaint from the top for the next related section' . I
far prefer singular, concatenated, scrollable text, that doesn't give the
effect of 'entirely separate disjointed document that is likely not part of
what you were reading' . - even if it is exactly what is needed to be
read.
Oddly enough, the HTML output version of a texinfo manual is a useful UI/UX
metaphor for such a document, but then I don't want to open up
{e}l(y|i)n(k|x){s} to view it from a shell. It at least presents all the
related subsections linearly which helps me find my place.
I simply want the electronic textual equivalent of fan-fold form-feed boxes
of dot-matrix-printer-paper: there's a known top, and a bottom, and I can
scroll through it always seeing the parts above, and below as a coherent
piece.
A manual page, presented through a pager such as 'less', is precisely this
metaphor of single fanfold paper encompassing everything.
Texinfo's presentation style is like that of a laser printer, but one that
has a paper cutter attached, so that every time there's any excess blank
white paper, it is removed, and an entirely new sheet is created for even
the next section of a related document, leaving one with some full and a
lot of tiny half-sheets that are hard to piece together.
I've turned to Google many times, not realizing(before), or wanting to go
through the hassle(now that I am aware of texinfo and how its used, and
still don't like it anywhere as much as a simple manual page) to find these
nice-to-know-but-hidden tidbits of help.
If texinfo forced HTML-browser semantics: one visable section, whereby
pressing and holding one's arrow key scrolls ONLY to the bottom, and NOT
somehow has the ability to transport you far and wide outside of the scope
of what you were looking at, using texinfo may have not have been such a
horrible experience, to the point that I am writing this entire piece to
persuade your project to change the documentation enough to make the manual
pages "useful" and not just tell me "heres a tidbit, go and actually find
the real manual instead ya derp".
*** skip to here ***
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.
For 'ls' the entirety of what is presented from section 10.1 through
10.1.7, simply should be concatenated and made into a single manual page
for 'ls'. Keep the full text descriptions, keep the presentation format,
just make it one single file that I can read from top to bottom, and
hopefully sort the full set of commandline options in alphabetical order.
This would allow the sanity of saying 'I want to know everything about "ls"
and I want to see it presented to me as a single document that I know has
defined beginnings and ends, and that I know has no extra information that
I might scroll to beyond 'ls' that isn't about 'ls'. Thus a manual page
is presented as a defined, easy navigation experience.
Please consider a documentation change that would place 'all documentation
about $this_command' within the manual page for '$this_command'. Please
stop treating manual pages that existed long before texinfo, as
second-class citizens.
Thank you,
Mike Hodson
On Wed, Mar 11, 2015 at 3:46 PM, Eric Blake <[email protected]> wrote:
> On 03/11/2015 03:33 PM, Peng Yu wrote:
> >> It is already there:
> >>
> >> $ info coreutils 'What information is listed'
>
> >> A file with any other combination of alternate access methods is
> >> marked with a '+' character.
> >
> > Shall the information about "+" be added to the manpage?
>
> The man page is generated from 'ls --help', and is intentionally
> shorter. We prefer the full documentation in the info page for a
> reason. But if you have a particular patch in mind, feel free to
> propose it and get some feedback on whether it would make sense to add.
>
> --
> Eric Blake eblake redhat com +1-919-301-3266
> Libvirt virtualization library http://libvirt.org
>
>
