• Re: Internal navigation in the online manual

    From Carlos E. R.@3:633/10 to All on Saturday, October 31, 2026 19:53:52
    On 2026-10-31 14:11, St‚phane CARPENTIER wrote:
    Le 31-10-2026, Nuno Silva <nunojsilva@invalid.invalid> a ‚crit˙:
    On 2026-10-31, Carlos E. R. wrote:

    Talking of manuals, I find large man pages very difficult to use,
    specially when you need something specific. No clickable table of
    content, no clickable index. Info pages are somewhat better.

    Isn't that more about the viewer using to read the manual pages, than a
    flaw of the online manual in itself?

    Maybe. When I wanted to learned about Linux, I hated man pages. I found
    them awful and useless. Now, I'm using them only when I know what I'm
    looking for. I mean, when I don't know something, I know that the man
    page will send me a useless shit load of details without anything
    useful. Or, if anything is useful it's buried and hidden among useless
    stuff. If I'm looking for a fast way to use a command, I'm using tldr.
    If I want to understand a command, I avoid man pages and go look for
    some information on Internet. It's only when I want to know what an
    option is really doing or if an option exists that I'm going to look for
    it in the man pages.

    I ask chatgpt how to use the command.


    --
    Cheers,
    Carlos E.R.
    ES??, EU??.

    --- PyGate Linux v1.5.19
    * Origin: Dragon's Lair, PyGate NNTP<>Fido Gate (3:633/10)
  • From Carlos E. R.@3:633/10 to All on Saturday, October 31, 2026 19:56:32
    On 2026-10-31 11:49, Nuno Silva wrote:
    On 2026-10-31, Carlos E. R. wrote:

    On 2026-10-30 20:24, Charlie Gibbs wrote:
    On 2026-10-30, c186282 <c186282@nnada.net> wrote:

    On 10/29/26 12:27, Chris Ahlstrom wrote:

    rbowman wrote this screed in ALL-CAPS (fixed):

    On Wed, 28 Oct 2026 19:33:23 GMT, Charlie Gibbs wrote:

    The closest I ever came to using an IDE was the symbolic debugger that >>>>>>> came with Lattice C for MS-DOS. Simple, effective... and gone.

    I missed that one although I did use MS C after they bought Lattice and >>>>>> developed it further. I will say for its era Microsoft C had excellent >>>>>> hard copy documentation.

    I agree with that last sentence. In the 80's the manuals for their
    C and FORTRAN were very good, and obviously inspired by the layout
    of DEC's manuals.

    You are correct - manuals/docs were EXTREMELY good
    for such stuff "back in the day". Found a manual
    for "Aztec C" (great !) from the old days ... WOW ! ...
    literally bit-level shit in there in case you needed
    to hyper-optimize something. Clearly the people who
    wrote the doc also wrote the compiler.

    More VOLUME of docs these days ... but "As Good" ???

    Hardly. Most manuals back in the day had a section titled
    "Theory of Operation". I really miss that.


    Talking of manuals, I find large man pages very difficult to use,
    specially when you need something specific. No clickable table of
    content, no clickable index. Info pages are somewhat better.

    Isn't that more about the viewer using to read the manual pages, than a
    flaw of the online manual in itself?

    No, man pages do not contain links to section of the document. It is not structured.


    --
    Cheers,
    Carlos E.R.
    ES??, EU??.

    --- PyGate Linux v1.5.19
    * Origin: Dragon's Lair, PyGate NNTP<>Fido Gate (3:633/10)
  • From Richard Kettlewell@3:633/10 to All on Saturday, October 31, 2026 22:41:58
    "Carlos E. R." <robin_listas@es.invalid> writes:
    On 2026-10-31 11:49, Nuno Silva wrote:
    On 2026-10-31, Carlos E. R. wrote:
    Talking of manuals, I find large man pages very difficult to use,
    specially when you need something specific. No clickable table of
    content, no clickable index. Info pages are somewhat better.

    Isn't that more about the viewer using to read the manual pages, than
    a flaw of the online manual in itself?

    No, man pages do not contain links to section of the document. It is
    not structured.

    Nuno is right; a viewer can include links. For an example see man7.org.

    --
    https://www.greenend.org.uk/rjk/

    --- PyGate Linux v1.5.19
    * Origin: Dragon's Lair, PyGate NNTP<>Fido Gate (3:633/10)
  • From Carlos E. R.@3:633/10 to All on Sunday, November 01, 2026 12:31:21
    On 2026-10-31 23:41, Richard Kettlewell wrote:
    "Carlos E. R." <robin_listas@es.invalid> writes:
    On 2026-10-31 11:49, Nuno Silva wrote:
    On 2026-10-31, Carlos E. R. wrote:
    Talking of manuals, I find large man pages very difficult to use,
    specially when you need something specific. No clickable table of
    content, no clickable index. Info pages are somewhat better.

    Isn't that more about the viewer using to read the manual pages, than
    a flaw of the online manual in itself?

    No, man pages do not contain links to section of the document. It is
    not structured.

    Nuno is right; a viewer can include links. For an example see man7.org.

    Maybe the viewer can, but the man files don't.


    There is the tool "pinfo", it can highlight somethings like the name of another man page, and jump to it.

    Still, no table of content. No jumping from one section while browsing
    the man page.

    See man man page, for example.

    SYNOPSIS
    man [man options] [[section] page ...] ...
    man -k [apropos options] regexp ...
    man -K [man options] [section] term ...
    man -f [whatis options] page ...
    man -l [man options] file ...
    man -w|-W [man options] page ...

    I can not click or tap on the third line to explain to me about "man -K"

    --
    Cheers,
    Carlos E.R.
    ES??, EU??.

    --- PyGate Linux v1.5.19
    * Origin: Dragon's Lair, PyGate NNTP<>Fido Gate (3:633/10)
  • From Carlos E. R.@3:633/10 to All on Sunday, November 01, 2026 13:03:44
    On 2026-11-01 02:08, Nuno Silva wrote:
    On 2026-10-31, Carlos E. R. wrote:
    On 2026-10-31 16:57, Janis Papanagnou wrote:
    On 2026-10-31 11:40, Carlos E. R. wrote:

    Talking of manuals, I find large man pages very difficult to use,
    specially when you need something specific. No clickable table of
    content, no clickable index. Info pages are somewhat better.

    I agree with you on the _horrendous large_ 'man' "pages".
    They shouldn't replace exhaustive and thorough documentation, IMO.
    But worse I think are the ("maneuverable") 'info' pages.
    Or the habit of some "Unixes" to have no man-page information but
    only a stub with the hint to look into the (IMO horrendous) 'info'
    pages. (I'm aware that some certainly prefer them; how else would
    their proliferation be otherwise explainable.)

    Concerning "clickable" information generally, mind the time when
    man-pages were introduced!

    Yes, I understand that. Isn't time we get something better?

    A question is how much of that is already possible using the current
    format.

    And another question is whether the current format, which could easily
    be printed besides being installed as an online manual, does make for
    better documentation to read than something focused on having more
    internal references.

    Printed documentation did have indexes and tables of content, with page numbers, so that you could find where something was in the paper.

    As to printing man pages, well.. I can't store that much paper any more.




    --
    Cheers,
    Carlos E.R.
    ES??, EU??.

    --- PyGate Linux v1.5.19
    * Origin: Dragon's Lair, PyGate NNTP<>Fido Gate (3:633/10)
  • From Christian Weisgerber@3:633/10 to All on Sunday, November 01, 2026 20:50:14
    On 2026-10-31, Carlos E. R. <robin_listas@es.invalid> wrote:

    No, man pages do not contain links to section of the document. It is not structured.

    There are two roff macro sets for man pages: man(7) and mdoc(7).

    man(7) is poorly structured. mdoc(7), which originated in 4.4BSD
    but is now widely available, provides semantic markup. With mdoc(7),
    the structure is there, it's up to the downstream tools to use it.

    The HTML output mode of Kristaps Dzonsons' mandoc(1) formatter,
    which appears to have spread to all BSDs, seems to mostly limit
    itself to providing lots of #anchors as potential targets for
    linking, e.g.:
    https://man.openbsd.org/ls

    When you are piping formatted text into less(1), there are few
    possibilities. OpenBSD's man(1) uses mandoc(1) to dump various
    definitions into a temporary ctags(1) file that is passed to
    less -T. So when I run "man ls" and want to know what the -u option
    does, I can jump straight to it by entering ":tu". That can be
    very useful when navigating long manpages, such as got(1) from Game
    of Trees, where I can jump directly to the subcommand I want to
    look up.

    mdoc(7)'s semantic markup also allows for a more powerful apropos(1)
    that, for instance, allows you to seach for all man pages that
    mention the type "struct stat":

    $ apropos Vt='struct stat'
    stat(1) - display file status
    fhopen, fhstat, fhstatfs(2) - access file via file handle
    getfsstat(2) - get list of all mounted file systems
    pledge(2) - restrict system operations
    stat, fstat, fstatat, lstat, S_ISBLK, S_ISCHR, S_ISDIR, S_ISFIFO,
    S_ISLNK, S_ISREG, S_ISSOCK(2) - get file status
    statfs, fstatfs(2) - get file system statistics
    ftw, nftw(3) - traverse (walk) a file tree
    ...

    --
    Christian "naddy" Weisgerber naddy@mips.inka.de

    --- PyGate Linux v1.5.19
    * Origin: Dragon's Lair, PyGate NNTP<>Fido Gate (3:633/10)
  • From Carlos E. R.@3:633/10 to All on Monday, November 02, 2026 23:27:13
    On 2026-11-01 20:40, Charlie Gibbs wrote:
    On 2026-10-31, Nuno Silva <nunojsilva@invalid.invalid> wrote:

    On 2026-10-31, Carlos E. R. wrote:

    On 2026-10-30 20:24, Charlie Gibbs wrote:

    On 2026-10-30, c186282 <c186282@nnada.net> wrote:


    More VOLUME of docs these days ... but "As Good" ???

    Hardly. Most manuals back in the day had a section titled
    "Theory of Operation". I really miss that.

    Talking of manuals, I find large man pages very difficult to use,
    specially when you need something specific. No clickable table of
    content, no clickable index. Info pages are somewhat better.

    Isn't that more about the viewer using to read the manual pages, than a
    flaw of the online manual in itself?

    At least the man command can search a man page for a text string.
    It's not perfect, but it's better than nothing.


    If you know the string to search for, and it doesn't happen a hundred times.

    For instance, in openSUSE the search is not case sensitive, so looking
    for -l can find -L first. And of course, finds anywhere where -l or -L
    is mentioned in the text, dozen of times.

    For example, the "man zypper" page (specific to *suse systems) has many sections, but there is not a table of contents at the start listing the section so that we know what section to search for.

    --
    Cheers,
    Carlos E.R.
    ES??, EU??.

    --- PyGate Linux v1.5.19
    * Origin: Dragon's Lair, PyGate NNTP<>Fido Gate (3:633/10)
  • From Christian Weisgerber@3:633/10 to All on Saturday, November 07, 2026 16:07:26
    On 2026-11-01, Carlos E. R. <robin_listas@es.invalid> wrote:

    There is the tool "pinfo", it can highlight somethings like the name of another man page, and jump to it.

    Still, no table of content. No jumping from one section while browsing
    the man page.

    "A more modern man page viewer for our terminals"
    https://github.com/plp13/qman

    Qman [i]s a modern, full-featured manual page viewer featuring
    hyperlinks, web browser like navigation, a table of contents for
    each page, incremental search, on-line help, and more. It also
    strives to be fast and tiny, so that it can be used everywhere. For
    this reason, it's been written in plain C and has only minimal
    dependencies.

    (I haven't tried it myself.)

    --
    Christian "naddy" Weisgerber naddy@mips.inka.de

    --- PyGate Linux v1.5.19
    * Origin: Dragon's Lair, PyGate NNTP<>Fido Gate (3:633/10)