proto-wayic/read/manual.task - Instructions < see also http://reluk.ca/project/proto-Web/manual.task Basic use` - instructions to the waycaster on how basically to use `proto-wayic.read` - - requirements * a waycast * a recent version of Chrome or Firefox ( changing? sync'd → README.html - though any recent browser should work, only Chrome and Firefox are tested - working example < http://reluk.ca/project/proto-waycast/waycast.xml < http://reluk.ca/project/proto-waycast/way_declaration_document.css < http://reluk.ca/project/proto-waycast/way_declaration_document.js + waycast configuration file ( http://reluk.ca/project/proto-wayic/cast/doc.task § configuration of a waycast - above the first element of your `waycast.xml`, insert this processing instruction: │ ( [COR] - re `href`: avoid any whitespace before or after the '=' ( the correct function of `./waycast_configuration_file.xslt` depends on this - re `type`: the standard "application/xslt+xml" is not among those recognized by Chrome ( https://www.codingforums.com/xml/343437-xslt-chrome.html - limitations under 'file' scheme - when viewing the waycast configuration file by loading it from a 'file' scheme URI * Chrome ( version 69 - fails complaining of an "unsafe attempt" to load `waycast_configuration_file.xslt`: "'file:' URLs are treated as unique security origins" - workaround < cf. http://reluk.ca/project/proto-waycast/_/waycast_configuration_file.xslt.README 1 download from `http://reluk.ca/project/proto-wayic/read/` to the waycast a copy each of `waycast_configuration_file.css`, `waycast_configuration_file.js` and `waycast_configuration_file.xslt` - 2 refer to the downloaded `waycast_configuration_file.xslt` - from the `xml-stylesheet` processing instruction of `waycast.xml`, e.g.: │ 3 run Chrome with the `--allow-file-access-from-files` option [AFA] + personal style sheet ( http://reluk.ca/project/proto-wayic/cast/doc.task § configuration of a waycast - atop your `way_declaration_document.css` insert this: │ @import 'http://reluk.ca/project/proto-wayic/read/readable.css'; ( [COR] - optionally add this: │ @import 'http://reluk.ca/project/proto-wayic/read/pre_note.css'; ( [COR] + personal presentation program ( http://reluk.ca/project/proto-wayic/cast/doc.task § configuration of a waycast - in your `way_declaration_document.js` insert the equivalent of this: │ const s = document.body.appendChild( │ document.createElementNS( 'http://www.w3.org/1999/xhtml', 'script' )); │ s.setAttribute( 'src', 'http://reluk.ca/project/proto-Web/client_side.js' ); │ s.addEventListener( 'load', ( _Event ) => │ { │ const s = document.body.appendChild( │ document.createElementNS( 'http://www.w3.org/1999/xhtml', 'script' )); │ s.setAttribute( 'src', 'http://reluk.ca/project/proto-wayic/read/readable.js' ); │ s.addEventListener( 'load', ( _Event ) => │ { │ ca_reluk_wayic_read_WayDecDoc.start(); │ }); │ }); ( [COR] - limitations under 'file' scheme - when viewing a way declaration document by loading it from a 'file' scheme URI * Chrome ( version 69 - fails with an error message about loading `waycast.xml`, "Cross origin requests are only supported for protocol schemes: http, data, chrome, chrome-extension, https" - workaround - run Chrome with the `--allow-file-access-from-files` option [AFA] * Firefox ( version unknown, ≤ 60 - when the way declaration document is located in a waycast *sub*directory and was loaded as the "originating file" [SPF] - bitform referential jointers to ancestor and sister directories fail to show subjoint previews, instead showing '?' - and generally the presentation is incomplete and the way model harder to view - security constraints enforced by the browser are the underlying cause [SPF] - workaround - first load a document from the waycast *root* directory ( first, thus the "originating file" [SPF] - then follow its hyperlinks to other documents - any travel by means other than a document's hyperlinks (say bookmark or address bar) will break this workaround ──────────────────────────────────────────────────────────────────────────────────────────────────── Anonymous element and prefix declarations` - the presenter takes as anonymous any Wayscript element in which the local part of the name is encoded by a single underscore '_' - it transforms and presents the element accordingly - likewise it gives an element with a namespace prefix of '_' the same form as an element that has no prefix ──────────────────────────────────────────────────────────────────────────────────────────────────── Configuration` < see also http://reluk.ca/project/proto-Web/manual.task § configuration - instructions to the waycaster on how to configure `proto-wayic.read` before starting it + personal presentation program - edit your `way_declaration_document.js` to include the equivalent of this: ( extending the example of § basic use § personal presentation program │ ⋮ │ s.addEventListener( 'load', ( _Event ) => │ { │ const WayDecDoc = ca_reluk_wayic_read_WayDecDoc; │ WayDecDoc.setLightingStyle( 'neon' ); │ WayDecDoc.start(); │ }); - for the available configuration options, see <./readable.js § PUBLIC INTERFACE> ──────────────────────────────────────────────────────────────────────────────────────────────────── Publication` - instructions to the project provider: how to Web serve this project + programmatic resource files - these are the files named with an extension of `.css`, `.js` or `.xslt` - - they are served to the Web each with a special response header as detailed below - working example of a suitable header configuration for Apache HTTP Server < http://reluk.ca/sys/computer/server/etc/apache2/7_domain/reluk.ca/public/5_in_project_proto.conf * cross origin responses are enabled - the programmatic resource files of this project are served to the Web each with a response header of `Access-Control-Allow-Origin: *` - ( https://fetch.spec.whatwg.org/#http-access-control-allow-origin - this header grants to programmatic requesters originating from all network domains (`*`) permission to read the files ( https://www.w3.org/TR/cors/ - such requesters include those of the waycasts that use this project ( § basic use ──────────────────────────────────────────────────────────────────────────────────────────────────── Sectioning` - the presenter adds vertical margins to HTML `section` elements - it adds the same margins to Wayscript elements that are *direct children of the body* - to defeat this addition for a given group of `body` children - put them together in a single `section` element ──────────────────────────────────────────────────────────────────────────────────────────────────── Troubleshooting` < see also http://reluk.ca/project/proto-Web/manual.task § troubleshooting * console reporting - the presenter reports problems it detects to the browser's debugging console ( https://console.spec.whatwg.org/ * alert reporting under 'file' scheme - when the user requests a way declaration document from a 'file' scheme URI, the presenter assumes that the user is the author of that document - then, in addition to console reporting, it opens an `alert` window to report malformed content or any other problem that an author might be able to remedy //////////////////////////////////////////////////////////////////////////////////////////////////////// // N o t e s / [AFA] Chrome option `--allow-file-access-from-files`. https://peter.sh/experiments/chromium-command-line-switches/#allow-file-access-from-files https://code.google.com/p/chromium/codesearch#chromium/src/content/public/common/content_switches.cc&q=kAllowFileAccessFromFiles&sq=package:chromium&type=cs Security implications: https://stackoverflow.com/questions/29371600 [COR] Each request to `reluk.ca` requires that "cross origin responses are enabled". § publication http://reluk.ca/project/proto-Web/manual.task § publication [SPF] Same-origin policy for file scheme requests. In Firefox, "a file can read another file only if the parent directory of the originating file is an ancestor directory of the target file." https://developer.mozilla.org/en-US/docs/Same-origin_policy_for_file%3a_URIs Copyright © 2017-2019 Michael Allan and contributors. Licence MIT.