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.

Fix/improve restarts by just waiting a sec

The previous method of attempting to retroactively reduce the timestamp
of the make·file when compiling dependencies hasn’t seemed reliable in
practice and probably isn’t portable either. However, a simple
`sleep 1` after touching the make·file but before the first restart
seems to reliably ensure the second restart happens.

Initial commit; minimal working implementation