Lady’s Gitweb - CGirls/blob - make/documentation.mak

   1 #!/bin/sh
   2 # SPDX-FileCopyrightText: 2025 Lady <https://www.ladys.computer/about/#lady>
   3 # SPDX-License-Identifier: MPL-2.0
   4
   5 SHELL = /bin/sh
   6
   7 # This Source Code Form is subject to the terms of the Mozilla Public License, v 2.0.
   8 # 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/>.
   9
  10 # This make·file should be run from the root of the source directory.
  11
  12 CAT := cat
  13 GIT := git
  14 MKDIR := mkdir
  15 PRINTF := printf
  16 SED := gsed
  17 TEST := test
  18 XARGS := xargs
  19 XSLTPROC := xsltproc
  20
  21 LESML := LesML
  22
  23 DOCDIR := doc
  24
  25 PROJECT_NAME := C·Girls
  26
  27 HEADER_FILES = $(sort $(patsubst ./%,%,$(shell find . '(' -path '.' -o -prune ')' -a -type f -a  -name '*.h')))
  28 DOCUMENTATION_FILES = $(patsubst %.h,$(DOCDIR)/%.xhtml,$(HEADER_FILES))
  29
  30 documentation : $(DOCDIR)/README.xhtml $(DOCUMENTATION_FILES) $(DOCDIR)/index.xhtml ;
  31
  32 # (callable) Strip portions between `(*´ and `*)´ and collapse newlines in the argument.
  33 # Backslash sequences in the argument are handled ⅌ `printf´.
  34 # Single quotes must not appear in the argument or this will break.
  35 makeunreadable = $(shell LANG=C LC_ALL=C printf '%s\n' '$(subst $(newline),$(space),$1)' | $(SED) 's/^ *//;s/ *$$//;s/ *([*][^*]*[*]) *//g' | $(XARGS) -0 $(PRINTF) '%b\n')
  36
  37 define readablesedcmd
  38 \\@^/[*]$$@,\\@^[\t]*[*]/$$@d; (*delete multiline comments*)
  39 \\@^/[*][^*]*.?[^/]*[*]/$$@d; (*delete singleline traditional comments*)
  40 \\@^//@d; (*delete singleline newstyle comments*)
  41 \\@^/[*][*]$$@s@^.*$$@@; (*delete start of documentation comments (leaving newline)*)
  42 \\@^ [*][*]//*$$@s@^.*$$@@; (*delete end of documentation comments (leaving newline)*)
  43 \\@^ [*][*]$$@s@$$@ @; (*add trailing space to empty documentation comment lines*)
  44 \\@^ [*][*] @!{\\@.@s@^@\t|`@;\\@.@s@$$@´@;}; (*format non·empty lines of code*)
  45 \\@^ [*][*] @{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*)
  46 endef
  47 sedcmd := $(call makeunreadable,$(readablesedcmd))
  48
  49 define readablestylesheet
  50 @charset "UTF-8";
  51 article{ Margin: Auto; Width: Min-Content; Max-Width: 100% }
  52 article::after{ Display: Block; Width: 31REM; Max-Width: 100%; Min-Width: 100%; Content: "" }
  53 blockquote>pre{ Margin: Auto; Width: 71CH; Max-Width: 100%; White-Space: Pre-Wrap }
  54 blockquote>pre+pre{ Margin-Top: 1LH }
  55 endef
  56 stylesheet := $(call makeunreadable,$(readablestylesheet))
  57
  58 # The first argument should be shell commands producing Les·M·L; the second should be the title of the page.
  59 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>' ; }
  60
  61 $(DOCUMENTATION_FILES) : $(DOCDIR)/%.xhtml : %.h $(LESML)/parser.xslt
  62         @if $(TEST) '!' -d $(DOCDIR); then $(MKDIR) -p $(DOCDIR); fi
  63         @$(PRINTF) '%s\n' 'Building documentation for <$<>…' >&2
  64         @$(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) >|'$@'
  65
  66
  67 $(DOCDIR)/README.xhtml : README $(LESML)/parser.xslt
  68         @$(PRINTF) '%s\n' 'Building documentation README…' >&2
  69         @$(call processlesml,$(CAT) README; $(PRINTF) '\n\n%s' '⁂' 'A part of {🔗$(PROJECT_NAME) Documentation<./index.xhtml>}.',$(PROJECT_NAME) Readme | $(PROJECT_NAME) Documentation) >|'$@'
  70
  71 $(DOCDIR)/index.xhtml : FORCE $(LESML)/parser.xslt
  72         @$(PRINTF) '%s\n' 'Building documentation index…' >&2
  73         @$(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) >|'$@'
  74
  75 $(LESML)/parser.xslt : %/parser.xslt : FORCE
  76         $(GIT) submodule update --init '$*'
  77
  78 FORCE : ;
  79 .PHONY : FORCE documentation