Update readme

⛩️📰 is now tested on newer versions of Make, al·be·it not
particularly extensively.

Add listout target

Useful for post·processing of files which were installed by ⛩️📰 书社.

Note: There will be plenty of other Make output; use the following to
get just the files :—

    make listout | sed '/^⛩️📰 书社 Output:/!d;s/^⛩️📰 书社 Output://'

Don’t use xargs -J

It isn’t portable!

Update documentation to reflect usage on Linux

Make base64 handling Posix

Posix doesn’t allow for a `-r` option on `uudecode` or `uuencode`, but
the headers and footers are easy enough to manually add and remove.

Fix T·S·V parser

A pair of mistakes meant that the final body column was dropped, and
would have been unprocessable if it wasn’t.

Touch important files before making with xsltproc

When there is nothing to output, `xsltproc` does not create files.
However, Make will find itself in an endless restart loop if these
files are never created.

Fix X·M·L 1.1 handling to be portable

A typo meant it was calling `PRINTF` instead of `printf`; amazingly,
the built·in seems to be case‐insensitive on Macintosh so it wasn’t
noticed.

Don’t allow network or DTD loading

This still processes the internal DTD in a nonvalidating way.

Formerly, it would try to fetch the XML catalog DTD every time.

Support GNU stat

`stat` isn’t at all portable; it’s necessary to just try to figure out
which version is being used and then handle each case accordingly.

Don’t use <<<

This isn’t supported in Dash.

Allow injecting raw output in X·M·L serialization

It’s not possible to serialize things like entities using the normal
X·S·L·T processes. With this commit, one can instead use something like
`<书社:raw-output>&amp;my-entity;</书社:raw-output>` inside of
`<书社:serialize-xml>` elements to get this result.

Add support for manually serializing X·M·L

This commit adds a transform for a new `<书社:serialize-xml>` element,
which is useful in conjunction with `<书社:raw-text>` to produce a more
finely‐controlled X·M·L output, or in other X·M·L‐y situations where an
escaped X·M·L value is required. The algorithm used for serialization
attempts to closely match the DOM Parsing and Serialization spec,
including such behaviours as mandating an undeclared `xml:` prefix for
the X·M·L name·space and dropping the prefix from elements whose
name·space matches the default, but it probably isn’t exactly the same
(due in part to the fact that the underlying data structure is an X·M·L
infoset, not a potentially dynamically‐modified Dom). No special
allowances are made for elements in the H·T·M·L name·space; this is not
(yet) a suitable polyglot serializer (or intended to be one).

Make <书社:raw-text> a C·data section element

Disallow archive paths beginning with `/`

This would have resulted in final paths starting with `.//`, which,
while probably mostly harmless, is definitely weird.

Allow creation of tarballs

This is useful when using ⛩️📰 书社 directly as a static site
generator to provide archive downloads (archives are not compressed; it
is assumed that they will be gzipped over the wire). This requires
a recursive call to Make for each archive file, which performs the
following steps :—

- Extracts all of the elements slated for archiving into separate
  files.

- Restarts.

- Processes the resulting extracted files and then archives them.

The extraction step in particular is somewhat convoluted; it requires
dynamically generating a transform which has the appropriate
`<exsl:document>` elements for a given source file, and then applying
that transform in a second call to `xsltproc`.

X·M·L outputs are now passed through an extra call to `xmllint` to
remove any unnecessary namespace attributes instead of just symlinked;
the symlinks weren’t compatible with archiving anyway.

Use @extension-element-prefixes to exclude E·X·S·L

This follows the recommendations on the website and enables the use of
E·X·S·L extension elements in addition to the extension functions.

Don’t “compile” assets, just “build”

This reserves the `build/results/` directory for _just_ the results of
transformations, and delays the copying of asset files into the build
directory until the actual “build” step. (Likewise for recursive files,
altho these still just error).

`make all` now builds all installable files, including assets, which
were formerly excluded. A downstream script might expect assets to
appear in `build/public` after a `make all` and shouldn’t require a
`make install` to get them.

