
Vim PDF Documentation - chris_wot
http://nathangrigg.net/vimhelp/
======
houshuang
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...](http://nathangrigg.net/2013/09/reproducing-vim-help-as-a-fully-cross-
referenced-pdf/). 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

~~~
kroger
The Emacs manual is available in many formats, including PDF:

[http://www.gnu.org/software/emacs/manual/emacs.html](http://www.gnu.org/software/emacs/manual/emacs.html)

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

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

~~~
nathangrigg
The PDF is full to the brim with hyperlinks. That is the point of this.

~~~
coherentpony
Making vimites use the mouse? That's essentially blasphemy.

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

I fucking like it :)

~~~
keithpeter
2567 A4 pages in my PDF viewer. Quite neat.

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!

~~~
Walkman
> why PDF?

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.

~~~
steveklabnik
PDFs have links, including this one!

> The files are fully cross referenced using interal hyperlinks

------
djtriptych
Awesome. This is something that's been on my idea list for years. Set up a git
tip then SHUT UP AND TAKE MY MONEY.

------
lemcoe9
Not too many pieces of software out there that can say their software is so
well-documented, it almost takes up 3000 pages.

~~~
xradionut
Is help documentation almost 3000 pages or is the source almost 3000 pages? :D

~~~
MetaCosm
Help documentation. I am honestly a little shocked by the length, I knew the
docs were exceptional, but surprised by how long they are.

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

------
chris_wot
One thing I'd love is for the PDF to have a TOC. It would be great to have
when opening on my iPad in iBooks!

~~~
nathangrigg
It has both a "printed" TOC starting at the end of the first page, and a PDF
TOC which should be visible to iBooks.

------
weavie
It is amazing how much I rely on Vim on a daily basis and yet how small a
proportion of it I actually know.

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

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

~~~
plantsbeans
the "c" verb is called "change"

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

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

------
phaer
...but you can't read it in vim, you have to use emacs doc-view-mode for that
;)

------
mrgreenfur
I suggest playing nethack to get comfortable with VIM navigation. Helped me a
lot.

~~~
qu4z-2
I'd just like to point out, though, that in the real world "vim navigation" is
not very hjkl-heavy. (Much more w, b, f, t, search, etc).

Having said that, go play nethack anyway :)

------
jason_slack
Thank you Nathan. This will be nice to have the reference on my ipad while I
am learning.

------
McUsr
This is sure going to be very useful at times! Thank you very much!!! :)

------
dfdashh
Thank you, Nathan! This is going straight onto the e-book reader.

------
lightblade
Now I want a pdf for every man page on my system.

~~~
kroger
You can do that easily with:

    
    
        man -t bash | ps2pdf - > bash.pdf
    

You can even list all man pages with "man -k" to automate the process.

------
augbot
Very cool, added it to my iPad! Thank you!

------
jsogarro
Thanks! Added to my iPad!

------
Aldo_MX
As a Kindle owner, I don't really appreciate PDFs...

~~~
bloodorange
As a regular PDF reader, I don't appreciate devices that can't make it easy to
read an old and common format easily.

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

------
yOutely
This is an ironic project because the Vim docs are one of the worst places to
go for Vim help, partly due to their size and unsearchability.

~~~
johncoltrane

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

~~~
yOutely
Let's look up help on how to write a function

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

~~~
johncoltrane
"writing a function"

    
    
        :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?

------
FridayWithJohn
not the best help book imo

~~~
malkomalko
This is wonderful, thanks!

I also use the vim docset with Dash constantly!

------
eliasmacpherson
Sorry to be that guy, but it should at least point out it's also accessible
with :help within vim.

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

~~~
eliasmacpherson
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!

