Vim PDF Documentation | Hacker News Reader

Vim PDF Documentation

nathangrigg.net

104 pointschris_wot53 comments

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 manual is available in many formats, including PDF:

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

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.

Of course there's an emacs command to do that

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

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.

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

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

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

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!

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

PDFs have links, including this one!

> The files are fully cross referenced using interal hyperlinks

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

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.

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

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

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

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.

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!

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

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

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

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 "c" verb is called "change"

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.

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

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

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

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

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

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

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

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.

If you're on a mac, try this:

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

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

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

Thanks! Added to my iPad!

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

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

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.

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.

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

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.

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

not the best help book imo

This is wonderful, thanks!

I also use the vim docset with Dash constantly!

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

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!

Reply on news.ycombinator.com