Improve documentation generation

[CGirls] / make / documentation.mak

diff --git a/make/documentation.mak b/make/documentation.mak
index cf80196221ad0767de488f4b25e9b893d0191c55..9946ed82f99a48941c70469739ebad4cf072bcc0 100644 (file)
--- a/make/documentation.mak
+++ b/make/documentation.mak
@@ -32,7 +32,7 @@ documentation : $(DOCDIR)/README.xhtml $(DOCUMENTATION_FILES) $(DOCDIR)/index.xh
 # (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.
 # (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')
+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*)
 
 define readablesedcmd
 \\@^/[*]$$@,\\@^[\t]*[*]/$$@d; (*delete multiline comments*)


@@ -41,36 +41,56 @@ define readablesedcmd
 \\@^/[*][*]$$@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@^.*$$@@; (*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*)
+\\@^ [*][*] @!{ (*format non·empty lines of code*)
+       s@/[*]\\([^* ]*\\)[*]/@\\1@g; (*explicit formatting*)
+       \\@/[*][^ ]*[*]/@!{ (*autoformat lines without explicit formatting*)
+               s@^\0043ifndef \\([^ ]*\\)@\0043ifndef ⟨\\1⟩@; (*macro ifndef*)
+               s@^\0043define \\([^ ]*\\)@\0043define ⟨\\1⟩@; (*macro define*)
+               s@^\0043endif /[*] \\([^ ]*\\) [*]/@\0043endif /* ⟨\\1⟩ */@; (*macro define*)
+               \\@\t*[?:]@!s@^\\(\t\t*\\)\\([^ ]*\\);@\\1⟨\\2⟩;@; (*handle (presumed) enum members without assignment*)
+               \\@\t*[?:]@!s@^\\(\t\t*\\)\\([^ ]*\\) =@\\1⟨\\2⟩ =@; (*handle (presumed) enum members with assignment*)
+               \\@\t*[?:]@!s@^\\(\t\t*\\)\\([^= ]\\( *[^= ]\\)*\\) \\([^ ][^ ]*\\);@\\1⸤\\2⸥ ⟨\\4⟩;@; (*handle (presumed) struct members*)
+               s@^\\(constexpr \\)*\\([^\t= ]\\( *[^= ]\\)*\\) \\([^= ][^= ]*\\) =@\\1⸤\\2⸥ ⟨\\4⟩ =@; (*handle file‐scope assignments*)
+               s@^enum \\([^ ][^ ]*\\)@enum ⸤\\1⸥@; (*enum declarations*)
+               \\@^enum@s@: \\([^{]*[^{ ]\\)@: ⸤\\1⸥@; (*enum underlying values*)
+               s@^struct \\([^ ][^ ]*\\)@struct ⸤\\1⸥@; (*struct declarations*)
+               s@^typedef \\([^ ]\\( *[^ ]\\)*\\) \\([^ ][^ ]*\\);@typedef ⸤\\1⸥ ⸤\\3⸥;@; (*typedef definitions*)
+               \\@^[^\t ][^\t ]* [^ ][^ ]*(@s@, *@⸥, ⸤@g; (*format function arguments*)
+               s@^\\([^\t ][^ ]*\\) \\([^ ][^ ]*\\)(\\([^)][^)]*\\))@⸤\\1⸥ ⟨\\2⟩(⸤\\3⸥)@; (*format functions*)
+               s@\\(//.*\\)$$@⟦\\1⟧@; (*format comments*)
+       };
+       \\@.@s@^@\t|`@; (*format beginning of line*)
+       \\@.@s@$$@´@; (*format end of line*)
+};
+\\@^ [*][*] @{ (*format documentation*)
+       s@^ [*][*] [ \t]*@@; (*drop documentation leader*)
+       s@ :—@ :⁠—@g; (*fixup spacing for :—*)
+       s@« @« @g; (*fixup spacing for «*)
+       s@‹ @‹ @g; (*fixup spacing for ‹*)
+       s@—: @—⁠: @g; (*fixup spacing for —:*)
+       s@ »@ »@g; (*fixup spacing for »*)
+       s@ ›@ ›@g; (*fixup spacing for ›*)
+       s@{<\\([^>]*\\)[.]h>}@{🔗`\\1`<./\\1>}@g; (*header file linking*)
+};

 endef
 sedcmd := $(call makeunreadable,$(readablesedcmd))
 
 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.
 # 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>' ; }
+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 -

 
 

-$(DOCUMENTATION_FILES) : $(DOCDIR)/%.xhtml : %.h $(LESML)/parser.xslt
+$(DOCUMENTATION_FILES) : $(DOCDIR)/%.xhtml : %.h $(LESML)/parser.xslt xslt/documentation.xslt

        @if $(TEST) '!' -d $(DOCDIR); then $(MKDIR) -p $(DOCDIR); fi
        @$(PRINTF) '%s\n' 'Building documentation for <$<>…' >&2
        @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) >|'$@'
+       @$(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 <$<>) >|'$@'

 
 
 
 

-$(DOCDIR)/README.xhtml : README $(LESML)/parser.xslt
+$(DOCDIR)/README.xhtml : README $(LESML)/parser.xslt xslt/documentation.xslt

        @$(PRINTF) '%s\n' 'Building documentation README…' >&2
        @$(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) >|'$@'
+       @$(call processlesml,$(CAT) README; $(PRINTF) '\n\n%s' '⁂' 'A part of {🔗$(PROJECT_NAME) Documentation<./index.xhtml>}.',$(PROJECT_NAME) Readme) >|'$@'

 
 

-$(DOCDIR)/index.xhtml : FORCE $(LESML)/parser.xslt
+$(DOCDIR)/index.xhtml : FORCE $(LESML)/parser.xslt xslt/documentation.xslt

        @$(PRINTF) '%s\n' 'Building documentation index…' >&2
        @$(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) >|'$@'
+       @$(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))>}'),) >|'$@'

 
 $(LESML)/parser.xslt : %/parser.xslt : FORCE
        $(GIT) submodule update --init '$*'
 
 $(LESML)/parser.xslt : %/parser.xslt : FORCE
        $(GIT) submodule update --init '$*'