From ee5c3bde054d6631df45d90dace0d5269d3c3bf3 Mon Sep 17 00:00:00 2001 From: Marc Coquand Date: Wed, 27 Mar 2024 10:57:44 -0600 Subject: Add essay on offline doc exploration --- posts/search-internet.njk | 101 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 101 insertions(+) create mode 100644 posts/search-internet.njk diff --git a/posts/search-internet.njk b/posts/search-internet.njk new file mode 100644 index 0000000..d9df239 --- /dev/null +++ b/posts/search-internet.njk @@ -0,0 +1,101 @@ +--- +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:

+ +

Offline Documentation - Linux

+

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.

+

Searching man pages

+

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?

+

Searching info pages

+

Particularly useful is info -a X which searches all info +pages for X.

+

To get started, you can type info info.

+

How do I know which one to +use?

+

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.

+

Offline Docs - Programming

+

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.

+

The ecosystem +for offline docs could be improved

+

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.

-- cgit v1.2.3