Allow ⛩️📰 书社 to produce plain text

This requires adding _another_ build stage; the result of the
transformation step is output to `build/results`, which is then
processed again to create the `build/public` final result. In most
cases, this additional processing just produces a symlink. However,
when the root element is a special value, a derived file will be
produced.

The only special elements supported right now are `<书社:raw-text>`,
which outputs the raw text contents of the text nodes in the result
tree, and `<书社:base64-binary>`, which produces a binary file from the
base64 text contents determined using the same method.

Make REUSE‐compliant

Improve (fix) the T·S·V parser

Although `exslstr:tokenize()` is fast, it should not be used when
splitting the columns of a T·S·V file, as it will collapse empty
columns. Introduce a new transform in `lib/` for splitting, and import
it into the T·S·V parser.

This transform was largely copied from Caudex
<https://git.ladys.computer/Caudex/blob/0.1.1:/lib/split.xslt> and is
likely to be useful downstream as well.

Continue using `exslstr:tokenize()` for splitting the _rows_ of the
T·S·V, as empty rows _should_ be collapsed.

Improve the implementation of wrapplaintext

- Use `printf` and octal escapes instead of hexadecimal ones, as they
  are more portable.

- Use `xargs` and piping to compose the wrapper and its contents,
  rather than a subcommand.

“Support” X·M·L 1.1

The X·M·L 1.1 “support” amounts to deleting the declaration and
replacing any character escapes for C·0 controls with
`U+0091 PRIVATE USE ONE`, which is a valid character in X·M·L 1.0.
This is done entirely in `sed`, so it’s not perfect, but it should be
“good enough”.

Correct syntax for X·Path booleans

The correct syntax is `true()` and `false()`; `true` and `false` refer
to elements with those names.

Refactor transforms & add 书社:application stage

The main goal of this commit was to add a
`<书社:apply-attributes-to-root>` element, to allow transforms to pass
attributes up to the root element of the result, for example `@lang`
information. This required an extensive refactor of a lot of the
transform infrastructure and the creation of a new transform stage,
`书社:application`, which follows the ordinary transform and solely
handles `<书社:apply-attributes-to-root>` and
`<书社:apply-attributes>`. Other `@书社:*` attributes are removed at
this stage, but it isn’t generally recommended that transforms try to
hook in here.

This commit also makes a number of smaller changes :⁠—

- Use `node()` in place of element wildcards anywhere where
  specifically only matching elements wasn’t intended.

  In particular, even in places where text is not expected, there may
  be comments to preserve.

- Only add `@itemscope` and `@itemtype` attributes to H·T·M·L elements,
  since they are only defined for elements in that namespace.

- Provide `@书社:identifier` on documents and embeds to get the
  `about:shushe` u·r·i of the resource.

- In transforms which generate transforms, `<xsla:text>` elements which
  provide only white·space need `<xslt:text>` children to ensure the
  whitespace isn’t stripped. (Note: In the actual source text, `xsla:`
  is given the `xslt:` prefix and `xslt:` is the default prefix.)
  Similarly, it’s necessary to provide attribute value templates using
  a `<xslt:attribute>` element rather than with the literal result
  element syntax, to prevent them from being prematurely applied.

Replace GENERATOR and VERSION with THISREV

Instead of replacing existing `<html:meta name="generator">`s, format
them into a comma‐separated list with ⛩️📰 书社 as the final entry.
Don’t allow overriding of ⛩️📰 书社 generator metadata.

Manually specifying `THISREV` is still possible to allow it to be
filled by users running Make without Git, but it should not be
overridden with the version of the calling generator, as it is used to
fill `@书社:version`.

Update parser documentation

- Remove class names which are no longer provided from description.

- Document attributes added during parsing.

Don’t add attributes to non·elements in parser

Check to see if it is an element first with `self::*`.

Add @书社:media-type to parsed nodes

Only keep the outermost media type, however (`@书社:parsed-by` records
all parsers).

Track catalog & magic prereqs and diff for changes

