My working notes for the Breccia Web imager readable Web images+ : cf. `^^parity between Web images and edit buffers$` \ + Divisions. \ + Titling. \ - A `DivisionLabel` preceded by `Markup` that ends with a zero or more spaces preceded \ by a newline. \ + Looks like a line spacing of zero is needed in divider segments, too. \ : see ~/work/wayic/Web/imager/test/waycast/scratch.brec.xht \ + Style whatever remains unstyled. \ : see ~/.Xresources / All that remains, I believe, is hyperlinking. : see e.g. `^^referencing$` 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/FileTransformer.java : e.g. `formalReferenceAt` @ ~/work/Breccia/Web/imager/BrecciaHTMLTransformer.java : e.g. `formalReferenceAt` @ ~/work/wayic/Web/imager/WaybrecHTMLTransformer.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/FileTransformer.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 + Tell the user how many remote resources in total are to be probed for timestamps.   ⇒ 207 (max) remote resources to probe, 3 threads for( each resource ) + Give feedback to the user. : join + Send feedback to the user by printing a dot after each probe, periodically followed by an updated count of probes outstanding.   ⇒ 207 (max) remote resources to probe, 3 threads   .......   200 ..................................................   150 ..................................................   100 ............. + 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`. + 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. iv. Probe the locally reachable resources. v. Await the remote-resource probes of iii above. 3. Transform each imageable source file (a). + Overwrite|delete no image file unproven by signature. - Fail with an error message instead. + Delete any orphan image file. - Look for a `.xht` file that has a sibling of the same name minus the `.xht`. + Apply a read-only `umask`, or its Java equivalent, to the image. : see e.g. /usr/local/bin/sync-to build persistence+ - I need a persistent build of the imager for end use. \ | copying \ + Code `sync-build`. \ + Refer to it from Makeshift. \ / If only from my own branch. \\ \ - 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. + Learn whether something better is now available. + Code this target. - 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. element naming - Do not use custom names for elements. / : see https://html.spec.whatwg.org/multipage/dom.html#elements - 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/ : see test/drawing.brec , justification of choice : see image.css head: each is self referencing - The bullet of each fractum head is a self-referencing hyperlink referrer. : see `^^referent self-identifier$` 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 transforms each `.brec` file of the source to a `.brec.xht` file in the image. 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. \ - Any feature creep outside that purpose warrants a critical appraisal. \ / A Web browser makes a poor platform for text editing, \ on which waycasting relies heavily. referencing associative - Associative references are given hover effects that operate in both directions, either from referrer (control) to referent clause (view), or vice versa. / Not by insertion of hyperlink referrers. - Where two referrers overlap or nest, the two spans marking them break into three, the middle of which does double duty. / Which it could not were the middle span encoded as a hyperlink referrer. hyperlink - Cueing exit from the way model by e.g. cursor styling and opening of a separate tab. Breccian referents : see `^^referent self-identifier$` - Referring to the image (`.brec.xht`) if present, else to the Breccian original (`.brec`). - Waiting therefore till all (would be) HTML output files of the image (if not their contents) are in place before testing for the presence of any referent internal to that image. implicit : cf. `^^term reference` @ ~/work/editing/notepad.brec / The purpose is to avoid overburdening authors with writing cross references. - Any word outside of an associative referrer 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. lexicons of ancestor directories, nearest first the general index : see http://reluk.ca/project/wayic/refractory/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`. inline URI reference - A URI reference in free-form text. / E.g. in a comment carrier or indent blind, or anywhere in a division label or the descriptor of a point (other than a command point). - If it does not begin with a scheme component (is not a full URI), other cues are relied on for recognition. : see notebook:2019-8-6 - Authors are expected to ensure that no inline URI reference is directly followed by punctuation which might be taken as part of it unless the reference is symmetrically quoted, e.g. using backquotes or angle braces. / Like this, for example, <http://reluk.ca/#foo>. Or even this, .http://reluk.ca/#foo. But not this, http://reluk.ca/#foo. (wrong) peculiar URI reference : cf. @ ~/work/wayic/model/compiler/notepad.brec - A URI reference malformed, or with an unrecognized scheme. - Authors are going to use ad hoc schemes for private purposes. - Authors are going to use absolute-path references to refer to local files. : see https://datatracker.ietf.org/doc/html/rfc3986#section-4.1 - Many, too, will form them using `~` prefixes. : see `Tilde Expansion` @ non-fractal man:bash ? How deal with them? : cf. ~/work/Breccia/Web/imager/ImageMould.java : Here `formalResources_recordFrom` simply refuses to deal with `~` prefixes, pending a solution. | 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. \\ \\ referent identification - The browser finding the referent in order to relocate to it. - The hyperlink reference encodes the referent self-identifier. / A good balance of stability and simplicity. More stable identifiers might be possible (though how is yet unclear) but none nearly so simple. referent self-identifier - An `id` attribute on each fractum element of the image that encodes the lineo-hierarchic ordinal of the fractum. / E.g. ‘7.1.3’ for the 3rd child of the 1st child of the 7th child of the file fractum. regular-expression pattern language : cf. @ ~/work/wayic/model/compiler/notepad.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$` signature, image - To avoid overwriting or deleting a non-image file, the imager first seeks a tell-tale mark written into the leading content, and aborts if it is missing. - Its form is an HTML comment. Relatively stable ∵ independent of other content. - Its location is the topmost allowed by XML syntax. Rapidly found. testing workstation >+ Breccia/Web/imager/build-all && breccia-web-image --force Breccia/Web/imager/test/ > Breccia/Web/imager/build-all > breccia-web-image --force Breccia/Web/imager/test/ server : see @ `^^testing @ $` @ ~/work/wayic/Web/imager/notepad.brec \ Copyright © 2019-2022 Michael Allan. Licence MIT.