Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

TLDR pages: Simplified, community-driven man pages

tldr.sh

Post reply on HN
Print view View original

151–160 of 179 posts

Re: TLDR pages: Simplified, community-driven man pages

#151

Post by jcl »

catalogia wrote: post #132
xorcist wrote: post #97

Earlier quoted context omitted.

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.

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.

Many man pages have examples, but they consistently bury them at the end, after exhaustively covering every flag, file, or environment variable that could possibly affect execution.

It might not be crazy to move the examples section to the top, since it would more quickly provide what most readers are looking for: a sample command line to tweak. Anyone who is genuinely looking for what a particular flag does is just going to search for it anyway, so it doesn't really matter if that flag appears on the 24th screen instead of the 23rd.

Re: TLDR pages: Simplified, community-driven man pages

#152

Post by catalogia »

jcl wrote: post #151
catalogia wrote: post #132

Earlier quoted context omitted.

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.

Many man pages have examples, but they consistently bury them at the end, after exhaustively covering every flag, file, or environment variable that could possibly affect execution. It might not be crazy to move the examples section to the top, since it would more quickly provide what most readers are looking for: a sample command line to tweak. Anyone who is genuinely looking for what a particular flag does is just…

Something I like about tldr is that tldr pages are short enough to not necessitate using a pager, so you can print the tldr of a command and read it while typing the command in the same terminal emulator.

I know you can disable the pager for man, but the typical manpage is going to be fairly long anyway so the pager is generally desired. I suppose you could pipe man through head to just print out the first section, but honestly tldr seems to fill this niche better than I see that working.

Re: TLDR pages: Simplified, community-driven man pages

#153

Post by anjbe »

beefhash wrote: post #106
joshklein wrote: post #83

Earlier quoted context omitted.

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

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 wo…

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

Re: TLDR pages: Simplified, community-driven man pages

#154

Post by SanchoPanda » 

  cheat() { 
   curl "http://cheat.sh/$1"
  }

  man2txt() {
    man "$1" | col -bx
  }

  manflags(){
    man "$1" | awk '{$1=$1;print}' | grep "^\-"
  } #man pages just the flags more or less, captures some extra 

  ubuman() { 
   w3m -dump "https://manpages.ubuntu.com/manpages/bionic/en/man1/"$1".1.html"
  } # ubuntu web manpages note bionic, update with do release up

  ubumanflags() { 
   w3m -dump "https://manpages.ubuntu.com/manpages/bionic/en/man1/$1.1.html" | \
   awk '{$1=$1;print}' | grep "^\-"
  } # ubuntu web manpages

  explain () {
    if [ "$#" -eq 0 ]; then
      while read  -p "Command: " cmd; do
        curl -Gs "https://www.mankier.com/api/v2/explain/?cols="$(tput cols) --data-urlencode "q=$cmd"
      done
      echo "Bye!"
    elif [ "$#" -eq 1 ]; then
      curl -Gs "https://www.mankier.com/api/v2/explain/?cols="$(tput cols) --data-urlencode "q=$1"
    else
      echo "Usage"
      echo "explain                  interactive mode."
      echo "explain 'cmd -o | ...'   one quoted command to explain it."
    fi
  }
# notetoself: check ```info``` check ```help``` check ```apropos``` check ```whatis```

Re: TLDR pages: Simplified, community-driven man pages

#155

Post by anjbe »

thrwaway69 wrote: post #61
CaptArmchair wrote: post #26

Earlier quoted context omitted.

> it's pretty clear from the context I think that largely depends on who's using the tools and how acquainted they are with command line tools. An absolute beginner likely will not know what tar's 'f' flag does, or assume something else. > OTOH, sometimes I'll copy-paste some perl or awk dark magic from Stack Overflow, and then try modify it piecemeal to fit my case. That's an incantation :) And I absolutely have no…

