CommonDoc ยป Files

Documents are hardly ever self-contained, and references to external resources are necessary and useful for the following reasons:

  1. We don't want to have to load images to memory just to represent the document, and then have to write those images to base-64 when writing the document to an output format.
  2. External resources can reduce errors. For instance, if we're writing an article detailing the internals of a piece of code, we can keep the code in an external file (along with a script to test it), and simply include bits of it using the very flexible include contrib. Then, changes to the file will be automatically reflected in the document, reducing duplication and removing the need to manually synchronize contents.
  3. Just about every markup format supports at least referencing images both on the local filesystem and on the web, so we have to support that if we are to support that markup.

CommonDoc has simple support for doing operations with external files. There's a special variable, *base-directory*, which basically the directory where all relative pathnames referenced in the document begin. Once that variable is bound, a couple of functions can be used to manipulate pathnames.


The directory all resources with relative paths are based from. This is intended to be bound by a let by specific input formats.
Take a pathname or namestring. If it's absolute, return it, otherwise, merge it with *base-directory*.
If a pathname is inside *base-directory*, return a relative pathname. Otherwise, return the pathname unchanged.


(in-package :common-doc.file)(let ((*base-directory* (user-homedir-pathname)))
  (absolute-path #p"directory/file.txt"))
;; => #p"/home/eudoxia/directory/file.txt"