From: Lady Date: Sat, 20 Sep 2025 04:57:21 +0000 (-0400) Subject: Refactor to just be a parser & transform X-Git-Tag: 0.3.0^0 X-Git-Url: https://git.ladys.computer/Caudex/commitdiff_plain/cf6053a61ae55de5f3e8f593df94df614618a23f?ds=sidebyside;hp=f52091c8d140d0426975f3e8698daddb067d9103 Refactor to just be a parser & transform As opposed to sitting on top of ⛩📰 书社, restricting codex webpages to basically not containing anything else, 🪾📰 Caudex now (more simply) just provides a parser and transform which can be used _with_ ⛩📰 书社, assuming a properly set up installation. This is more complicated to configure properly (you can¦t just clone the repo and do a `make +category` to get started anymore), but it enables codices to be created and included in other websites, which is really necessary (and also provides much more flexibility with controlling the output). Some areas where the code was too opinionated have been loosened, and the implementation has been simplified into (1) parsing Les·M·L parse results into R·D·F, and (2) transforming that R·D·F into codex pages. The checksum digits have changed to `+!@=U` as these are the only options which work with both ⛩📰 书社 and U·R·N syntaxes. --- diff --git a/.gitmodules b/.gitmodules deleted file mode 100644 index 850d190..0000000 --- a/.gitmodules +++ /dev/null @@ -1,9 +0,0 @@ -# SPDX-FileCopyrightText: 2024 Lady -# SPDX-License-Identifier: CC0-1.0 - -[submodule "LesML"] - path = .💄📝 - url = https://git.ladys.computer/LesML.git -[submodule "书社"] - path = .⛩📰 - url = https://git.ladys.computer/Shushe.git diff --git "a/.\342\233\251\360\237\223\260" "b/.\342\233\251\360\237\223\260" deleted file mode 160000 index 84e79eb..0000000 --- "a/.\342\233\251\360\237\223\260" +++ /dev/null @@ -1 +0,0 @@ -Subproject commit 84e79eb9ea63d28dfa93dfe7d3acd457905cc53e diff --git "a/.\360\237\222\204\360\237\223\235" "b/.\360\237\222\204\360\237\223\235" deleted file mode 160000 index 608a140..0000000 --- "a/.\360\237\222\204\360\237\223\235" +++ /dev/null @@ -1 +0,0 @@ -Subproject commit 608a1404e5b5f27df451d8a4c50c1c356a39a8d5 diff --git a/GNUmakefile b/GNUmakefile index 526170b..3e8888e 100644 --- a/GNUmakefile +++ b/GNUmakefile @@ -1,4 +1,4 @@ -# SPDX-FileCopyrightText: 2024 Lady +# SPDX-FileCopyrightText: 2024, 2025 Lady # SPDX-License-Identifier: MPL-2.0 SHELL = /bin/sh @@ -10,31 +10,28 @@ override define makefileinfo ║╰──────────────────────────────╯ ║ ╟┬ ¶ Prerequisites ───────────────────────────────────────────┬╢ ║│ │║ -║│ Requires G·N·U Make, at least version 3.81, and all of the │║ -║│ requirements of ⛩📰 书社, which is included as a git │║ -║│ submodule. Run `make help-shushe´ for more information. │║ -║╰────────────────────────────────────────────────────────────╯║ -╟┬ ¶ Usage ───────────────────────────────────────────────────┬╢ -║│ │║ -║│ • `make all´ (default): Compile, but do not install, all │║ -║│ files. │║ -║│ │║ -║│ • `make clean´: Remove `BUILDDIR´. │║ +║│ Requires G·N·U Make, at least version 3.81. Otherwise, │║ +║│ only programs specified by Posix are required. The full │║ +║│ list of program requirements is as follows :— │║ ║│ │║ -║│ • `make clean´: Remove `BUILDDIR´. │║ +║│ • awk │║ +║│ • mkdir │║ +║│ • od │║ +║│ • printf │║ +║│ • sed │║ +║│ • test │║ +║│ • tr │║ +║│ • xargs │║ ║│ │║ -║│ • `make gone´: Remove `BUILDDIR´ and installed files. │║ -║│ │║ -║│ • `make help´: Print this message. │║ -║│ │║ -║│ • `make install´: Compile all files and install in │║ -║│ `DESTDIR´. │║ +║│ In all cases, you can supply your own version of any │║ +║│ program `program´ by overriding the corresponding variable │║ +║│ `PROGRAM´ when calling Make. │║ +║╰────────────────────────────────────────────────────────────╯║ +╟┬ ¶ Usage ───────────────────────────────────────────────────┬╢ ║│ │║ -║│ • `make list´: List all recognized source files and their │║ -║│ classification (including media type and dependencies). │║ +║│ • `make help (default)´: Print this message. │║ ║│ │║ -║│ • `make uninstall´: Remove installed files, but not │║ -║│ `BUILDDIR´. │║ +║│ • `make wrmg´: Output a random unused identifier. │║ ║│ │║ ║│ • `make +⟨CATEGORY⟩´: Create a new entry in ⟨CATEGORY⟩ and │║ ║│ output its path. │║ @@ -47,7 +44,7 @@ override define makefileinfo ║╰────────────────────────────────────────────────────────────╯║ ╟┬ ¶ Copyright & License ─────────────────────────────────────┬╢ ║│ │║ -║│ Copyright © 2024 Lady [@ Ladys Computer]. │║ +║│ Copyright © 2024–2025 Lady [@ Ladys Computer]. │║ ║│ │║ ║│ This Source Code Form is subject to the terms of the │║ ║│ Mozilla Public License, v 2.0. If a copy of the M·P·L was │║ @@ -62,76 +59,26 @@ endef # Programs needed to run this make·file. # # If these are not installed on your computer, or you need to use a different implementation, you can override the appropriate variable. -# -# See also the documentation for ⛩📰 书社, which specifies additional programs. AWK := awk -CAT := cat -GIT := git MKDIR := mkdir OD := od PRINTF := printf -RM := rm SED := sed TEST := test TR := tr XARGS := xargs -XMLCATALOG := xmlcatalog # The directory which contains the codex entries and related metadata. -SRCDIR := entries - -# The directory which contains additional assets for the codex generator. -ASSETDIR := assets - -# The directory which contains includes for additional assets for the codex generator. -ASSETINCLUDEDIR := $(ASSETDIR)/includes - -# The directory in which to generate temporary buildfiles. -BUILDDIR := build - -# The directory into which to output files on `make´. -DESTDIR := public +SRCDIR := data/codex -# The location of this Makefile, relative to the current working directory. -# -# It is expected that other files packaged as a part of 🪾📰 Caudex can also be found in this directory. -# -# By default, this is inferred from the variable `MAKEFILE_LIST´. -THISDIR := $(patsubst %/,%,$(dir $(lastword $(MAKEFILE_LIST)))) - -# Extra magic files to forward to ⛩📰 书社. -# -# Your computer probably has several already installed at `/usr/share/file/magic´. -EXTRAMAGIC := - -# Extra parsers to forward to ⛩📰 书社. -# -# Which parsers are provided will influence which kinds of files are recognized as plaintext. -EXTRAPARSERS := - -# Extra transforms to forward to ⛩📰 书社. -EXTRATRANSFORMS := - -# A description of the current git revision of 🪾📰 Caudex. -THISREV := $(shell cd $(THISDIR); $(GIT) describe 2> /dev/null || $(GIT) rev-parse HEAD 2> /dev/null || true) - -# Variables to communicate to further calls to Make. -# -# By default, `MAKEOVERRIDES´ contains all variable overrides specified on the commandline. -# However, some values are specific to 🪾📰 Caudex and may have different meaning in other make·files; filter these out. -MAKEOVERRIDES := $(filter-out SRCDIR=% ASSETDIR=% BUILDDIR=% DESTDIR=% THISDIR=% EXTRAMAGIC=% EXTRAPARSERS=% EXTRATRANSFORMS=% THISREV=%,$(MAKEOVERRIDES)) - -# The location of 💄📝 Les·M·L. -LESML := $(THISDIR)/.💄📝 - -# The location of ⛩📰 书社. -SHUSHE := $(THISDIR)/.⛩📰 +# The default language for new entries. +DOCLANG := en # Set to a non·empty value to print all commands as they run. VERBOSE := # The default target for this makefile. -.DEFAULT_GOAL := all +.DEFAULT_GOAL := help # ━ § BEGIN MAKE·FILE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ @@ -149,117 +96,39 @@ override quote = '$(subst ','"'"',$1)' # Outputs an `@´ to silence rules, unless `VERBOSE´ is nonempty. override silent := $(if $(VERBOSE),,@) -# The list of categories, determined by the set of directories in `SRCDIR´ with corresponding metadata files. -override categories := $(sort $(patsubst $(SRCDIR)/%/@,%,$(wildcard $(SRCDIR)/*/@))) - -# (callable) The set of file locations for the entries of the provided categories. -override entriesforcategory = $(sort $(foreach category,$1,$(wildcard $(SRCDIR)/$(category)/???-????) $(wildcard $(SRCDIR)/$(category)/???-????,*))) - # A random W·R·M·G(·like) base⹀32 identifier. # # This variable returns a different value each time it is referenced. # Use `foreach´ to save the value for repeated usage. # # This variable recursively calls itself to ensure there is no existing entry with the resulting identifier. -override wrmg = $(foreach attempt,$(shell $(OD) -t u4 -N 4 /dev/random | $(SED) 's/^[0-9]* *//' | $(TR) -d ' \n' | $(AWK) 'BEGIN{chars="0123456789ABCDEFGHJKMNPQRSTVWXYZ&~@=U"}{d=32^5;r=$$0%(32^6);printf("%s",substr(chars,r%37,1));while(d>0){printf("%s", substr(chars,int(r/d),1));if(d==32^4)printf("%s", "-");r%=d;d=int(d/32)}}'),$(if $(wildcard $(SRCDIR)/*/($(attempt))*),$(call wrmg),$(attempt))) - -# (callable) Returns the identifiers of the provided entries. -override identifier = $(shell $(PRINTF) '%s\n' $(call quote,$1) | $(TR) ' ' '\n' | $(SED) 's/^\(.*[/]\)\{0,1\}\(.\{3\}-.\{4\}\)\(,[^/]*\)\{0,1\}$$/\2/') - -# Output locations for compiled catalog files for categories. -override categorycatalogs := $(patsubst %,$(BUILDDIR)/catalogs/categories/%/index,$(categories)) - -# Output locations for compiled catalog files for entries. -override entrycatalogs := $(foreach entry,$(call entriesforcategory,$(categories)),$(patsubst $(SRCDIR)/%,$(BUILDDIR)/catalogs/entries/%,$(entry))) - -# Output locations for all compiled catalog files. -override allcatalogs := $(BUILDDIR)/catalogs/indices/index $(BUILDDIR)/catalogs/indices/fullindex $(categorycatalogs) $(entrycatalogs) - -# (overridable) Options to pass to ⛩📰 书社. -override shusheopts := SRCDIR=$(call quote,$(if $(wildcard $(ASSETDIR)),$(ASSETDIR),) $(if $(entrycatalogs),$(BUILDDIR)/catalogs/entries,) $(BUILDDIR)/catalogs/indices) BUILDDIR=$(call quote,$(BUILDDIR)/⛩📰) INCLUDEDIR=$(call quote,$(SRCDIR) $(if $(wildcard $(ASSETINCLUDEDIR)),$(ASSETINCLUDEDIR),) $(if $(categorycatalogs),$(BUILDDIR)/catalogs/categories,)) DESTDIR=$(call quote,$(DESTDIR)) EXTRAMAGIC=$(call quote,$(sort $(patsubst ./%,%,$(wildcard $(THISDIR)/magic/*)) $(LESML)/magic $(EXTRAMAGIC))) EXTRAPARSERS=$(call quote,$(sort $(patsubst ./%,%,$(wildcard $(THISDIR)/parsers/*.xslt)) $(LESML)/parser.xslt $(EXTRAPARSERS))) EXTRATRANSFORMS=$(call quote,$(sort $(patsubst ./%,%,$(wildcard $(THISDIR)/transforms/*.xslt)) $(EXTRATRANSFORMS))) +# +# The checksum digits differ from W·R·M·G to get around limitations in Make and to enable usage with·in a U·R·N. +override wrmg = $(foreach attempt,$(shell $(OD) -t u4 -N 4 /dev/random | $(SED) 's/^[0-9]* *//' | $(TR) -d ' \n' | $(AWK) 'BEGIN{chars="0123456789ABCDEFGHJKMNPQRSTVWXYZ+!@=U"}{d=32^5;r=$$0%(32^6);printf("%s",substr(chars,r%37,1));while(d>0){printf("%s", substr(chars,int(r/d),1));if(d==32^4)printf("%s", "-");r%=d;d=int(d/32)}}'),$(if $(wildcard $(SRCDIR)/*/$(attempt)*),$(call wrmg),$(attempt))) # ─ ¶ Recipe Variable Definitions ───────────────────────────────────── # (callable) Check to see if the given directory exists and create it if not. override ensuredirectory = if $(TEST) ! -d $(call quote,$1); then $(MKDIR) -p $(call quote,$1); fi -# (callable) Test to see if the file provided by the first argument exists and the dependencies provided by the third argument matches the value in the file corresponding to the second argument in `$(BUILDDIR)/lastprereqs´. -# If not, return the fourth argument, plus an additional rule to save the new prerequisites. -# -# ※ If the third argument is empty, the fourth argument is always returned. -override makeandsavedeps = $(if $(or $(if $3,,1),$(if $(wildcard $1),,1),$(subst $(shell $(CAT) $(call quote,$(BUILDDIR)/lastdeps/$2) 2> /dev/null || true),,$3)),$4$(newline)$(silent)$(call ensuredirectory,$(BUILDDIR)/lastdeps)$(newline)$(silent)$(PRINTF) '%s\n' $(call quote,$3) > $(call quote,$(BUILDDIR)/lastdeps/$2),) - -# (callable) Make the catalog for the provided category. -override define makecategorycatalog -@$(PRINTF) '%s\n' $(call quote,Generating catalog for category `$1´…) -$(silent)$(call ensuredirectory,$(BUILDDIR)/catalogs/categories/$1) -$(silent)$(XMLCATALOG) --create --noout $(call quote,$(BUILDDIR)/catalogs/categories/$1/index) -$(silent)$(XMLCATALOG) --add uri '?' 'about:category' --noout $(call quote,$(BUILDDIR)/catalogs/categories/$1/index) -$(silent)$(XMLCATALOG) --add uri '@' $(call quote,$1/@) --noout $(call quote,$(BUILDDIR)/catalogs/categories/$1/index) -$(foreach entry,$(call entriesforcategory,$1),$(silent)$(XMLCATALOG) --add uri $(call quote,$(call identifier,$(entry))) $(call quote,$(patsubst $(SRCDIR)/%,%,$(entry))) --noout $(call quote,$(BUILDDIR)/catalogs/categories/$1/index)$(newline)) -endef - -# (callable) Make the catalog for the dynamic or static index. -override define makeindexcatalog -@$(PRINTF) '%s\n' 'Generating $(if $1,static,dynamic) catalog index…' -$(silent)$(call ensuredirectory,$(BUILDDIR)/catalogs/indices) -$(silent)$(XMLCATALOG) --create --noout $(call quote,$(BUILDDIR)/catalogs/indices/$(if $1,full,)index) -$(silent)$(XMLCATALOG) --add uri '.' '$(if $1,standalone,index).xhtml' --noout $(call quote,$(BUILDDIR)/catalogs/indices/$(if $1,full,)index) -$(silent)$(XMLCATALOG) --add uri '?' 'about:$(if $1,full,)index' --noout $(call quote,$(BUILDDIR)/catalogs/indices/$(if $1,full,)index) -$(silent)$(XMLCATALOG) --add uri '@' '@' --noout $(call quote,$(BUILDDIR)/catalogs/indices/$(if $1,full,)index) -$(foreach category,$(categories),$(silent)$(XMLCATALOG) --add uri $(call quote,$(category)) $(call quote,$(category)/index) --noout $(call quote,$(BUILDDIR)/catalogs/indices/$(if $1,full,)index)$(newline)) -endef - -# ─ ¶ ⛩📰 书社 Targets ────────────────────────────────────────────── - -# Targets to forward to ⛩📰 书社. -all install list uninstall : $(SHUSHE)/GNUmakefile catalogs - $(silent)$(MAKE) -f $(call quote,$<) $(call quote,$@) $(shusheopts) -%-shushe : $(SHUSHE)/GNUmakefile FORCE - $(silent)$(MAKE) -f $(call quote,$<) $(call quote,$*) $(shusheopts) -build/⛩📰/% : $(SHUSHE)/GNUmakefile catalogs FORCE - $(SILENT)$(MAKE) -f $(call quote,$<) $(call quote,$@) $(shusheopts) -public/% : $(SHUSHE)/GNUmakefile catalogs FORCE - $(SILENT)$(MAKE) -f $(call quote,$<) $(call quote,$@) $(shusheopts) - # ─ ¶ Phony Targets ─────────────────────────────────────────────────── -# Generate all catalogs, then remove any which no longer have corresponding source files. -catalogs : $(allcatalogs) - @$(PRINTF) '%s\n' 'Removing any outdated catalogs…' - $(foreach deletedcategory,$(filter-out $(categorycatalogs),$(wildcard $(BUILDDIR)/catalogs/categories/*/index)),@$(PRINTF) '%s\n' $(call quote,Removing `$(patsubst $(BUILDDIR)/catalogs/categories/%/index,%,$(deletedcategory))´…)$(newline)$(silent)$(RM) -rf $(call quote,./$(dir $(deletedcategory)))$(newline)$(silent)$(RM) -rf $(call quote,./$(patsubst $(BUILDDIR)/catalogs/categories/%,$(BUILDDIR)/catalogs/entries/%,$(dir $(deletedcategory))))$(newline)) - $(foreach deletedentry,$(filter-out $(entrycatalogs),$(wildcard $(BUILDDIR)/catalogs/entries/*/*)),@$(PRINTF) '%s\n' $(call quote,Removing `$(patsubst $(BUILDDIR)/catalogs/entries/%,%,$(deletedentry))´…)$(newline)$(silent)$(RM) $(call quote,./$(deletedentry))$(newline)) - -# Destroy buildfiles. -clean: - $(if $(BUILDDIR),$(silent)$(RM) -rf $(call quote,$(BUILDDIR)/),) - # Provide help. help : - @$(PRINTF) '%b' '$(subst $(newline),\n,$(makefileinfo))' - -# Destroy build directory and installed files. -gone : clean uninstall ; - -# List the i·d’s of all recognized entries. -listids : - @$(TR) '| ' ' \n' <<< '$(strip $(foreach category,$(categories),\0033[1m$(category)\0033[22m: $(patsubst %,•|%,$(call identifier,$(call entriesforcategory,$(category)))) ))' | $(XARGS) -0 $(PRINTF) '%b' + @$(PRINTF) '%b' $(call quote,$(subst $(newline),\n,$(makefileinfo))) # Output a random unused identifier. wrmg : @$(PRINTF) '%s\n' $(wrmg) # Create a new entry in the provided category and output its path. -+% : FORCE ++% : $(SRCDIR)/~ FORCE $(silent)$(call ensuredirectory,$(SRCDIR)/$*) - $(if $(wildcard $(SRCDIR)/$*/@),,$(silent)$(PRINTF) '%b' '%%\nCATEGORY : $*\n%%\n' > '$(SRCDIR)/$*/@') - $(foreach identifier,$(wrmg),@$(PRINTF) '%b' '\0043!lesml\nENTRY : $(identifier)\n%%\n\n' > '$(SRCDIR)/$*/$(identifier)'$(newline)@$(PRINTF) '%s\n' '$(SRCDIR)/$*/$(identifier)') + $(if $(wildcard $(SRCDIR)/$*/~),,$(silent)$(PRINTF) '%b@%s$$ profile=urn:fdc:ladys.computer:20240204:Caudex:pf:category\n%s\n' '\0043!lesml' '$(DOCLANG)' '%%' >|$(call quote,$(SRCDIR)/$*/~)) + $(foreach identifier,$(wrmg),$(silent)$(PRINTF) '%b@%s$$ profile=urn:fdc:ladys.computer:20240204:Caudex:pf:entry\n%s\n' '\0043!lesml' '$(DOCLANG)' '%%' >|$(call quote,$(SRCDIR)/$*/$(identifier))$(newline)$(silent)$(PRINTF) '%s\n' $(call quote,$(SRCDIR)/$*/$(identifier))) # ─ ¶ Special Targets ───────────────────────────────────────────────── -# Perform secondary expansion; this enables pattern rules to determine their prerequisites based on the matched pattern. -.SECONDEXPANSION : ; - # Don’t use any implicit rules. .SUFFIXES : ; @@ -269,43 +138,10 @@ wrmg : FORCE : ; # Phony rules; always consider these out·of·date. -.PHONY : FORCE all build catalogs clean gone help install list listids uninstall wrmg ; +.PHONY : FORCE help wrmg ; # ─ ¶ Build Targets ─────────────────────────────────────────────────── -# Initialize the ⛩📰 书社 repository if it is empty. -ifneq ($(filter $(THISDIR)/%,$(SHUSHE)),) -$(SHUSHE)/GNUmakefile : $(THISDIR)/%/GNUmakefile : - @$(PRINTF) '%s\n' $(call quote,Initializing git submodule at `$*´) - $(silent)cd $(THISDIR) && $(GIT) submodule update --init $(call quote,$*) -endif - -# Initialize the 💄📝 Les·M·L repository if it is empty. -ifneq ($(filter $(THISDIR)/%,$(LESML)),) -$(LESML)/parser.xslt : $(THISDIR)/%/parser.xslt : - @$(PRINTF) '%s\n' $(call quote,Initializing git submodule at `$*´) - $(silent)cd $(THISDIR) && $(GIT) submodule update --init $(call quote,$*) -endif - # Create an empty codex metadata file if none exists. -$(SRCDIR)/@ : - $(silent)$(PRINTF) '%b' '%%\nCODEX :\n%%\n' > $(call quote,$@) - -# Create category catalogs. -$(categorycatalogs) : $(BUILDDIR)/catalogs/categories/%/index : FORCE - $(call makeandsavedeps,$@,$*,$(call entriesforcategory,$*),$(call makecategorycatalog,$*)) - -# Create entry catalogs. -$(entrycatalogs) : $(BUILDDIR)/catalogs/entries/% : - @$(PRINTF) '%s\n' $(call quote,Generating catalog for document `$(call identifier,$*)´…) - $(silent)$(call ensuredirectory,$(dir $@)) - $(silent)$(XMLCATALOG) --create --noout $(call quote,$@) - $(silent)$(XMLCATALOG) --add uri '.' '$(call identifier,$*).xhtml' --noout $(call quote,$@) - $(silent)$(XMLCATALOG) --add uri '?' 'about:entry' --noout $(call quote,$@) - $(silent)$(XMLCATALOG) --add uri '@' $(call quote,$*) --noout $(call quote,$@) - -$(BUILDDIR)/catalogs/indices/index : FORCE | $(SRCDIR)/@ - $(call makeandsavedeps,$@,index,$(categories),$(call makeindexcatalog,)) - -$(BUILDDIR)/catalogs/indices/fullindex : FORCE | $(SRCDIR)/@ - $(call makeandsavedeps,$@,fullindex,$(categories),$(call makeindexcatalog,1)) +$(SRCDIR)/~ : + $(silent)$(PRINTF) '%b@%s$$ profile=urn:fdc:ladys.computer:20240204:Caudex:pf:codex\n%s\n' '\0043!lesml' '$(DOCLANG)' '%%' >|$(call quote,$@) diff --git a/README.markdown b/README.markdown index 778a4cb..af420df 100644 --- a/README.markdown +++ b/README.markdown @@ -1,5 +1,5 @@ # 🪾📰 Caudex @@ -7,14 +7,22 @@ SPDX-License-Identifier: CC0-1.0 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 @@ -23,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 @@ -54,200 +57,139 @@ 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 + +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. -- **`ENTRY`:** - Indicates that the current record is an entry record. - The value of this field gives the identifier for the entry. +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 +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]: diff --git a/parser.xslt b/parser.xslt new file mode 100644 index 0000000..d20da12 --- /dev/null +++ b/parser.xslt @@ -0,0 +1,134 @@ + + + + + +]> + + <书社:id>urn:fdc:ladys.computer:20240204:Caudex:parser.xslt + + + + diff --git a/parsers/catalog.xslt b/parsers/catalog.xslt deleted file mode 100644 index c1f4883..0000000 --- a/parsers/catalog.xslt +++ /dev/null @@ -1,57 +0,0 @@ - - - - - <书社:id>urn:fdc:ladys.computer:20240204:Caudex:catalog.xslt - - - diff --git a/transform.xslt b/transform.xslt new file mode 100644 index 0000000..a614363 --- /dev/null +++ b/transform.xslt @@ -0,0 +1,321 @@ + + + + + +]> + + <书社:id>urn:fdc:ladys.computer:20240204:Caudex:transform.xslt + + + + + + diff --git a/transforms/entry.xslt b/transforms/entry.xslt deleted file mode 100644 index 2021e7f..0000000 --- a/transforms/entry.xslt +++ /dev/null @@ -1,60 +0,0 @@ - - - - - - -]> - - <书社:id>&Caudex;entry.xslt - - diff --git a/transforms/index.xslt b/transforms/index.xslt deleted file mode 100644 index fdcfe8b..0000000 --- a/transforms/index.xslt +++ /dev/null @@ -1,205 +0,0 @@ - - - - - - -]> - - <书社:id>&Caudex;index.xslt - - diff --git a/transforms/metadata.xslt b/transforms/metadata.xslt deleted file mode 100644 index 810b6a6..0000000 --- a/transforms/metadata.xslt +++ /dev/null @@ -1,41 +0,0 @@ - - - - - <书社:id>urn:fdc:ladys.computer:20240204:Caudex:metadata.xslt - -