I will bite - I have been using linux for 4 years. I have used tar a lot and I don't know what v means. I switch between -xvf, -xvz, etc. x - extract | f - file | z - operating on tar.gz or similar. Edit: v - verbose

On OpenBSD (and other systems using mandoc as the default “man” program), I can jump to an unknown flag right away with the pager’s tag support: “:tv”

    -v      Verbose operation mode.  If -v is specified multiple times or if
            the -t option is also specified, tar will use a long format for
            listing files, similar to ls(1) -l.
Or I can tack #v onto the end of the web URL: https://man.openbsd.org/tar.1#v

Re: TLDR pages: Simplified, community-driven man pages

#156

Post by tingletech »

downerending wrote: post #48
stared wrote: post #12

I would be happy to see such a thing taking off. Typical man pages are well, like learning a language by studying a dictionary, alphabetically. It may contain all information, but a clear F on UX. Some packages get slightly better with starting from the most common use cases, with examples (and digestible errors). However, I would be even more interested to see what is the actual usage pattern (e.g. from .bash_histor…

It's true that the man pages aren't meant to be the primary method of learning Unix. But they are indeed a spectacular and irreplaceable resource. One of the best things that ever happened in my career was having a desk across from the entire SunOS manual set. I'd pull them down one at a time and read them, cover to cover. It paid off, big time, and I strongly recommend it.

I was a bio major who would hang out in rooms with terminals in the early 90s.

One day I saw “type ‘man man’” and “apropos” written on a chalk board.

That is how I learned Unix.

Re: TLDR pages: Simplified, community-driven man pages

#157

Post by SanchoPanda »

SanchoPanda wrote: post #154

cheat() { curl "http://cheat.sh/$1" } man2txt() { man "$1" | col -bx } manflags(){ man "$1" | awk '{$1=$1;print}' | grep "^\-" } #man pages just the flags more or less, captures some extra ubuman() { w3m -dump "https://manpages.ubuntu.com/manpages/bionic/en/man1/"$1".1.html" } # ubuntu web manpages note bionic, update with do release up ubumanflags() { w3m -dump "https://manpages.ubuntu.com/manpages/bionic/en/man1/$1…

--

  tldr-web() {
   w3m -dump "https://raw.githubusercontent.com/tldr-pages/tldr/master/pages/common/$1.md"
   w3m -dump "https://raw.githubusercontent.com/tldr-pages/tldr/master/pages/linux/$1.md"
  }

Re: TLDR pages: Simplified, community-driven man pages

#158

Post by jopsen »

catalogia wrote: post #152
jcl wrote: post #151

Earlier quoted context omitted.

Many man pages have examples, but they consistently bury them at the end, after exhaustively covering every flag, file, or environment variable that could possibly affect execution. It might not be crazy to move the examples section to the top, since it would more quickly provide what most readers are looking for: a sample command line to tweak. Anyone who is genuinely looking for what a particular flag does is just…

Something I like about tldr is that tldr pages are short enough to not necessitate using a pager, so you can print the tldr of a command and read it while typing the command in the same terminal emulator. I know you can disable the pager for man, but the typical manpage is going to be fairly long anyway so the pager is generally desired. I suppose you could pipe man through head to just print out the first section, b…

But they are not system specific... I don't need `tldr opkg` on my system.

In fact, having pages I don't need just causes confusion.

Moreover, commands can have system specific names.

Re: TLDR pages: Simplified, community-driven man pages

#159

Post by cowsandmilk »

Polylactic_acid wrote: post #141
bauerd wrote: post #33

Earlier quoted context omitted.

Some ecosystems even eschew manpages. For example, I wouldn't know how to ship manpages as part of a Ruby gem, it's discouraged iirc

For a ruby gem you would most likely use the --help flag. This has the advantage of working on sub commands so you can do `gemname command --help` and get more specific help.

Git has subcommands and still ships man pages. They just put a dash into the name. E.g. `man git-fetch`
Post reply on HN