Add essay on offline doc exploration

1 files changed, 101 insertions, 0 deletions

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