X-Git-Url: https://git.ladys.computer/Caudex/blobdiff_plain/b525fdbcbb4e7b54eb941426992f629af2d504cc..0ad7eaa34fa2533489f9b3f4ed7cda455243a398:/README.markdown diff --git a/README.markdown b/README.markdown index 90470f6..14b1424 100644 --- a/README.markdown +++ b/README.markdown @@ -1,16 +1,28 @@ + # 🪾📰 Caudex A simple codex generator. 🪾📰 Caudex is a static website generator aimed at - generating simple, category⹀based lists of documents akin to the + generating simple, category‐based lists of documents akin to the “Codex” feature of games like Dragon Age. -It is built on top of [⛩📰 书社][Shushe] and consequently inherits - all of the (few) dependencies and prerequisites of the latter. -Using 🪾📰 Caudex is fairly straightforward, but customizing its - output requires some familiarity with X·S·L·T and, probably, a - minimal level of comfort using G·N·U Make. +Actually, 🪾📰 Caudex is a collection of files intended for use with + [💄📝 Les·M·L][LesML] and [⛩📰 书社][Shushe], which does the actual + site generation. +It consists of the following components :⁠— + +- The parser, `parser.xslt`, processes parsed 💄📝 Les·M·L files into + an R·D·F representation of the codex. + +- The transform, `transform.xslt`, converts the R·D·F into rendered + X·H·T·M·L. + +- The makefile, `GNUmakefile` provides some conveniences for codex + creation. ## Nomenclature @@ -19,30 +31,25 @@ Using 🪾📰 Caudex is fairly straightforward, but customizing its It is the historical antecedent of Latin (and English) cōdex. -## Basic Usage - -For an easy quickstart, you can simply clone the 🪾📰 Caudex - repository and work directly in that folder. - -```sh -git clone https://git.ladys.computer/Caudex +## Prerequisites -# Create a new entry in `my_category´ :— -make +my_category | xargs -o nano +🪾📰 Caudex expects a ⛩📰 书社 setup which includes its parser and + transform as well as the 💄📝 Les·M·L magic and parser. -# Build the website -make install -``` +## Basic Usage -However, the most flexible way to get started with 🪾📰 Caudex is to - include it in a project as a Git submodule :⁠— +The most flexible way to get started with 🪾📰 Caudex is to + include it in a project as a Git submodule, presumably alongside + ⛩📰 书社 and 💄📝 Les·M·L :⁠— ```sh -git submodule add https://git.ladys.computer/Caudex +git submodule add https://git.ladys.computer/Shushe.git +git submodule add https://git.ladys.computer/LesML.git +git submodule add https://git.ladys.computer/Caudex.git ``` -It can then be conigured, and activated, through recursive invocation - of G·N·U Make :⁠— +You will then need to create a make·file for building your site. +A sample one follows :⁠— ```make SHELL = /bin/sh @@ -50,200 +57,145 @@ SHELL = /bin/sh # Location of the 🪾📰 Caudex submodule. CAUDEX := Caudex -# Additional options to pass to 🪾📰 Caudex. -# -# Any variable overrides you explicitly give on the command line will -# also automatically be forwarded. -CAUDEXOPTS := +# Location of the ⛩📰 书社 submodule. +LESML := LesML -# Build the website by running 🪾📰 Caudex `make install´. -build: $(CAUDEX)/GNUmakefile - $(MAKE) -f $(CAUDEX)/GNUmakefile install $(CAUDEXOPTS) +# Location of the ⛩📰 书社 submodule. +SHUSHE := Shushe -# Forward targets which begin with a plus; these have special meaning -# in 🪾📰 Caudex. -+%: $(CAUDEX)/GNUmakefile - $(MAKE) -f $(CAUDEX)/GNUmakefile $@ $(CAUDEXOPTS) +# Location of ⛩📰 书社 source files. +SRCDIR := site -# If the make·file of 🪾📰 Caudex doesn’t exist, the submodule needs -# to be initialized. -$(CAUDEX)/GNUmakefile: - git submodule update --init --recursive '$(CAUDEX)/GNUmakefile' -``` +# Location of ⛩📰 书社 includes. +INCLUDEDIR := data -## Setup and Configuration +# Location of the 🪾📰 Caudex codex—should be inside $(INCLUDEDIR). +CODEXDIR := $(INCLUDEDIR)/codex -🪾📰 Caudex inherits all of the dependencies of ⛩📰 书社 and enables - you to override them in the same way. - -In addition to the configuration variables for ⛩📰 书社, the - following variables are recognized and treated specially by - 🪾📰 Caudex :⁠— - -- **`SRCDIR`:** - The location of the codex entries and related metadata (default: - `entries`). - Only one directory is supported. - -- **`ASSETDIR`:** - The location of additional source files (default: `assets`). - Multiple asset directories can be provided, so long as the same file - subpath doesn’t exist in more than one of them. - -- **`ASSETINCLUDEDIR`:** - The location of includes to be used by additional source files - (default: `assets/includes`). - Multiple asset include directories can be provided, so long as the - same file subpath doesn’t exist in more than one of them. - -- **`BUILDDIR`:** - The location of the (temporary) build directory (default: `build`). - `make clean` will delete this, and it is recommended that it not be - used for programs aside from 🪾📰 Caudex. - -- **`DESTDIR`:** - The location of directory to output files to (default: `public`). - `make install` will overwrite files in this directory which - correspond to those in `SRCDIR` and `ASSETDIR`. - It *will not* touch other files, including those generated from files - in `SRCDIR` which have since been deleted. - - Files are first compiled to `$(BUILDDIR)/⛩📰/public` before they - are copied to `DESTDIR`, so this folder is relatively quick and - inexpensive to re·create. - It’s reasonable to simply delete it before every `make install` to - ensure stale content is removed. - -- **`THISDIR`:** - The location of the 🪾📰 Caudex `GNUmakefile`. - This should be set automatically when calling Make and shouldn’t ever - need to be set manually. +# Options to pass to ⛩📰 书社. +# +# This just identifies the source and include directories, and +# identifies the appropriate 💄📝 Les·M·L and 🪾📰 Caudex files. +SHUSHEOPTS := SRCDIR='$(SRCDIR)' INCLUDEDIR='$(INCLUDEDIR)' EXTRAMAGIC='$(LESML)/magic' EXTRAPARSERS='$(LESML)/parser.xslt $(CAUDEX)/parser.xslt' EXTRATRANSFORMS='$(CAUDEX)/transform.xslt' -- **`EXTRAMAGIC`:** - Additional magic files for ⛩📰 书社. +# Options to pass to 🪾📰 Caudex. +# +# This identifies the codex directory. +CAUDEXOPTS := SRCDIR='$(CODEXDIR)' -- **`EXTRAPARSERS`:** - Additional parsers for ⛩📰 书社. +# Build the website by running ⛩📰 书社 `make install´. +build: + $(MAKE) -f $(SHUSHE)/GNUmakefile install $(SHUSHEOPTS) -- **`EXTRATRANSFORMS`:** - Additional transforms for ⛩📰 书社. +# Forward targets which begin with a plus to the 🪾📰 Caudex +# make·file. ++%: + $(MAKE) -f $(CAUDEX)/GNUmakefile $@ $(CAUDEXOPTS) +``` -- **`GENERATOR`:** - The name of the generator program (default: `🪾📰 Caudex`). +The above make·file is intentionally simplified; in practice, it might + wind up considerably more complex. -- **`VERSION`:** - The current version of `GENERATOR` (default: derived from the current - git tag/branch/commit). +Once ⛩📰 书社 is set up, you can generate a codex at subdirectory + `codex/` in your site by creating a file `site/codex` with the + following contents :⁠— -- **`SRCREV`:** - The current version of the source files (default: derived from the - current git tag/branch/commit). +```xml + + + <书社:link + xlink:href="about:shushe?include=codex/" + xlink:show="embed" + /> + +``` -- **`VERBOSE`:** - If this variable has a value, every recipe instruction will be - printed when it runs (default: empty). - This is helpful for debugging, but typically too noisy for general - usage. +This code assumes that the codex directory (`data/codex/`) conforms to + the source file expectations below. ## Source Files -Codex entries should be placed in subdirectories of `SRCDIR` and have - a file·name of the form `???-????` or `???-????,*`, where `???-????` - is a unique identifier for the entry within the codex. +Codex entries should be placed in subdirectories of `CODEXDIR` and + should generally have a filename of the form `???-????` or + `???-????,*`, where `???-????` is a unique identifier for the entry + within the codex. +Any characters following the comma are ignored; they may be used to + provide a human‐friendly description of the files contents. + The command `make +⟨category⟩` is provided as a convenience to create a new entry with a random identifier within the subdirectory `⟨category⟩/`. -If the identifier is followed by a comma, the remainder of the - file·name may be used to provide a human⹀friendly description of the - file’s contents. -Remember: The file·name still needs to be compatible with ⛩📰 书社 + +**Remember:** The filename still needs to be compatible with ⛩📰 书社 and Make (it must not contain spaces or other fraught Ascii characters). -Entries need to be in [💄📝 Les·M·L][LesML] format. +A file named `~` is required to be present in `CODEXDIR` and each + category directory. +These files provide metadata for the codex and categories. -## Metadata +Codex entries and metadata files are expected to be in 💄📝 Les·M·L + format and have a profile which is one of the following :⁠— -Codices, categories, and entries should all have metadata. -For entries, the metadata is provided by the record which begins the - document. -For codices and categories, the metadata is provided by a special file - named `@` in `SRCDIR` or the category directory, respectively. -In all cases, metadata is kept in the Record Jar format. +- `urn:fdc:ladys.computer:20240204:Caudex:pf:codex` for codex metadata -The following metadata fields are recognized by default :⁠— +- `urn:fdc:ladys.computer:20240204:Caudex:pf:category` for category + metadata -- **`CATEGORY`:** - Indicates that the current record is a category record. - The value of this field gives the identifier for the category. +- `urn:fdc:ladys.computer:20240204:Caudex:pf:entry` for codex entries -- **`CODEX`:** - Indicates that the current record is a codex record. - The value of this field gives the identifier for the codex. +## Metadata -- **`ENTRY`:** - Indicates that the current record is an entry record. - The value of this field gives the identifier for the entry. +Codices, categories, and entries should all have metadata. +For codices and categories, the metadata is provided by a special + 💄📝 Les·M·L file named `~` in `$(CODEXDIR)` or the category + directory, respectively. +The (non‐metadata) contents of this file are presently ignored; in the + future they may be interpreted as a longer‐form description. + +The following metadata fields are recognized by default :⁠— - **`TITLE`:** - For all record types, gives the title of the thing being described. + Gives the title of the thing being described. -If the `@` file is missing from a category directory, none of the +- **`ORDER`:** + Provides a manual ordering of the category or entry. + This must be an integer. + When multiple categories or entries have the same order, they are + then arranged by title. + +If the `~` file is missing from a category directory, none of the entries in the category will be recognized. -However, a minimal `@` file will be created for you when you create an +However, a minimal `~` file will be created for you when you create an entry in a new category using `make +⟨category⟩`. ## Output Files -Assets are installed to their corresponding location in `DESTDIR` - (default: `public/`). -An entry with the identifier `%` will be installed to `%.xhtml`. +Under the hood, 🪾📰 Caudex defines codices as “expanded + archives”—essentially, tarballs that ⛩📰 书社 automatically expands + into their final locations. +This means that it is _not possible_ for a codex to appear in the root + directory of the install location—it must be given a subdirectory. +(Of course, it is always possible to just serve the site from that + subdirectory instead.) -Two index files are created :⁠— `index.xhtml` loads entries - dynamically upon request, and `standalone.xhtml` contains all of the - entries and does not require a network connection. +Within this conceptual archive, two index files are created :⁠— + `index.xhtml` loads entries dynamically upon request, and + `standalone.xhtml` contains all of the entries within its source code + and consequently does not require a network connection. +Both files make use of (minimal) Javascript for full functionality. Output can be customized by supplying additional transforms, ⅌ normal ⛩📰 书社 conventions. The easiest way to customize the transform is to introduce new templates which operate in the `书社:header`, `书社:footer`, or `书社:metadata` modes. - -If you want to customize the actual main body output of 🪾📰 Caudex, - you will need a pattern like this :⁠— - -```xml - - - <书社:id>example:modify-caudex-index - - - -``` +Additionally, the `Caudex:codex-entry` mode is used to process the + contents of codex entries themselves. [LesML]: [Shushe]: -[draft-phillips-record-jar-01]: