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 \\@^ [*][*] @!{ (*format non·empty lines of code*)
  45         s@/[*]\\([^* ]*\\)[*]/@\\1@g; (*explicit formatting*)
  46         \\@/[*][^ ]*[*]/@!{ (*autoformat lines without explicit formatting*)
  47                 s@^\0043ifndef \\([^ ]*\\)@\0043ifndef ⟨\\1⟩@; (*macro ifndef*)
  48                 s@^\0043define \\([^ ]*\\)@\0043define ⟨\\1⟩@; (*macro define*)
  49                 s@^\0043endif /[*] \\([^ ]*\\) [*]/@\0043endif /* ⟨\\1⟩ */@; (*macro define*)
  50                 \\@\t*[?:]@!s@^\\(\t\t*\\)\\([^ ]*\\);@\\1⟨\\2⟩;@; (*handle (presumed) enum members without assignment*)
  51                 \\@\t*[?:]@!s@^\\(\t\t*\\)\\([^ ]*\\) =@\\1⟨\\2⟩ =@; (*handle (presumed) enum members with assignment*)
  52                 \\@\t*[?:]@!s@^\\(\t\t*\\)\\([^= ]\\( *[^= ]\\)*\\) \\([^ ][^ ]*\\);@\\1⸤\\2⸥ ⟨\\4⟩;@; (*handle (presumed) struct members*)
  53                 s@^\\(constexpr \\)*\\([^\t= ]\\( *[^= ]\\)*\\) \\([^= ][^= ]*\\) =@\\1⸤\\2⸥ ⟨\\4⟩ =@; (*handle file‐scope assignments*)
  54                 s@^enum \\([^ ][^ ]*\\)@enum ⸤\\1⸥@; (*enum declarations*)
  55                 \\@^enum@s@: \\([^{]*[^{ ]\\)@: ⸤\\1⸥@; (*enum underlying values*)
  56                 s@^struct \\([^ ][^ ]*\\)@struct ⸤\\1⸥@; (*struct declarations*)
  57                 s@^typedef \\([^ ]\\( *[^ ]\\)*\\) \\([^ ][^ ]*\\);@typedef ⸤\\1⸥ ⸤\\3⸥;@; (*typedef definitions*)
  58                 \\@^[^\t ][^\t ]* [^ ][^ ]*(@s@, *@⸥, ⸤@g; (*format function arguments*)
  59                 s@^\\([^\t ][^ ]*\\) \\([^ ][^ ]*\\)(\\([^)][^)]*\\))@⸤\\1⸥ ⟨\\2⟩(⸤\\3⸥)@; (*format functions*)
  60                 s@\\(//.*\\)$$@⟦\\1⟧@; (*format comments*)
  61         };
  62         \\@.@s@^@\t|`@; (*format beginning of line*)
  63         \\@.@s@$$@´@; (*format end of line*)
  64 };
  65 \\@^ [*][*] @{ (*format documentation*)
  66         s@^ [*][*] [ \t]*@@; (*drop documentation leader*)
  67         s@ :—@ :⁠—@g; (*fixup spacing for :—*)
  68         s@« @« @g; (*fixup spacing for «*)
  69         s@‹ @‹ @g; (*fixup spacing for ‹*)
  70         s@—: @—⁠: @g; (*fixup spacing for —:*)
  71         s@ »@ »@g; (*fixup spacing for »*)
  72         s@ ›@ ›@g; (*fixup spacing for ›*)
  73         s@{<\\([^>]*\\)[.]h>}@{🔗`\\1`<./\\1>}@g; (*header file linking*)
  74 };
  75 endef
  76 sedcmd := $(call makeunreadable,$(readablesedcmd))
  77
  78 # The first argument should be shell commands producing Les·M·L; the second should be the title of the page.
  79 processlesml = { $(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 --stringparam PROJECT_NAME '$(PROJECT_NAME)' --stringparam TITLE '$2' xslt/documentation.xslt -
  80
  81 $(DOCUMENTATION_FILES) : $(DOCDIR)/%.xhtml : %.h $(LESML)/parser.xslt xslt/documentation.xslt
  82         @if $(TEST) '!' -d $(DOCDIR); then $(MKDIR) -p $(DOCDIR); fi
  83         @$(PRINTF) '%s\n' 'Building documentation for <$<>…' >&2
  84         @$(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 <$<>) >|'$@'
  85
  86
  87 $(DOCDIR)/README.xhtml : README $(LESML)/parser.xslt xslt/documentation.xslt
  88         @$(PRINTF) '%s\n' 'Building documentation README…' >&2
  89         @$(call processlesml,$(CAT) README; $(PRINTF) '\n\n%s' '⁂' 'A part of {🔗$(PROJECT_NAME) Documentation<./index.xhtml>}.',$(PROJECT_NAME) Readme) >|'$@'
  90
  91 $(DOCDIR)/index.xhtml : FORCE $(LESML)/parser.xslt xslt/documentation.xslt
  92         @$(PRINTF) '%s\n' 'Building documentation index…' >&2
  93         @$(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))>}'),) >|'$@'
  94
  95 $(LESML)/parser.xslt : %/parser.xslt : FORCE
  96         $(GIT) submodule update --init '$*'
  97
  98 FORCE : ;
  99 .PHONY : FORCE documentation