DocSpec

• Creating the file

DocSpec provides a standard, predictable interface to access the four different types of documentation.

DocSpec is

1. a configuration file in your project root, specifying how to reach sections of your documentation, and associating symbols with them if desired
2. a Common Lisp library to query the file
3. a command line client built on the library
4. an Emacs package, providing a completing-read interface

It is hoped that providing such a tool will not only make life easier for users of (DocSpec-using) projects, but also make more projects aware of the Diataxis Framework, helping them make their documentation easier to read and maintain.

Creating the file

Below is what an example DocSpec file for the McCLIM project might look like.

Each documentation type has topics it covers - in this example, each topic is a symbol, but they could also be strings.

The documentation for each topic can be presented in one or more formats - a string, a PDF file, an HTML file, etc.

((tutorial
  (first-attempt     (:pdf "<url>") (:html "<url>"))
  (defining-commands (:pdf "<url>") (:html "<url>"))
  ...)
 (howto
  (create-text-editor-pane    (:pdf "<url>") (:html "<url>"))
  (run-app-in-separate-thread (:pdf "<url>") (:html "<url>"))
  (create-new-backend         (:pdf "<url>") (:html "<url>"))
  ...)
 (explanation
  (coordinate-systems  (:pdf "<url>") (:html "<url>"))
  (sheet-hierarchies   (:pdf "<url>") (:html "<url>"))
  (development-history (:pdf "<url>") (:html "<url>"))
  ...)
 (reference
  (redisplay       (:pdf "<url>") (:html "<url>"))
  (layout-protocol (:pdf "<url>") (:html "<url>"))
  (output-protocol (:pdf "<url>") (:html "<url>"))
  ...))

Tools making use of DocSpec can offer commands such as view-tutorial, view-howto, view-explanation, and view-reference. Users can configure a priority list for their preferred formats; if the package does not offer documentation in any of those formats, the tool could prompt them to select an available format.