--- layout: post.njk title: Exploring the Offline Doc Landscape tags: post date: 2024-03-27 ---
Lately, I have been trying to cut down my dependency of using the internet for programming. I do this in part because:
From my research, there are a few options out there for offline documentation. For Linux and CLI, there are the classics:
IMO info is superior to man, as info supports both info and man docs but info has other features such as linking.
In the terminal, you can lookup documentation of commands and systems
using man X
. You can also search for multiple docs using
man -K X
.
There is also apropos
, that allows you to search man
pages. I find it to be quite confusing though, man apropos
states that it searches through all docs with regex by default. However,
I use sway Wm on my computer, but apropos sway
yields
nothing, man sway
works fine, why is that?
Particularly useful is info -a X
which searches all info
pages for X.
To get started, you can type info info
.
Info and man-pages are where you should turn to be able to find documentation on (good) CLI tools and GNU tools. GNU projects tend to provide excellent manuals that you can search through for AWK, Guix and Emacs.
Finally, I also can recommend the tool tldr pages. I particularly find them useful for VCS, usually it works great with commands like tar and git.
Now what if I am searching for programming specific documentation? Typically this will not be found in the info or man pages (unfortunately :(). Each language tends to have their own conventions, some better than others.
There are a few offline documentation tools out there that I know of:
For devdocs there is also this nice Emacs package:
These tools have a decent collection of docs with varying up-to-date-documentation, depending on the language. I personally use Devdocs, and found it strong for HTML + CSS + Typescript and weak for languages like OCaml and Terraform.
Google is great in that, when you search for docs, you get everything. Navigating documentation offline is doable but slightly frustrating. Documentation is so scattered across different sources and it is hard to know how and where to look for them. However, I think with some improvements, searching offline docs could be faster than googling.
There is an issue in fragmentation of formatting. For Terraform and AWS, the only up-to-date docs I could find were PDF and HTML docs. Searching through PDFs to find a specific method or part doesn’t allow you to search through multiple files with decent search.
Searching with man has not worked particularly great
for me either. The man -K
command is slow as hell on my computer,
and you have to go through each entry one-by-one rather than it just
showing grep results with a small previews and letting you pick the docs you want to see.
There is also an issue with man and info pages that examples tend to
be sparse. A single example of how to use apropos
would
have made it obvious for me how I am supposed to use it, yet the manual
contains no such thing.
Within Emacs, I also find there are so many commands available for finding documentation about a single function. There is opening the Emacs manual, there is describe-function, there are the info pages etc. I think this could all be consolidated.
It is unfortunate that there is not a single repository that you can
just run grep keyword
and search through all documentation
sources, info pages, man pages, devdocs and more. It would save so much
energy, and actually speed up development work compared to Google.
But hey, I have probably missed a lot in my exploration. I would love to know what workflow people have for searching through documentation offline, feel free to send me an email with tips.