+<!--
+SPDX-FileCopyrightText: 2024, 2025 Lady <https://www.ladys.computer/about/#lady>
+SPDX-License-Identifier: CC0-1.0
+-->
# 📰 Caudex
<b>A simple codex generator.</b>
<dfn>📰 Caudex</dfn> is a static website generator aimed at
- generating simple, category⹀based lists of documents akin to the
+ generating simple, category‐based lists of documents akin to the
“Codex” feature of games like <cite>Dragon Age</cite>.
-It is built on top of [⛩📰 书社][Shushe] and consequently inherits
- all of the (few) dependencies and prerequisites of the latter.
-Using 📰 Caudex is fairly straightforward, but customizing its
- output requires some familiarity with X·S·L·T and, probably, a
- minimal level of comfort using G·N·U Make.
+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
It is the historical antecedent of Latin (and English) <i
lang="la">cōdex</i>.
-## Basic Usage
-
-For an easy quickstart, you can simply clone the 📰 Caudex
- repository and work directly in that folder.
-
-```sh
-git clone https://git.ladys.computer/Caudex
+## Prerequisites
-# Create a new entry in `my_category´ :—
-make +my_category | xargs -o nano
+📰 Caudex expects a ⛩📰 书社 setup which includes its parser and
+ transform as well as the 💄📝 Les·M·L magic and parser.
-# Build the website
-make install
-```
+## Basic Usage
-However, the most flexible way to get started with 📰 Caudex is to
- include it in a project as a Git submodule :—
+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/Caudex
+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
```
-It can then be conigured, and activated, through recursive invocation
- of G·N·U Make :—
+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
-# Additional options to pass to 📰 Caudex.
-#
-# Any variable overrides you explicitly give on the command line will
-# also automatically be forwarded.
-CAUDEXOPTS :=
+# Location of the ⛩📰 书社 submodule.
+LESML := LesML
-# Build the website by running 📰 Caudex `make install´.
-build: $(CAUDEX)/GNUmakefile
- $(MAKE) -f $(CAUDEX)/GNUmakefile install $(CAUDEXOPTS)
+# Location of the ⛩📰 书社 submodule.
+SHUSHE := Shushe
-# Forward targets which begin with a plus; these have special meaning
-# in 📰 Caudex.
-+%: $(CAUDEX)/GNUmakefile
- $(MAKE) -f $(CAUDEX)/GNUmakefile $@ $(CAUDEXOPTS)
+# Location of ⛩📰 书社 source files.
+SRCDIR := site
-# If the make·file of 📰 Caudex doesn’t exist, the submodule needs
-# to be initialized.
-$(CAUDEX)/GNUmakefile:
- git submodule update --init --recursive '$(CAUDEX)/GNUmakefile'
-```
+# Location of ⛩📰 书社 includes.
+INCLUDEDIR := data
-## Setup and Configuration
+# Location of the 📰 Caudex codex—should be inside $(INCLUDEDIR).
+CODEXDIR := $(INCLUDEDIR)/codex
-📰 Caudex inherits all of the dependencies of ⛩📰 书社 and enables
- you to override them in the same way.
-
-In addition to the configuration variables for ⛩📰 书社, the
- following variables are recognized and treated specially by
- 📰 Caudex :—
-
-- **`SRCDIR`:**
- The location of the codex entries and related metadata (default:
- `entries`).
- Only one directory is supported.
-
-- **`ASSETDIR`:**
- The location of additional source files (default: `assets`).
- Multiple asset directories can be provided, so long as the same file
- subpath doesn’t exist in more than one of them.
-
-- **`ASSETINCLUDEDIR`:**
- The location of includes to be used by additional source files
- (default: `assets/includes`).
- Multiple asset include directories can be provided, so long as the
- same file subpath doesn’t exist in more than one of them.
-
-- **`BUILDDIR`:**
- The location of the (temporary) build directory (default: `build`).
- `make clean` will delete this, and it is recommended that it not be
- used for programs aside from 📰 Caudex.
-
-- **`DESTDIR`:**
- The location of directory to output files to (default: `public`).
- `make install` will overwrite files in this directory which
- correspond to those in `SRCDIR` and `ASSETDIR`.
- It *will not* touch other files, including those generated from files
- in `SRCDIR` which have since been deleted.
-
- Files are first compiled to `$(BUILDDIR)/⛩📰/public` before they
- are copied to `DESTDIR`, so this folder is relatively quick and
- inexpensive to re·create.
- It’s reasonable to simply delete it before every `make install` to
- ensure stale content is removed.
-
-- **`THISDIR`:**
- The location of the 📰 Caudex `GNUmakefile`.
- This should be set automatically when calling Make and shouldn’t ever
- need to be set manually.
+# 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'
-- **`EXTRAMAGIC`:**
- Additional magic files for ⛩📰 书社.
+# Options to pass to 📰 Caudex.
+#
+# This identifies the codex directory.
+CAUDEXOPTS := SRCDIR='$(CODEXDIR)'
-- **`EXTRAPARSERS`:**
- Additional parsers for ⛩📰 书社.
+# Build the website by running ⛩📰 书社 `make install´.
+build:
+ $(MAKE) -f $(SHUSHE)/GNUmakefile install $(SHUSHEOPTS)
-- **`EXTRATRANSFORMS`:**
- Additional transforms for ⛩📰 书社.
+# Forward targets which begin with a plus to the 📰 Caudex
+# make·file.
++%:
+ $(MAKE) -f $(CAUDEX)/GNUmakefile $@ $(CAUDEXOPTS)
+```
-- **`GENERATOR`:**
- The name of the generator program (default: `📰 Caudex`).
+The above make·file is intentionally simplified; in practice, it might
+ wind up considerably more complex.
-- **`VERSION`:**
- The current version of `GENERATOR` (default: derived from the current
- git tag/branch/commit).
+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 :—
-- **`SRCREV`:**
- The current version of the source files (default: derived from the
- current git tag/branch/commit).
+```xml
+<?xml version="1.0"?>
+<codex
+ xmlns="urn:fdc:ladys.computer:20240204:Caudex"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xmlns:书社="urn:fdc:ladys.computer:20231231:Shu1She4"
+>
+ <书社:link
+ xlink:href="about:shushe?include=codex/"
+ xlink:show="embed"
+ />
+</codex>
+```
-- **`VERBOSE`:**
- If this variable has a value, every recipe instruction will be
- printed when it runs (default: empty).
- This is helpful for debugging, but typically too noisy for general
- usage.
+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 `SRCDIR` and have
- a file·name of the form `???-????` or `???-????,*`, where `???-????`
- is a unique identifier for the entry within the codex.
+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⟩/`.
-If the identifier is followed by a comma, the remainder of the
- file·name may be used to provide a human⹀friendly description of the
- file’s contents.
-Remember: The file·name still needs to be compatible with ⛩📰 书社
+
+**Remember:** The filename still needs to be compatible with ⛩📰 书社
and Make (it must not contain spaces or other fraught Ascii
characters).
-Entries need to be in [💄📝 Les·M·L][LesML] format.
+A file named `~` is required to be present in `CODEXDIR` and each
+ category directory.
+These files provide metadata for the codex and categories.
-## Metadata
+Codex entries and metadata files are expected to be in 💄📝 Les·M·L
+ format and have a profile which is one of the following :—
-Codices, categories, and entries should all have metadata.
-For entries, the metadata is provided by the record which begins the
- document.
-For codices and categories, the metadata is provided by a special file
- named `@` in `SRCDIR` or the category directory, respectively.
-In all cases, metadata is kept in the Record Jar format.
+- `urn:fdc:ladys.computer:20240204:Caudex:pf:codex` for codex metadata
-The following metadata fields are recognized by default :—
+- `urn:fdc:ladys.computer:20240204:Caudex:pf:category` for category
+ metadata
-- **`CATEGORY`:**
- Indicates that the current record is a category record.
- The value of this field gives the identifier for the category.
+- `urn:fdc:ladys.computer:20240204:Caudex:pf:entry` for codex entries
-- **`CODEX`:**
- Indicates that the current record is a codex record.
- The value of this field gives the identifier for the codex.
+## 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.
-- **`ENTRY`:**
- Indicates that the current record is an entry record.
- The value of this field gives the identifier for the entry.
+The following metadata fields are recognized by default :—
- **`TITLE`:**
- For all record types, gives the title of the thing being described.
+ Gives the title of the thing being described.
-If the `@` file is missing from a category directory, none of the
+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
+However, a minimal `~` file will be created for you when you create an
entry in a new category using `make +⟨category⟩`.
## Output Files
-Assets are installed to their corresponding location in `DESTDIR`
- (default: `public/`).
-An entry with the identifier `%` will be installed to `%.xhtml`.
+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.)
-Two index files are created :— `index.xhtml` loads entries
- dynamically upon request, and `standalone.xhtml` contains all of the
- entries and does not require a network connection.
+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.
-
-If you want to customize the actual main body output of 📰 Caudex,
- you will need a pattern like this :—
-
-```xml
-<?xml version="1.0"?>
-<transform
- xmlns="http://www.w3.org/1999/XSL/Transform"
- xmlns:exsl="http://exslt.org/common"
- xmlns:html="http://www.w3.org/1999/xhtml"
- xmlns:书社="urn:fdc:ladys.computer:20231231:Shu1She4"
- exclude-result-prefixes="exsl"
- version="1.0"
->
- <书社:id>example:modify-caudex-index</书社:id>
- <!-- Create a template with increased priority, excluding elements with a `@data-caudex-parse´ attribute. -->
- <template match="/html:div[@书社:parsed-by='urn:fdc:ladys.computer:20240204:Caudex:catalog.xslt'][@class='index' or @class='fullindex'][not(@data-caudex-parse)]" priority="1">
- <!-- Add the attribute to the element in a variable. -->
- <variable name="toparse">
- <copy>
- <attribute name="data-caudex-parse"/>
- <copy-of select="@*|node()"/>
- </copy>
- </variable>
- <!-- Apply templates to the contents of the variable, saving the result. -->
- <variable name="parsed">
- <apply-templates select="exsl:node-set($toparse)/*"/>
- </variable>
- <!-- Do something with the result. -->
- <for-each select="exsl:node-set($parsed)/*">
- <!-- … -->
- </for-each>
- </template>
-</transform>
-```
+Additionally, the `Caudex:codex-entry` mode is used to process the
+ contents of codex entries themselves.
[LesML]: <https://git.ladys.computer/LesML>
[Shushe]: <https://git.ladys.computer/Shushe>
-[draft-phillips-record-jar-01]: <https://datatracker.ietf.org/doc/html/draft-phillips-record-jar-01>
Lady’s Gitweb / Caudex / blobdiff