News for hackers. Stuff that matters.
Re:Giteveryday – A useful minimum set of commands for Everyd... by libeclipse on Sunday October 30, 2016 @06:40AM (#12829067)
Wow, a man page that is actually readable and understandable.

I've been using Linux for years, and never once have I seriously looked at a man page. One of the more useless pieces of advice Linux beginners are given is to `man [tool]`. The documentation often has tonnes of useless information and no examples. It's frustrating, and it's also why projects like tldr[0] have gotten so popular.

But, the page linked in the OP is actually brilliant. It's easy to read, has examples, compartmentalises into sections that are relevant to different people. It's a step in the right direction.

Note: I'm not saying there aren't other pages like OP. There probably are, but the vast majority are not.

[0] https://github.com/tldr-pages/tldr

Re:Giteveryday – A useful minimum set of commands for Everyd... by jlgaddis on Sunday October 30, 2016 @07:49AM (#12829282)
> One of the more useless pieces of advice Linux beginners are given is to `man [tool]`.

On the other hand, when I was first introduced to Linux ~20 years ago, I didn't have an "always-on" Internet connection and web sites weren't that popular.

Probably 90% of what I learned in the first few years or so came from the man pages and a locally downloaded copy of the guides and howto's from TLDP [0].

I might also mention that not all man pages are created equal. I've seen some in Ubuntu that serve no purpose other than wasting bytes on the disk while some of those in OpenBSD act as a single source for everything one needs to know about <tool>.

[0]: http://www.tldp.org/

Re:Giteveryday – A useful minimum set of commands for Everyd... by Anthony-G on Sunday October 30, 2016 @12:27PM (#12830632)
Similar situation for me. My first Linux distribution was Red Hat 5.2 which included an off-line copy of the Linux Documentation Project on the CD (as did other contemporary distros such as Mandrake). Since I only had a slow dial-up connection, I found these off-line copies to be an invaluable resource. I remember using Lynx to read Guides and Howtos during the two weeks it took me to get X working on my old laptop.

After those early days, I hadn’t looked at the LDP site in ages but about 4/5 years ago I looked at the project again with a view towards contributing (now that I know more about GNU/Linux and Unix in general). However, it looks like the project was (is) largely moribund and I got the impression that the active community had dwindled significantly over the past 15 years or so – which is a pity.

Re:Giteveryday – A useful minimum set of commands for Everyd... by jasoncchild on Sunday October 30, 2016 @09:45AM (#12829747)
Same here; I was constrained to what was on my stack of floppies comprising my Slackware dist
Re:Giteveryday – A useful minimum set of commands for Everyd... by jlgaddis on Sunday October 30, 2016 @01:00PM (#12830832)
Slackware was the first Linux distro I ever installed on my own machine (I think that was the case for most of us at that time).

I can remember very well trying to scrounge up enough floppies to write out the "A" and "N" sets -- the minimum needed to have a functional system with working "networking" (in my case, dial-up).

After struggling for days to get a working "chat script", I finally managed to get online.

I don't miss it but, in a way, it was sort of a "rite of passage" and you were forced to learn how your system really worked.

Re:Giteveryday – A useful minimum set of commands for Everyd... by pwdisswordfish on Sunday October 30, 2016 @10:08AM (#12829854)
Wow, a man page that is actually readable and understandable... just like any other man page.

I've been using Linux for years, and never once have I seriously looked at replacements for man pages. In your average man page, I can look up even the most obscure option and know exactly how to use it and what it actually does. With a detailed enough man page, I don't even need to look anywhere else much of the time. It irritates me when I have to lookup documentation which isn't written in a similar format. (Say, LaTeX.)

I don't see any appeal in "tldr pages" or "bro pages", and frankly, I get rather annoyed when every once in a while I see HN posts promoting projects like that which basically reinvent the square wheel instead of solving the real problems of man pages (which I'd say there are two: lack of hyperlinks and poor searchability).

Re:Giteveryday – A useful minimum set of commands for Everyd... by cx1000 on Sunday October 30, 2016 @11:13AM (#12830209)
I have never heard of bro pages before. It sounded like a pejorative but it's actually a thing http://bropages.org/. I find them to be a lot of wasted time too and totally agree about the hyperlinks. As far as searching man pages, I do pretty well with the trusty forward slash. Would you prefer more semantic searching like google?
Re:Giteveryday – A useful minimum set of commands for Everyd... by catern on Sunday October 30, 2016 @11:49AM (#12830423)
>solving the real problems of man pages (which I'd say there are two: lack of hyperlinks and poor searchability

texinfo (info) has hyperlinks, and I can search through multiple manuals if that's what you mean by searchability. And it's probably already installed on your system.

Re:Giteveryday – A useful minimum set of commands for Everyd... by pwdisswordfish on Sunday October 30, 2016 @12:21PM (#12830600)
I can never remember which manual page contains a description of struct timespec, for example. Running apropos or man -k didn't help me. I only found out it's time.h(0p) by a lucky guess.

Info is actually a quite decent idea, it's just executed poorly. Info pages are written like books, while I really miss the concise lexicon-like format of man pages. And it doesn't help that the default GNU info viewer is on one hand unusable for someone who isn't already an Emacs user, and on the other redundant for Emacs users. (I am the former. Fortunately, there's pinfo.)

Re:Giteveryday – A useful minimum set of commands for Everyd... by catern on Sunday October 30, 2016 @01:02PM (#12830844)
Ah. Just open the libc manual with "info libc", then "i" to look something up in the index, and type "struct timespec". (You can even tab-complete the name of the struct).

>And it doesn't help that the default GNU info viewer is on one hand unusable for someone who isn't already an Emacs user

Yes, well, did you consider running "info info"? :) There's a tutorial accessible with "h". It's not as if there's much to learn, the arrow keys and Enter work fine for navigating and following links.

Re:Giteveryday – A useful minimum set of commands for Everyd... by glandium on Monday October 31, 2016 @01:51AM (#12834555)
`info info` is useless when you don't know info and don't have emacs installed: https://news.ycombinator.com/item?id=12301491
Re:Giteveryday – A useful minimum set of commands for Everyd... by catern on Monday October 31, 2016 @09:16AM (#12836393)
That's incorrect. That's what happens when the info documentation for info has not been installed by your distribution. Normally you get https://www.gnu.org/software/texinfo/manual/info-stnd/info-s...
Re:Giteveryday – A useful minimum set of commands for Everyd... by JdeBP on Sunday October 30, 2016 @12:02PM (#12830496)
> lack of hyperlinks and poor searchability

Meet Daniel J. Bernstein's slashdoc.

* http://cr.yp.to/slashdoc.html

Re:Giteveryday – A useful minimum set of commands for Everyd... by hk__2 on Sunday October 30, 2016 @08:50AM (#12829495)
I’ve been using Linux for years too, and I learned more useful things about Bash with `man bash` than anything I could find on the web.
Re:Giteveryday – A useful minimum set of commands for Everyd... by pjc50 on Sunday October 30, 2016 @09:21AM (#12829632)
For a while I had a printout of the bash manpage, neatly bound. It's something like 60 pages. Nroff actually produces great print output, which hardly anyone ever uses it for these days.
Re:Giteveryday – A useful minimum set of commands for Everyd... by rkowalick on Sunday October 30, 2016 @09:26AM (#12829660)
I don't think anything matches paper in terms of annotatability. I print things put all the time to just mark them up with red pen.
Re:Giteveryday – A useful minimum set of commands for Everyd... by cx1000 on Sunday October 30, 2016 @11:34AM (#12830333)
I don't know, I saw a Microsoft surface commercial the other day... /s
Re:Giteveryday – A useful minimum set of commands for Everyd... by ekr on Sunday October 30, 2016 @06:56AM (#12829122)
One place where the MSDN docs is way ahead of the manpages is the documentation of function paramters. For instance, here's the ouput of man 2 write.

  ssize_t write(int fd, const void *buf, size_t count);

  DESCRIPTION
  write()  writes  up  to  count  bytes  from  the buffer pointed buf to the file referred to by the file descriptor fd.

  The number of bytes written may be less than count if, for example, there is insufficient space on  the underlying  physical  medium,  or the RLIMIT_FSIZE resource limit is encountered (see setrlimit(2)), or call was interrupted by a signal handler after having written less than  count  bytes.   (See  also (7).)

  For  a  seekable file (i.e., one to which lseek(2) may be applied, for example, a regular file) writing takes place at the file offset, and the file offset is incremented by  the  number  of  bytes  actually written. If the file was open(2)ed with O_APPEND, the file offset is first set to the end of the file before writing.  The adjustment of the file offset and the write operation are performed as  an  atomic step.
I have to go through a block of text scanning for the parameter I'm interested in. When I'm using the manpage as a reference (which is most of the time), this is less than ideal.

MSDN indexes the documentation by parameter so you can quickly find what you're interested in.

LE. Sample msdn link for comparison: https://msdn.microsoft.com/en-us/library/windows/desktop/aa3... .

Re:Giteveryday – A useful minimum set of commands for Everyd... by pjc50 on Sunday October 30, 2016 @09:26AM (#12829656)
One of the things that never ceases to amaze me is how slow MSDN is. It feels faster to look something up on stackoverflow, even if it's not as well organised.

Version-specificness on MSDN is often a little odd. I do Windows CE and for some reason Google returns hits from the Wince5 docs more often than the rest, and it's not straightforward to get to the docs for a different version. Sometimes this is important.

Re:Giteveryday – A useful minimum set of commands for Everyd... by qwertyuiop924 on Sunday October 30, 2016 @07:08AM (#12829158)
That's actually just one sentence you have to scan, so I don't totally see the issue.
Re:Giteveryday – A useful minimum set of commands for Everyd... by viraptor on Sunday October 30, 2016 @08:13AM (#12829356)
It could still be better. It could be 0 sentences to scan it it was formatted in a better way.
Re:Giteveryday – A useful minimum set of commands for Everyd... by koytch on Sunday October 30, 2016 @08:27AM (#12829415)
Sections 2 and 3 contain the most readable man pages out there. The pages in sections 1 and 8 are often terrible, being the result of some texinfo->man filter.
Re:Giteveryday – A useful minimum set of commands for Everyd... by brohee on Sunday October 30, 2016 @07:30AM (#12829225)
That's under Linux (not sure if that man page is maintained by glibc or the kernel seeing as it is a syscall).

That's pretty different under a system that cares : http://man.openbsd.org/OpenBSD-current/man2/write.2

Re:Giteveryday – A useful minimum set of commands for Everyd... by St-Clock on Sunday October 30, 2016 @07:52AM (#12829289)
I'm sorry, how is it different than the linux example?

They both describe all the parameters in the first sentence of the description.

Re:Giteveryday – A useful minimum set of commands for Everyd... by brohee on Sunday October 30, 2016 @08:15AM (#12829364)
I was mislead by the non formatting in the HN paste. Looking at https://linux.die.net/man/2/write it's about as good.
Re:Giteveryday – A useful minimum set of commands for Everyd... by JdeBP on Sunday October 30, 2016 @01:03PM (#12830848)
It's worth noting that there's a difference between reference documentation and tutorials. The world needs both, of course. The user manual on Unices and Linux operating systems is meant to be reference doco.

In the BSD world, in addition to the user manuals there are the various handbooks and guides:

* https://freebsd.org/doc/handbook/

* https://netbsd.org/docs/guide/en/

* https://www.trueos.org/handbook/trueos.html

* http://dragonflybsd.org/docs/handbook/

The Linux world has the Linux Documentation Project, but that is of variable quality, has patchy coverage, and is wildly outdated in some areas.

There's a collaborative project on Wikibooks, as well.

* https://en.wikibooks.org/wiki/Guide_to_Unix

Re:Giteveryday – A useful minimum set of commands for Everyd... by qwertyuiop924 on Sunday October 30, 2016 @07:09AM (#12829165)
man pages are quite useful as reference documents. Which is their intended purpose.
Re:Giteveryday – A useful minimum set of commands for Everyd... by tmsbrg on Sunday October 30, 2016 @09:00AM (#12829546)
I have the idea of creating a tool which is more like a tutorial for commands rather than the reference that `man` is. Has anyone made something like that before?

I thought of giving it a name like `tutor`. Where you can use it without arguments for a general shell tutorial and with arguments for a mini-tutorial about a command

$ tutor

Welcome to the Bash command shell. This is a short tutorial about how (and why) to use the shell...

$ tutor ls

Use `ls` to view files in the current directory or one you specify. Examples:

- ls

Lists current directory (excluding files starting with a ., these are "hidden files")

- ls -A

Lists current directory including hidden files ... ===

Something like that at least. I think one of the worst things about the shell is finding out about the functionality there actually is, so having something like that built in could be handy. Maybe you could also have it do something like `tutor copy file` and have it find and list commands that fit the description.

Re:Giteveryday – A useful minimum set of commands for Everyd... by prashnts on Sunday October 30, 2016 @09:15AM (#12829607)
How about tldr-pages? [1]

[1] https://tldr-pages.github.io/

Re:Giteveryday – A useful minimum set of commands for Everyd... by tmsbrg on Sunday October 30, 2016 @11:28AM (#12830302)
That does look a lot better! Bit weird that the main client requires Node.JS though.
Re:Giteveryday – A useful minimum set of commands for Everyd... by prashnts on Monday October 31, 2016 @01:43PM (#12839091)
Yeah, the node-js client isn't fast either. There's a client written in C and available from homebrew: `brew install tldr`.
Re:Giteveryday – A useful minimum set of commands for Everyd... by andrewchambers on Sunday October 30, 2016 @07:28AM (#12829219)
Try a project like freebsd or openbsd for better man pages that are centrally curated.
Re:Giteveryday – A useful minimum set of commands for Everyd... by whack on Sunday October 30, 2016 @12:32PM (#12830662)
I've generally found that most man pages are primarily useful for people who already know the basics of how to use that tool, and need to consult the man page in order to figure out how to understand/accomplish some specific functionality they're looking for.

On the other hand, if you're completely new to the tool, man pages are pretty much useless like you mentioned. I generally just google for "<tool> tutorial" instead.

Re:Giteveryday – A useful minimum set of commands for Everyd... by djhworld on Sunday October 30, 2016 @09:37AM (#12829704)
Thanks for that link to the TLDR project, looks kinda interesting.

The fact that project exists though suggests to me there is a problem with the man page system in general.

Re:Giteveryday – A useful minimum set of commands for Everyd... by paulddraper on Sunday October 30, 2016 @02:37PM (#12831449)
For beginners, sure. Point them to tutorials or heavily abbreviated documentation.

But I want to list all commits in the topological order they are in the graph, or need to understand date format specifiers, man git-log .

I actually think quite highly of git's man pages for anything more than rudimentary first steps.

Re:Giteveryday – A useful minimum set of commands for Everyd... by thms0 on Sunday October 30, 2016 @08:53AM (#12829512)
> One of the more useless pieces of advice Linux beginners are given is to `man [tool]`.

You're such an idiot, my god. Maybe get yourself a brain and you'll understand all manpages :)