4 ms·

No, they serve two different purposes. Man pages are a reference/spec on all options and parameters, aimed at those who already have use a tool/technology/conc

No, they serve two different purposes. Man pages are a reference/spec on all options and parameters, aimed at those who already have use a tool/technology/concept. This is something different. It's a tutorial of how to do the most common things using that tool. It's a bit like learning a programming language: would you read the formal spec, or would you learn from code examples? Unless you've read formal specs for other languages with a similar paradigm before, it's way easier to learn from examples first, which gets you to the level of understanding where the formal specs start to make sense. Improvements to man pages should be made, but not at the cost of beginner-friendly projects.

joshklein 7y ago
> they serve two different purposes I agree, but I'm also painfully aware of man page incompleteness every time I'm on a non-OpenBSD system. I'd be grateful to anyone who chipped away at proper tagging for any GNU software. One should be able to :t to jump to the reference for any flag.
- beefhash 7y ago
  That's impossible by means of how they're written. GNU still cares about operating systems that don't bundle the mdoc macros with their troff processor and don't use mandoc (which is... exactly only AIX and HP-UX at this point), so they write all their text in man so that they render correctly everywhere. For tagging, the formatting would need to be redone to be mdoc, which breaks both the OSes mentioned above and would be an immensely arduous task at this point. Probably not going to happen. Note GNU and and the Linux man-pages project are mostly outliers; everyone else that lives in BSD/illumos land has long since moved on to mdoc since like the 80s. See also https://www.usenix.org/system/files/login/articles/141-dzonsons.pdf https://www.usenix.org/system/files/login/articles/141-dzons...
  - anjbe 7y ago
    > That's impossible by means of how they're written. GNU still cares about operating systems that don't bundle the mdoc macros with their troff processor Sudo supports such systems even though its manuals are written in mdoc. The source tarball contains both the original mdoc manuals and man manuals, autogenerated by mandoc (https://mandoc.bsd.lv https://mandoc.bsd.lv) which can convert mdoc to man—easy to do, since mdoc is a semantic format. Then at build time one format or the other will be installed depending on how capable the system manpage formatter is. Any project using mdoc pages could do the same thing. Projects using autotools could even copy Sudo’s autoconf macros for this.
Scarblac 7y ago
It would be quite nice to have that quick tutorial in a new section at the top of man pages, in addition to what's already there.
deleted 7y ago
[deleted]
SaulOfTheJungle 7y ago
> No, they serve two different purposes. I don't see why they could not serve both purposes. Man pages should start with a tldr section followed by the full reference/spec.
- fhennig 7y ago
  Yes, put both things in the man page! Looking at some examples of tldrs, it mostly boils down to the most common use cases as examples. So well written man pages already have an "examples" section, and that really helps!
xorcist 7y ago
There's no reason man pages can't be both. Many man pages contain examples and common usages. See for example the rsync man page, with complete examples of how to backup common file systems.
- catalogia 7y ago
  One of the nice qualities of man pages is comprehensiveness, while one of the nice qualities of tldr docs is succinctness. Both are mutually exclusive; man pages cannot be both. An examples section in a manpage is a fine idea which I would certainly encourage, but that wouldn't render tldr obsolete.
  - neckardt 7y ago
    Ideally I would like to see an additional section in man pages devoted to examples. The TLDR pages could then be moved into the man pages.
    - killjoywashere 7y ago
      tldr didn't choose tar as their front-page demo by accident. The tar manpage is a classic example of the CLI gods apparently going to some effort to design the Examples section to effectively tell new users to bugger the hell off.
      - voltagex_ 7y ago
        https://www.freebsd.org/cgi/man.cgi?query=tar&apropos=0&sektion=0&manpath=FreeBSD+12.1-RELEASE+and+Ports&arch=default&format=html https://www.freebsd.org/cgi/man.cgi?query=tar&apropos=0&sekt...
        deleted 7y ago
        [deleted]
      - ori_b 7y ago
        This reads fine to me: https://man.openbsd.org/tar https://man.openbsd.org/tar
