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.
> 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>.
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.
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.
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).
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?
>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.
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.)
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.
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.
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.
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.
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.
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:
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.
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.
I love that they try to make it assessible. But I disagree with that it would be an acceptable goal in git just to understand a subset of it. You need to understand nearly everything, even the internals. Only then it can really become useful to you.
The mistake the community made is putting git on the throne of version control. It's not. It's a tool for experts that can do a lot for you if you know how to use it. But to achieve that it pays the price of not really being assessible.
Now that it's in its position, the best thing you can do is to learn it. There is the git book. Read it. Annoying, I know. But that's the gameplan. Not doing it is just dragging out the inevitable.
I think the same could be said about C. It should not be put on the throne of "programming language" - you need to actually read and understand what it does internally. (pointers etc) - it's not enough to learn some incantations.
So then let me ask: is there a room for x, where git:x::C:python (git is to x, as C is to Python).
People everywhere deserve to have x. Not just right-clicking a file in Dropbox or OS X for previous versions, but a full commandline and detailed history including commit messages, and many other aspects of git.
In a way this is completely orthogonal to your comment, just as Python is to C.
EDIT: I've thought more about it and I no longer agree. The "language" presented here is a subset of C/C++ - not everything is mentioned or taught: https://www.arduino.cc/en/Reference/HomePage
It is in fact exactly this type of simplified subset. Not even malloc and free are mentioned... So while what you wrote is true for this audience (HN) there is room to learn less or a subset.
Mercurial. I'm not being flippant; the UX is light years ahead in terms of accessibility to newcomers to dvcs. With a ui like tortoisehg, even five years ago, someone without any prior experience in any vcs at all could become productive after a fifteen minute primer. Git does not compare.
It also makes sense, I think, considering that Git consists of small tools interacting with each other, while Hg is written as a whole application/system by itself, which can then be extended as needed.
Yes, I believe as well there should be an assessible solution and that should be the standard. However in this case there is none, since weirdly enough git is sitting on the throne. You can try to establish other tools like mercurial in some projects, but you may end up getting harsh resistance by exactly the people you try to serve with that option.
> "But I disagree with that it would be an acceptable goal in git just to understand a subset of it. You need to understand nearly everything, even the internals. Only then it can really become useful to you."
Sorry, but this is patently false. I've been using git very effectively for years, both as a participant and as a repo admin, have had other Senior Developers call me a "git hacker" and ask me for git help, and I have no idea how the internals of git work. I also use a very small subset of git functionality, and many of the commands in the OP look like greek to me.
I don't doubt that your approach is one way to learn/use git. But learning git as a black box, and using just the parts you need, is perfectly useful as well.
Potentially dumb question here, but couldn't 'dragging out the inevitable' be another way of phrasing 'the learning process'? It seems that immediately making a tool usable would be preferable to keeping it as a purely theoretical device until it's fully learned.
If you are this kind of person who is interested to learn, but has no problem with using stuff despite it being a little rough in the beginning, then yes you are more than welcome. In fact I would say that is how people learn. You cannot just read a book. You also need to use it.
But that is not how most beginners approach tools. For most people a tool should serve a purpose and do that immediately from the get go. And for them git is really painful in the beginning. And if they don't put in the learning effort it will still be that annoying a few years down the road.
That's what I meant. Thanks for letting us clarify that together.
Both merge and rebase, but no cherry-pick. Goodbye then, I guess.
I've seen a dozen of those tools wishing to "simplify" git and they all fail my workflow, which is pretty common I guess, team git with central server and source control.
I don't care about any commits that are not under code review. If I have fifty duplicate commits on different branches in my local, that's okay with me.
Fast-forward doesn't work usually, and rebase is confusing compared to cherry-pick.
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