Programming Sans Internet

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 power This post was completed just before the power company tripped over itself. and Internet 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.

Manpages are so old school now that it’s somewhat rare to see anyone using man let alone making 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 context Multitasking. Every context switch has a mental cost. 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 all On NixOS 20.03 man is broken. You’ll need to wire up mandb or wait until release 20.09. manuals on the system. Display manuals containing a keyword with man -k <keyword>. Convert 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 -

Zeal offers an offline graphical documentation browser for many popular programming APIs (Application Programming Interfaces). Install zeal and download the documentation sets that are relevant to your programming environment.

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 (global regular expression print) or search through the files.

This applies doubly so 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 repository 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 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.

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 good, Haskell’s ghc and hlint as well as Unix 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 configuration 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

The Bonus section for NixOS users. NixOS offline documentation is impeccable. You can run the command line tool man on configuration.nix, nix.conf, nixos-rebuild and more. The problem 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.

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

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