avodonosov 7y ago
I often have this difficulty with man pages. But man page format allows examples, contributing many examples to original man pages would make them more accessible. Also, a gentle, human oriented intro can be a part of man page I think.
Kalq 7y ago
I disagree. Plenty of man pages have very excellent examples that serve as a beginner tutorial. Ones that are just as good (and easy to understand) if not better than what I've seen from TLDR. There's no reason manpages can't be both.

joshklein 7y ago

> they serve two different purposes I agree, but I'm also painfully aware of man page incompleteness every time I'm on a non-OpenBSD system. I'd be grateful to anyone who chipped away at proper tagging for any GNU software. One should be able to :t to jump to the reference for any flag.

beefhash 7y ago
That's impossible by means of how they're written. GNU still cares about operating systems that don't bundle the mdoc macros with their troff processor and don't use mandoc (which is... exactly only AIX and HP-UX at this point), so they write all their text in man so that they render correctly everywhere. For tagging, the formatting would need to be redone to be mdoc, which breaks both the OSes mentioned above and would be an immensely arduous task at this point. Probably not going to happen. Note GNU and and the Linux man-pages project are mostly outliers; everyone else that lives in BSD/illumos land has long since moved on to mdoc since like the 80s. See also https://www.usenix.org/system/files/login/articles/141-dzonsons.pdf https://www.usenix.org/system/files/login/articles/141-dzons...
- anjbe 7y ago
  > That's impossible by means of how they're written. GNU still cares about operating systems that don't bundle the mdoc macros with their troff processor Sudo supports such systems even though its manuals are written in mdoc. The source tarball contains both the original mdoc manuals and man manuals, autogenerated by mandoc (https://mandoc.bsd.lv https://mandoc.bsd.lv) which can convert mdoc to man—easy to do, since mdoc is a semantic format. Then at build time one format or the other will be installed depending on how capable the system manpage formatter is. Any project using mdoc pages could do the same thing. Projects using autotools could even copy Sudo’s autoconf macros for this.

Scarblac 7y ago

It would be quite nice to have that quick tutorial in a new section at the top of man pages, in addition to what's already there.

deleted 7y ago

[deleted]

SaulOfTheJungle 7y ago

> No, they serve two different purposes. I don't see why they could not serve both purposes. Man pages should start with a tldr section followed by the full reference/spec.

fhennig 7y ago
Yes, put both things in the man page! Looking at some examples of tldrs, it mostly boils down to the most common use cases as examples. So well written man pages already have an "examples" section, and that really helps!

xorcist 7y ago

There's no reason man pages can't be both. Many man pages contain examples and common usages. See for example the rsync man page, with complete examples of how to backup common file systems.

catalogia 7y ago
One of the nice qualities of man pages is comprehensiveness, while one of the nice qualities of tldr docs is succinctness. Both are mutually exclusive; man pages cannot be both. An examples section in a manpage is a fine idea which I would certainly encourage, but that wouldn't render tldr obsolete.
- neckardt 7y ago
  Ideally I would like to see an additional section in man pages devoted to examples. The TLDR pages could then be moved into the man pages.
  - killjoywashere 7y ago
    tldr didn't choose tar as their front-page demo by accident. The tar manpage is a classic example of the CLI gods apparently going to some effort to design the Examples section to effectively tell new users to bugger the hell off.
    - voltagex_ 7y ago
      https://www.freebsd.org/cgi/man.cgi?query=tar&apropos=0&sektion=0&manpath=FreeBSD+12.1-RELEASE+and+Ports&arch=default&format=html https://www.freebsd.org/cgi/man.cgi?query=tar&apropos=0&sekt...
      - deleted 7y ago
        [deleted]
    - ori_b 7y ago
      This reads fine to me: https://man.openbsd.org/tar https://man.openbsd.org/tar

avodonosov 7y ago

I often have this difficulty with man pages. But man page format allows examples, contributing many examples to original man pages would make them more accessible. Also, a gentle, human oriented intro can be a part of man page I think.

Kalq 7y ago

I disagree. Plenty of man pages have very excellent examples that serve as a beginner tutorial. Ones that are just as good (and easy to understand) if not better than what I've seen from TLDR. There's no reason manpages can't be both.