If a new prerequisite for a catalog (or the compiled magic file) is
added, and it is newer than the last build, then the catalog (or
compiled magic file) will be rebuilt. However, formerly, the file would
not be rebuilt if the added file was older, or if a prerequisite was
removed instead of added, due to limitations in Make.

This commit tracks the list of prerequisites separately, and if it
changes, forces a rebuild of the file regardless of whether the
prerequisites are newer or older than the target.

Add parser.xslt as a prerequisite for parsing

Although this file will generally be generated as a part of the
make·file restart loop, it is possible to wind up with an early error
during dependency generation if files cannot be parsed prior to
resolving make·file dependencies. Depend on it in this case as well,
with the understanding that this will update the types yet again.

If `parser.xslt` _is_ generated as a part of dependency generation
(and, presumably, `.update-types` does not exist) then the dependency
update message should be suppressed, since the other make·file build
script will also be present and active.

Apply @书社:cksum to result when parsing

Because this indiscriminately adds the attribute to the result of
parsing the root node, the checksum should be added for both X·M·L and
plaintext sources.

Provide source checksums to parsers and transforms

Just manually parse hexadecimal in Awk

The biggest performance bottleneck in this code was the fact that, for
compatibility reasons, Awk was piping hexadecimal numbers to the shell
in order to parse them. (Macintosh Awk can parse hexadecimal numbers in
`printf`, but G·N·U Awk cannot.)

Because the hexadecimal number is known to be two digits, it’s easy to
just parse it in Awk directly, avoiding the shell pipe and considerably
speeding up the program.

Run time‐related programs with command substitution

It’s not necessary to make these values available within make, and
they’re safe to appear unquoted in the commandline.

Pipe id function instead of calling in subshell

Cache file u·r·i’s on startup

It’s possible to generate every needed file u·r·i in a single go. Do
this rather than spawning a subshell for each one.

Reduce subshells created by percent·encoding

It’s possible to use `%0A` as a component separator assuming that
file·names will never contain newlines; this allows all filenames to
be processed at once rather than needing a separate subshell for each.

It’s not necessary to encode each path component separately; just
encode the whole path and replace `%2F` with `/` at the end. It’s not
possible for file·names to contain literal `/` characters.

The above two changes should increase the speed of operations such as
building the parser catalog in ⛩️📰 书社 considerably.

Make generator metadata more easy to override

Make all the default rule

This better conforms to Make conventions, and the help rule is of
pretty limited utility considering the make·file still has to restart
at least twice to use it.

Calculate dependencies for includes also

This is only used by `make list`, but that’s still useful.

Pad colons with spaces on both sides

G·N·U Make recognizes `&:` as indicating grouped targets. Ampersands
are allowed in filenames, so it’s best not to place them directly next
to the colons.

Make percent‐decoding awk script portable

This script depended on `printf` having the same behaviour within `awk`
and on the commandline. This doesn’t appear to be true in G·N·U Awk.
Instead, pipe into the shell version from within the Awk script.

Disallow filenames which end in a cloparen

There is a bug in G·N·U Make which causes the `wildcard` function to
ignore files and directories which end in a cloparen (`)`). To be safe,
disallow these files as sources, even though parens are generally 🆗.

Specifiy magic files, not a directory

This is more flexible and matches how parsers and transforms work.
Compiling magic requires these to all be placed in the same directory
at some point, but symbolic linking works for this purpose.

Add EXTRA* variables

It shouldn’t be necessary to know where existing parsers and transforms
are kept or what the default find rules are in order to supply
additional ones.

Reduce the strength of magic matches

The strength of magic matches is based on the length of the first line.
Boost this by `100` by default, but add an additional `10` for each
byte in additional match lines. This should provide a more comfortable
set of default strengths to work with.

Update readme (new tagline; more compat info)

Disallow backslash in filenames; filter out spaces

Space characters will break this make·file, so like other characters
which might break it should be filtered out by `find`. Backslashes feel
very fraught, especially under secondary expansion, and should be
dis·allowed for simplicity.

Consider destinations akin to dependencies

