Vim PDF Documentation

http://nathangrigg.net/vimhelp/

by chris_wot • 13 years ago

104 53 13 years ago

nathangrigg.net

chris_wot• 13 years ago

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!

nathangrigg2• 13 years ago

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

mineo• 13 years ago

All 3 PDF files have a TOC - at least Evince is able to show me one in its sidebar.

FridayWithJohn• 13 years ago

not the best help book imo

malkomalko• 13 years ago

This is wonderful, thanks!

I also use the vim docset with Dash constantly!

lemcoe9• 13 years ago

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

xradionut• 13 years ago

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

MetaCosm• 13 years ago

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

dfdashh• 13 years ago

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

DrinkWater• 13 years ago

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

keithpeter2• 13 years ago

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• 13 years ago

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.

jsogarro• 13 years ago

Thanks! Added to my iPad!

phaer• 13 years ago

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

eliasmacpherson2• 13 years ago

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

jh3• 13 years ago

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.

eliasmacpherson2• 13 years ago

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!

agscala• 13 years ago

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.

nathangrigg2• 13 years ago

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

coherentpony• 13 years ago

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

djtriptych• 13 years ago

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.

weavie• 13 years ago

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• 13 years ago

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• 13 years ago

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.

Aldo_MX2• 13 years ago

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

bloodorange• 13 years ago

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_MX2• 13 years ago

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.

SiVal• 13 years ago

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.

houshuang• 13 years ago

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

pelario• 13 years ago

Of course there's an emacs command to do that

bo1024• 13 years ago

Oh, yeah. Good old C-m M-x M-generate-hyperlinked-documentation.

kroger2• 13 years ago

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

http://www.gnu.org/software/emacs/manual/emacs.html

mheathr3• 13 years ago

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.

mrgreenfur• 13 years ago

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

qu4z-2• 13 years ago

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• 13 years ago

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

yOutely2• 13 years ago

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.

johncoltrane2• 13 years ago

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

yOutely2• 13 years ago

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.

phunehehe0• 13 years ago

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.

lightblade• 13 years ago

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

kroger2• 13 years ago

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.

keithpeter2• 13 years ago

Pandoc? Some kind of bash script? Go for it, the result would be amazing.

MrScruff• 13 years ago

If you're on a mac, try this:

man -t <whatever> | open -f -a Preview

augbot• 13 years ago

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

darkchasma• 13 years ago

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.

McUsr• 13 years ago

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

Vim PDF Documentation

Related Stories