"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".
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.