proto-wayic/read/project.task
< pushd ~/work/_/proto-wayic/read/
( http://reluk.ca/project/proto-wayic/read/
( http://reluk.ca/var/deploy/test/proto-wayic/read/
- new name `proto-wayic.layout` -
= rename 'proto-wayic.read' -> 'proto-wayic.layout'
- including variants such as 'proto-wayic/read' and 'wayic_read'
= rename 'readable.*' -> 'way_declaration_document.*'
_____
+ engagement indexing
- presenting a comprehensive, hyperlinked list of the waycaster's engagements
( proto-wayic.exec § engagement
- the necessary code deploys in waycast configuration file `waycast.xml` -
- therefore it is proper to the present project,
not e.g. to `proto-wayic.exec` whose concerns cut across `waycast.xml` -
< waycast.xml
* transformation method
- for the styling and other presentation tasks below
- testing under `xsltproc` -
> xsltproc ~/work/_/proto-wayic/read/waycast_configuration_file.xslt waycast.xml
( bug: it fails if the style sheet argument is omitted
| a modified identity transform of the source XML
- modified to add the triggers
| transformation by XSLT
-! it does not escape the tag delimiters
- viz. does not serialize
- unable simply to use the `serialize` function of XPath 3
( https://www.w3.org/TR/xpath-functions-30/#func-serialize
- Firefox (at least) appears to be stuck at an earlier version
without this function
< https://developer.mozilla.org/en-US/docs/Web/XPath/Functions
| XSLT transformation to boot a JavaScript program
- the JavaScript program does all the real work
= code this
= document why a simpler `CDATA` wrapping (below) fails
- generally the poor support of client side XSLT, viz. in browers
/ | CDATA wrapping followed by JavaScript transformation
/ * CDATA wrapping
/ | https://stackoverflow.com/a/1648776/2402790
/
/ <html:pre style='color: blue; font-weight: bold;'>
/ <text disable-output-escaping="yes"><![CDATA[</text>
/ <call-template name='serialize-document'/>
/ <text disable-output-escaping="yes">]]</text>
/ <text disable-output-escaping="yes">></text>
/ </html:pre>
/
// ! `disable-output-escaping` is unsupported in Firefox
/ ( https://developer.mozilla.org/en-US/docs/Web/XSLT/Common_Errors#Missing_features
/ - works in Chrome
/ | using the `output` attribute `cdata-section-elements` -
/ ( https://www.xmltutorial.info/xslt/how-to-output-cdata-with-xsl/
/
/ <output method='xml' version='1.0' encoding='UTF-8' media-type='application/xhtml+xml'
/ data-section-elements='html:pre'/>
/ <template match='/'>
/ <html:html xml:lang='en-CA'>
/ <html:body bgcolor='#FFFFCC'>
/ <html:pre style='color: blue; font-weight: bold;'>
/ <call-template name='serialize-document'/>
/ </html:pre>
/ </html:body>
/ </html:html>
/ </template>
/
// ! fails
/ - I expect I am misusing it, owing to ignorance of XSLT
/ * JavaScript transformation
/ - quotation and unwrapping
/ - exhaustive quotation is easy under JavaScript
| use Lenz
< http://lenzconsulting.com/xml-to-string/
- it works
/ ! Lenz is a huge file
/ - there must be a simpler way
// no longer matters because normally it needn't be installed in waycast
| exhaustive quotation
< https://stackoverflow.com/a/1162495/2402790
- exhaustive quotation is awkward under XSLT
/ | transformation by JavaScript
/ - but using `<xsl:output>` to define the content type of the output
/ - thus transforming after the fact of layout
// ! clumsy
/ | XML script call
/ - how
/ | XHTML `script` tag
/ < https://stackoverflow.com/a/1451526/2402790
/ | XHTML script call
/ - transforming the XML to XHTML,
/ which then calls the script
/ - testing that it will work directly from the local filsystem
/ ( under a 'file' scheme, that is
= present hyperlink triggers
- on all hyperlinkable references
- both intracast (`way location`) and extracast (`description`)
= ensure viewers know of it
- e.g. by pointing from the README
= style the `engagement` elements
- for clarity and consistency with the inway, Web presentation
- note
= `href` of `xml-stylesheet` constrained
- with 'file' scheme
- to a 'file' scheme target
- not 'http'
- under ./
- with 'http' scheme
- not tested
- probably to the same domain
/ = give engagement markup a travel target locator
/ - for clarity on where precisely the waycaster is engaged
/ - often the target is difficult to find in the Web view
// ! no longer needed
/ - now triggers and targets are similar in appearance
/ - now targets are clearly marked
_____
- regressions attending Chrome upgrades
=! broken scroll positioning
- on reload or back travel
=! partial losss of breadcrumb cueing
- lost after first return to a trigger
- subsequent returns no longer show the breadcrumb
- affects both the latest revision and the current working copy
_____
= try to simplify CAST_ROOT_PATH
- by giving it a trailing slash
- since now it is guaranteed to be non-empty
_____
- URI delimiter fontification, for sake of clarity
( proto-wayic.emacs
- detected patterns
- URI reference
= distinctly fontify URI delimiters
- formally intracast reference
= distinctly fontify the leading '/'
- subjoining waybit reference
= distinctly fontify the elemental part
_____
= proto-wayic.cast § waycast relative references and waycast public locations
= proto-wayic.cast § Configuration of a waycast § future proof loading of way_declaration_document.js
_____
- travel cues
- removing focus outline from bitform referential jointers
- a reversion bug
- occurs after activatation
- when they acquire the focus
- does *not* occur when developer tools are enabled
- because it steals the focus
= find fix
- in an old revision
= re-apply it
_____
= try reforming the missle as a cross-hair
( notebook 2018-7-17
- it will probably need a *drop-shadow* transform for the rotation
= try *drop-shadow* transform instead of box shadow
= answer whether colour transforms may now be used
- *contrast*, brightness, and so forth
- in place of *opacity*
- whether they work as expected now that a *drop-shadow* transform is used
= try replacing target symbol with a circled cross
- with rotation of missle's cross ending at the same angle as the circled cross
- and flight perspective ending at the same size
- for visual coherence
- for a more satisfying, convincing effect
= try replacing symbol in case of broken joint with a slash
- instead of a bar
- circled for subjoining waybit, uncircled for missile
_____
= show relative direction of back-travel from subjoining waybit
- using an 'outflight' animation
- blue line
- growing in size and diminishing in opacity (alpha)
- the opposite of inflight
- and (of course) in the opposite direction
- hitting the nominal hyperlink trigger, there seeming to cause the outline to appear
_____
= look into translation as an added directional cue
( something like this is slated for later as part of scene selection, in any case
- only in case of unit travel extent
- this anyway being the condition of directional determination
and thus all directional cueing
( as noted/coded elsewhere
- form
- interdocument
- fading and translation of the view just prior to the location change
- as though the referent document lay under the referring document
- intradocument
= determine this
- needs an effect that is scroll compatible
( notebook 2018-7-17
- scroll-like in look and feel
- e.g. more-or-less continuous
- works correctly when target already in view
- on back travel, too
- then reversing the effect, of course
_____
= give to subjoining waybit a 'self' cursor
( because it is self targeting, of course
- based on a new drawing: trigger_cursor/target_self.svg
- using for symbol a simplified target
- instead of an arrow
= give to generic extracast hyperlink the generic cursor
- viz. trigger_cursor/base.svg
- aka HLINK_CURSOR, but now this is the only use of it
= give to other generic hyperlinks a directional cursor
_____
= light cone to direct eye to action
( notebook 2018-8-4, connected notes (i) and (ii)
_____
= try to replace *opacity* property with contrast filter
- in order to achieve same effect at less cost
_____
-! vertical scroll flash
- when window just tall enough to hold final layout
/ - probably caused by a slightly taller layout prior to resolving interdocument referential joints
/ - probably (in particular) by temporary placeholders that are too tall
// but eager subjoint image caching should be preventing that, in nearly all cases
= find the cause
= fix
_____
= add site icon
- to waycast configuration
- to wayic personalized READMEs
- testing these first
=? or could/should these somehow be configured into *httpd*
_____
- healing broken referential joints
- where the subjoining waybit has moved in the waycast
= seek the new location exhaustively
= notify the user in *tsk* message
_____
=§ bidirectional traversal of referential joints
_____
= disable the 'visited' colouring of hyperlinks
- it distracts from visuals of greater significance in an already complex document
_____
= visibly warn if browser is of an untested type
────────────────────────────────────────────────────────────────────────────────────────────────────
Bidirectional traversal of referential joints`
- including back-travel from a subjoining waybit to any of its surjoining elements
[ scene selection model
- based on document location
- function: switches the view to the surjoint scene of a given subjoining waybit
- form
- a query component in this form:
( Extended Backus-Naur syntax notation, ISO/IEC 14977
'scn=srj&bit=', extended element reference ;
extended element reference = ? as per proto-wayic.script
§ Extended element referencing ?;
- example
file:/waycast/foo.xht?scn=srj&bit=bar
- operated via *History.pushState* in order to avoid reloading the page
- errors (parse, missing referent) are messaged in an alert box
[ document scene
- a way declaration document has one document scene
- it is the default scene, pending a scene change
- the document scene is nominally located to the right of each (off-page) surjoint scene
+ inway approach
- gradient rendering of approach path
- if formed as a shape, as opposed to an empty path
( https://www.w3.org/TR/SVG11/pservers.html
( https://developer.mozilla.org/en-US/docs/Web/API/SVGLinearGradientElement
+ leftward scene switch
- modal function of the inway approach
- modally enabled only for a subjoining waybit that is window targeted
- appearance when enabled
- the approach reveals itself in full:
1waybit
_
∙··_······················· ◉ 2sbj
= Content of 2sbj
3waybit
Content of 3waybit, a non-subjoining waybit
∙ · · · · · 4sbj
Content of 4sbj
- the stacked lines prefigure the count and arrangement of joint images
in the joint list
- their appearance is less prominent than shown here
- and they need not appear at all when the count is only one
- it operates like the (§) rightward scene switch
- fully appearing only when the pointer (☝) pauses over it
- full appearance:
_
◀——_——————————————————————— ◉ 2sbj
= ☝ Content of 2sbj
- the edging becomes an arrow head
= code just enough to show an empty surjoint scene
- click function is coded (but disabled) in SelfHyperlinking.hearClick
[ surjoint scene
- each subjoining waybit has one surjoint scene of its own
- nominally located to the left of the (off-page) document scene
joint list
⋰
⋰
↗ 1srj
Preview of 1st surjoining element
1sbj · · · · · · · · · · · · · · · · ·
Subjoint preview ·
⋱⋱ ·
← 2srj ·
Preview of 2nd surjoining element ·
2sbj · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · ◉
Subjoint preview ·
⋱⋱ ·
← 3srj · ⋱
Preview of 3rd surjoining element · ⋱
3sbj · · · · · · · · · · · · · · · · · ⋱
Subjoint preview ·
⋱⋱ · rightward
↘ 4srj · scene switch
Preview of 4th surjoining element ·
⋰ 4sbj · · · · · · · · · · · · · · · · ·
⋰ Subjoint preview
⋰ ⋮ ⋱⋱
surjoint ⋮
image + ⋮
subjoint = joint image
image
+ joint list
= figure how to include joints formed using hyperform jointers
- renders an ordered list of joint images
- one for each joint (each surjoining element) of the subjoining waybit
- ordered by the location of the surjoining element relative to the subjoining waybit:
- inner above
- outer
- inner below
+ joint image
- previews the presentation (in surjoint document) of both surjoining element
and subjoining waybit
- previews it using the operational forms of a *surjoint image* (of the surjoining element)
infrabutted by a *subjoint image* (of the subjoining waybit)
( see diagram above
* surjoint image
- its preview component appears only if the surjoining element is a waybit
- then it shows its leader, as per LeaderReader
- hyperlinks back to the surjoining element
- its surjointDirectionChar indicates the direction of travel to the surjoining element
and its location relative to the subjoining waybit
- roughly symmetric[al] with the jointer's associated *targetDirection*
in the surjoint document
- glyph
↗ intradocument travel upward of the subjoining waybit
( // '↗' is Unicode 2197 ('north east arrow')
← extradocument travel
( // '←' is Unicode 2190 ('leftwards arrow')
↘ intradocument travel downward of the subjoining waybit
( // '↘' is Unicode 2198 ('south east arrow')
- otherwise no target direction cueing (e.g. cursor)
* subjoint image
- largely replicates the jointer presentation in the surjoint document
- except no targetDirection cueing (e.g. cursor)
- for sake of symmetry with the surjoint image
- the link target is always to the right,
as shown by the (§) rightward scene switch
+ rightward scene switch
- extends to page edge right
- fully appears only when the pointer (☝) pauses over either a subjoint image
- or some part of the switch itself
- full appearance:
← 2srj ·
Preview of 2nd surjoining element ·
2sbj · · · · · · · · · · · · · · · · · ——————————————————————————————————▶ ◉
Subjoint preview ☝ · ☝
☝ ⋱⋱ ·
·
- operates via the scene selection model (§ q.v.)
- with a subtle (brief) rightward translation of scene
────────────────────────────────────────────────────────────────────────────────────────────────────
Blazing`
- marking the route to a way destination
- by highlighting jointers' vertical truncators and other hyperlink triggers
+ destination types
* engagement
< proto-wayic.exec § commitment declaration
────────────────────────────────────────────────────────────────────────────────────────────────────
Extended element referencing`
- implementation of proto-wayic.script § Extended element referencing
= look ahead for hazards
- I recall trouble trying to force an initial position in the viewport
- wrestling with the browsers own mechanism only to finish with unwanted vertical deflection
= give self-target function to all waybits
- not only to self-identified waybits
- also to those that lack an *id* attribute
- self-targeting each by means of extended element referencing
=preliminary: grep code for related, breakable uses of 'id'
- method
| hyperlink trigger injection
- each trigger given an *href* with an *element-relative offset*
- will become functional on coding the (§) extended view positioning mechanism
- advantages of this method
- enables foreseeing the target location via the browser's hyperlink HUD
= is hyperlink HUD wanted here?
= cannot the hyperlink HUD be controlled by other methods?
- fulfils purpose (§ q.v.) without need of travelling
- instead the wayscribe uses the browser's built-in function
for hyperlink reference copying
= is that actually easier?
| direct invocation of (§) extended view positioning mechanism
- by activation|click event handler
- purpose
- aid wayscribe in writing *element-relative offsets* where they are supported
( proto-wayic.script § Extended element referencing § form
- by realizing them in runtime references
* extended view positioning mechanism
- acting on any *element-relative offset* that is passed via window location
( proto-wayic.script § Extended element referencing § form
= code
= use in waycast
- to get on top of *id* proliferation
────────────────────────────────────────────────────────────────────────────────────────────────────
Troubleshooting`
( additional to `./readable.css` § Troubleshooting
- to test my local, Havoc copies of `readable.*`: see 'TEST' in `zz-swatch` § wayscript
Copyright © 2017-2019 Michael Allan and contributors. Licence MIT.