`breccia-web-image` - Make a Web image

breccia-web-image [<options>] <boundary path>
breccia-web-image -help | -?

- The `breccia-web-image` command makes a Web image delimited by the given boundary path.
- It ensures that each Breccian source file (`.brec`) stored at or under the boundary path
is accompanied by its HTML image file, a sibling namesake with a `.brec.xht` extension.
- Any image file that is missing is formed anew, any that is outdated is reformed.
- An image file is outdated unless it postdates both its source file
and all formal resources of the source file.
: re `formal resources` see `formalResources` @ non-fractal ../ExternalResources.java :
Typically these are Breccian referent files.
- The working directory must be the command directory.
: see `^*working directory$` @ `^*shell commands$` @
http://reluk.ca/project/Java/editorial_guidelines.brec
- One positional argument is required:

<boundary path>
/ The path of a file or directory.
- Sets the bounds of the Web image: any Breccian source file stored at or under this path
is eligible for imaging unless explicitly excluded.
: re `explicitly excluded` see `^*-exclude`

- Any number of nominal arguments, aka options, may accompany the positional argument:
/ Nominal arguments may appear anywhere on the command line,
they need not precede the positional argument.

\ -allow: -allow=broken-source-reference
\ - Allow for missing Breccian referent files where a corresponding image file exists.
\\ [broken-source-reference], q.v. at end note
-author-home-directory: -author-home-directory=<file path>
- The home directory of the author of the source text.
/ It may serve for the purpose of expanding any tilde prefix of a URI reference.
: see e.g. `Tilde Expansion` @ non-fractal
https://man7.org/linux/man-pages/man1/bash.1.html#EXPANSION
- The default value is the home directory of the user.
-centre-column: -centre-column=<number>
- The columnar offset on which to centre the text.
: re `columnar offset` see http://reluk.ca/project/Breccia/parser/Granum.java :
Columnar offsets are zero based.
- In wide viewports, this column of the source file will appear at centre.
- The default is 52.5.
-co-service-directory: -co-service-directory=<URI reference CS>
: re `URI reference` see https://www.rfc-editor.org/rfc/rfc3986#section-4.1
- The location of the co-service directory.
- It may be given with or without a trailing ‘/’.
- It must not be be given as a relative-path reference.
: re `relative-path reference` see https://www.rfc-editor.org/rfc/rfc3986#section-4.2
- The co-service directory contains the auxiliary files of the Web image.
- Its given location (CS) is written verbatim into the HTML files of the Web image
and must therefore be accessible to Web clients.
- If CS is given as an absolute-path reference or network-path reference (as opposed to
a URI), then it might be made accessible not only to Web clients but also the local
computer. This can be useful when it comes to debugging the Web image.
: re `(absolute-path reference) or (network-path reference)` see
https://www.rfc-editor.org/rfc/rfc3986#section-4.2
: re `absolute-path reference` e.g. `-co-service-directory=/_/Web_service/` @
non-fractal http://reluk.ca/.bashrc
: re `URI` see https://www.rfc-editor.org/rfc/rfc3986#section-3
a) Image files loaded directly into a Web browser from the local file system
(under a `file:` scheme) may be viewed without CORS errors.
: re `.file:. scheme` see https://datatracker.ietf.org/doc/html/rfc8089
- An actual copy of the co-service directory must exist locally at CS
in order for this to work.
b) Glyph testing may work by default.
: see `^*-glyph-test-font`
- The co-service directory must contain the following auxiliary files at a minimum.

style sheet: `<CS>/Breccia/Web/imager/image.css`
- Typically this is a copy of the bundled sheet, or a custom sheet
that imports from a copy of the bundled sheet.
: re `bundled sheet` see ../image.css

- Any resource files referred to by the style sheet must also be included.
For the bundled sheet, these are:

font files: `<CS>/Breccia/Web/imager/FairfaxHD.ttf`,
`<CS>/Breccia/Web/imager/FairfaxHD.woff2`
: see https://www.kreativekorp.com/software/fonts/fairfaxhd.shtml

