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

   1 <!--
   2 SPDX-FileCopyrightText: 2024 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 It is built on top of [⛩📰 书社][Shushe] and consequently inherits
  13   all of the (few) dependencies and prerequisites of the latter.
  14
  15 Using 🪾📰 Caudex is fairly straightforward, but customizing its
  16   output requires some familiarity with X·S·L·T and, probably, a
  17   minimal level of comfort using G·N·U Make.
  18
  19 ## Nomenclature
  20
  21 <i lang="la">Caudex</i> is a Latin word meaning “tree trunk, bollard,
  22   book”.
  23 It is the historical antecedent of Latin (and English) <i
  24   lang="la">cōdex</i>.
  25
  26 ## Basic Usage
  27
  28 For an easy quickstart, you can simply clone the 🪾📰 Caudex
  29   repository and work directly in that folder.
  30
  31 ```sh
  32 git clone https://git.ladys.computer/Caudex
  33
  34 # Create a new entry in `my_category´ :—
  35 make +my_category | xargs -o nano
  36
  37 # Build the website
  38 make install
  39 ```
  40
  41 However, the most flexible way to get started with 🪾📰 Caudex is to
  42   include it in a project as a Git submodule :⁠—
  43
  44 ```sh
  45 git submodule add https://git.ladys.computer/Caudex
  46 ```
  47
  48 It can then be conigured, and activated, through recursive invocation
  49   of G·N·U Make :⁠—
  50
  51 ```make
  52 SHELL = /bin/sh
  53
  54 # Location of the 🪾📰 Caudex submodule.
  55 CAUDEX := Caudex
  56
  57 # Additional options to pass to 🪾📰 Caudex.
  58 #
  59 # Any variable overrides you explicitly give on the command line will
  60 # also automatically be forwarded.
  61 CAUDEXOPTS :=
  62
  63 # Build the website by running 🪾📰 Caudex `make install´.
  64 build: $(CAUDEX)/GNUmakefile
  65         $(MAKE) -f $(CAUDEX)/GNUmakefile install $(CAUDEXOPTS)
  66
  67 # Forward targets which begin with a plus; these have special meaning
  68 # in 🪾📰 Caudex.
  69 +%: $(CAUDEX)/GNUmakefile
  70         $(MAKE) -f $(CAUDEX)/GNUmakefile $@ $(CAUDEXOPTS)
  71
  72 # If the make·file of 🪾📰 Caudex doesn’t exist, the submodule needs
  73 # to be initialized.
  74 $(CAUDEX)/GNUmakefile:
  75         git submodule update --init --recursive '$(CAUDEX)/GNUmakefile'
  76 ```
  77
  78 ## Setup and Configuration
  79
  80 🪾📰 Caudex inherits all of the dependencies of ⛩📰 书社 and enables
  81   you to override them in the same way.
  82
  83 In addition to the configuration variables for ⛩📰 书社, the
  84   following variables are recognized and treated specially by
  85   🪾📰 Caudex :⁠—
  86
  87 - **`SRCDIR`:**
  88   The location of the codex entries and related metadata (default:
  89     `entries`).
  90   Only one directory is supported.
  91
  92 - **`ASSETDIR`:**
  93   The location of additional source files (default: `assets`).
  94   Multiple asset directories can be provided, so long as the same file
  95     subpath doesn’t exist in more than one of them.
  96
  97 - **`ASSETINCLUDEDIR`:**
  98   The location of includes to be used by additional source files
  99     (default: `assets/includes`).
 100   Multiple asset include directories can be provided, so long as the
 101     same file subpath doesn’t exist in more than one of them.
 102
 103 - **`BUILDDIR`:**
 104   The location of the (temporary) build directory (default: `build`).
 105   `make clean` will delete this, and it is recommended that it not be
 106     used for programs aside from 🪾📰 Caudex.
 107
 108 - **`DESTDIR`:**
 109   The location of directory to output files to (default: `public`).
 110   `make install` will overwrite files in this directory which
 111     correspond to those in `SRCDIR` and `ASSETDIR`.
 112   It *will not* touch other files, including those generated from files
 113     in `SRCDIR` which have since been deleted.
 114
 115   Files are first compiled to `$(BUILDDIR)/⛩📰/public` before they
 116     are copied to `DESTDIR`, so this folder is relatively quick and
 117     inexpensive to re·create.
 118   It’s reasonable to simply delete it before every `make install` to
 119     ensure stale content is removed.
 120
 121 - **`THISDIR`:**
 122   The location of the 🪾📰 Caudex `GNUmakefile`.
 123   This should be set automatically when calling Make and shouldn’t ever
 124     need to be set manually.
 125
 126 - **`EXTRAMAGIC`:**
 127   Additional magic files for ⛩📰 书社.
 128
 129 - **`EXTRAPARSERS`:**
 130   Additional parsers for ⛩📰 书社.
 131
 132 - **`EXTRATRANSFORMS`:**
 133   Additional transforms for ⛩📰 书社.
 134
 135 - **`GENERATOR`:**
 136   The name of the generator program (default: `🪾📰 Caudex`).
 137
 138 - **`VERSION`:**
 139   The current version of `GENERATOR` (default: derived from the current
 140     git tag/branch/commit).
 141
 142 - **`SRCREV`:**
 143   The current version of the source files (default: derived from the
 144     current git tag/branch/commit).
 145
 146 - **`VERBOSE`:**
 147   If this variable has a value, every recipe instruction will be
 148     printed when it runs (default: empty).
 149   This is helpful for debugging, but typically too noisy for general
 150     usage.
 151
 152 ## Source Files
 153
 154 Codex entries should be placed in subdirectories of `SRCDIR` and have
 155   a file·name of the form `???-????` or `???-????,*`, where `???-????`
 156   is a unique identifier for the entry within the codex.
 157 The command `make +⟨category⟩` is provided as a convenience to create
 158   a new entry with a random identifier within the subdirectory
 159   `⟨category⟩/`.
 160 If the identifier is followed by a comma, the remainder of the
 161   file·name may be used to provide a human⹀friendly description of the
 162   file’s contents.
 163 Remember: The file·name still needs to be compatible with ⛩📰 书社
 164   and Make (it must not contain spaces or other fraught Ascii
 165   characters).
 166
 167 Entries need to be in [💄📝 Les·M·L][LesML] format.
 168
 169 ## Metadata
 170
 171 Codices, categories, and entries should all have metadata.
 172 For entries, the metadata is provided by the record which begins the
 173   document.
 174 For codices and categories, the metadata is provided by a special file
 175   named `@` in `SRCDIR` or the category directory, respectively.
 176 In all cases, metadata is kept in the Record Jar format.
 177
 178 The following metadata fields are recognized by default :⁠—
 179
 180 - **`CATEGORY`:**
 181   Indicates that the current record is a category record.
 182   The value of this field gives the identifier for the category.
 183
 184 - **`CODEX`:**
 185   Indicates that the current record is a codex record.
 186   The value of this field gives the identifier for the codex.
 187
 188 - **`ENTRY`:**
 189   Indicates that the current record is an entry record.
 190   The value of this field gives the identifier for the entry.
 191
 192 - **`TITLE`:**
 193   For all record types, gives the title of the thing being described.
 194
 195 If the `@` file is missing from a category directory, none of the
 196   entries in the category will be recognized.
 197 However, a minimal `@` file will be created for you when you create an
 198   entry in a new category using `make +⟨category⟩`.
 199
 200 ## Output Files
 201
 202 Assets are installed to their corresponding location in `DESTDIR`
 203   (default: `public/`).
 204 An entry with the identifier `%` will be installed to `%.xhtml`.
 205
 206 Two index files are created :⁠— `index.xhtml` loads entries
 207   dynamically upon request, and `standalone.xhtml` contains all of the
 208   entries and does not require a network connection.
 209
 210 Output can be customized by supplying additional transforms, ⅌ normal
 211   ⛩📰 书社 conventions.
 212 The easiest way to customize the transform is to introduce new
 213   templates which operate in the `书社:header`, `书社:footer`, or
 214   `书社:metadata` modes.
 215
 216 If you want to customize the actual main body output of 🪾📰 Caudex,
 217   you will need a pattern like this :⁠—
 218
 219 ```xml
 220 <?xml version="1.0"?>
 221 <transform
 222   xmlns="http://www.w3.org/1999/XSL/Transform"
 223   xmlns:exsl="http://exslt.org/common"
 224   xmlns:html="http://www.w3.org/1999/xhtml"
 225   xmlns:书社="urn:fdc:ladys.computer:20231231:Shu1She4"
 226   exclude-result-prefixes="exsl"
 227   version="1.0"
 228 >
 229   <书社:id>example:modify-caudex-index</书社:id>
 230   <!-- Create a template with increased priority, excluding elements with a `@data-caudex-parse´ attribute. -->
 231   <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">
 232     <!-- Add the attribute to the element in a variable. -->
 233     <variable name="toparse">
 234       <copy>
 235         <attribute name="data-caudex-parse"/>
 236         <copy-of select="@*|node()"/>
 237       </copy>
 238     </variable>
 239     <!-- Apply templates to the contents of the variable, saving the result. -->
 240     <variable name="parsed">
 241       <apply-templates select="exsl:node-set($toparse)/*"/>
 242     </variable>
 243     <!-- Do something with the result. -->
 244     <for-each select="exsl:node-set($parsed)/*">
 245       <!-- … -->
 246     </for-each>
 247   </template>
 248 </transform>
 249 ```
 250
 251 [LesML]: <https://git.ladys.computer/LesML>
 252 [Shushe]: <https://git.ladys.computer/Shushe>
 253 [draft-phillips-record-jar-01]: <https://datatracker.ietf.org/doc/html/draft-phillips-record-jar-01>