Programming Sans Internet

The Internet is down
The internet is down

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 This post was completed just before the power company tripped over itself. and Here's to hoping that the Starlink project becomes successful and affordable. 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.

Manpage for mmap
Manpage for mmap

Manpages are so old school now that it’s somewhat rare to see anyone using man let alone Create manpages with the troff and groff typsetting family of programs. 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.” Samuel Johnson, The Life of Samuel Johnson

Manpages are faster than a search engine lookup if you know what you are looking for. Search engine lookups can be expensive Multitasking. Every context switch has a mental cost. switching actions, but you often get what you’re looking for.

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 you have manpages for all tools and target languages that you work with if available. Check your local distribution’s repository to see if there are any extra manuals available.

Run man -k . to see On NixOS man is broken. You'll need to wire up mandb or wait until release 20.09. current manuals on the system. Display all manuals containing a keyword with man -k <keyword>.

PDF version of mmap's manpage PDF version of mmap's manpage manuals to PDF format by using man -Tpdf <keyword>. Pipe the output into the PDF reader of choice.

man -Tpdf mmap | zathura -

Offline The Wiki

The Arch Wiki is a well known and respected documentation source. If you find a wiki that you visit more than once — offline it. Relegate any downloaded wiki to a directory where you can grep through the files.

This applies doubly for any GitHub wiki. Extract markdown copies of a repository’s wiki by using the git clone command.

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 There should be an offline copy of any repository you work with. using the Github API (Application Programming Interface).

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 the general expectation of its action and return state.

You’ll reach 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.

Elixir's REPL
Messing around with Elixir's REPL iex in Vim

Offline The Static Code Analysis

Static code analysis offers refactoring advice, sniffing out high level coding errors, and correcting naive approaches to a problem. 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 Haskell's ghc and hlint as well as Shell's shellcheck. 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 How many of us are familiar with vulnerabilities such as HTTP request and response splitting? based programs like Nginx have their own static analysis tools like 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

Bonus section for NixOS users. NixOS offline documentation is impeccable. You can run the command line tool man on configuration.nix, nix.conf, nix-rebuild and more. The Documentation lookups have yet to be implemented. 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 adds this feature to the nix REPL. Let’s wire it up while we wait on upstream. Create a basic default.nix for nix-doc using rustPlatform.

{ stdenv, 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 stdenv.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.

{ 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 a documentation lookup function builtins.doc and the command line utility nix-doc.

Updated 10 August 2020