My notes for the Breccia Web imager + have the imager treat bullet content thus: : privately cf. @ ~/base.brec : where tasked • math expressions - left unstyled that MathJax may do its own thing unimpeded if( this suffices to enable math expressions in bullets ) + reform bullets *LaTeX* and *TeX* → *⁠\LaTeX⁠* and *⁠\TeX⁠* : see ~/work/index.brec if( Brec Mode must face in-bullet math expressions (as such) up-front while facing the bullet content ) + consider I might have to guard against duplicate math facing at the end / else duplicates may accumulate, for then it appends the face : re `guard` see ~/work/Java/Emacs/jmt-mode.el : § Javadoc comment It includes an example of a face guard in a Font-Lock matcher. • `bold` encapsulation - characters which are known to present well in a bold face, e.g. alphanumerics and (their separator) plain spaces • `subdued` encapsulation, e.g. most (if not all) punctuation plus the no-break space - yet only ‘semi-subdued’ (e.g. left unstyled) absent other visible content / for sake of readability - wherefore include the no-break space / what is effectively the non-alphanumeric separator - such that the absence of other content suffices also to indicate the absence of other *visible* content ! Images are largely unindexed by Google. - Apparently Google is unaware of them. / Learned by inspecting an image URL using Google’s search console. - I asked (2022-12-30) that `http://reluk.ca/project/way/index.brec.xht` be indexed. build persistence - A persistent build of the imager for end use. \ | copying \ + Code `sync-build`. \ + Refer to it from Makeshift. \ / If only from my own branch. \\ !! Nothing could run from that copy. \ - The commands have a fixed classpath. | release copy - Run the command from a cached copy of the release package. release package - E.g. executable jars, or whatever better method is now available. - Files and directories are given read-only permissions. | programmatic rebuild / A stopgap pending actual persistence. - Whatever calls the imager calls first its builder. | linkage / Undesireable where it defeats `tmpfs`, writing test builds to the drive instead of RAM. - Ensure `clean` never deletes a symbolically linked output directory, only its content. - Explain this so the user understands it allows for building outside the temporary directory, e.g. for sake of persistence. - Ensure the classloader workaround of `build` optimally handles the case of a symbolic linked. - Test how the classloader behaves in that case. colouration, the alternative (infeasible) of basing it on browser settings - Colouration according to the user’s own browser settings, while appealing in theory, would be infeasible in practice. - Most of the style colours would be given as named, system colours. : see https://www.w3.org/TR/css-color/#css-system-colors - Others could be given in one of two alternatives, chosen to contrast with the actual background brightness of the page. : cf. https://www.w3.org/TR/mediaqueries-5/#descdef-media-prefers-color-scheme : Presently this has no connection, however, with the *actual* background brightness. - The actual background brightness would be detected by a runtime script. : see e.g. http://reluk.ca/project/proto-waycast/way.xht : see ~/project/proto-wayic/read/readable.css : see ~/project/proto-wayic/read/readable.js - For this be reliable, however, the system `Canvas` colour would have to be set on the background prior to the detection attempt. : re `Canvas` see https://www.w3.org/TR/css-color/#css-system-colors : cf. ~/project/proto-wayic/read/readable.js / Otherwise Chrome, at least, is known to have reported the (default) colour as being black or transparent. - One problem is that most users will not set their preferred browser colours. - There is little point in doing so, because most Web sites ignore these preferences. - Another problem is the (crucial) prominence of task bullets on a bright background. - Colours are not very useful here unless applied lightly to the background, and background shading works poorly for the short spans of text that comprise bullets. : cf. http://reluk.ca/project/proto-waycast/way.xht : The button-like forms it resorts to for bright backgrounds would be too disruptive of Breccia, I think. : see ~/project/proto-wayic/read/readable.css : see ~/project/proto-wayic/read/readable.js ∴ It seems better to have one colour scheme for all users, at least for now. deferral of HTTP fetches - Deferring HTTP access of remote referents in favour of more urgent tasks elsewhere. - Meantime remapping my remote Breccian references locally, so ensuring (as a workaround) that any fractum locants nevertheless get parsed out and precisely targeted in hyperlinks. : re `remapping` see ~/sys/bin/publish-files : `-reference-mapping` : re `remapping` see `^*testing$` @ ~/code/WP3/wayic/Web/imager/notes.brec : `-reference-mapping` : re `hyperlinks` see ~/work/Breccia/Web/imager/BreccianFileTranslator.java : `hRefRemote` / All (or nearly all) of my remote Breccian references refer to my own Web site, which allows them to be remapped to relative-path references. element naming - Do not use custom names for elements. : see https://html.spec.whatwg.org/multipage/dom.html#elements - Use Tag names as defined by the Breccian parser. - Just going ahead and using them. / Not formalizing their definition (as the HTML standard allows) unless it proves necessary. : re `as.+HTML.+allows` see https://html.spec.whatwg.org/multipage/custom-elements.html : pace https://html.spec.whatwg.org/multipage/dom.html#elements : ‘Authors must not use elements, attributes, or attribute values that are not permitted by this specification or other applicable specifications’. : see https://html.spec.whatwg.org/multipage/infrastructure.html#other-applicable-specifications : Here ‘other applicable specifications’ is defined so broadly as to include nearly anything I care to recognize. feedback, user : join @ `^*moulding process$` + Have the mould take a print stream for warnings and survivable errors. + Give to the mould a stream to a string buffer, to print the contents after image formation. + Report to this stream instead of the logger. fidelity, images true to the Breccian source : cf. `^*parity between Web images and edit buffers$` !!+ No-break spaces are lost in clipboard copies. - Chrome and Firefox (and who knows what other browsers) substitute plain spaces. - Firefox 103 has a partial fix. : see https://bugzilla.mozilla.org/show_bug.cgi?id=359303 : Non-breaking spaces (nbsp) not copied as such - It applies only to a “sequence of no-break spaces that isn't preceded or followed by an ASCII space”. : see https://bugzilla.mozilla.org/show_bug.cgi?id=1769534 : see https://bugzilla.mozilla.org/show_bug.cgi?id=359303 ∴ It might or might not help in the case of indent blind delimiters. - It depends on the effect of each being individually wrapped in a `Delimiter` element. ∴ It will not help in all cases of a no-break space forming the end boundary of a bullet; namely those in which it is followed by a space. ∴ It will not help in all cases of a no-break space in a comment block. ?+ Try adopting an alternative character in Breccia? ?+ What other characters are more-or-less appropriate to the purpose? ?+ Which of them is faithfully copied by browsers. ?+ Try adopting an alternative character in Web images, one that users might easily replace with no-break spaces in order to repair the damage themselves? / A workaround, pending a permanent fix. ?+ What other characters are more-or-less appropriate to the purpose? ?+ Which of them is faithfully copied by browsers. !!+ Firefox 91.6 is widening the bold characters of our font, Fairfax HD. : re `font, Fairfax HD` see / Chrome 98.0 does not do this. font, Fairfax HD : see https://www.kreativekorp.com/software/fonts/fairfaxhd.shtml , choosing : see https://www.programmingfonts.org/ : privately see ~/work/Breccia/Web/imager/test/drawing.brec , justification of choice : see image.css language: XML-form HTML : see `^*element naming$` - The formal language of the Web image, in which the imager encodes it, is XML-form HTML. - XML syntax for sake of namespacing, easy inclusion of data, and maybe easier processing/manipulation (e.g. as part of image formation) as well. - The imager translates each `.brec` file of the source to a `.brec.xht` file in the image. moulding process : see ~/work/Breccia/Web/imager/ImageMould.java 1. Pull selected source files into the mould, sorting between the following logical sets and discarding the remainder. a) Imageable source files, those to certainly image because each has either no image file, or none that postdates it. b) Indeterminate source files, each to *maybe* image depending on whether its image file postdates an external, formal resource of the source file. + Handle redundant source arguments. / Viz. one contained in another, or identical to another. | filter and warn - Already the filter part is done by virtue of set collection. | throw error 2+ Reduce the indeterminate source files (b), moving each to the imageable set (a) or discarding it from the mould. i. Compose the set of resource hosts of the indeterminate source files (b), including the default, local host of relative references. - Record for each host the set of files there referred to. - Record for each file the set of indeterminate source files that refer to it. : see `formalResources_recordFrom` @ ~/work/Breccia/Web/imager/ImageMould.java : see `formalReferenceAt` @ ~/work/Breccia/Web/imager/FileTranslator.java : e.g. `formalReferenceAt` @ ~/work/Breccia/Web/imager/BreccianFileTranslator.java : e.g. `formalReferenceAt` @ ~/code/WP3/wayic/Web/imager/WaybreccianFileTranslator.java + Ensure that formal resources are those *actually* required for image formation, e.g. by some partial pre-run of the code that actually forms the image. : see `formalReferenceAt` @ ~/work/Breccia/Web/imager/FileTranslator.java - Not all references require parsing of the referent. / This does not, for instance, not unless we amend it to `see @` and forget to add `non-fractal`.   : re `Canvas` see https://www.w3.org/TR/css-color/#css-system-colors ii. Maintain hence thread safety of each determination state of set (b). iii+ Start processes to probe remote resources, one process for each remote host. : see ~/work/Breccia/Web/imager/RemoteChangeProbe.java + Make more accurate use of `RemoteChangeProbe.msQueryInterval` by recording the precise time of the last probe. - Bear in mind that delays (even of `msQueryInterval`) occur elsewhere, outside of `RemoteChangeProbe`. for( each resource ) + Probe it with a lightweight `HEAD` request to learn its last modification time. : re `\`HEAD\` request` see https://datatracker.ietf.org/doc/html/rfc7231#section-4.3.2 : re `last modification time` see https://datatracker.ietf.org/doc/html/rfc7231#section-7.2 : re `last modification time` see https://datatracker.ietf.org/doc/html/rfc7232#section-2.2 + Store timestamps in a time-sensitive cache in order to avoid overly frequent tests. / Else re-imaging after correction of source errors will try user patience. for( each referring source file ) + Either elevate its determination state in (b) to `imageable` or leave it untouched. feedback, user : join + Meter progress of local and remote probes. /   Probing referent files: 97 local, 21 remote   Translating source files en passent   ,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,, 0-73 to translate   ,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,;,,,,,,;; 1-16   ;;;;;;;;;;;;;;;;;;   3 translated - The lower bound on the number of source files to translate is got by counting the `imageable` files of `imageabilityDeterminations`. - The upper bound (more of interest) is got by counting the `indeterminate` files of `imageabilityDeterminations` that might yet become `imageable` because each has at least one formal resource whose probe is pending. - This requires adding to `imageabilityDeterminations` (for each source file) the number of the formal resources (of that file) whose probe is pending. + Add a legend to the meter at verbosity level 2. /   Probing referent files: 97 local, 21 remote   Legend: local (,) bypassed (.)   remote (;) bypassed (:) timed out (?)   Translating source files en passent   ,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,, 0-73 to translate   ,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,;,,,,,,;; 1-16   ;;;;;;;;;;;;;;;;;;   3 translated + Rework the symbols for legibility. iv. Probe the locally reachable resources. v. Await the remote-resource probes of iii above. 3. Extend the image to its bounds. - Translates each imageable source file (a). 4. Finish the image files. + Apply a read-only `umask`, or its Java equivalent, to the image. : privately see e.g. /usr/local/bin/sync-to namespace, `data:,Breccia/Web/imager` : re `data` see https://datatracker.ietf.org/doc/html/rfc2397 - The conventional prefix is `img`. parity between Web images and edit buffers : see also `^*fidelity, images true to the Breccian source$` - Web images (in browser) and edit buffers of the originals (in editor) should have the same features and capabilities as far as feasible given their differences of form and purpose. - Public reading is the main purpose of the images. referencing afterlinkers - Afterlinkers might be given hover effects that operate bidirectionally between subject (control) and object clause (view). - Where two subjects overlap or nest, the two spans marking them would break into three, the middle doing double duty. identification, fractum identifiers based on proven fractum locants - Prefer a fractum identifier (`id` attribute) based on a proven fractum locant, one that has successfully referred to that fractum. / E.g. a fractum locant of the referring file, or another within the image bounds. / As opposed to the present keyword-based identifier, which nevertheless would remain the default. : see BreccianFileTranslator.java : `translate(Document)` § Body fracta § Identification by `id` attribution ∵ This would preserve information of potential use to authors. - E.g. it gives Brec Mode for Emacs proven fractum locants to use where it prompts the user to substitute source-file references for image-file references. : see `^*image-file references, replacement by source-file references` @ ~/work/Breccia/Emacs/notes.brec - Form the identifier by: • Stripping any file locant • Encoding the result lightly in order to improve readability - Where two references to a fractum employ different locants, choose one by applying a stable selection criterion. implicit : cf. `^*term reference` @ ~/work/editorial_guidelines.brec / The purpose is to avoid overburdening authors with writing cross references. - Any word outside of a link subject is eligible for implicit reference. - Any eligible word `w` that matches the first word of at least one index entry gets encoded into it an implicit reference trigger. - Recorded in the trigger is the longest span of eligible words `s` that both starts with `w` and matches an index entry, plus a reference to that entry. / Somehow a match of multiple entries will be resolved to a single entry, unless and until a means of offering the user a choice is implemented. / The method of matching will need refinement in practice. / E.g. start by ignoring case, except maybe where it helps in narrowing multiple matches. - The trigger activates when the mouse enters `w`, then deactivates when it leaves. - While active, a temporary hyperlink reference appears around `s`, enabling user access to the index entry. / Consider here the standard help form of mouse cursor, which I believe is interrogative. - The index entries considered include, in priority order: • unique headings of the present file / These need definition, but the obvious candidates are division titles, plain bullets and word-form task bullets. • glossaries of ancestor directories, nearest first • the general index : see http://reluk.ca/project/way/index.brec - Index entries will need further paring. - Some cut entirely from consideration. / E.g. a component keyword of the general index (‘bar’) that merely points to a full entry (‘foo bar’). - Others cut in part. / E.g. a heading such as `LS, localization separator`, which pares to a plain bullet of `LS,`, should be further pared to `LS`. peculiar URI reference : cf. @ ~/code/WP3/wayic/model/compiler/working_notes.brec : see ~/work/Breccia/Web/imager/RemoteChangeProbe.java : `improbeableMessage` - An absolute-path reference, or a URI with an unrecognized scheme. - Authors are going to use absolute-path references to refer to local files. : see https://www.rfc-editor.org/rfc/rfc3986#section-4.2 - Many, too, will form them using `~/` prefixes. : privately see `Tilde Expansion` @ non-fractal man:bash - Authors are going to use ad hoc schemes for private purposes. ? How deal with them? | translate any for which the user gives (through configuration) a translation / Cannot rely exclusively on `wayic.model.compiler` here, ∵ the image might be of an uncompiled waycast, or (case of `Breccia.Web.imager`) no waycast at all. - The translation would be applied to the `href` attribute of the `a` element, not to the source-form trigger (body of `a` element). | form the remainder as inactive hyperlinks in the Web image \ - Consider coding a user script that activates them privately, \ where that makes sense. \\ users should not browse images locally; rather their source files, \\ e.g. with a text editor regular-expression pattern language : cf. @ ~/code/WP3/wayic/model/compiler/working_notes.brec + Guide compliance with the Breccian definition by throwing errors for unsupported elements. : see `Cannot rely exclusively on \`wayic.model.compiler\` here` @ `^*peculiar URI reference$` testing : see also `^^testing$`i @ ~/code/WP3/wayic/Web/imager/notes.brec >+ (p=Breccia/Web/imager; $p/build-all && $p/bin/web-image-clean $p/test/) > Breccia/Web/imager/build-all > (p=Breccia/Web/imager; $p/bin/web-image-clean $p/test/) >+ (p=Breccia/Web/imager; $p/build-all && $p/bin/breccia-web-image -co-service-directory=/_/Web_service/ -force Breccia/Web/imager/test/) > Breccia/Web/imager/build-all > Breccia/Web/imager/bin/breccia-web-image -co-service-directory=/_/Web_service/ -force Breccia/Web/imager/test/