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 If the `~` file is missing from a category directory, none of the
 166   entries in the category will be recognized.
 167 However, a minimal `~` file will be created for you when you create an
 168   entry in a new category using `make +⟨category⟩`.
 169
 170 ## Output Files
 171
 172 Under the hood, 🪾📰 Caudex defines codices as “expanded
 173   archives”—essentially, tarballs that ⛩📰 书社 automatically expands
 174   into their final locations.
 175 This means that it is _not possible_ for a codex to appear in the root
 176   directory of the install location—it must be given a subdirectory.
 177 (Of course, it is always possible to just serve the site from that
 178   subdirectory instead.)
 179
 180 Within this conceptual archive, two index files are created :⁠—
 181   `index.xhtml` loads entries dynamically upon request, and
 182   `standalone.xhtml` contains all of the entries within its source code
 183   and consequently does not require a network connection.
 184 Both files make use of (minimal) Javascript for full functionality.
 185
 186 Output can be customized by supplying additional transforms, ⅌ normal
 187   ⛩📰 书社 conventions.
 188 The easiest way to customize the transform is to introduce new
 189   templates which operate in the `书社:header`, `书社:footer`, or
 190   `书社:metadata` modes.
 191 Additionally, the `Caudex:codex-entry` mode is used to process the
 192   contents of codex entries themselves.
 193
 194 [LesML]: <https://git.ladys.computer/LesML>
 195 [Shushe]: <https://git.ladys.computer/Shushe>