1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
|
---
layout: post.njk
title: Exploring the Offline Doc Landscape
tags: post
date: 2024-03-27
---
<p>Lately, I have been trying to cut down my dependency of using the
internet for programming. I do this in part because:</p>
<ul>
<li>A single google search is surprisingly energy intensive</li>
<li>I find that it forces you to really think and learn. With answers
from Stackoverflow not at your fingertips, you really need to understand
how things function.</li>
<li>I believe you should be able to just sit somewhere remote without
internet and still be able to code. There are plenty of places that still
have poor internet connection.</li>
<li>It is a fun intellectual challenge</li>
</ul>
<h2 id="state-of-the-offline-ecosystem---linux">Offline Documentation - Linux</h2>
<p>From my research, there are a few options out there for offline
documentation. For Linux and CLI, there are the classics:</p>
<ul>
<li>Info pages</li>
<li>Man pages</li>
</ul>
<p>IMO info is superior to man, as info supports both info and man docs
but info has other features such as linking.</p>
<h3 id="searching-man-pages">Searching man pages</h3>
<p>In the terminal, you can lookup documentation of commands and systems
using <code>man X</code>. You can also search for multiple docs using
<code>man -K X</code>.</p>
<p>There is also <code>apropos</code>, that allows you to search man
pages. I find it to be quite confusing though, <code>man apropos</code>
states that it searches through all docs with regex by default. However,
I use sway Wm on my computer, but <code>apropos sway</code> yields
nothing, <code>man sway</code> works fine, why is that?</p>
<h3 id="searching-info-pages">Searching info pages</h3>
<p>Particularly useful is <code>info -a X</code> which searches all info
pages for X.</p>
<p>To get started, you can type <code>info info</code>.</p>
<h3 id="how-do-i-know-which-one-to-use">How do I know which one to
use?</h3>
<p>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.</p>
<p>Finally, I also can recommend the tool <a
href="https://tldr.sh/">tldr pages</a>. I particularly find them useful
for VCS, usually it works great with commands like tar and git.</p>
<h2 id="offline-docs---programming">Offline Docs - Programming</h2>
<p>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.</p>
<p>There are a few offline documentation tools out there that I know
of:</p>
<ul>
<li>Zeal, a multi-platform GUI interface</li>
<li>Devdocs, a website with offline support</li>
<li>Dash (Mac only)</li>
</ul>
<p>For devdocs there is also this nice Emacs package:</p>
<ul>
<li><a href="https://github.com/astoff/devdocs.el">devdocs.el</a> -
Emacs viewer for devdocs</li>
</ul>
<p>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.</p>
<h2 id="the-ecosystem-for-offline-docs-could-be-improved">The ecosystem
for offline docs could be improved</h2>
<p>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.</p>
<p>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.</p>
<p>Searching with man has not worked particularly great
for me either. The <code>man -K</code> 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.</p>
<p>There is also an issue with man and info pages that examples tend to
be sparse. A single example of how to use <code>apropos</code> would
have made it obvious for me how I am supposed to use it, yet the manual
contains no such thing.</p>
<p>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.</p>
<p>It is unfortunate that there is not a single repository that you can
just run <code>grep keyword</code> 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.</p>
<p>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.</p>
|