This includes both the user's manual, the reference manual, and platform specific information in one file. The user's manual is a subset of the reference manual, and that is 500-600 pages long by itself. The reference manual is enormous, but that is the nature of reference manuals. What is even more shocking is how clear the reference material is despite its breadth and technical subject.
It's an excellent example of how to write quality documentation. What Vim's maintainers get, and what is often neglected in products, is that the documentation is part of the product's value and must be as high of a priority as the rest of the product. If you have had the misfortune of working with Cadence's OrCAD (or pretty much any engineering software) the value of excellent documentation being available is very apparent.
Despite OrCAD's potentially 20k+ USD cost the documentation is very scant and greatly harms its barrier to entry for user's; as a result understanding how it works require tutelage from another expert as though writing has not yet been invented and stories are still only being passed down orally.
It's helpful, and also a clever pun: there is not a lot of software that can claim a help document of a approx. 2600 pages. very correlated to the steep learning curve of vim.
Honest question: why PDF? From within Vim one uses :help and the internal hyperlinks. What do people here think the value added of the PDF is? I won't be printing it!
I have read it from the beginning, and the individuals who maintain the documentation likely have as well.
What format supports interpage linking, can be displayed both electronically and is print quality, and can be read on virtually every platform?
The only print quality formats are postscript or PDF and from that only PDFs can be viewed electronically as well being print ready.
So, there does not exist a solution that is not PDF in this case, especially if other attributes are desired such as the readers not requiring a costly license to use.
I am not incredibly happy with that being the case, but there are open source readers and exporters for (most) PDFs nowadays so it is more or less a non-issue.
I didn't even read the entire blog post yet, but he says right at the start that a primary motivation was wanting to be able to read through it while using his iPad.
Makes sense to me. I enjoy and find useful reading technical documentation while not sitting at a computer. Sometimes, it almost seems most productive when I read a few pages, drift off into a 10 minute nap, and then resume. Things then seem to stick better in my long term memory. (Meaning, when I'm in pure "assimilation" mode as opposed to actively working with/on/using the topic, which is also a great aid to remembering.)
The OP knows this already. He stated it in his blog post:
> Vim’s documentation is incredibly complete and very useful. Unfortunately, it makes heavy use of cross references, and the cross references only work with Vim’s internal help viewer. I have no qualms about reading a reference document, but I would strongly prefer to do this kind of reading reclining on a couch with an iPad, rather that Control+F-ing my way through a read-only Vim buffer.
This isn't a useful reply, it's clear the OP knows it - how else would he have compiled them?
It gives the wrong impression to link to 11MB of pdf's with no mention of :help!
This is neat until you realize that by converting it to a PDF, you lose all of the jumping around goodness that Vim offers you to help you navigate this monstrosity.
Same. I use d$ (i.e. d and the movement command $) to delete to the end of the line. Apparently you can just use D. Also, I didn't even know you could do N | to move the the Nth column (e.g. 30| moves to the 30th column).
I don't know if this is the case in vim, but in nvi C works like D except it also puts you in insert mode. Which is exactly what I want to do almost every time I delete to the end of the line.
S is likewise super nice: it clears the line and puts you in insert mode.
The problem it's not the device, but the constrains of the format.
Most PDFs resemble an A4-sized sheet of paper, and downscaling it to fit the screen of a small device usually ends up in usability/readability problems.
I'm totally with you. I couldn't care less about all the marvelous games you can play with each new device people stand in line for. What I'm waiting for is the perfect PDF reader for my thousands of PDF books and articles.
Probably would have been more helpful to link to the blog post explaining the project - http://nathangrigg.net/2013/09/reproducing-vim-help-as-a-ful.... It would be great if the top comments at least had a look at the PDF, and maybe read that blog post - the file is full of hyperlinks (that was the whole point), has a beautiful index viewable in the sidebar of Skim, and he made it because he wanted to read on his iPad, and be able to annotate...
Very cool. Would love something similar for Emacs... Maybe it exists, haven't really looked
The Emacs documentation is excellent and among the handful of products that have documentation that approaches that of Vim's in any meaningful way, but the PDF does not have interpage links like the one in the OP does. That is not as important as it is with Vim's documentation because of how the documentation is written and because the topics are more self-contained, but it is a significant difference.
The documentation within Emacs has such links though and the topics are slightly more discoverable because the documentation can be searched without knowing its prefixes for different sections ahead of time. I have to know that some commands are organized with i_<topic> to find some insert mode documentation for instance with Vim. They are consistent in their semantics though, but that is one gotcha for newcomers and something I did not realize initially. Without that merely doing :h <topic> won't return what the user is actually wanting the documentation for as topics shadow each other in their naming and are made distinct with the naming prefixes.
:h 'option'
:h :command
:h i_ctrl-w
:h ctrl-w
:h v:
:help auto<Tab>
:help <C-d>
:helpgrep foo | cw
<C-]> on an highlighted word to jump to its doc
<C-t> to jump back
The vim documentation is the best place to go for Vim help and it's on your computer.
Its size is a direct consequence of its completeness and its "unsearchability" is a direct consequence of the ignorance and possible unwillingness to learn of those who can't find their way.
:help
(scroll a bit)
(find "usr_41.txt Write a Vim script")
<C-]>
(read)
"learn about |"
:h :|
"split an array in vimscript" (what does that mean? "splitting a string into an array" or… something else?)
:h split() or if that's not what you want,
:h list-functions
:h i_ctrl-w is not intuitive when you start Vim for the first time but:
1. it is easy to understand how it works and apply that to subsequent searches,
2. it is indicated in the first screen of :help.
So yeah, after using that search query once, it is very intuitive. Schizophrenia != intelligence + curiosity.
"Let's say on entering a ruby file we want to press enter"
:h autocmd
(reading)
autocmd BufEnter *.rb <CR>
(doesn't work)
(thinking)
(oh! <CR> should be a normal mode command of course!)
autocmd BufEnter *.rb normal <CR>
(doesn't work)
(oh! I remember, :normal only accepts ^M!)
autocmd BufEnter *.rb normal ^M
"change the background color"
(look at how it's done in a random colorscheme)
:hi Normal guibg=#0066ff
"how to set guicursor"
:h guicursor
What do you want to do with your guicursor if not setting its color and/or shape and/or blinking behavior? Everything is right there.
Vim has a large documentation that you learn to use little by little, query after query but all your examples assume no prior experience with Vim's :help
Impatience leads nowhere.
---
By the way I never downvote anything: I upvote to express my agreement and I answer to express my disagreement. That, and I don't have downward triangles anyway, a consequence of my presumably low "karma", maybe?
I have read the introducing blog post. I also appreciate the effort the author put into this, which will be useful for others. However, I think using an SSH client on a tablet to connect to a machine with Vim and reading `:help` from there would have been a better practice of Vim.
I love this, I just wish there was a way to have the font in something more readable for the areas that aren't positional format sensitive. For some reason, I can read monospaced fonts for code perfectly, but when it comes to text, I have difficulty reading it.
53 comments
[ 4.6 ms ] story [ 189 ms ] threadI also use the vim docset with Dash constantly!
It's an excellent example of how to write quality documentation. What Vim's maintainers get, and what is often neglected in products, is that the documentation is part of the product's value and must be as high of a priority as the rest of the product. If you have had the misfortune of working with Cadence's OrCAD (or pretty much any engineering software) the value of excellent documentation being available is very apparent.
Despite OrCAD's potentially 20k+ USD cost the documentation is very scant and greatly harms its barrier to entry for user's; as a result understanding how it works require tutelage from another expert as though writing has not yet been invented and stories are still only being passed down orally.
I fucking like it :)
Honest question: why PDF? From within Vim one uses :help and the internal hyperlinks. What do people here think the value added of the PDF is? I won't be printing it!
I wanted to ask the exact question. Nobody sits down and read it from the beginning, and without links, there is no point of a PDF.
> The files are fully cross referenced using interal hyperlinks
What format supports interpage linking, can be displayed both electronically and is print quality, and can be read on virtually every platform?
The only print quality formats are postscript or PDF and from that only PDFs can be viewed electronically as well being print ready.
So, there does not exist a solution that is not PDF in this case, especially if other attributes are desired such as the readers not requiring a costly license to use.
I am not incredibly happy with that being the case, but there are open source readers and exporters for (most) PDFs nowadays so it is more or less a non-issue.
Makes sense to me. I enjoy and find useful reading technical documentation while not sitting at a computer. Sometimes, it almost seems most productive when I read a few pages, drift off into a 10 minute nap, and then resume. Things then seem to stick better in my long term memory. (Meaning, when I'm in pure "assimilation" mode as opposed to actively working with/on/using the topic, which is also a great aid to remembering.)
> Vim’s documentation is incredibly complete and very useful. Unfortunately, it makes heavy use of cross references, and the cross references only work with Vim’s internal help viewer. I have no qualms about reading a reference document, but I would strongly prefer to do this kind of reading reclining on a couch with an iPad, rather that Control+F-ing my way through a read-only Vim buffer.
S is likewise super nice: it clears the line and puts you in insert mode.
Most PDFs resemble an A4-sized sheet of paper, and downscaling it to fit the screen of a small device usually ends up in usability/readability problems.
Very cool. Would love something similar for Emacs... Maybe it exists, haven't really looked
http://www.gnu.org/software/emacs/manual/emacs.html
The documentation within Emacs has such links though and the topics are slightly more discoverable because the documentation can be searched without knowing its prefixes for different sections ahead of time. I have to know that some commands are organized with i_<topic> to find some insert mode documentation for instance with Vim. They are consistent in their semantics though, but that is one gotcha for newcomers and something I did not realize initially. Without that merely doing :h <topic> won't return what the user is actually wanting the documentation for as topics shadow each other in their naming and are made distinct with the naming prefixes.
Having said that, go play nethack anyway :)
Its size is a direct consequence of its completeness and its "unsearchability" is a direct consequence of the ignorance and possible unwillingness to learn of those who can't find their way.
:h function
Ok, that's wrong.
Let's look up vimscript then, that probably has function information
:h vimscript
Nope, that's not what we want. But obviously function is further down the list
/function
Oh dear.
Let's say we want to do something on opening a python file, and we see someone else using Bufenter
:h bufenter
Ok, no usage examples. What to do?
Eventually we find out about autocmd, by luck. What if we want to include multiple statements in an autocmd?
:h autocmd
Nothing
/multiple
Nothing
Let's say (when you get lucky, again) and find out about :cmd1 | cmd2, you want to learn about |
:h |
nope
:h pipe
not even close!
Ooooooooooh maybe we have to escape it?
:h \|
what?
ooooh wait, we're in command mode, DUH
:h :pipe
aw, shit.
Maybe we want to split an array in vimscript.
:h split
Nope.
:h arary
Nothing. Maybe it's a list?
:h list
Nope. No splitting today, I guess.
If you think :h i_ctrl-w is intuitive, then, well. Have you ever been treated for schizophrenia or psychosis?
Let's say on entering a ruby file we want to press enter.
:au bufenter *.rb <cr>
open rb file..
trailing characters: <cr>
Oh god what the shit?
:h bufenter
nothing
:h ... it's now impossible to look up help on this problem. It's also impossible to google for it
We want to change the background color
:h background
Uhhhhh
:h color
Ok, I get it, I'm not going to find help on this. Time to give up.
I want to figure out how to set guicursor
:h guicursor
Are you 98% serious right now? Why are the examples using :highlight Cursor? Jesus.
Vim has horrible help. I will wait patiently for you to upvote my answer as opposed to downvote it, and I'll consider us even.
1. it is easy to understand how it works and apply that to subsequent searches,
2. it is indicated in the first screen of :help.
So yeah, after using that search query once, it is very intuitive. Schizophrenia != intelligence + curiosity.
"Let's say on entering a ruby file we want to press enter"
"change the background color" "how to set guicursor" What do you want to do with your guicursor if not setting its color and/or shape and/or blinking behavior? Everything is right there.Vim has a large documentation that you learn to use little by little, query after query but all your examples assume no prior experience with Vim's :help
Impatience leads nowhere.
---
By the way I never downvote anything: I upvote to express my agreement and I answer to express my disagreement. That, and I don't have downward triangles anyway, a consequence of my presumably low "karma", maybe?
man -t <whatever> | open -f -a Preview