Add basic Les·M·L documentation generation

diff --git a/.gitignore b/.gitignore
index 16119d3a746b15d7dbeb74988626ee572372635a..38b847a260505a95257ad9fcc928ac21ca042607 100644 (file)
--- a/.gitignore
+++ b/.gitignore
@@ -8,5 +8,6 @@ VERSION
 cgirls
 cgirls-test-*
 !cgirls-test-*.c
+doc/
 make/config.mak
 test/*/logs

diff --git a/.gitmodules b/.gitmodules
index 4604ce6f9b63daa8f413d0342c21e51b45da43db..a2bdd95bb76a79c1a69d9f22ff67522f9a74cc4c 100644 (file)
--- a/.gitmodules
+++ b/.gitmodules
@@ -4,3 +4,6 @@
 [submodule "Git"]
        path = Git
        url = https://git.kernel.org/pub/scm/git/git.git
+[submodule "LesML"]
+       path = LesML
+       url = https://git.ladys.computer/LesML.git

diff --git a/GNUmakefile b/GNUmakefile
index bd9639b7d49a3fc025684b73055788e57db9b530..dd28fba944c2f8279f504ed6e57939783cf8fbe5 100644 (file)
--- a/GNUmakefile
+++ b/GNUmakefile
@@ -10,7 +10,7 @@ GITDIR := Git
 CGIRLS_VERSION := 0.1.0
 GIT_VERSION := 2.49.0
 
-all : cgirls cgirls-tests ;
+all : cgirls cgirls-tests documentation ;
 
 -include $(GITDIR)/config.mak.uname
 -include $(GITDIR)/shared.mak
@@ -24,6 +24,9 @@ cgirls cgirls-tests :
 cgirls-test-% : FORCE
        $(QUIET_SUBDIR0)Git $(QUIET_SUBDIR1) -f ../make/cgirls.mak ../$@ $(EXTRA_GIT_TARGETS) NO_PERL=1 NO_GITWEB=1 NO_PYTHON=1 NO_TCLTK=1 NO_GETTEXT=1 NO_EXPAT=1 NO_CURL=1
 
+documentation : FORCE
+       @$(MAKE) -f make/documentation.mak $@
+
 $(GITDIR)/shared.mak : %/shared.mak : FORCE
        $(GIT) submodule update --init '$*'
 

diff --git a/LesML b/LesML
new file mode 160000 (submodule)
index 0000000..27fb10d
--- /dev/null
+++ b/LesML
@@ -0,0 +1 @@
+Subproject commit 27fb10d1b6e7ce74d4af82888c0ef3fdc6870f8d

diff --git a/README b/README
new file mode 100644 (file)
index 0000000..bd5b560
--- /dev/null
+++ b/README
@@ -0,0 +1,3 @@
+#!lesml@en$
+
+⁌ C·Girls Readme

diff --git a/make/documentation.mak b/make/documentation.mak
new file mode 100644 (file)
index 0000000..cf80196
--- /dev/null
+++ b/make/documentation.mak
@@ -0,0 +1,79 @@
+#!/bin/sh
+# SPDX-FileCopyrightText: 2025 Lady <https://www.ladys.computer/about/#lady>
+# SPDX-License-Identifier: MPL-2.0
+
+SHELL = /bin/sh
+
+# 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 not distributed with this file, You can obtain one at <https://mozilla.org/MPL/2.0/>.
+
+# This make·file should be run from the root of the source directory.
+
+CAT := cat
+GIT := git
+MKDIR := mkdir
+PRINTF := printf
+SED := gsed
+TEST := test
+XARGS := xargs
+XSLTPROC := xsltproc
+
+LESML := LesML
+
+DOCDIR := doc
+
+PROJECT_NAME := C·Girls
+
+HEADER_FILES = $(sort $(patsubst ./%,%,$(shell find . '(' -path '.' -o -prune ')' -a -type f -a  -name '*.h')))
+DOCUMENTATION_FILES = $(patsubst %.h,$(DOCDIR)/%.xhtml,$(HEADER_FILES))
+
+documentation : $(DOCDIR)/README.xhtml $(DOCUMENTATION_FILES) $(DOCDIR)/index.xhtml ;
+
+# (callable) Strip portions between `(*´ and `*)´ and collapse newlines in the argument.
+# Backslash sequences in the argument are handled ⅌ `printf´.
+# Single quotes must not appear in the argument or this will break.
+makeunreadable = $(shell LANG=C LC_ALL=C printf '%s\n' '$(subst $(newline),$(space),$1)' | $(SED) 's/^ *//;s/ *$$//;s/ *([*][^*]*[*]) *//g' | $(XARGS) -0 $(PRINTF) '%b\n')
+
+define readablesedcmd
+\\@^/[*]$$@,\\@^[\t]*[*]/$$@d; (*delete multiline comments*)
+\\@^/[*][^*]*.?[^/]*[*]/$$@d; (*delete singleline traditional comments*)
+\\@^//@d; (*delete singleline newstyle comments*)
+\\@^/[*][*]$$@s@^.*$$@@; (*delete start of documentation comments (leaving newline)*)
+\\@^ [*][*]//*$$@s@^.*$$@@; (*delete end of documentation comments (leaving newline)*)
+\\@^ [*][*]$$@s@$$@ @; (*add trailing space to empty documentation comment lines*)
+\\@^ [*][*] @!{\\@.@s@^@\t|`@;\\@.@s@$$@´@;}; (*format non·empty lines of code*)
+\\@^ [*][*] @{s@^ [*][*] [ \t]*@@;s@ :—@ :⁠—@g;s@« @« @g;s@‹ @‹ @g;s@—: @—⁠: @g;s@ »@ »@g;s@ ›@ ›@g;s@{<\\([^>]*\\)[.]h>}@{🔗`\\1`<./\\1>}@;}; (*drop prefix from documentation lines and format*)
+endef
+sedcmd := $(call makeunreadable,$(readablesedcmd))
+
+define readablestylesheet
+@charset "UTF-8";
+article{ Margin: Auto; Width: Min-Content; Max-Width: 100% }
+article::after{ Display: Block; Width: 31REM; Max-Width: 100%; Min-Width: 100%; Content: "" }
+blockquote>pre{ Margin: Auto; Width: 71CH; Max-Width: 100%; White-Space: Pre-Wrap }
+blockquote>pre+pre{ Margin-Top: 1LH }
+endef
+stylesheet := $(call makeunreadable,$(readablestylesheet))
+
+# The first argument should be shell commands producing Les·M·L; the second should be the title of the page.
+processlesml = { $(PRINTF) '%s\n' '<?xml version="1.0"?>' '<html xmlns="http://www.w3.org/1999/xhtml"><head><title>$2</title><style>$(stylesheet)</style></head><body>'; { $(PRINTF) '%s\n%s' '<?xml version="1.0"?>' '<script xmlns="http://www.w3.org/1999/xhtml" type="text/lesml"><![CDATA['; $1; $(PRINTF) '\n%s\n' ']]></script>'; } | xsltproc $(LESML)/parser.xslt - | $(SED) '1{/^<?xml/d;}'; $(PRINTF) '%s\n' '</body></html>' ; }
+
+$(DOCUMENTATION_FILES) : $(DOCDIR)/%.xhtml : %.h $(LESML)/parser.xslt
+       @if $(TEST) '!' -d $(DOCDIR); then $(MKDIR) -p $(DOCDIR); fi
+       @$(PRINTF) '%s\n' 'Building documentation for <$<>…' >&2
+       @$(call processlesml,$(PRINTF) '%s\n\n' '#!lesml@en$$' '⁌ Documentation for `<$<>´'; $(SED) '$(sedcmd)' <'$<'; $(PRINTF) '\n\n%s' '⁂' 'A part of {🔗$(PROJECT_NAME) Documentation<./index.xhtml>}.',Documentation for &lt;$<&gt; | $(PROJECT_NAME) Documentation) >|'$@'
+
+
+$(DOCDIR)/README.xhtml : README $(LESML)/parser.xslt
+       @$(PRINTF) '%s\n' 'Building documentation README…' >&2
+       @$(call processlesml,$(CAT) README; $(PRINTF) '\n\n%s' '⁂' 'A part of {🔗$(PROJECT_NAME) Documentation<./index.xhtml>}.',$(PROJECT_NAME) Readme | $(PROJECT_NAME) Documentation) >|'$@'
+
+$(DOCDIR)/index.xhtml : FORCE $(LESML)/parser.xslt
+       @$(PRINTF) '%s\n' 'Building documentation index…' >&2
+       @$(call processlesml,$(PRINTF) '%s\n\n' '#!lesml@en$$' '⁌ $(PROJECT_NAME) Documentation' '• {🔗$(PROJECT_NAME) Readme<./README.xhtml>}'$(foreach header,$(HEADER_FILES), '• {🔗Documentation for `$(header)´<./$(patsubst %.h,./%.xhtml,$(header))>}'),$(PROJECT_NAME) Documentation) >|'$@'
+
+$(LESML)/parser.xslt : %/parser.xslt : FORCE
+       $(GIT) submodule update --init '$*'
+
+FORCE : ;
+.PHONY : FORCE documentation