There were a couple statements which predate the addition of the
destinations file which check for or remove the dependencies file.
These two files should be considered interchangable for the purpose of
this kind of detection, i·e their impact on make·file rebuilding.

Make find more cross‐compatible

The `-flags -nohidden` check doesn’t appear to work in G·N·U Find.
Apparently `-a` and `-o` are the Posix‐correct versions of `-and` and
`-or`, even though both G·N·U and B·S·D find seem to prefer the latter.

The `-type f` check is moved to the end, as it is computationally more
expensive than `-name` and so would benefit from an early exit.

Add uninstall command; fix other phonies

`make uninstall` can now be used to remove (only) installed files. Note
that it only removes files which correspond to presently‐extant source
files; if a source is removed, then `make uninstall` will not remove
any previously‐installed derivatives.

`make all` used to compile assets, but this is unnecessary.

`make clean` now guards against `BUILDDIR` being empty (which would
otherwise result in a dangerous `rm -rf /`).

Reformat & update source comments in GNUmakefile

It doesn’t really make sense for make·file comments to be manually
wrapped at 72 characters; none of the actual code can be.

Pass single result tree to modes in wrapper

When matching a `<xslt:include>` inside of a `书社:metadata` transform,
it’s useful to be able to easily match elements in the result. Right
now, that requires a reference to the little‐documented variable
`$书社:result`, because `<xslt:include>` elements don’t belong to the
same document as result tree elements.

This commit creates a new tree which simply copies over all the result
nodes and all of the `<xslt:include>` elements, and then passes that to
the modal templates. Consequently, matches like `/html:div` or
`/xslt:include` should work regardless of what the current context node
is.

Better wrapper support for plural result trees

It’s not unsensible for a result tree to consist of both a
`<html:body>` and an `<html:head>` without a wrapping `<html:html>`
element, assuming that the result is going to be wrapped. This commit
improves support for this pattern in the wrapper.

Copy all nodes, not just elements, in transform

Use absolute file: u·r·i’s in catalogs

The previous approach broke some things when parsers/transforms were
located in a subdirectory.

Redirect some errors to /dev/null

It’s not useful or helpful for these errors to appear in the terminal
while executing the makefile.

Minor, largely‐inconsequential refactors

- Make some prints always be silent (use `@` not `$(silent)`).

- Don’t give includes mappings in `sourcecompiledpair` (they will
  always be empty, because includes aren’t compiled).

- Remove white·space between prereqs and trailing semi.

Allow underscores in u·r·l’s

Somehow I missed allowing these the first time.

Disallow a few more characters in file·names

- Make will try to expand the glob characters `*`, `?`, and `[` when
  followed by `]`. Forbid all of these (including both brackets in all
  cases for simplicity).

- `#` and `;` are dangerous in make prerequisites (at least under
  secondary expansion).

Fully remove FINDOPTS

This hasn’t been officially supported for some time, but the variable
was still being referenced and could have been supplied on the command
line.

Quote source and include directories

Special characters should be allowed here, too.

Remove classes from parse results

Now that `@书社:parsed-by` is provided, these are unnecessary.

Improve global params in parsers/transforms

- Uppercase global params to make them distinct.

- Make global params available in parsers, not just transforms, where
  possible.

- Add params for the current ⛩️📰 书社 version and the current rev
  of the source files (this requires `git` and makes some assumptions
  about the location of the git directory.)

Improve default parser/transform i·d’s

Use a format of `about:shushe?parser=<name>` and
`about:shushe?transform=<name>` as default i·d’s for parsers and
transforms which do not have one explicitly specified.

Add @书社:parsed-by to parse results

This switches the parser to use a two‐stage parse, in which each node
is by default first processed in the `书社:parse` mode, which then
applies templates to the node. This provides a hook for selecting
certain kinds of elements, for example `<html:script>` elements, and
doing something to the result.

The “something” in this case is “making note of the parser which is
registered to that type on each result element by setting the
`@书社:parsed-by` attribute to its `@id`.

