diff options
| -rw-r--r-- | posts/search-internet.njk | 101 |
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> |