cl-hssg/TODO.rst

.. default-role:: code

###################
 Things to be done
###################


Core
####

New feature: file systems
=========================

Currently file output is strongly coupled to the file system of the OS. If we
want to write an artifact, then writing the artifact is the responsibility of
the artifact: it performs the low-level file system access, it generates the
output text and it manages the file names, including the output directory path.

My proposal is to add a lever of indirection by separating concerns. There are
three participants:

- File systems
- Artifacts
- Instructions

The artifact is an abstract representation of one or more future files. It is
then *derived* to produce a low-level instruction on what action to actually
perform to produce the file (relative file name, contents). The file system
interprets the instruction by accessing the file systems and outputting the
actual contents.

All this will be implemented using CLOS. A generic function dispatches on both
instruction and file system. There will be core implementations for elemental
instructions and file systems. Implementations for new classes will then be
implemented on top of these primitive methods. For example, an implementation
for an instruction which produces multiple files will created multiple
lower-level instructions and call the generic function for each of these
instructions and the original file system.


New feature: sources
====================

Currently the way we get data into HSSG is a mess without any consistency. I
propose the idea of "sources", "processors" and "sinks".

- A source is some object which represents the initial point of data
- A processor is some object which transforms data into other data
- A sink is the final destination of the data which produces the actual output
  file

We already have artifacts as sinks and templates as filters. This only leaves
sources to be implemented. A source is some object which implements the source
protocol:

- `GET-DATA`: Returns the data for further processing

It is up to the source to implement for example some form of caching. A source
could read data from a file, it could be hard-coded data, or it could use OCR
to parse a message delivered by carrier pigeon.


Cleanup
=======

- A proper public interface to the various artifact classes
- Expose reader interface to public
- Remove `WRITE-ARTIFACT` generic function and its methods once file system and
  instructions are implemented everywhere

Testing
=======

- Artifacts
  - Come up with a proper artifacts interface
  - Test the individual artifact implementations (function `WRITE-ARTIFACT`)
- Update reader tests to public interface once it is done


Blog
####

Fixes
=====

- Make sure the `lisp` reader uses throwaway packages instead of polluting the
  global namespace

Features
========

- Template: docstrings in template
- Localization: Fall back to English if a particular key does not exist for the
  target language

Cleanup
=======

- How much of each artifact's internals need to be exposed? Make accessor
  functions? Constructor functions over `MAKE-INSTANCE`?
- Static page metadata without binding (see comment in definition)

Testing
=======

Everything


CommonMark reader
#################

Testing
=======

Everything