This setup also allows a reparsing of the parse result (in case new
`<html:script>` elements were produced by it); it is worth noting that
this could result in an endless loop if the `<html:script>` element is
not actually transformed by any parser.

Remember types in parser

Rather than derive the types from the parser via a separate transform,
collect them when building the parser and remember them in a
`<html:dl>` which can be queried with X·Path.

This is a prerequisite to accessing this information at parse time,
but also a useful optimization in its own right.

Update FINDRULES documentation

This comment is out‐of‐date (since the removal of `FINDOPTS`), and the
readme prose misses that percents are also problematic and not matched
by default.

Don’t double‐newline specials in perdec

It’s not necessary to insert newlines (as pipes) before and after the
`sed` substitutions for pipe and backslash, because these substitutions
take place before the substitution for percent‐encoded characters
(which adds its own newlines). (The extra newlines are harmless, they
just mean `awk` gets a few more empty records to process.)

Enable output redirection with 书社:destination

Specifying this attribute on the root element (after parsing, but
before transformation) will override the default output location. All
of the processing for this can be done at the same time as dependency
detection, as it depends on media typing but not on the dependency
tree.

Use pipe as internal delimiter instead of colon

Colons are valid characters in u·r·i’s, whereas pipes are not. Both
characters are forbidden in filenames because they have special meaning
in make·files, so there’s no reason to use the more confusing option.

Simplify recursive dependency error printing

There are new functions which can make this rule a lot simpler and more
straightforward.

Update allowed characters; make find more selective

With percent‐encoding, it seems like the only problematic characters
are :—

- Whitespace (incompatible with make)
- Colons (incompatible with make)
- Pipes (incompatible with make as they introduce order‐only
  prerequisites)
- Bucks (incomaptible with make secondary expansion)
- Percents (incompatible with secondary expansion inside static pattern
  rules, and possibly other things)
- Leading hyphen‐minuses (confusable with a command‐line argument)

This commit updates the `find` rules to not select these files, in
addition to the existing behaviour of not selecting hidden files or
those which start with a period.

`FINDOPTS` is removed as the default is virtually always the correct
behaviour; users can override `FIND` if supplying options is absolutely
necessary.

Percent‐encode filenames when generating u·r·i’s

It’s not known or expected whether tools like `xmlcatalog` can handle
full leiris. It’s better and safer to just only use u·r·i’s for
identifying resources.

Note that this _does_ have implications on includes (they must also be
percent‐encoded). Ideally, it would be possible to run this conversion
in the transforms, but this probably is not possible in X·S·L·T 1.0.

Use colon as delimiter and hymin as recursive sigil

Colon is already forbidden in paths by the make syntax, and initial
hyphen is forbidden because it is confusable with command‐line options.
Re·use these for other semantics to hopefully reduce the number of
forbidden characters in filenames.

Get rid of weird superfluous sed in i·d fallback

Allow multiple source directories

⛩️📰 书社 might be called from another script or make·file, which
might have built files of its own. It would be a pain if each parent
script needed to copy all the source files into a new build directory
at every step, and it’s much easier to just allow ⛩️📰 书社 to support
multiple source directories (one for the original sources, and
additional ones for any files built by other scripts).

Naturally, ⛩️📰 书社 can’t support the same file subpath across
multiple source directories, as these would compile to the same place.
This commit tries to migitage this by just taking the first match, but
it hasn’t been tested and the behaviour should formally be considered
undefined.

Make X·M·L types take priority over plaintext ones

If `XMLTYPES` defines something as X·M·L, it should be treated as
X·M·L, regardless of whether there is a parser which claims to support
it.

This avoids awkward footguns where a parser might transform and claim
support for (through `@书社:supported-media-types`) an X·M·L dialect,
resulting in ⛩️📰 书社 treating that type as plaintext and wrapping it
in an `<html:script>` element. X·M·L types listed in
`@书社:supported-media-types` should instead not have any effect
(⛩️📰 书社 should not require parsers to reparse X·M·L).