- The default location for the co-service directory is `http://reluk.ca/_/Web_service/`.
/ Better not rely on it, however. The files there may be incompatible
with your installation, or become so at any time, or be slow to serve.
Rather you should supply a directory under your own control.
-exclude: -exclude=<pattern>
- A pattern of file and directory paths to exclude from the image.
/ Do not use tilde prefixes here, they will not be expanded.
- The form of the pattern is a regular expression as defined by the `Pattern` class of Java.
: see https://docs.oracle.com/en/java/javase/18/docs/api/java.base/java/util/regex/Pattern.html
- Paths that match the pattern in whole or part will not be traversed if they are
directories, and not imaged if they are Breccian source files.
/ Do not use a terminal name separator (e.g. `/` or `\`) to match a directory path.
To match a root directory `foo`, for instance, use `^/foo$` as opposed to `^/foo/$`.
-fake
- Runs the Web imager without effect. Makes no Web image, nor any image files.
-force
- Forcefully remakes the Web image. Any preexisting image files are reformed
regardless of whether they were out of date.
-glyph-test-font: -glyph-test-font=<file path> | none
- The font file for glyph tests.
- If the value is `none`, then no glyph tests are performed.
- Otherwise the file must contain an OpenType font
- A test is performed on each character of the source text and a warning emitted
for any whose glyph is missing from the font.
- The default value is either read from the style sheet, or it is `none`.
: re `style sheet` see `^*${same}` @ `must contain the following auxiliary files` @
`^*-co-service-directory`
- Use `-speak` to report the actual default value in use.
: re `-speak` see `^*${same}$`
- For the value to be read from the style sheet, the co-service directory must exist
locally and the style sheet there (or one of its locally reachable imports) must
contain a font reference with a ‘[GTF]’ mark.
: re `co-service directory` see `^*-co-service-directory`
: re `font reference` see https://www.w3.org/TR/css-fonts/#src-desc
- The bundled style sheet describes and gives an example of this mark.
: re `bundled style sheet` see ../image.css
-math
- Renders ⁠\LaTeX⁠/⁠\TeX⁠ mathematic expressions using MathJax.
: re `MathJax` see https://www.mathjax.org/
- Use word joiners (2060) to delimit your in-line mathematics.
: re `delimit` see `math delimiters` @ non-fractal
https://docs.mathjax.org/en/latest/basic/mathematics.html#tex-and-latex-input
: re `2060` see http://unicode.org/charts/PDF/U2000.pdf
\ A criterion for the in-line delimiters, in keeping with the WYSIWYG principle
\ of Breccia as a lightweight markup language (What You See (in source views)
\ Is What You Get (in public views)), is narrow (if not zero) width.
/ Should automated line breaking ever be a concern in writing Breccia,
authors may use the zero-width no-break space (FEFF) in place of word joiners.
\ Except at the start of a file (where yet no words can join), the two should
\ (in Breccia) have the same effect. http://unicode.org/faq/utf_bom.html#bom6
: re `FEFF` see http://unicode.org/charts/PDF/UFE70.pdf
: ad `(automated line breaking).+(a concern)` : This seems unlikely at present,
as it would be contrary to Breccia’s WYSIWYG principle.
- Use halfwidth katakana middle dots (FF65) to delimit your block (aka display) mathematics.
: re `delimit` see `math delimiters` @ non-fractal
https://docs.mathjax.org/en/latest/basic/mathematics.html#tex-and-latex-input
: re `FF65` see http://unicode.org/charts/PDF/UFF00.pdf
-reference-mapping: -reference-mapping=<translation> [|| <translation>] ...
- A list of translations to apply to URI references of the source text,
separated by double bars ‘||’.
: re `URI references` see e.g. `─ (URI reference) ─` @ `^^object clause$`i @
http://reluk.ca/project/Breccia/language_definition.brec
: re `URI references` see e.g. `─ +(URI).+(reference)`s @ `^^fractum locant$`i @
http://reluk.ca/project/Breccia/language_definition.brec
- The translations are attempted in the given order on each URI reference of the source text
until one succeeds or the list is exhausted.
/ At most one translation of the list will be applied to a given reference;
to apply multiple translations, use multiple `-reference-mapping` options.
- Any translation that succeeds on a reference determines the referent for imaging purposes.
/ For instance, although the image will still show the original reference,
any associated hyperlink will be formed using the translated reference.
- The form of each translation is:

translation: ;<pattern>;<replacement>; \ [three separators]

- The semicolons ‘;’ of the separator triplet may be replaced with any other character.
- The form of the given pattern is a regular expression as defined by the `Pattern` class
of Java.
: see https://docs.oracle.com/en/java/javase/18/docs/api/java.base/java/util/regex/Pattern.html
- If the pattern is found in a reference, then translation proceeds and all parts of
the reference that match the pattern are replaced by the given replacement string.
- The form of the given replacement string is defined by the `Matcher.appendReplacement`
method of Java.
: see https://docs.oracle.com/en/java/javase/18/docs/api/java.base/java/util/regex/Matcher.html#appendReplacement(java.lang.StringBuffer,java.lang.String)
- In particular, the replacement string may contain references to groups
that were captured in the pattern match.
/ ‘Each occurrence of `${<name>}` or `$<g>` will be replaced by the result of
evaluating the corresponding `group(<name>)` or `group(<g>)` respectively.’
- Further — in extension of `Matcher.appendReplacement` — any ‘${boundary}’ at the
start of the replacement string will be replaced by a relative-path reference
to the boundary-path directory, without a trailing ‘/’. \ [relative replacement]
/ Relative, that is, to the parent directory of the source file in which
the reference appears.
- So it will be replaced by one of `.` or `..` or `../..` etc.
\ While the result may be abnormally long, e.g. when referring to a sibling,
\ it abides by the user expectation of a simple string replacement,
\ which the addition of a normalization step would defy.
: re `relative-path.+reference`s see
https://www.rfc-editor.org/rfc/rfc3986#section-4.2
: re `boundary-path directory` see @ ../glossary.brec
-speak
- Sets the verbosity to level 2.
: re `verbosity` see `^*-verbosity`
-stifle
- Sets the verbosity to level 0.
: re `verbosity` see `^*-verbosity`
-verbosity: -verbosity=0|1|2
- The allowed amount of user feedback on the standard output stream:
0 none, 1 some, and 2 more.
: see also `^*-stifle$`
: see also `^*-speak$`
- The default is 1.

━━━━━
Bug
─────
- Parallel runs of `breccia-web-image` by the same user may lead to unexpected results.
: e.g. ../ImagingCommands.java : All runs will share the same `projectOutputDirectory`.

━━━━━━━━━━
See also
──────────
• Working example
: e.g. `^*testing$` @ http://reluk.ca/project/Breccia/Web/imager/notes.brec
• The `waycast-web-image` command
: see http://reluk.ca/project/wayic/Web/imager/bin/waycast-web-image.brec
- For imaging a boundary path that might include a waycast.

━━━━━━━
Notes
───────
\\ [broken-source-reference]
\ - An author may refer to a Web site that publishes an image without its source files.
\ - The best practice in that case would be to refer to the source files as usual,
\ as though they existed.
\ - An option such as `-allow=broken-source-reference` would make allowance for this, e.g. by
\ suppressing the warnings that would otherwise ensue, and might be enabled by default.
\\ [relative replacement]
\ - A relative replacement is wanted for sake of image portability. The image might be copied
\ elsewhere (e.g. to a Web server), or it might lie in a local mount of a foreign file system
\ (e.g. that of a Web server) that operates independently.
\\ [three separators]
\ - The initial separator serves to define the separator character in use.
\ while the final separator allows for later addition of match modifiers.