From: Lady Date: Fri, 6 Mar 2026 02:48:52 +0000 (-0500) Subject: Stylistic readme edits X-Git-Tag: 1.1.0^0 X-Git-Url: https://git.ladys.computer/Shushe/commitdiff_plain Stylistic readme edits --- diff --git a/README.markdown b/README.markdown index be400b9..658866e 100644 --- a/README.markdown +++ b/README.markdown @@ -1,5 +1,5 @@ # ⛩📰 书社 @@ -70,7 +70,7 @@ Macintosh systems somewhat interestingly implement this option extensions rather than standardized.][rdar-92753335] Despite this, the default Macintosh implementation will still work with ⛩📰 书社, with the caveat that the timestamp will only include a - fractional component when a Posix⹀compliant (e·g, Macintosh legacy or + fractional component when a Posix‐compliant (e·g, Macintosh legacy or G·N·U) implementation is used. ### `file` @@ -93,9 +93,8 @@ It requires support for the following additional options :⁠— - **`--separator`** must be useable to set the separator that `file` uses to separate file names from types. -These options are implemented by the - [Fine Free File Command](https://darwinsys.com/file/), which is used - by most operating systems. +These options are implemented by the [Fine Free File Command][F3C], + which is used by most operating systems. ### `git` @@ -125,8 +124,7 @@ These are Posix utilities, but they were considered optional in `POSIX.1-2001` (altho they are made mandatory in `POSIX.1-2008`) and they are not included in the Linux Standard Base or installed by default in many distributions. -The G·N·U [Sharutils](https://www.gnu.org/software/sharutils/) package - provides one implementation. +The G·N·U [Sharutils][] package provides one implementation. ### `xmlcatalog` and `xmllint` @@ -246,12 +244,19 @@ The following additional variables can be used to control the behaviour file subpath doesn’t exist in more than one of them. - **`DATADIR`:** - If set to the location of a directory, ⛩📰 书社 will run a two‐stage build. - In the first stage, only files in `SRCDIR` which match `FINDDATARULES` (see below) will be built, with files in `DATADIR` serving as includes. - In the second stage, the remaining files in `SRCDIR` will be built, with the files built during the first stage, in addition to any files in `INCLUDEDIR`, serving as includes. - Files built during the first stage are copied into `DESTDIR` alongside those from the second stage when installing. - - This functionality is intended for sites where the bulk of the site can be built from a few data files which are expensive to create. + If set to the location of a directory, ⛩📰 书社 will run a two‐stage + build. + In the first stage, only files in `SRCDIR` which match + `FINDDATARULES` (see below) will be built, with files in `DATADIR` + serving as includes. + In the second stage, the remaining files in `SRCDIR` will be built, + with the files built during the first stage, in addition to any + files in `INCLUDEDIR`, serving as includes. + Files built during the first stage are copied into `DESTDIR` + alongside those from the second stage when installing. + + This functionality is intended for sites where the bulk of the site + can be built from a few data files which are expensive to create. - **`BUILDDIR`:** The location of the (temporary) build directory (default: `build`). @@ -262,18 +267,19 @@ The following additional variables can be used to control the behaviour The location of directory to output files to (default: `public`). `make install` will overwrite files in this directory which correspond to those in `SRCDIR`. - It *will not* touch other files, including those generated from files + It _will not_ touch other files, including those generated from files in `SRCDIR` which have since been deleted. Files are first compiled to `$(BUILDDIR)/public` before they are copied to `DESTDIR`, so this folder is relatively quick and inexpensive to re·create. It’s reasonable to simply delete it before every `make install` to - ensure stale content is removed. + ensure stale content is removed, assuming copies are quick on your + file·system. - **`THISDIR`:** The location of the ⛩📰 书社 `GNUmakefile`. - This should be set automatically when calling Make and shouldn’t ever + This should be set automatically when calling Make and shouldn¦t ever need to be set manually. This variable is used to find the ⛩📰 书社 `lib/` folder, which is expected to be in the same location. @@ -284,7 +290,8 @@ The following additional variables can be used to control the behaviour - **`EXTRAMAGIC`:** The value of this variable is appended to `MAGIC` by default, to - enable additional magic files without overriding the existing ones. + enable additional magic files without overriding the existing + ones (default: empty). - **`FINDRULES`:** Rules to use with `find` when searching for source files. @@ -297,7 +304,8 @@ The following additional variables can be used to control the behaviour - **`EXTRAFINDRULES`:** The value of this variable is appended to `FINDRULES` by default, to - enable additional rules without overriding the existing ones. + enable additional rules without overriding the existing ones + (default: empty). - **`FINDINCLUDERULES`:** Rules to use with `find` when searching for includes (default: @@ -306,16 +314,20 @@ The following additional variables can be used to control the behaviour - **`EXTRAFINDINCLUDERULES`:** The value of this variable is appended to `FINDINCLUDERULES` by default, to enable additional rules without overriding the existing - ones. + ones (default: empty). - **`DATAOPTS`:** - Additional options to use when calling Make during the first stage of a two‐stage build using `DATADIR`. + Additional options to use when calling Make during the first stage of + a two‐stage build using `DATADIR` (default: empty). - This can be used to override variables which are only applicable during the second stage. - Note that when supplying this variable on the shell, it will need to be double‐quoted. + This can be used to override variables which are only applicable + during the second stage. + Note that when supplying this variable on the shell, it will need to + be twice‐quoted. - **`DATAEXT`:** - A list of file extensions which signify “data” files during a two‐stage build using `DATADIR`. + A list of file extensions which signify “data” files during a + two‐stage build using `DATADIR` (default: `rdf`). - **`FINDDATARULES`:** Rules to use with `find` when searching for data files. @@ -324,33 +336,49 @@ The following additional variables can be used to control the behaviour - **`EXTRAFINDDATARULES`:** The value of this variable is appended to `FINDDATARULES` by default, to enable additional rules without overriding the existing - ones. + ones (default: empty). - **`FINDFILTERONLY`:** - A semicolon‐separated list of regular expressions, at least one of which the paths for sources and includes are required to match, unless empty (default: empty). + A semicolon‐separated list of regular expressions, at least one of + which the paths for sources and includes are required to match, + unless empty (default: empty). - **`FINDFILTEROUT`:** - A semicolon‐separated list of regular expressions, each of which matches paths that should _not_ be considered sources or includes (default: empty). + A semicolon‐separated list of regular expressions, each of which + matches paths that should _not_ be considered sources or includes + (default: empty). - **`FINDINCLUDEFILTERONLY`:** - A semicolon‐separated list of regular expressions, at least one of which the paths for includes are required to match, unless empty (default: empty). + A semicolon‐separated list of regular expressions, at least one of + which the paths for includes are required to match, unless empty + (default: empty). - Note that only paths which already match `FINDFILTERONLY` are considered. + Note that only paths which already match `FINDFILTERONLY` are + considered. - **`FINDINCLUDEFILTEROUT`:** - A semicolon‐separated list of regular expressions, each of which matches paths that should _not_ be considered includes, but may still be considered sources (default: empty). + A semicolon‐separated list of regular expressions, each of which + matches paths that should _not_ be considered includes, but may + still be considered sources (default: empty). - **`FINDFILTERONLYEXTENDED`:** - If non·empty, `FINDFILTERONLY` is an extended regular expression; otherwise, it is basic (default: empty). + If non·empty, `FINDFILTERONLY` is an extended regular expression; + otherwise, it is basic (default: empty). - **`FINDFILTEROUTEXTENDED`:** - If non·empty, `FINDFILTEROUT` is an extended regular expression; otherwise, it is basic (default: matches `FINDFILTERONLYEXTENDED`). + If non·empty, `FINDFILTEROUT` is an extended regular expression; + otherwise, it is basic (default: matches `FINDFILTERONLYEXTENDED`). - **`FINDINCLUDEFILTERONLYEXTENDED`:** - If non·empty, `FINDINCLUDEFILTERONLY` is an extended regular expression; otherwise, it is basic (default: matches `FINDFILTERONLYEXTENDED`). + If non·empty, `FINDINCLUDEFILTERONLY` is an extended regular + expression; otherwise, it is basic (default: matches + `FINDFILTERONLYEXTENDED`). - **`FINDINCLUDEFILTEROUTEXTENDED`:** - If non·empty, `FINDINCLUDEFILTEROUT` is an extended regular expression; otherwise, it is basic (default: `1` if either `FINDFILTEROUTEXTENDED` or `FINDINCLUDEFILTERONLYEXTENDED` is non·empty). + If non·empty, `FINDINCLUDEFILTEROUT` is an extended regular + expression; otherwise, it is basic (default: `1` if either + `FINDFILTEROUTEXTENDED` or `FINDINCLUDEFILTERONLYEXTENDED` is + non·empty). - **`PARSERS`:** A white·space‐separated list of parsers to use (default: @@ -358,7 +386,8 @@ The following additional variables can be used to control the behaviour - **`EXTRAPARSERS`:** The value of this variable is appended to `PARSERS` by default, to - enable additional parsers without overriding the existing ones. + enable additional parsers without overriding the existing ones + (default: empty). - **`PARSERLIBS`:** A white·space‐separated list of parser dependencies (default: @@ -367,7 +396,7 @@ The following additional variables can be used to control the behaviour - **`EXTRAPARSERLIBS`:** The value of this variable is appended to `PARSERLIBS` by default, to enable additional parser dependencies without overriding the - existing ones. + existing ones (default: empty). - **`TRANSFORMS`:** A white·space‐separated list of transforms to use (default: @@ -375,7 +404,8 @@ The following additional variables can be used to control the behaviour - **`EXTRATRANSFORMS`:** The value of this variable is appended to `TRANSFORMS` by default, to - enable additional transforms without overriding the existing ones. + enable additional transforms without overriding the existing ones + (default: empty). - **`TRANSFORMLIBS`:** A white·space‐separated list of transform dependencies (default: @@ -384,7 +414,7 @@ The following additional variables can be used to control the behaviour - **`EXTRATRANSFORMLIBS`:** The value of this variable is appended to `TRANSFORMLIBS` by default, to enable additional transform dependencies without overriding the - existing ones. + existing ones (default: empty). - **`XMLTYPES`:** A white·space‐separated list of media types or media type suffixes to @@ -422,7 +452,7 @@ The following additional variables can be used to control the behaviour Source files may be placed in `SRCDIR` in any manner; the file structure used there will match the output. -The type of source files is *not* determined by file extension, but +The type of source files is _not_ determined by file extension, but rather by magic number; this means that files **must** begin with something recognizable. Supported magic numbers include :⁠— @@ -449,7 +479,7 @@ Source files whose media type does not have an associated X·S·L·T The former characters have the potential to conflict with make syntax, a leading hyphen‐minus is confusable for a commandline argument, and a trailing cloparen [activates a bug in G·N·U Make - 3.81](https://stackoverflow.com/questions/17148468/capturing-filenames-including-parentheses-with-gnu-makes-wildcard-function#comment24825307_17148894). + 3.81][so-17148468-comment]. ## Parsers @@ -480,7 +510,7 @@ New ⛩📰 书社 parsers which target plaintext formats should have an - Follows this with a quoted string giving a media type supported by the parser. - Media type parameters are *not* supported. + Media type parameters are _not_ supported. - Follows this with the string `]`. @@ -520,16 +550,19 @@ The result tree of applying the transform to the `` The value of this attribute will be the value of the `<书社:id>` toplevel element in the parser. +Parsers **should** have an `<书社:id>` and, if present, it **must** be + unique. + It is possible for parsers to support zero plaintext types. This is useful when targeting specific dialects of X·M·L; parsers in this sense operate on the same basic principles as transforms (described below). The major distinction between X·M·L parsers and transforms is where in the process the transformation happens: -Parsers are applied *prior* to embedding (and can be used to generate - embeds); transforms are applied *after*. +Parsers are applied _prior_ to embedding (and can be used to generate + embeds); transforms are applied _after_. -It is **strongly recommended** that auxillary templates in parsers be +It is **strongly recommended** that auxiliary templates in parsers be name·spaced (by `@name` or `@mode`) whenever possible, to avoid conflicts between parsers. @@ -668,8 +701,8 @@ Transforms are used to convert X·M·L files into their final output, - **`transforms/asset.xslt`:** Converts `` elements which correspond to recognized media types into the appropriate H·T·M·L elements, and deletes - `` elements from the body of the document and moves - them to the head. + `` elements from the body of the document while + transferring them to the head. This conversion happens during the finalization phase, after the main transformation. @@ -685,7 +718,7 @@ Transforms are used to convert X·M·L files into their final output, Provides the title of the page. ⛩📰 书社 automatically encapsulates H·T·M·L embeds so that their - metadata does not propogate up to the embedding document. + metadata does not propagate up to the embedding document. To undo this behaviour, remove the `@itemscope` and `@itemtype` attributes from the embed during the transformation phase. @@ -888,6 +921,9 @@ This repository conforms to [REUSE][]. Most source files are licensed under the terms of the Mozilla Public License, version 2.0. +[F3C]: [REUSE]: +[Sharutils]: [draft-phillips-record-jar-01]: [rdar-92753335]: +[so-17148468-comment]: