+++
date = "2020-07-30T16:11:25+00:00"
publishdate = "2023-12-29T07:08:55+00:00"
title = "Programming Sans Internet"
slug = "programming-sans-internet"
author = "Thedro"
tags = ["general"]
type = "posts"
summary =  "Software development is tightly coupled to the internet. Some programs refuse to run or fail catastrophically without an internet connection."
draft =  ""
syntax =  "1"
toc =  ""
updated =  "2022-03-10"
+++

{{< image source="/images/programming-sans-internet.png" title="The Internet is down" >}}
The Internet is down {{< /image >}}

Software development is tightly coupled to the Internet. Some programs refuse to
run or fail catastrophically without an Internet connection. For most people a
computer becomes a useless pile of metal without the Internet. My circumstances
have required the dreaded skill of programming without the Internet. The
{{< sidenote mark="power" set="left" >}} This post was completed just before the
power company tripped over itself. {{< /sidenote >}} and
{{< sidenote mark="Internet" set="right" >}} Here's to hoping that the
[Starlink](https://en.wikipedia.org/wiki/Starlink) project becomes successful
and affordable. {{< /sidenote >}} infrastructure in my country royally sucks.

Keeping in a state of "flow" when the Internet goes down is difficult. Let's
take a look at my basic approach to remedying the difficulty of programming
without an Internet connection.

## Offline The Documentation

Many kind people exist in this world. Some of them write manuals that no one
reads. Linux based distributions have first class support for `POSIX` style
programming. One could run `man` to bring up any function or program instruction
in the `POSIX` programmer's manual. If we wanted to know how to use `mmap` we
could run `man mmap`.

{{< image source="/images/mmap-manpage.png" title="Manpage for mmap" >}} Manpage
for mmap {{< /image >}}

Manpages are so old school now that it's somewhat rare to see anyone using `man`
let alone {{< sidenote mark="making" set="left" >}} Create manpages with the
[troff](https://linux.die.net/man/1/troff) and
[groff](https://linux.die.net/man/1/groff) typsetting family of programs.
{{< /sidenote >}} localized manuals.

> "Knowledge is of two kinds. We know a subject ourselves, or we know where we
> can find information upon it. When we enquire into any subject, the first
> thing we have to do is to know what books have treated of it. This leads us to
> look at catalogues, and at the backs of books in libraries."
{{< footer >}}Samuel Johnson, The Life of Samuel Johnson{{< /footer >}}

Manpages are faster than a search engine lookup if you know what you are looking
for. Search engine lookups can be expensive
{{< sidenote mark="context" set="right" >}} Multitasking. Every context switch
has a mental cost. {{< /sidenote >}} switching actions, but you often get what
you're looking for quickly. Good manuals contain a synopsis of a program or
function, an example of its usage pattern, return value references, and most
important of them all --- error handling instructions.

Ensure that you have manpages for all tools and target languages that you work
with if available. Check your local distribution repositories to see if there
are any extra manuals available. Run `man -k .` to see
{{< sidenote mark="all" set="left" >}} On [NixOS](https://nixos.org/) `20.03`
`man` is [broken](https://github.com/NixOS/nixpkgs/pull/86489). You'll need to
wire up `mandb` or wait until release `20.09`. {{< /sidenote >}} manuals on the
system. Display manuals containing a keyword with `man -k <keyword>`.
{{< sideimage mark="Convert" set="right" source="/images/mmap-pdf-manpage.png" >}}
`PDF` version of mmap's manpage {{< /sideimage >}} manuals to `PDF` format by
using `man -Tpdf <keyword>`. Pipe the output into the `PDF` reader of choice.

```shell
man -Tpdf mmap | zathura -
```

[Zeal](https://zealdocs.org/) offers an _offline_ graphical documentation
browser for many popular programming [`APIs`](https://en.wikipedia.org/wiki/API)
(Application Programming Interfaces). Install `zeal` and download the
documentation sets that are relevant to your programming environment.

{{< image source="/images/programming-sans-internet-zeal.png" title="Zeal documentation browser interface" >}}
Zeal browser showing JavaScript's `Math.floor()` function documentation.
{{< /image >}}

## Offline The Wiki

The [Arch Wiki](https://wiki.archlinux.org/) is a well known and respected
documentation source. If you find a wiki that you visit more than once ---
[offline](https://www.archlinux.org/packages/community/any/arch-wiki-docs/) it.
Relegate any downloaded wiki to a directory where you can `grep` (global regular
expression print) or search through the files.

This applies doubly so for any [GitHub](https://github.com/) wiki. Extract
markdown copies of a repository's wiki by using the `git clone` command.

```shell
git clone https://github.com/koalaman/shellcheck.wiki.git
```

GitHub's pull requests and issues contain critical information. Grab all pull
requests and issues from any working
{{< sidenote mark="repository" set="left" >}} There should be an offline copy of
any repository you work with. {{< /sidenote >}} using the Github `API`
(Application Programming Interface).

```text
https://api.github.com/repos/<repo-owner>/<repo-name>/issues?state=all
https://api.github.com/repos/<repo-owner>/<repo-name>/pulls?state=all
```

## Offline The REPLs

`REPL` stands for read, evaluate, print, and loop. It's a command line shell for
your language. Get comfortable using a `REPL` just like any other familiar shell
to reduce Internet lookups and context switching. Most of us use our heads as
rudimentary `REPLs` --- basically, we write a piece of code with a general
imagination of its action and return state.

Eventually there's a point where you're doing that weird `JavaScript` style
crash and burn programming. The target code is now large enough that it can't
fit inside your head, so you'll edit what you approximate is wrong, and run it
again to see if it doesn't crash and burn. Repeat ad nauseam.

Unpacking a tricky error state is often much quicker in a `REPL` than with an
Internet search or using a crude crash and burn method. This saves time and
having to context switch to a search lookup for some common or obscure error
message. Make sure to have all `REPLs` offline for any language or tool you use
if available.

{{< image source="/images/iex-repl.gif" title="Elixir's REPL" >}} Messing around
with Elixir's REPL iex in Vim {{< /image >}}

## Offline The Static Code Analysis

Static code analysis offers refactoring advice, sniffing out high level coding
errors, and correcting naive approaches to simple problems. Static code analysis
tools can hold your hand and carry you a good distance. In fact, there are some
static analysis tools that are so {{< sidenote mark="good," set="right" >}}
Haskell's `ghc` and `hlint` as well as Unix Shell's `shellcheck`.
{{< /sidenote >}} that if you have good cursory knowledge of a language, you can
learn the ins and outs quicker than reading a book.

The authors of static code analysis tools know more than you --- it's as simple
as that. Static analysis coalesces a collection of common questions, answers,
and pitfalls that experienced people have encountered time and time again. Even
{{< sidenote mark="configuration" set="left" >}} How many of us are familiar
with vulnerabilities such as `HTTP` request and response splitting?
{{< /sidenote >}} based programs like
[Nginx](https://nginx.org/en/docs/contributing_changes.html) have their own
static analysis tools like [gixy.](https://github.com/yandex/gixy) Ensure you
have all static analysis tools for any language or program that you work with
offline.

## Offline The Editor

Most programmers use integrated development environments (`IDE`) nowadays which
handles most of the above (with or without Internet probably), but in a
situation without an Internet connection --- having a flexible editor is
paramount.

This means an editor like `vim` or `emacs`. In the wastelands, you don't have
the luxury of downloading a plugin or extra feature to assist you. Flexible
editors have configuration that is dynamic enough to code your own plugins
trivially on the fly.

Emacs uses Emacs Lisp, and Vim uses Vimscript. Vim itself has one of the most
thorough manuals in existence, so implementing an ad hoc plugin for an odd
workflow is not too difficult as long as you know how to read.

## Offline NixOS Documentation

{{< sidenote mark="The" set="left" >}} Bonus section for NixOS users.
{{< /sidenote >}} [NixOS](https://nixos.org/) offline documentation is
impeccable. You can run the command line tool `man` on `configuration.nix`,
`nix.conf`, `nixos-rebuild` and more. The
{{< sidenote mark="problem" set="right" >}} Documentation lookups have yet to be
[implemented](https://github.com/NixOS/nix/pull/1652). {{< /sidenote >}} is the
`nix REPL`. The `nix REPL` doesn't have the ability to lookup `function`
documentation strings. A function's documentation requires a search of the
source code, and that's not fun. The plugin
[nix-doc](https://github.com/lf-/nix-doc) adds this feature to the `nix REPL`.
Let's wire it up while we wait on
[upstream.](https://github.com/NixOS/nixpkgs/pull/95161) Create a basic
`default.nix` for `nix-doc` using `rustPlatform`.

```nix
{ lib, rustPlatform, fetchgit, pkgs }:

rustPlatform.buildRustPackage rec {
  pname = "nix-doc";
  version = "v0.3.1";

  src = fetchgit {
    rev = version;
    url = "https://github.com/lf-/nix-doc.git";
    sha256 = "1hiz0fsbsl74m585llg2n359gs8i2m6jh8zdikkwxd8xq7qmw032";
  };

  buildInputs = with pkgs; [ boost nix ];

  nativeBuildInputs = with pkgs; [ pkg-config ];

  cargoSha256 = "1d1gvx14yai4dyz44pp2ffx2swfxnm0fwvldy96dw9gqmar69cpv";

  meta = with lib; {
    homepage = url;
    license = licenses.lgpl3;
    description = "A Nix documentation lookup tool that quickly dumps the docs of the library function";
  };
}
```

Install the program using `environment.systemPackages` and its plugin using
`nix.extraOptions` where `./nix-doc/default.nix` is the path to the derivation.

```nix
{ pkgs, ... }:

{
  nix.extraOptions = ''
    plugin-files = ${pkgs.callPackage ./nix-doc/default.nix {}}/lib/libnix_doc_plugin.so
  '';

  environment.systemPackages = with pkgs; [
    (callPackage ./nix-doc/default.nix {})
  ];
}
```

The `nix REPL` now has access to the documentation lookup function
`builtins.doc` and the command line utility `nix-doc`.