INCLUDEDIR should default to be in SRCDIR

…not the literal value `sources`, regardless of what `SRCDIR` might
be.

Mark GNUmakefile as precious

One would hope that Make wouldn’t ever delete the make·file it is
running, but the documentation doesn’t seem to explicitly give that
guarantee, so it’s good to be explicit about it.

Reformat redirections

- Remove the space after, but not before redirection operators.

- Do `>>/dev/null` instead of `> /dev/null`; appending makes more
  logical sense in this case.

- Use `>|` for other outputs because this make·file should always
  clobber.

Improve documentation regarding Posix utilities

Set .SHELLFLAGS to match Posix behaviour

Early failure upon the failure of a command seems like a good thing??

Move variable overrides before targets in submake

It doesn’t matter, but this is the Posix ordering.

Use exit with a nonzero exit status, not false

Use colon (:), not true

These are equivalent, but `:` is a special shell builtin and `true` is
not.

Allow overriding of cd

Altho `cd` is builtin in most shells, it is not a special builtin
utility as defined by Posix, and the use of an alternative
implementation is conceivable.

Prepend X·M·L declaration on parsed assets

⛩️📰 书社 policy is to never omit it.

FORCE on type updates

When this was originally implemented, I’m not sure `FORCE` was defined,
but it’s needed now for `diffprereqs` so there’s no reason why not to
use it here as well.

Fix typeoffile

The old implementation switched some things around and probably would
not work if called with multiple files (it never was).

Use diff to get better dates

See the comments for more information, including Macintosh quirks. This
is a great deal better than using `ls` and allows for the dropping of
the latter as a dependency.

Redirect messages to stderr & support disabling

This enables `make -s listout` to work as intended without need for
additional processing.

Support +xml suffix for determining X·M·L files

This gets around operating system extensions to `file` which might
identify S·V·G files (for example) as `image/svg+xml` before
attempting magic detection. If not every X·M·L‐based syntax should be
handled as such by ⛩️📰 书社, redefine `XMLTYPES` to exclude the
`+xml`.

Remove support for pagination

Expanded archives support this need better.

Remove stat dependency

This is, strictly speaking, a downgrade in functionality, with the
upside of reducing reliance on non·Posix programs (namely `stat`). A
better, Posix‐compliant solution is to archive an empty file with the
correct modification time and then list out the time from that archive;
however, as far as I’m aware, it’s not possible to obtain an
implementation of the `pax` utility which actually supports this. macOS
only supports a very limited subset of the `listopt` option, and only
for pax archives (not tarballs); other implementations don’t seem to
support it at all.

Force removal of existing directories

…prior to processing results or installing. Mostly, this prevents a
failure when an expanded archive is changed to no longer be expanded.
This also simplifies the installation code a bit.

Fix base64 decoding

The `tr -d` in this pipeline also removed the trailing newline, so it’s
necessary to re·add it prior to the closing equals.

Remove sed range expressions

These are technically only Posix in the Posix locale and have undefined
meaning otherwise. It’s not the policy of ⛩️📰 书社 to require the
Posix locale, so the safest thing is to just not use range expressions
here.

(Actually, this policy might be worth revisiting for things which
definitely need to be operating on Unicode text.)

Explicitly declare ustar format to pax

In Posix, the default format for writing is implementation‐defined, but
⛩️📰 书社 is documented to always produce tarballs.

Use compound commands to join strings, not sed

Previously, the script would sometimes use sed to insert text at the
beginning or end of a string, but it is better to just printf as a
separate step instead.

Remove dependency on echo

`printf` is always preferable to `echo` for portability reasons.

Support “expanded” archives

The intent is for this mechanism, which is much simpler to implement,
to replace the pagination functionality which was recently added.

Fix base64 output

Due to a typo, the `uuencode` trailer of four equals signs was being
appended to base64 outputs.

Improve xargs handling

- Always specify -E '' to disable end‐of‐file handling

- Quote standard input before passing it thru to xargs, and eliminate
  usage of the nonstandard `-0` option

- Get rid of xargs where it isn’t strictly required, to avoid line
  length limits

Add @data-tsv-header to TSV data cells

This produces pretty verbose output, but gzipping should be able to
significantly compress it as the attributes will be repeated verbatim
every row.

Use -u option on date, instead of TZ=

`-u` is a Posix option, so it’s safe to use.

Update documentation regarding (non‐)Posix needs

Support pagination

It’s not clear to me that this is actually a good idea, and this
functionality may be reverted later. It adds a lot of complexity
despite still having significant drawbacks, and the alternative pattern
of just generating archives and later expanding them is a much safer
and more versatile solution.

However, the pattern of e·g needing a paginated feed of all the posts
in one’s blog suggests that something along these lines (backed by this
method or archiving~expanding) *should* be supported by default in
⛩️📰 书社. One alternative might be to add (e·g) a `@书社:expand`
attribute to <书社:archive> elements, tho how exactly this would be
tracked on the resulting archives is unclear, and it would be
restricted to producing folders (with exclusively archive contents)
that could not easily be mixed with other files.

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.)