This commit also removes the unused `simpletypes` variable; it was
formerly used for categorization of types into plaintext or asset prior
to the implementation of automatic detection.

Allow separate find rules for includes

This hypothetically enables the situation where `SRCDIR` and
`INCLUDEDIR` are the same, and files are grouped into one or the other
by some other factor.

Do not follow symbolic links with `find`

⛩️📰 书社 expects that source files exist within `SRCDIR` and includes
exist within `INCLUDEDIR`. Following symlinks can break this
assumption. Other commands should follow symlinks by default, so there
shouldn’t be any need to resolve them this early in the process.

Update readme documentation

- Provide more information regarding parsers, including X·M·L parsers.

- Update advice on allowed characters, to exclude all Ascii characters
  not allowed in u·r·i’s as well as those known to cause potential
  commandline problems.

- Improve the documentation regarding BUILDDIR and DESTDIR

Explicitly declare UTF-8 output for all transforms

This prevents needless character escaping when building the parser and
transforms.

Copy all language attributes to wrapper <html:html>

Copy over existing <html:body> attributes

Add <书社:apply-attributes> transformation

The behaviour of `transforms/asset.xslt` is useful, but limited in that
the H·T·M·L elements it creates don’t have any attributes beyond
`@src`. `<书社:apply-attributes>` fixes this by allowing attributes to
be declared in a parent element which wraps the `<书社:link>`.

Fix <html:head> copying

Remove some debugging information

Escape / in sed regular expressions

Don’t try to install asset includes

Fix magic file generation in non‐default location

As it turns out, `file -C` always creates a file named `magic.mgc` in
the current working directory. Navigate to the build directory before
calling it instead of moving the file after.

Provide $buildtime, $srctime, and $path variables

Provide a mechanism to override parser media types

If `@书社:supported-media-types` is present on the root element of a
parser, the normal media type detection is disabled and the value of
the attribute is used instead.

Add a basic record-jar parser

Re·order remakes to (again) fix restarts

In cases where `$(BUILDDIR)/dependencies` exists but
`$(BUILDDIR)/.update-types` (initially) does not, it is important to
check for dependency updates *first*, prior to checking for parser
updates. This is because when parsers are updated, the dependency file
will be deleted, causing the dependency reload recipe to activate
immediately (prior to a restart) if it hasn’t already been checked.

Having correct behaviour depend on the ordering of these recipes isn’t
ideal, but the alternative is checking whether
`$(BUILDDIR)/.update-types` was created *in the course of processing
the make·file* and disabling dependency creation until the next restart
if it had been. This sounds unbearably complex and difficult to phrase
in a readable manner.

Improve asset transforms

This commit converts `audio/*`, `image/*` and `video/*` embeds to their
appropriate H·T·M·L element, enables inline `<html:style>`s, and
improves the handling of `text/css` embeds.

Allow inserting nodes before and after result

This commit adds two new modes akin to `书社:metadata`: `书社:header`,
which supplies nodes to insert at the beginning of the `<html:body>`,
and `书社:footer`, which supplies nodes to insert at the end. Like
`书社:metadata`, these modes do not run if output wrapping is disabled.

Allow output wrapping to be disabled

This also extracts wrapping out into a separate mode, `书社:wrap`,
enabling it to be overridden by transforms if necessary.

Automatically encapsulate metadata and preserve it

During the embedding phase, give top‐level elements and embeds
`@itemscope` properties as well as a `@itemtype` which indicates which
they are. Don’t remove microdata from the output, and make use of these
properties when processing to ensure only document metadata is actually
used.

Allow creation of metadata without matching result

Each node in the result can only be matched once in any given mode, and
transforms need a mechanism for inserting elements without requiring a
match. This commit gives them a means of doing so by also matching
every `<xslt:include>` in the main transform. If a transform has a
`书社:id` top‐level element which is an i·r·i, then its include will
have a corresponding attribute, and transforms can (by convention)
match this include without fear of conflicts.

This commit also makes the expansion and result available as top‐level
variables in the `书社:` namespace, so that transforms can easily match
within them.