`breccia-web-image` - Make a Web image   breccia-web-image []   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: / 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= - 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= - 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= : 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: `/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: `/Breccia/Web/imager/FairfaxHD.ttf`, `/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= - 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= | 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= [|| ] ... - 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: ;;; \ [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 `${}` or `$` will be replaced by the result of evaluating the corresponding `group()` or `group()` 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. \ Copyright © 2020-2024 Michael Allan. Licence MIT.