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

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