# 📰 Caudex
A simple codex generator.
📰 Caudex is a static website generator aimed at
generating simple, category‐based lists of documents akin to the
“Codex” feature of games like Dragon Age.
Actually, 📰 Caudex is a collection of files intended for use with
[💄📝 Les·M·L][LesML] and [⛩📰 书社][Shushe], which does the actual
site generation.
It consists of the following components :—
- The parser, `parser.xslt`, processes parsed 💄📝 Les·M·L files into
an R·D·F representation of the codex.
- The transform, `transform.xslt`, converts the R·D·F into rendered
X·H·T·M·L.
- The makefile, `GNUmakefile` provides some conveniences for codex
creation.
## Nomenclature
Caudex is a Latin word meaning “tree trunk, bollard,
book”.
It is the historical antecedent of Latin (and English) cōdex.
## Prerequisites
📰 Caudex expects a ⛩📰 书社 setup which includes its parser and
transform as well as the 💄📝 Les·M·L magic and parser.
## Basic Usage
The most flexible way to get started with 📰 Caudex is to
include it in a project as a Git submodule, presumably alongside
⛩📰 书社 and 💄📝 Les·M·L :—
```sh
git submodule add https://git.ladys.computer/Shushe.git
git submodule add https://git.ladys.computer/LesML.git
git submodule add https://git.ladys.computer/Caudex.git
```
You will then need to create a make·file for building your site.
A sample one follows :—
```make
SHELL = /bin/sh
# Location of the 📰 Caudex submodule.
CAUDEX := Caudex
# Location of the ⛩📰 书社 submodule.
LESML := LesML
# Location of the ⛩📰 书社 submodule.
SHUSHE := Shushe
# Location of ⛩📰 书社 source files.
SRCDIR := site
# Location of ⛩📰 书社 includes.
INCLUDEDIR := data
# Location of the 📰 Caudex codex—should be inside $(INCLUDEDIR).
CODEXDIR := $(INCLUDEDIR)/codex
# Options to pass to ⛩📰 书社.
#
# This just identifies the source and include directories, and
# identifies the appropriate 💄📝 Les·M·L and 📰 Caudex files.
SHUSHEOPTS := SRCDIR='$(SRCDIR)' INCLUDEDIR='$(INCLUDEDIR)' EXTRAMAGIC='$(LESML)/magic' EXTRAPARSERS='$(LESML)/parser.xslt $(CAUDEX)/parser.xslt' EXTRATRANSFORMS='$(CAUDEX)/transform.xslt'
# Options to pass to 📰 Caudex.
#
# This identifies the codex directory.
CAUDEXOPTS := SRCDIR='$(CODEXDIR)'
# Build the website by running ⛩📰 书社 `make install´.
build:
$(MAKE) -f $(SHUSHE)/GNUmakefile install $(SHUSHEOPTS)
# Forward targets which begin with a plus to the 📰 Caudex
# make·file.
+%:
$(MAKE) -f $(CAUDEX)/GNUmakefile $@ $(CAUDEXOPTS)
```
The above make·file is intentionally simplified; in practice, it might
wind up considerably more complex.
Once ⛩📰 书社 is set up, you can generate a codex at subdirectory
`codex/` in your site by creating a file `site/codex` with the
following contents :—
```xml
<书社:link
xlink:href="about:shushe?include=codex/"
xlink:show="embed"
/>
```
This code assumes that the codex directory (`data/codex/`) conforms to
the source file expectations below.
## Source Files
Codex entries should be placed in subdirectories of `CODEXDIR` and
should generally have a filename of the form `???-????` or
`???-????,*`, where `???-????` is a unique identifier for the entry
within the codex.
Any characters following the comma are ignored; they may be used to
provide a human‐friendly description of the files contents.
The command `make +⟨category⟩` is provided as a convenience to create
a new entry with a random identifier within the subdirectory
`⟨category⟩/`.
**Remember:** The filename still needs to be compatible with ⛩📰 书社
and Make (it must not contain spaces or other fraught Ascii
characters).
A file named `~` is required to be present in `CODEXDIR` and each
category directory.
These files provide metadata for the codex and categories.
Codex entries and metadata files are expected to be in 💄📝 Les·M·L
format and have a profile which is one of the following :—
- `urn:fdc:ladys.computer:20240204:Caudex:pf:codex` for codex metadata
- `urn:fdc:ladys.computer:20240204:Caudex:pf:category` for category
metadata
- `urn:fdc:ladys.computer:20240204:Caudex:pf:entry` for codex entries
## Metadata
Codices, categories, and entries should all have metadata.
For codices and categories, the metadata is provided by a special
💄📝 Les·M·L file named `~` in `$(CODEXDIR)` or the category
directory, respectively.
The (non‐metadata) contents of this file are presently ignored; in the
future they may be interpreted as a longer‐form description.
The following metadata fields are recognized by default :—
- **`TITLE`:**
Gives the title of the thing being described.
- **`ORDER`:**
Provides a manual ordering of the category or entry.
This must be an integer.
When multiple categories or entries have the same order, they are
then arranged by title.
If the `~` file is missing from a category directory, none of the
entries in the category will be recognized.
However, a minimal `~` file will be created for you when you create an
entry in a new category using `make +⟨category⟩`.
## Output Files
Under the hood, 📰 Caudex defines codices as “expanded
archives”—essentially, tarballs that ⛩📰 书社 automatically expands
into their final locations.
This means that it is _not possible_ for a codex to appear in the root
directory of the install location—it must be given a subdirectory.
(Of course, it is always possible to just serve the site from that
subdirectory instead.)
Within this conceptual archive, two index files are created :—
`index.xhtml` loads entries dynamically upon request, and
`standalone.xhtml` contains all of the entries within its source code
and consequently does not require a network connection.
Both files make use of (minimal) Javascript for full functionality.
Output can be customized by supplying additional transforms, ⅌ normal
⛩📰 书社 conventions.
The easiest way to customize the transform is to introduce new
templates which operate in the `书社:header`, `书社:footer`, or
`书社:metadata` modes.
Additionally, the `Caudex:codex-entry` mode is used to process the
contents of codex entries themselves.
[LesML]:
[Shushe]: