intro⌗

go doc is one of the best tools that exist in a programming language. Take a look at the following examples:

$ go doc os OpenFile
package os // import "os"

func OpenFile(name string, flag int, perm FileMode) (*File, error)
    OpenFile is the generalized open call; most users will use Open or Create
    instead. It opens the named file with specified flag (O_RDONLY etc.).
    If the file does not exist, and the O_CREATE flag is passed, it is created
    with mode perm (before umask). If successful, methods on the returned File
    can be used for I/O. If there is an error, it will be of type *PathError.

$ # viewing documentation for a third-party package
$ go doc aqwari.net/net/styx
package styx // import "aqwari.net/net/styx"

Package styx serves network filesystems using the 9P2000 protocol.

The styx package provides types and routines for implementing 9P servers.
The files served may reflect real files on the host operating system, or an
in-memory filesystem, or bi-directional RPC endpoints. Regardless, the protocol
operations used to access these files are the same.

....

go doc simply translates Go code into viewable documentation in your terminal. It is very useful when writing code because it gives you types, descriptions of functions, data structures, et cetera.

Luckily, Common Lisp has a similar system. Instead of going the Javascript path and not including documentation with the language, Common Lisp has documentation both in the language and outside of the language.

DESCRIBE⌗

DESCRIBE is a god send. This function basically describes any function, variable, constant, class, class-field and heck even types too. Check this out:

<CL-USER> (defun my-function (a)
  "Add 1 to the parameter"
  (1+ a))
;;
<CL-USER> (describe #'my-function)
#<FUNCTION MY-FUNCTION>
  [compiled function]


Lambda-list: (A)
Derived type: (FUNCTION (T) (VALUES NUMBER &OPTIONAL))
Documentation:
  Add 1 to the parameter
Source form:
  (LAMBDA (A) "Add 1 to the parameter" (BLOCK MY-FUNCTION (1+ A)))

We can see the type of a function, its documentation string and its source form. How cool is that? You can literally view the source code of a function using another function.

This also applies to builtin functions such as length, elt, car or any other function.

<CL-USER> (describe '+)
COMMON-LISP:+
  [symbol]

+ names a special variable:
  Declared type: T
  Declared always-bound.
  Value: +
  Documentation:
    the value of the most recent top level READ

+ names a compiled function:
  Lambda-list: (&REST NUMBERS)
  Declared type: (FUNCTION (&REST NUMBER) (VALUES NUMBER &OPTIONAL))
  Derived type: (FUNCTION (&REST T) (VALUES NUMBER &OPTIONAL))
  Documentation:
    Return the sum of its arguments. With no args, returns 0.
  Known attributes: foldable, flushable, unsafely-flushable, movable, commutative
  Source file: SYS:SRC;CODE;NUMBERS.LISP

Here, + is a function as well as a special variable. Since Common Lisp differentiates between functions and variables, one symbols can have a function and variable definition.

We can tell that + retains the value of the most recent top level READ. If you Google + in Common Lisp, you could stumble across this definition..

Reading from the variable section, we can see that there are similar variables to + like ++ and +++. Furthermore, there is an See Also function which denotes similar variables.

Cool, right? It is like the Common Lisp bible. The name of these collection of pages is the Common Lisp Hyperspec.

the hyperspec⌗

If you were stranded to an island and wanted to program in Common Lisp, all you need is the hyperspec.

It is seriously that well documented and powerful. One doesn’t even need a runtime because back in those days, somebody had the idea to use a static site generator to generate the documentation.

What this means is that you could have the hyperspec on your local machine. What’s cooler is that this doesn’t need an internet connection and is as simple as pie to install.

installing the hyperspec⌗

  1. Download the hyperspec tarball
  2. Extract it to your favorite directory
  3. Create a script to open a browser window.
  4. Profit.

Seriously, that is all. Everything in the hyperspec tarball is prepacked and all you need is to point a web browser to it. I used netsurf-gtk3 but you could use Firefox, Chromium or some other web browser.

Here’s my script for reference:

#!/bin/sh
DIRECTORY="/tmp/cl-doc"
netsurf-gtk3 file://$DIRECTORY/Front/index.htm

going further: Common Lisp Cookbook.⌗

The Common Lisp Cookbook is known to be a certified hood classic. It is such a good resource of doing X in Common Lisp. Concurrency, HTTP, Graphics, GUI, Audio, you name it, Common Lisp Cookbook has it.

It is available in PDF and ePub formats which make it 24/7 available for offline usage as well as searchable without an Internet Connection.

I cannot tell you how many times I came to the Cookbook and only to find my knowledge expanded and my understanding deepened. Seriously, try out the cookbook.