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 should be of the `text/x.codex-entry` format, which is defined
 164   as follows :⁠—
 165
 166 1. The string `%%`, followed by a newline and
 167
 168 2. A [Record Jar][draft-phillips-record-jar-01] record starting with
 169      `ENTRY :`, followed by
 170
 171 3. Any number of additional records, followed by
 172
 173 4. Zero or more lines of (mostly⹀)plain text.
 174
 175 For example :⁠—
 176
 177 ```txt
 178 %%
 179 ENTRY : 30W-5M41
 180 TITLE : My Amazing Entry
 181 %%
 182
 183 This is the text of my amazing entry.
 184 ```
 185
 186 The text of the entry is processed minimally:
 187 It is broken into paragraphs on blank lines, and paragraphs for which
 188   each line begins with white·space are considered block quotations.
 189 All other whitespace is trimmed and collapsed.
 190
 191 ## Metadata
 192
 193 Codices, categories, and entries should all have metadata.
 194 For entries, the metadata is provided by the record which begins the
 195   `text/x.codex-entry` format.
 196 For codicies and categories, the metadata is provided by a special file
 197   named `@` in `SRCDIR` or the category directory, respectively.
 198 In all cases, metadata is kept in the Record Jar format.
 199
 200 The following metadata fields are recognized by default :⁠—
 201
 202 - **`CATEGORY`:**
 203   Indicates that the current record is a category record.
 204   The value of this field gives the identifier for the category.
 205
 206 - **`CODEX`:**
 207   Indicates that the current record is a codex record.
 208   The value of this field gives the identifier for the codex.
 209
 210 - **`ENTRY`:**
 211   Indicates that the current record is an entry record.
 212   The value of this field gives the identifier for the entry.
 213
 214 - **`TITLE`:**
 215   For all record types, gives the title of the thing being described.
 216
 217 If the `@` file is missing from a category directory, none of the
 218   entries in the category will be recognized.
 219 However, a minimal `@` file will be created for you when you create an
 220   entry in a new category using `make +⟨category⟩`.
 221
 222 ## Output Files
 223
 224 Assets are installed to their corresponding location in `DESTDIR`
 225   (default: `public/`).
 226 An entry with the identifier `%` will be installed to `%.xhtml`.
 227
 228 Two index files are created :⁠— `index.xhtml` loads entries
 229   dynamically upon request, and `standalone.xhtml` contains all of the
 230   entries and does not require a network connection.
 231
 232 Output can be customized by supplying additional transforms, ⅌ normal
 233   ⛩️📰 书社 conventions.
 234 The easiest way to customize the transform is to introduce new
 235   templates which operate in the `书社:header`, `书社:footer`, or
 236   `书社:metadata` modes.
 237
 238 If you want to customize the actual main body output of 🪾📰 Caudex,
 239   you will need a pattern like this :⁠—
 240
 241 ```xml
 242 <?xml version="1.0"?>
 243 <transform
 244   xmlns="http://www.w3.org/1999/XSL/Transform"
 245   xmlns:exsl="http://exslt.org/common"
 246   xmlns:html="http://www.w3.org/1999/xhtml"
 247   xmlns:书社="urn:fdc:ladys.computer:20231231:Shu1She4"
 248   exclude-result-prefixes="exsl"
 249   version="1.0"
 250 >
 251   <书社:id>example:modify-caudex-index</书社:id>
 252   <!-- Create a template with increased priority, excluding elements with a `@data-caudex-parse´ attribute. -->
 253   <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">
 254     <!-- Add the attribute to the element in a variable. -->
 255     <variable name="toparse">
 256       <copy>
 257         <attribute name="data-caudex-parse"/>
 258         <copy-of select="@*|node()"/>
 259       </copy>
 260     </variable>
 261     <!-- Apply templates to the contents of the variable, saving the result. -->
 262     <variable name="parsed">
 263       <apply-templates select="exsl:node-set($toparse)/*"/>
 264     </variable>
 265     <!-- Do something with the result. -->
 266     <for-each select="exsl:node-set($parsed)/*">
 267       <!-- … -->
 268     </for-each>
 269   </template>
 270 </transform>
 271 ```
 272
 273 [Shushe]: <https://git.ladys.computer/Shushe>
 274 [draft-phillips-record-jar-01]: <https://datatracker.ietf.org/doc/html/draft-phillips-record-jar-01>