Documents are hardly ever self-contained, and references to external resources are necessary and useful for the following reasons:
- 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.
- 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
includecontrib. Then, changes to the file will be automatically reflected in the document, reducing duplication and removing the need to manually synchronize contents. - 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.
API
*base-directory*The directory all resources with relative paths are based from. This is
intended to be bound by a
let by specific input formats.absolute-path(pathname-or-string)Take a pathname or namestring. If it's absolute, return it, otherwise, merge
it with
*base-directory*.relativize-pathname(pathname)If a pathname is inside
*base-directory*, return a relative
pathname. Otherwise, return the pathname unchanged.Examples
(in-package :common-doc.file)(let ((*base-directory* (user-homedir-pathname)))
(absolute-path #p"directory/file.txt"))
;; => #p"/home/eudoxia/directory/file.txt"