X-Git-Url: https://git.ladys.computer/Caudex/blobdiff_plain/94025c0529851882c0e1c1fa6b61491a5979ada9..refs/heads/current:/README.markdown?ds=inline diff --git a/README.markdown b/README.markdown index d0c0d0d..778a4cb 100644 --- a/README.markdown +++ b/README.markdown @@ -1,3 +1,7 @@ +<!-- +SPDX-FileCopyrightText: 2024 Lady <https://www.ladys.computer/about/#lady> +SPDX-License-Identifier: CC0-1.0 +--> # 📰 Caudex <b>A simple codex generator.</b> @@ -5,7 +9,7 @@ <dfn>📰 Caudex</dfn> is a static website generator aimed at generating simple, category⹀based lists of documents akin to the “Codex” feature of games like <cite>Dragon Age</cite>. -It is built on top of [⛩️📰 书社][Shushe] and consequently inherits +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 @@ -73,10 +77,10 @@ $(CAUDEX)/GNUmakefile: ## Setup and Configuration -📰 Caudex inherits all of the dependencies of ⛩️📰 书社 and enables +📰 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 +In addition to the configuration variables for ⛩📰 书社, the following variables are recognized and treated specially by 📰 Caudex :— @@ -108,7 +112,7 @@ In addition to the configuration variables for ⛩️📰 书社, the 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 + 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 @@ -120,13 +124,13 @@ In addition to the configuration variables for ⛩️📰 书社, the need to be set manually. - **`EXTRAMAGIC`:** - Additional magic files for ⛩️📰 书社. + Additional magic files for ⛩📰 书社. - **`EXTRAPARSERS`:** - Additional parsers for ⛩️📰 书社. + Additional parsers for ⛩📰 书社. - **`EXTRATRANSFORMS`:** - Additional transforms for ⛩️📰 书社. + Additional transforms for ⛩📰 书社. - **`GENERATOR`:** The name of the generator program (default: `📰 Caudex`). @@ -156,44 +160,18 @@ The command `make +⟨category⟩` is provided as a convenience to create 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 file·name still needs to be compatible with ⛩📰 书社 and Make (it must not contain spaces or other fraught Ascii characters). -Entries should be of the `text/x.codex-entry` format, which is defined - as follows :— - -1. The string `%%`, followed by a newline and - -2. A [Record Jar][draft-phillips-record-jar-01] record starting with - `ENTRY :`, followed by - -3. Any number of additional records, followed by - -4. Zero or more lines of (mostly⹀)plain text. - -For example :— - -```txt -%% -ENTRY : 30W-5M41 -TITLE : My Amazing Entry -%% - -This is the text of my amazing entry. -``` - -The text of the entry is processed minimally: -It is broken into paragraphs on blank lines, and paragraphs for which - each line begins with white·space are considered block quotations. -All other whitespace is trimmed and collapsed. +Entries need to be in [💄📝 Les·M·L][LesML] format. ## Metadata Codices, categories, and entries should all have metadata. For entries, the metadata is provided by the record which begins the - `text/x.codex-entry` format. -For codicies and categories, the metadata is provided by a special file + 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. @@ -230,7 +208,7 @@ Two index files are created :— `index.xhtml` loads entries entries and does not require a network connection. Output can be customized by supplying additional transforms, ⅌ normal - ⛩️📰 书社 conventions. + ⛩📰 书社 conventions. The easiest way to customize the transform is to introduce new templates which operate in the `书社:header`, `书社:footer`, or `书社:metadata` modes. @@ -270,5 +248,6 @@ If you want to customize the actual main body output of 📰 Caudex, </transform> ``` +[LesML]: <https://git.ladys.computer/LesML> [Shushe]: <https://git.ladys.computer/Shushe> [draft-phillips-record-jar-01]: <https://datatracker.ietf.org/doc/html/draft-phillips-record-jar-01>