Lady’s Gitweb - Caudex/blob - README.markdown

   1 <!--
   2 SPDX-FileCopyrightText: 2024, 2025 Lady <https://www.ladys.computer/about/#lady>
   3 SPDX-License-Identifier: CC0-1.0
   4 -->
   5 # 🪾📰 Caudex
   6
   7 <b>A simple codex generator.</b>
   8
   9 <dfn>🪾📰 Caudex</dfn> is a static website generator aimed at
  10   generating simple, category‐based lists of documents akin to the
  11   “Codex” feature of games like <cite>Dragon Age</cite>.
  12
  13 Actually, 🪾📰 Caudex is a collection of files intended for use with
  14   [💄📝 Les·M·L][LesML] and [⛩📰 书社][Shushe], which does the actual
  15   site generation.
  16 It consists of the following components :⁠—
  17
  18 - The parser, `parser.xslt`, processes parsed 💄📝 Les·M·L files into
  19     an R·D·F representation of the codex.
  20
  21 - The transform, `transform.xslt`, converts the R·D·F into rendered
  22     X·H·T·M·L.
  23
  24 - The makefile, `GNUmakefile` provides some conveniences for codex
  25     creation.
  26
  27 ## Nomenclature
  28
  29 <i lang="la">Caudex</i> is a Latin word meaning “tree trunk, bollard,
  30   book”.
  31 It is the historical antecedent of Latin (and English) <i
  32   lang="la">cōdex</i>.
  33
  34 ## Prerequisites
  35
  36 🪾📰 Caudex expects a ⛩📰 书社 setup which includes its parser and
  37   transform as well as the 💄📝 Les·M·L magic and parser.
  38
  39 ## Basic Usage
  40
  41 The most flexible way to get started with 🪾📰 Caudex is to
  42   include it in a project as a Git submodule, presumably alongside
  43   ⛩📰 书社 and 💄📝 Les·M·L :⁠—
  44
  45 ```sh
  46 git submodule add https://git.ladys.computer/Shushe.git
  47 git submodule add https://git.ladys.computer/LesML.git
  48 git submodule add https://git.ladys.computer/Caudex.git
  49 ```
  50
  51 You will then need to create a make·file for building your site.
  52 A sample one follows :⁠—
  53
  54 ```make
  55 SHELL = /bin/sh
  56
  57 # Location of the 🪾📰 Caudex submodule.
  58 CAUDEX := Caudex
  59
  60 # Location of the ⛩📰 书社 submodule.
  61 LESML := LesML
  62
  63 # Location of the ⛩📰 书社 submodule.
  64 SHUSHE := Shushe
  65
  66 # Location of ⛩📰 书社 source files.
  67 SRCDIR := site
  68
  69 # Location of ⛩📰 书社 includes.
  70 INCLUDEDIR := data
  71
  72 # Location of the 🪾📰 Caudex codex—should be inside $(INCLUDEDIR).
  73 CODEXDIR := $(INCLUDEDIR)/codex
  74
  75 # Options to pass to ⛩📰 书社.
  76 #
  77 # This just identifies the source and include directories, and
  78 # identifies the appropriate 💄📝 Les·M·L and 🪾📰 Caudex files.
  79 SHUSHEOPTS := SRCDIR='$(SRCDIR)' INCLUDEDIR='$(INCLUDEDIR)' EXTRAMAGIC='$(LESML)/magic' EXTRAPARSERS='$(LESML)/parser.xslt $(CAUDEX)/parser.xslt' EXTRATRANSFORMS='$(CAUDEX)/transform.xslt'
  80
  81 # Options to pass to 🪾📰 Caudex.
  82 #
  83 # This identifies the codex directory.
  84 CAUDEXOPTS := SRCDIR='$(CODEXDIR)'
  85
  86 # Build the website by running ⛩📰 书社 `make install´.
  87 build:
  88         $(MAKE) -f $(SHUSHE)/GNUmakefile install $(SHUSHEOPTS)
  89
  90 # Forward targets which begin with a plus to the 🪾📰 Caudex
  91 # make·file.
  92 +%:
  93         $(MAKE) -f $(CAUDEX)/GNUmakefile $@ $(CAUDEXOPTS)
  94 ```
  95
  96 The above make·file is intentionally simplified; in practice, it might
  97   wind up considerably more complex.
  98
  99 Once ⛩📰 书社 is set up, you can generate a codex at subdirectory
 100   `codex/` in your site by creating a file `site/codex` with the
 101   following contents :⁠—
 102
 103 ```xml
 104 <?xml version="1.0"?>
 105 <codex
 106   xmlns="urn:fdc:ladys.computer:20240204:Caudex"
 107   xmlns:xlink="http://www.w3.org/1999/xlink"
 108   xmlns:书社="urn:fdc:ladys.computer:20231231:Shu1She4"
 109 >
 110   <书社:link
 111     xlink:href="about:shushe?include=codex/"
 112     xlink:show="embed"
 113   />
 114 </codex>
 115 ```
 116
 117 This code assumes that the codex directory (`data/codex/`) conforms to
 118   the source file expectations below.
 119
 120 ## Source Files
 121
 122 Codex entries should be placed in subdirectories of `CODEXDIR` and
 123   should generally have a filename of the form `???-????` or
 124   `???-????,*`, where `???-????` is a unique identifier for the entry
 125   within the codex.
 126 Any characters following the comma are ignored; they may be used to
 127   provide a human‐friendly description of the files contents.
 128
 129 The command `make +⟨category⟩` is provided as a convenience to create
 130   a new entry with a random identifier within the subdirectory
 131   `⟨category⟩/`.
 132
 133 **Remember:** The filename still needs to be compatible with ⛩📰 书社
 134   and Make (it must not contain spaces or other fraught Ascii
 135   characters).
 136
 137 A file named `~` is required to be present in `CODEXDIR` and each
 138   category directory.
 139 These files provide metadata for the codex and categories.
 140
 141 Codex entries and metadata files are expected to be in 💄📝 Les·M·L
 142   format and have a profile which is one of the following :⁠—
 143
 144 - `urn:fdc:ladys.computer:20240204:Caudex:pf:codex` for codex metadata
 145
 146 - `urn:fdc:ladys.computer:20240204:Caudex:pf:category` for category
 147     metadata
 148
 149 - `urn:fdc:ladys.computer:20240204:Caudex:pf:entry` for codex entries
 150
 151 ## Metadata
 152
 153 Codices, categories, and entries should all have metadata.
 154 For codices and categories, the metadata is provided by a special
 155   💄📝 Les·M·L file named `~` in `$(CODEXDIR)` or the category
 156   directory, respectively.
 157 The (non‐metadata) contents of this file are presently ignored; in the
 158   future they may be interpreted as a longer‐form description.
 159
 160 The following metadata fields are recognized by default :⁠—
 161
 162 - **`TITLE`:**
 163   Gives the title of the thing being described.
 164
 165 - **`ORDER`:**
 166   Provides a manual ordering of the category or entry.
 167   This must be an integer.
 168   When multiple categories or entries have the same order, they are
 169     then arranged by title.
 170
 171 If the `~` file is missing from a category directory, none of the
 172   entries in the category will be recognized.
 173 However, a minimal `~` file will be created for you when you create an
 174   entry in a new category using `make +⟨category⟩`.
 175
 176 ## Output Files
 177
 178 Under the hood, 🪾📰 Caudex defines codices as “expanded
 179   archives”—essentially, tarballs that ⛩📰 书社 automatically expands
 180   into their final locations.
 181 This means that it is _not possible_ for a codex to appear in the root
 182   directory of the install location—it must be given a subdirectory.
 183 (Of course, it is always possible to just serve the site from that
 184   subdirectory instead.)
 185
 186 Within this conceptual archive, two index files are created :⁠—
 187   `index.xhtml` loads entries dynamically upon request, and
 188   `standalone.xhtml` contains all of the entries within its source code
 189   and consequently does not require a network connection.
 190 Both files make use of (minimal) Javascript for full functionality.
 191
 192 Output can be customized by supplying additional transforms, ⅌ normal
 193   ⛩📰 书社 conventions.
 194 The easiest way to customize the transform is to introduce new
 195   templates which operate in the `书社:header`, `书社:footer`, or
 196   `书社:metadata` modes.
 197 Additionally, the `Caudex:codex-entry` mode is used to process the
 198   contents of codex entries themselves.
 199
 200 [LesML]: <https://git.ladys.computer/LesML>
 201 [Shushe]: <https://git.ladys.computer/Shushe>