Enable manual ordering

[Caudex] / README.markdown

diff --git a/README.markdown b/README.markdown
index 90470f6934b5300340d5fdb384ff797ecd5f1377..14b1424397e8f4e9f2280ebf1f79517997b848f2 100644 (file)
--- a/README.markdown
+++ b/README.markdown
@@ -1,16 +1,28 @@
+<!--
+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
 # 🪾📰 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>.
   “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
 
 
 ## Nomenclature
 


@@ -19,30 +31,25 @@ Using 🪾📰 Caudex is fairly straightforward, but customizing its
 It is the historical antecedent of Latin (and English) <i
   lang="la">cōdex</i>.
 
 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
 
 ```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
 
 ```make
 SHELL = /bin/sh


@@ -50,200 +57,145 @@ SHELL = /bin/sh
 # Location of the 🪾📰 Caudex submodule.
 CAUDEX := Caudex
 
 # 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
 
 
 ## 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⟩/`.
 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).
 
   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

 
 

-- **`ENTRY`:**
-  Indicates that the current record is an entry record.
-  The value of this field gives the identifier for the entry.
+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`:**
 
 - **`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
+- **`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.
   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
 
   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.
 
 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>
 
 [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>