[Caudex] / README.markdown

# 🪾📰 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
  “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.

## Nomenclature

<i lang="la">Caudex</i> is a Latin word meaning “tree trunk, bollard,
  book”.
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

# Create a new entry in `my_category´ :—
make +my_category | xargs -o nano

# Build the website
make install
```

However, the most flexible way to get started with 🪾📰 Caudex is to
  include it in a project as a Git submodule :⁠—

```sh
git submodule add https://git.ladys.computer/Caudex
```

It can then be conigured, and activated, through recursive invocation
  of G·N·U Make :⁠—

```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 :=

# Build the website by running 🪾📰 Caudex `make install´.
build: $(CAUDEX)/GNUmakefile
        $(MAKE) -f $(CAUDEX)/GNUmakefile install $(CAUDEXOPTS)

# Forward targets which begin with a plus; these have special meaning
# in 🪾📰 Caudex.
+%: $(CAUDEX)/GNUmakefile
        $(MAKE) -f $(CAUDEX)/GNUmakefile $@ $(CAUDEXOPTS)

# If the make·file of 🪾📰 Caudex doesn’t exist, the submodule needs
# to be initialized.
$(CAUDEX)/GNUmakefile:
        git submodule update --init --recursive '$(CAUDEX)/GNUmakefile'
```

## Setup and Configuration

🪾📰 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.

- **`EXTRAMAGIC`:**
  Additional magic files for ⛩📰 书社.

- **`EXTRAPARSERS`:**
  Additional parsers for ⛩📰 书社.

- **`EXTRATRANSFORMS`:**
  Additional transforms for ⛩📰 书社.

- **`GENERATOR`:**
  The name of the generator program (default: `🪾📰 Caudex`).

- **`VERSION`:**
  The current version of `GENERATOR` (default: derived from the current
    git tag/branch/commit).

- **`SRCREV`:**
  The current version of the source files (default: derived from the
    current git tag/branch/commit).

- **`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.

## 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.
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 ⛩📰 书社
  and Make (it must not contain spaces or other fraught Ascii
  characters).

Entries need to be in [💄📝 Les·M·L][LesML] format.

## Metadata

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.

The following metadata fields are recognized by default :⁠—

- **`CATEGORY`:**
  Indicates that the current record is a category record.
  The value of this field gives the identifier for the category.

- **`CODEX`:**
  Indicates that the current record is a codex record.
  The value of this field gives the identifier for the codex.

- **`ENTRY`:**
  Indicates that the current record is an entry record.
  The value of this field gives the identifier for the entry.

- **`TITLE`:**
  For all record types, gives the title of the thing being described.

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

Assets are installed to their corresponding location in `DESTDIR`
  (default: `public/`).
An entry with the identifier `%` will be installed to `%.xhtml`.

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.

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>
```

[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>