refactor docs

This commit is contained in:
Leon van Kammen 2026-11-06 15:41:16 +01:00
parent 6b3737cd52
commit ce2a05ed26
12 changed files with 1442 additions and 40192 deletions

View file

@ -1,102 +1,33 @@
%%% % if( ENVIRON["HTML"] ){
Title = "XR Fragments" % print(" ")
area = "Internet" % }
workgroup = "Jens & Leon Internet Engineering Task Force"
[seriesInfo] ```
name = "XR-Fragments" ▄ ▄ ▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄ ▄▄▄▄▄▄ ▄▄▄ ▄▄▄ ▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄ ▄ ▄▄▄▄▄▄
value = "draft-XRFRAGMENTS-leonvankammen-00" ▓ ▓ ▓ ▓ ▓ ▓ ▓ ▓ ▓ ▓ ▄▄▄ ▓ ▓ ▓ ▓ ▓ ▓ ▓ ▓▄▄▄▄▄ ▓▄▄▄▄▄
stream = "IETF" ▄▀▀▀▀▀▄ ▒ ▒ ▒▀▀▀ ▒ ▒ ▒▀▀▀▀▀▒ ▒ ▒ ▒ ▒ ▒▄▄▄▄▄▒ ▒ ▒ ▒ ▒
status = "informational" ░ ░ ░ ░ ░ ░ ░ ░▄▄▄▄░ ░ ░ ░▄▄▄▄▄▄ ░ ░ ░▄▄▄▄▄ ▄▄▄▄▄░
```
date = 2023-04-12T00:00:00Z # XR Fragments spec
[[author]] ```
initials="L.R." stream: Guerilla Standardisation
surname="van Kammen"
fullname="L.R. van Kammen"
%%%
<!-- for annotated version see: https://raw.githubusercontent.com/ietf-tools/rfcxml-templates-and-schemas/main/draft-rfcxml-general-template-annotated-00.xml -->
<!--{
<style type="text/css">
body{
font-family: monospace;
max-width: 1000px;
font-size: 15px;
padding: 0% 10%;
line-height: 30px;
color:#555;
background:#F7F7F7;
}
h1 { margin-top:40px; }
pre{ line-height:18px; }
a,a:visited,a:active{ color: #70f; }
code{
border: 1px solid #AAA;
border-radius: 3px;
padding: 0px 5px 2px 5px;
}
pre{
line-height: 18px;
overflow: auto;
padding: 12px;
}
pre + code {
background:#DDD;
}
pre>code{
border:none;
border-radius:0px;
padding:0;
}
blockquote{
padding-left: 30px;
margin: 0;
border-left: 5px solid #CCC;
}
th {
border-bottom: 1px solid #000;
text-align: left;
padding-right:45px;
padding-left:7px;
background: #DDD;
}
td {
border-bottom: 1px solid #CCC;
font-size:13px;
}
</style>
<br>
<h1>XR Fragments</h1>
<br>
<pre>
stream: IETF
area: Internet area: Internet
status: informational status: informational
author: Leon van Kammen author: Leon van Kammen
date: 2023-04-12T00:00:00Z % system("printf \"date: \"; date -I")
workgroup: Internet Engineering Task Force workgroup: Internet Engineering Task Force
value: draft-XRFRAGMENTS-leonvankammen-00 value: draft-XRFRAGMENTS-leonvankammen-00
</pre> ```
}--> # Abstract
.# Abstract
> Version: 0.5 > Version: 0.5
An open specification for hyperlinking & deeplinking 3D fileformats. An open specification for hyperlinking & deeplinking 3D fileformats.
This draft is a specification for interactive URI-controllable 3D files, enabling [hypermediatic](https://github.com/coderofsalvation/hypermediatic) navigation, to enable a spatial web for hypermedia browsers with- or without a network-connection.<br> This is a specification for interactive URI-controllable 3D files, to enable spatial webs for local-first XR hypermedia browsers.<br/>
XR Fragments allows us to better use implicit metadata inside 3D scene(files), by mapping it to proven technologies like [URI Fragments](https://en.wikipedia.org/wiki/URI_fragment).<br> XR Fragments allows us to better use implicit metadata inside 3D scene(files), by mapping it to proven technologies like [URI Fragments](https://en.wikipedia.org/wiki/URI_fragment).<br>
> Almost every idea in this document is demonstrated at [https://xrfragment.org](https://xrfragment.org) > Almost every idea in this document is demonstrated at [https://xrfragment.org](https://xrfragment.org)
@ -110,7 +41,7 @@ XR Fragments allows us to better use implicit metadata inside 3D scene(files), b
1. [Introduction](#introduction) 1. [Introduction](#introduction)
1. [How does it work](#how-does-it-work) 1. [How does it work](#how-does-it-work)
1. [What does it solve](#what-does-it-solve) 1. [What does it solve](#what-does-it-solve)
1. [HFL (Hypermediatic Feedback Loop) for XR Browsers](#hfl-hypermediatic-feedback-loop-for-xr-browsers) 1. [Hypermediatic Feedback Loop for XR Browsers](#hfl-hypermediatic-feedback-loop-for-xr-browsers)
1. [Conventions and Definitions](#conventions-and-definitions) 1. [Conventions and Definitions](#conventions-and-definitions)
1. [XR Fragment URL Grammar](#xr-fragment-url-grammar) 1. [XR Fragment URL Grammar](#xr-fragment-url-grammar)
1. [Spatial Referencing 3D](#spatial-referencing-3d) 1. [Spatial Referencing 3D](#spatial-referencing-3d)
@ -126,10 +57,6 @@ XR Fragments allows us to better use implicit metadata inside 3D scene(files), b
1. [Level2: href links](#level2-href-links) 1. [Level2: href links](#level2-href-links)
1. [Interaction behaviour](#interaction-behaviour) 1. [Interaction behaviour](#interaction-behaviour)
1. [XR Viewer implementation](#xr-viewer-implementation) 1. [XR Viewer implementation](#xr-viewer-implementation)
1. [Level3: Media Fragments](#level3-media-fragments)
1. [Animation(s) timeline](#animation-s-timeline)
1. [Specify playback loopmode](#specify-playback-loopmode)
1. [Controlling embedded content](#controlling-embedded-content)
1. [Level4: prefix operators](#level4-prefix-operators) 1. [Level4: prefix operators](#level4-prefix-operators)
1. [Object teleports](#object-teleports) 1. [Object teleports](#object-teleports)
1. [Object multipliers](#object-multipliers) 1. [Object multipliers](#object-multipliers)
@ -137,6 +64,10 @@ XR Fragments allows us to better use implicit metadata inside 3D scene(files), b
1. [Sharing object or file (#|)](#sharing-object-or-file) 1. [Sharing object or file (#|)](#sharing-object-or-file)
1. [xrf:// URI scheme](#xrf-uri-scheme) 1. [xrf:// URI scheme](#xrf-uri-scheme)
1. [Level5: URI Templates (RFC6570)](#level5-uri-templates-rfc6570) 1. [Level5: URI Templates (RFC6570)](#level5-uri-templates-rfc6570)
1. [Level8: Media Fragments](#level8-media-fragments)
1. [Animation(s) timeline](#animation-s-timeline)
1. [Specify playback loopmode](#specify-playback-loopmode)
1. [Controlling embedded content](#controlling-embedded-content)
1. [Top-level URL processing](#top-level-url-processing) 1. [Top-level URL processing](#top-level-url-processing)
1. [UX](#ux) 1. [UX](#ux)
1. [Example: Navigating content href portals](#example-navigating-content-href-portals) 1. [Example: Navigating content href portals](#example-navigating-content-href-portals)
@ -156,17 +87,18 @@ XR Fragments allows us to better use implicit metadata inside 3D scene(files), b
1. [Appendix: Definitions](#appendix-definitions) 1. [Appendix: Definitions](#appendix-definitions)
# Introduction # Introduction
(!Introduction)
How can we add more control to existing text and 3D scenes, without introducing new dataformats?<br> How can we add more control to existing text and 3D scenes, without introducing new dataformats?<br>
Historically, there's many attempts to create the ultimate 3D fileformat.<br> Historically, there's many attempts to create the ultimate 3D fileformat.<br>
The lowest common denominator is: designers describing/tagging/naming things using **plain text**.<br> The lowest common denominator is: designers describing/tagging/naming things using **plain text**.<br>
XR Fragments exploits the fact that all 3D models already contain such metadata: XR Fragments exploits the fact that all 3D models already contain such metadata:
**XR Fragments allows deeplinking of 3D objects by mapping objectnames to URI fragments** ** Deeplinking 3D objects by mapping objectnames to URI fragments**
> For a better-readable, better-updated spec see the website https://xrfragment.org
# How does it work # How does it work
(!What is XR Fragments )
XR Fragments utilizes URLs: XR Fragments utilizes URLs:
@ -182,7 +114,6 @@ XR Fragments utilizes URLs:
It solves: It solves:
1. addressibility and [hypermediatic](https://github.com/coderofsalvation/hypermediatic) navigation of 3D scenes/objects: [URI Fragments](https://en.wikipedia.org/wiki/URI_fragment) using src/href spatial metadata 1. addressibility and [hypermediatic](https://github.com/coderofsalvation/hypermediatic) navigation of 3D scenes/objects: [URI Fragments](https://en.wikipedia.org/wiki/URI_fragment) using src/href spatial metadata
1. Interlinking text & spatial objects by collapsing space into a Word Graph (XRWG) to show [visible links](#visible-links)
1. unlocking spatial potential of the (originally 2D) hashtag (which jumps to a chapter) for navigating XR documents 1. unlocking spatial potential of the (originally 2D) hashtag (which jumps to a chapter) for navigating XR documents
1. refraining from introducing scripting-engines for mundane tasks (and preventing its inevitable security-headaches) 1. refraining from introducing scripting-engines for mundane tasks (and preventing its inevitable security-headaches)
1. the gap between text an 3d objects: object-names directly map to hashtags (=fragments), which allows 3D to text transcription. 1. the gap between text an 3d objects: object-names directly map to hashtags (=fragments), which allows 3D to text transcription.
@ -195,19 +126,18 @@ To aid adoption, the standard comprises of various (optional) support-levels, wh
> XR Fragments is in a sense, a <b>heuristical 3D format</b> or meta-format, which leverages heuristic rules derived from any 3D scene or well-established 3D file formats, to extract meaningful features from scene hierarchies.<br> > XR Fragments is in a sense, a <b>heuristical 3D format</b> or meta-format, which leverages heuristic rules derived from any 3D scene or well-established 3D file formats, to extract meaningful features from scene hierarchies.<br>
These heuristics, enable features that are both meaningful and consistent across different scene representations, allowing <b>higher interop</b> between fileformats, 3D editors, viewers and game-engines. These heuristics, enable features that are both meaningful and consistent across different scene representations, allowing <b>higher interop</b> between fileformats, 3D editors, viewers and game-engines.
# HFL (Hypermediatic Feedback Loop) for XR Browsers # Hypermediatic feedback Loop in XR Browsers
(!HFL (Hypermediatic Feedback Loop) for XR Browsers)
`href` metadata traditionally implies **click** AND **navigate**, however XR Fragments adds stateless **click** (`xrf://....`) via the `xrf://` scheme, which does not change the top-level URL-adress (of the browser). `href` metadata traditionally implies **click** AND **navigate**, however XR Fragments separates **click** via the `xrf://` scheme, which does not change the top-level URL-adress (of the browser).
This allows for many extra interactions via URLs, which otherwise needs a scripting language. This allows for many extra interactions via URLs, which otherwise needs a scripting language.
These are called **hashbus**-only events/ These are called **hash**-events in this sepc.
> Being able to use the same URI Fragment DSL for navigation (`href: #foo`) as well as interactions (`href: xrf://#foo`) greatly simplifies implementation, increases HFL, and reduces need for scripting languages. > Being able to use the same URI Fragment DSL for navigation (`href: #foo`) as well as interactions (`href: xrf://#foo`) greatly simplifies implementation, increases HFL, and reduces need for scripting languages.
This opens up the following benefits for traditional & future webbrowsers: This opens up the following benefits for traditional & future webbrowsers:
* [hypermediatic](https://github.com/coderofsalvation/hypermediatic) loading/clicking 3D assets (gltf/fbx e.g.) natively (with or without using HTML). * [hypermediatic](https://github.com/coderofsalvation/hypermediatic) loading/clicking 3D assets (gltf/fbx e.g.) natively (with or without using HTML).
* potentially allowing 3D assets/nodes to publish XR Fragments to themselves/eachother using the `xrf://` hashbus (`xrf://#person=walk` to trigger `walk`-animation for object `person`) * potentially allowing 3D assets/nodes to publish XR Fragments to themselves/eachother using the `xrf://` hash-events (`xrf://#person=walk` to trigger `walk`-animation for object `person`)
* potentially collapsing the 3D scene to an wordgraph (for essential navigation purposes) controllable thru a hash(tag)bus * potentially collapsing the 3D scene to an wordgraph (for essential navigation purposes) controllable thru a hash(tag)bus
* completely bypassing the security-trap of loading external scripts (by loading 3D model-files, not HTML-javascriptable resources) * completely bypassing the security-trap of loading external scripts (by loading 3D model-files, not HTML-javascriptable resources)
@ -216,26 +146,17 @@ XR Fragments itself are [hypermediatic](https://github.com/coderofsalvation/hype
| principle | 3D URL | HTML 2D URL | | principle | 3D URL | HTML 2D URL |
|-----------------------------|-------------------------------------------------|---------------------------------------| |-----------------------------|-------------------------------------------------|---------------------------------------|
| the XRWG | wordgraph (collapses 3D scene to tags) | Ctrl-F (find) | | the hash-events | hashtags alter camera/scene/object-projections | hashtags alter document positions |
| the hashbus | hashtags alter camera/scene/object-projections | hashtags alter document positions |
| src metadata | renders content and offers sourceportation | renders content |
| href metadata | teleports to other XR document | jumps to other HTML document | | href metadata | teleports to other XR document | jumps to other HTML document |
| href metadata | triggers predefined view | Media fragments |
| href metadata | triggers camera/scene/object/projections | n/a |
| href metadata | draws visible connection(s) for XRWG 'tag' | n/a |
| href metadata | filters certain (in)visible objects | n/a |
| href metadata | href="xrf://#-foo&bar" | href="javascript:hideFooAndShowBar()` | | href metadata | href="xrf://#-foo&bar" | href="javascript:hideFooAndShowBar()` |
| | (this does not update topLevel URI) | (this is non-standard, non-hypermediatic) |
> An important aspect of HFL is that URI Fragments can be triggered without updating the top-level URI (default href-behaviour) thru their own 'bus' (`xrf://#.....`). This decoupling between navigation and interaction prevents non-standard things like (`href`:`javascript:dosomething()`). > An important aspect is that URI Fragments can be triggered without updating the top-level URI (default href-behaviour) thru their own 'bus' (`xrf://#.....`). This decoupling between navigation and interaction prevents non-standard things like (`href`:`javascript:dosomething()`).
# Conventions and Definitions # Conventions and Definitions
(!Conventions and Definitions)
See appendix below in case certain terms are not clear. See appendix below in case certain terms are not clear.
## XR Fragment URL Grammar ## XR Fragment URL Grammar
(! XR Fragment URL Grammar )
For typical HTTP-like browsers/applications: For typical HTTP-like browsers/applications:
@ -254,12 +175,12 @@ sub-delims = "," / "="
> this is already implemented in all browsers > this is already implemented in all browsers
Pseudo (non-native) browser-implementations (supporting XR Fragments using HTML+JS e.g.) can use the `?` search-operator to address outbound content.<br> For in-browser implementations where hash is already used, the following formats can be used:
In other words, the URL updates to: `https://me.com?https://me.com/other.glb` when navigating to `https://me.com/other.glb` from inside a `https://me.com` WebXR experience e.g.<br>
That way, if the link gets shared, the XR Fragments implementation at `https://me.com` can load the latter (and still indicates which XR Fragments entrypoint-experience/client was used). * [janusweb](https://github.com/jbaicoianu/janusweb): `https://web.janus.org/#janus.url=https%3A%2F%2Ffoo.com%2Fmy3d.gltf%23room1%26prio%3D-5%26t%3D0%2C100`
* viewer using query for url-input: `https://my.org/myviewer?https%3A%2F%2Ffoo.com%2Fmy3d.gltf%23room1%26prio%3D-5%26t%3D0%2C100`
# Spatial Referencing 3D # Spatial Referencing 3D
(!Spatial Referencing 3D )
3D files contain an hierarchy of objects.<br> 3D files contain an hierarchy of objects.<br>
XR Fragments assumes the following objectname-to-URI-Fragment mapping, in order to deeplink 3D objects: XR Fragments assumes the following objectname-to-URI-Fragment mapping, in order to deeplink 3D objects:
@ -286,15 +207,11 @@ XR Fragments assumes the following objectname-to-URI-Fragment mapping, in order
> Every 3D fileformat supports named 3D object, and this name allows URLs (fragments) to reference them (and their children objects). > Every 3D fileformat supports named 3D object, and this name allows URLs (fragments) to reference them (and their children objects).
Clever nested design of 3D scenes allow great ways for re-using content, and/or previewing scenes.<br> Clever nested design of 3D scenes allow great ways for re-using content, and/or previewing scenes.<br>
For example, to render a portal with a preview-version of the scene, create an 3D object with: For example, to render a portal with a preview-version of the scene, create an 3D object with extra/metadata:
* href: `https://scene.fbx` * href: `https://scene.gltf`
> It also allows **sourceportation**, which basically means the enduser can teleport to the original XR Document of an `src` embedded object, and see a visible connection to the particular embedded object. Basically an embedded link becoming an outbound link by activating it.
# Level0: Files # Level0: Files
(!Level0: Files )
(!Level0: Files)
Compatible 3D fileformats: [glTF](https://www.khronos.org/gltf/), [usdz](https://openusd.org/release/spec_usdz.html), [obj](https://en.wikipedia.org/wiki/Wavefront_.obj_file), [collada](https://www.khronos.org/collada), [THREE.json](https://github.com/mrdoob/three.js/wiki/JSON-Object-Scene-format-4), [X3D](https://en.wikipedia.org/wiki/X3D) e.g. Compatible 3D fileformats: [glTF](https://www.khronos.org/gltf/), [usdz](https://openusd.org/release/spec_usdz.html), [obj](https://en.wikipedia.org/wiki/Wavefront_.obj_file), [collada](https://www.khronos.org/collada), [THREE.json](https://github.com/mrdoob/three.js/wiki/JSON-Object-Scene-format-4), [X3D](https://en.wikipedia.org/wiki/X3D) e.g.
<br> <br>
@ -310,14 +227,12 @@ they can accomodate developers or applications who (for whatever reason) must no
## Timelines ## Timelines
when a loaded file contains a timeline (animations/subtitles e.g.), then: When a loaded file contains a timeline (animations/subtitles e.g.), then:
> All timelines must play (looped) by default (to enable [[XR Movies]]) > All timelines must play (looped) by default (to enable [[XR Movies]])
Unless an object has multiple animations (actions e.g.), then just play the first or with name `default`. Unless an object has multiple animations (actions e.g.), then just play the first or with name `default`.
## via href metadata ## via href metadata
``` ```
@ -377,14 +292,12 @@ $ setfattr -n explainer.vtt -v "subtitles.vtt" explainer.glb
## JSON sidecar-file ## JSON sidecar-file
For developers, sidecar-file can allow for defining **explicit** XR Fragments links (>level1), outside of the 3D file.<br> > NOTE: the following approach is only recommended for archivist/userupload scenarios where the 3D file itself should not be altered.
This can be done via (objectname/metadata) key/value-pairs in a JSON [sidecar-file](https://en.wikipedia.org/wiki/Sidecar_file):
* experience.glb For developers, a json-sidecar-file can allow for defining explicit XR Fragments metadata (>level1), outside of the 3D file.
* experience.json `<----` This can be done via (objectname/metadata) key/value-pairs in a JSON sidecar-file:
```json
```json
{ {
"aria-description": "description of scene", "aria-description": "description of scene",
"button": { "button": {
@ -394,22 +307,21 @@ This can be done via (objectname/metadata) key/value-pairs in a JSON [sidecar-fi
} }
``` ```
> This will make object `button` clickable, and teleport the user to object `roomB`. This will make object button clickable, and teleport the user to object roomB.
<br>
> So after loading experience.glb the existence of experience.json is detected, to apply the explicit metadata. <br>The sidecar will define (or override already existing) extras, which can be handy for multi-user platforms (offer 3D scene customization/personalization to users).
So after loading `experience.glb` the existence of `experience.json` is detected, to apply the explicit metadata.<br> In THREE.js-code this would boil down to:
The sidecar will define (or **override** already existing) extras, which can be handy for multi-user platforms (offer 3D scene customization/personalization to users).
> In THREE.js-code this would boil down to:
```javascript ```javascript
scene.userData['aria-description'] = "description of scene" scene.userData['aria-description'] = "description of scene"
scene.getObjectByName("button").userData.href = "#roomB" scene.getObjectByName("button").userData.href = "#roomB"
// now the XR Fragments parser can process the XR Fragments userData 'extras' in the scene
``` ```
> now the XR Fragments parser can process the XR Fragments userData 'extras' in the scene
# Level1: URI # Level1: URI
(!Level1: URI)
> **XR Fragments allows deeplinking of 3D objects by mapping objectnames to URI fragments** > **XR Fragments allows deeplinking of 3D objects by mapping objectnames to URI fragments**
@ -446,26 +358,23 @@ Fact: our typical browser URL's are just **a possible implementation** of URI's
Below you can see how this translates back into good-old URLs: Below you can see how this translates back into good-old URLs:
``` ```
+───────────────────────────────────────────────────────────────────────────────────────────────+ +─────────────────────────────────────────────────────────────────────────────────────+
│ │ │ │
│ the soul of any URL: ://macro /meso ?micro #nano │ │ the soul of any URL: ://macro /meso ?micro #nano │
│ │ │ │
│ 2D URL: ://library.com /document ?search #chapter │ │ 2D URL: ://library.com /document ?search #chapter │
│ xrf:// │ │ │
│ 4D URL: ://park.com /4Dscene.fbx ─> ?other.glb ─> #object ─> hashbus │ │ 4D URL: ://park.com /4Dscene.fbx ─> ?other.glb ─> #object │
│ │ #filter │ │ │ │ │ │
│ │ #tag │ │ │ │ │ │
│ │ (hypermediatic) #material │ │ │ │ │ │
│ │ ( feedback ) #animation │ │ │ │ │ │
│ │ ( loop ) #texture │ │ │ │ │ │
│ │ #variable │ │ │ │ │ │
│ │ │ │ │ └─ view change ───────────────+ │
│ XRWG <─────────────────────<─────────────+ │ │ │
│ │ │ │ │ │
│ └─ objects ──────────────>─────────────+ │ +─────────────────────────────────────────────────────────────────────────────────────+
│ │
│ │
+───────────────────────────────────────────────────────────────────────────────────────────────+
``` ```
@ -476,7 +385,6 @@ Below you can see how this translates back into good-old URLs:
| fragment | type | example | info | | fragment | type | example | info |
|-------------------|------------|--------------------|----------------------------------------------------------------------| |-------------------|------------|--------------------|----------------------------------------------------------------------|
| `#......` | vector3 | `#room1` `#room2` `#cam2` | positions/parents camera(rig) (or XR floor) to xyz-coord/object/camera and upvector | | `#......` | vector3 | `#room1` `#room2` `#cam2` | positions/parents camera(rig) (or XR floor) to xyz-coord/object/camera and upvector |
| [Media Fragments](https://www.w3.org/TR/media-frags/) | [media fragment](#media%20fragments%20and%20datatypes) | `#t=0,2&loop` | play (and loop) 3D animation from 0 seconds till 2 seconds|
## List of **explicit* metadata ## List of **explicit* metadata
@ -489,7 +397,7 @@ These are the possible 'extras' for 3D nodes and sidecar-files
# Level2: href links # Level2: href links
(!Level2: href links)
Explicit href metadata ('extras') in a 3D object (of a 3D file), hint the viewer that the user ''can interact'' with that object : Explicit href metadata ('extras') in a 3D object (of a 3D file), hint the viewer that the user ''can interact'' with that object :
@ -513,10 +421,10 @@ The imported/teleported destination can be another object in the same scene-file
| level2 | click external 3D file [href](#via-href-metadata) (`foo.glb` e.g.) | replace the current scene with a new 3D file (`href: other.glb` e.g.) | | level2 | click external 3D file [href](#via-href-metadata) (`foo.glb` e.g.) | replace the current scene with a new 3D file (`href: other.glb` e.g.) |
| level2 | hover external 3D file [href](#via-href-metadata) | show the preview PNG thumbnail (if any sidecar, see level0) | | level2 | hover external 3D file [href](#via-href-metadata) | show the preview PNG thumbnail (if any sidecar, see level0) |
| level2 | activate animation | clicking href-value `#foo` will select animation `foo` (if exist) | | level2 | activate animation | clicking href-value `#foo` will select animation `foo` (if exist) |
| level2 | click [href](#via-href-metadata) | hashbus: execute without changing the toplevel URL location (`href: xrf://#someObjectName` e.g.) | | level2 | click [href](#via-href-metadata) | hash-events: execute without changing the toplevel URL location (`href: xrf://#someObjectName` e.g.) |
| level3 | click [href](#via-href-metadata) | set the global 3D animation timeline to its Media Fragment value (`#t=2,3` e.g.) | | higher levels | non-normative | non-normative |
> NOTE: hashbus links (`xrf://#foo&bar`) don't change the toplevel URL, which makes it ideal for interactions (in contrast to typical `#roomC` navigation, which benefit back/forward browser-buttons), see <a href="#hashbus">hashbus</a> for more info. > NOTE: hash-events links (`xrf://#foo&bar`) don't change the toplevel URL, which makes it ideal for interactions (in contrast to typical `#roomC` navigation, which benefit back/forward browser-buttons), see <a href="#hash-events">hash-events</a> for more info.
> **default camera (spawn) location**: When a 3D file is loaded, it will position the user/camera at xyz: 0,0,0 OR to the location of (an object called) ''spawn''. > **default camera (spawn) location**: When a 3D file is loaded, it will position the user/camera at xyz: 0,0,0 OR to the location of (an object called) ''spawn''.
@ -532,8 +440,58 @@ will load as default:
https://my.org/foo.glb#spawn https://my.org/foo.glb#spawn
``` ```
# Level3: Media Fragments # Level3: XR hints
(!Level3: Media Fragments )
> How to know whether a 3D file is a full scene or just a prop? <br>When should a 3D file hide its skybox?<br>How does a file know whether its embedded or not?<br>How to hide an object in AR-mode only?<br> How to ''hide'' an object by default, after loading a scene?
**Answer**: somehow tagging the file, or object with **predefined classes** ; universal XR keywords.
Example in JanusWeb JML:
```
<!-- xr layers: vr ar portal embed -->
<room>
<!-- override: dont show in AR by leaving 'ar' out -->
<object id="room_and_sky" class="vr portal embed">
<!-- override: only show in AR -->
<text text="welcome in AR mode" class="ar"/>
</room>
```
## Predefined hints: XR layers
| **hint/class** | desktop<br>mode | VR<br>mode | AR<br>mode | **usecase** |
|-|-|-|-|-|
| `vr` | show | show | hide | render object+children |
| `ar` | hide | hide | show | render object+children |
| `embed` | show | show | show | render object+children when loaded in another scene |
| `portal` | show | show | show | render object+children inside portal |
| `collection` | hide | hide | hide | object+children are not part of a scene/experience (think importing into inventory, openbrush brushes e.g.). |
| `hide` | hide | hide | hide | hide object+children |
Any element without any of these class-values is considered visible in all layers. Once class-value(s) are detected it'll work as a layer-mask: `class: 'vr ar'` will be visible in desktop-,VR- and AR-mode.
> **NOTE**: there's is no CSS: class attributes without CSS means **no cascade inheritance**; above class-definitions will apply to the element itself (and its children, which can override by defining their own XR layer class-definitions).
## Predefined hints: XR object interactions
| **hint/class** | **spec** | **document default** | **usecase** |
|-|-|-|-|
| `grabbable` | v1 | unset | allow single handtracking-pinch to reposition object, or via buttonhold + controllermove/mousemove |
| `stretchable` | v1 | unset | allow both handtracking-pinch to stretch object, or via buttonhold + controllermove/mousemove |
| `collidable` | v1 | unset | hints that `grabbable` and `stretchable` should halt upon collisions |
> **NOTE:** `href: #*foo` implies that object `foo` has `class: 'grabbable'`
## Usecases
* 3D previews: `class: 'vr ar'` prevents rendering (heavy) items when displayed in a portal (or embedded into another scene).
* extra info: `class: 'portal'` displays onboarding texts/info ONLY when rendered in a portal.
# Level8: Media Fragments
> these allow for XR Movies with a controllable timeline using `href` URI's with Media Fragments > these allow for XR Movies with a controllable timeline using `href` URI's with Media Fragments
@ -590,7 +548,7 @@ use [[URI Templates]] to control embedded media, for example a simple video-play
``` ```
# Level4: prefix operators # Level4: prefix operators
(!Level4: prefix operators)
Prefixing objectnames with the following simple operators allow for **extremely powerful** XR interactions: Prefixing objectnames with the following simple operators allow for **extremely powerful** XR interactions:
@ -603,7 +561,7 @@ Prefixing objectnames with the following simple operators allow for **extremely
> **Examples:** `#+menu` to show a object, `#-menu` to hide a menu, `#!menu` to teleport a menu, `#*block` to clone a grabbable block, `#|object` to share an object > **Examples:** `#+menu` to show a object, `#-menu` to hide a menu, `#!menu` to teleport a menu, `#*block` to clone a grabbable block, `#|object` to share an object
## Object teleports (!) ## Object teleports
Prefixing an object with an exclamation-symbol, will teleport a (local or remote) referenced object from/to its original/usercamera location.<br> Prefixing an object with an exclamation-symbol, will teleport a (local or remote) referenced object from/to its original/usercamera location.<br>
@ -715,14 +673,14 @@ The `xrf:` scheme will just do 2 & 3 (so the URL-values will not leak into the t
> **compliance with RFC 3986**: unimplemented/unknown URI schemes (`xrf:...` e.g.) will not update the top-level URL > **compliance with RFC 3986**: unimplemented/unknown URI schemes (`xrf:...` e.g.) will not update the top-level URL
# Level5: URI Templates (RFC6570) # Level5: URI Templates (RFC6570)
(!Level5: URI Templates (RFC6570))
XR Fragments adopts Level1 URI **Fragment** expansion to provide safe interactivity.<br> XR Fragments adopts Level1 URI **Fragment** expansion to provide safe interactivity.<br>
This is non-normative, and the draft spec is available on request. This is non-normative, and the draft spec is available on request.
# Top-level URL processing # Top-level URL processing
(!Top-level URL processing)
> Example URL: `://foo/world.gltf#room1&t=10&cam` > Example URL: `://foo/world.gltf#room1&t=10&cam`
@ -742,7 +700,7 @@ End-users should always have read/write access to:
# Example: Navigating content href portals # Example: Navigating content href portals
(!Example: Navigating content href portals)
navigation, portals & mutations navigation, portals & mutations
@ -772,18 +730,8 @@ navigation, portals & mutations
[» example 3D asset](https://github.com/coderofsalvation/xrfragment/blob/main/example/assets/href.gltf#L192)<br> [» example 3D asset](https://github.com/coderofsalvation/xrfragment/blob/main/example/assets/href.gltf#L192)<br>
[» discussion](https://github.com/coderofsalvation/xrfragment/issues/1)<br> [» discussion](https://github.com/coderofsalvation/xrfragment/issues/1)<br>
## Walking surfaces # Example: Virtual world webrings
> By default position `0,0,0` of the 3D scene represents the walkable plane, however this is overridden when the following applies:
XR Fragment-compatible viewers can infer this data based scanning the scene for:
1. materialless (nameless & textureless) mesh-objects (without `href` and >0 faces)
> optionally the viewer can offer thumbstick, mouse or joystick teleport-tools for non-roomscale VR/AR setups.
# Example: Virtual world rings
(!Example: Virtual world rings )
Consider 3D scenes linking to eachother using these `href` values, attached to 3D button-objects: Consider 3D scenes linking to eachother using these `href` values, attached to 3D button-objects:
@ -800,7 +748,7 @@ Now consider adding a 'webring index'-button to each file, with this href-value:
This would allow displaying the (remote 3D file) webring menu with various href-buttons inside, all centrally curated by the workgroup. This would allow displaying the (remote 3D file) webring menu with various href-buttons inside, all centrally curated by the workgroup.
# Additional scene metadata # Additional scene metadata
(!Additional scene metadata )
XR Fragments does not aim to redefine the metadata-space or accessibility-space by introducing its own cataloging-metadata fields. XR Fragments does not aim to redefine the metadata-space or accessibility-space by introducing its own cataloging-metadata fields.
Instead, it encourages browsers to scan nodes for the following custom properties: Instead, it encourages browsers to scan nodes for the following custom properties:
@ -844,7 +792,7 @@ There's no silver bullet when it comes to metadata, so XR Fragment-implementatio
> These attributes can be scanned and presented during an `href` or `src` eye/mouse-over. > These attributes can be scanned and presented during an `href` or `src` eye/mouse-over.
# Accessibility interface # Accessibility interface
(!Accessibility interface)
The addressibility of XR Fragments allows for unique 3D-to-text transcripts, as well as an textual interface to navigate 3D content.<br> The addressibility of XR Fragments allows for unique 3D-to-text transcripts, as well as an textual interface to navigate 3D content.<br>
Spec:<br><Br> Spec:<br><Br>
@ -876,7 +824,7 @@ Therefore a 2-button navigation-interface is the bare minimum interface:
2. objects with href metadata can be activated via a key (enter on a keyboard) 2. objects with href metadata can be activated via a key (enter on a keyboard)
3. the TTS reads the href-value (and/or aria-description if available) 3. the TTS reads the href-value (and/or aria-description if available)
## XRF microformat # XRF Microformat
How can applications discover 3D experiences on a network? How can applications discover 3D experiences on a network?
@ -884,7 +832,7 @@ How can applications discover 3D experiences on a network?
The XRF microformat is an [optional](#Progressive%20enhancement) text heuristics which applications can detect across various usecases. The XRF microformat is an [optional](#Progressive%20enhancement) text heuristics which applications can detect across various usecases.
#### via HTML webpage ## via HTML webpage
If the browser/application requests an webpage (`https://nlnet.nl` e.g.) it should check for the [rel-me microformat](https://gmpg.org/xfn/) : If the browser/application requests an webpage (`https://nlnet.nl` e.g.) it should check for the [rel-me microformat](https://gmpg.org/xfn/) :
@ -906,24 +854,56 @@ Another reason is that XR Fragments is filetype-agnostic, so flexibility is expe
> NOTE: in case of multiple 3D files mentioned in `<link rel="me"`, only the first (supported 3D filetype) will be chosen. > NOTE: in case of multiple 3D files mentioned in `<link rel="me"`, only the first (supported 3D filetype) will be chosen.
Example of multiple spatial microformats:
#### Collections
Example of a webpage with collection of 3D models (like [icosa.gallery](https://icosa.gallery)):
```xml
<link rel='alternate' as='spatial-portal' href="result1.glb"/>
<link rel='alternate' as='spatial-portal' href="result2.glb"/>
<link rel='alternate' as='spatial-portal' href="result3.glb#buildingA"/>
<link rel='alternate' as='spatial-portal' href="result3.glb#buildingB"/>
<!-- optional: pagination hints -->
<link rel='next' as='spatial-portal' href="..."/>
<link rel='prev' as='spatial-portal' href="..."/>
<link rel="pages" min="1" max="46" items="8" />
``` ```
3D engines (games/apps) can render these like clickable portals, for example JanusXR-style portals:
> NOTE: for more customizability [JML &lt;link&gt;](https://coderofsalvation.github.io/janus-guide/#/build/room?id=link) will allow for positioning/thumbnailed portals:
```xml
<fireboxroom>
<assets>
<assetimage src="/img/thumb1.jpg" id="img1"/>
<assetimage src="/img/thumb2.jpg" id="img2"/>
</assets>
<room skybox="true" pos="0 0 0" showavatar="false" use_local_asset="room_plane">
<link url="/myverse/janusxr_tutorial1/" thumb_id="img1" title_col="0.4 0.37 0.4" pos="0 0 0.001" draw_glow="true" scale="3 3 0.1" />
<link url="/myverse/janusxr_tutorial2/" thumb_id="img2" title_col="0.4 0.37 0.4" pos="3 0 0.001" draw_glow="true" scale="3 3 0.1" />
</room>
</fireboxroom>
```
### Mixing multiple spatial microformats:
```xml
<link rel="alternate" as="spatial-entrypoint" href="scene.xrf.glb"/> <link rel="alternate" as="spatial-entrypoint" href="scene.xrf.glb"/>
<link rel="me" href="myavatar.vrm"/> <link rel="me" href="myavatar.vrm"/>
<!-- JanusXR microformat https://github.com/jbaicoianu/janusweb <!-- JanusXR JML https://github.com/jbaicoianu/janusweb
<FireBoxRoom> <fireboxroom>
<Assets> <room>
<assetobject id="experience" src="scene.xrf.glb"/> <object id="scene.xrf.glb" pos="0 0 0"/>
</Assets> </room>
<Room> </fireboxroom>
<object pos="0 0 0" collision_id="experience" id="experience" />
</Room>
</FireBoxRoom>
--> -->
``` ```
#### via WebFinger
## via WebFinger
When John has an account on foo.com, how can other applications request his 3D homepage by simply entering `john@foo.com`? When John has an account on foo.com, how can other applications request his 3D homepage by simply entering `john@foo.com`?
@ -972,9 +952,9 @@ When John has an account on foo.com, how can other applications request his 3D h
This way the application will load `https://3d.john.foo.com/model/scene.glb` when the user types `john@foo.com` into the user field. This way the application will load `https://3d.john.foo.com/model/scene.glb` when the user types `john@foo.com` into the user field.
#### via Text (URI) ## via Text (URI)
Another way for an application to trigger loading a 3D scene is by detecting URI's of 3D scene-files any text: As a fallback, for an application to trigger loading a 3D scene is by detecting URI's of 3D scene-files any text:
* `foo.glb` (or any other popular 3D extension) * `foo.glb` (or any other popular 3D extension)
* `https://foo.com/scene.glb` (or any other popular protocol) * `https://foo.com/scene.glb` (or any other popular protocol)
@ -1002,7 +982,7 @@ If a glTF implementation does not support a particular extension, the (XRF) extr
> **Example 2** If an Extensions uses XR Fragments in URI's (`href: #otherroom` or `href: xrf://-walls` in OMI_LINK e.g.), then perform them according to XR Fragment spec (teleport user). But only once: ignore further overlapping metadata for that usecase. > **Example 2** If an Extensions uses XR Fragments in URI's (`href: #otherroom` or `href: xrf://-walls` in OMI_LINK e.g.), then perform them according to XR Fragment spec (teleport user). But only once: ignore further overlapping metadata for that usecase.
# Vendor Prefixes # Vendor Prefixes
(!Vendor Prefixes )
Vendor-specific metadata in a 3D scenefiles, are similar to vendor-specific [CSS-prefixes](https://en.wikipedia.org/wiki/CSS#Vendor_prefixes) (`-moz-opacity: 0.2` e.g.). Vendor-specific metadata in a 3D scenefiles, are similar to vendor-specific [CSS-prefixes](https://en.wikipedia.org/wiki/CSS#Vendor_prefixes) (`-moz-opacity: 0.2` e.g.).
This allows popular 3D engines/frameworks, to initialize specific features when loading a scene/object, in a progressive enhanced way. This allows popular 3D engines/frameworks, to initialize specific features when loading a scene/object, in a progressive enhanced way.
@ -1061,14 +1041,14 @@ String-templatevalues are evaluated as per [URI Templates (RFC6570)](https://www
# Security Considerations # Security Considerations
(!Security Considerations)
The only dynamic parts are [W3C Media Fragments](https://www.w3.org/TR/media-frags/) and [URI Templates (RFC6570)](https://www.rfc-editor.org/rfc/rfc6570).<br> The only dynamic parts are [W3C Media Fragments](https://www.w3.org/TR/media-frags/) and [URI Templates (RFC6570)](https://www.rfc-editor.org/rfc/rfc6570).<br>
The use of URI Templates is limited to pre-defined variables and Level0 fragments-expansion only, which makes it quite safe.<br> The use of URI Templates is limited to pre-defined variables and Level0 fragments-expansion only, which makes it quite safe.<br>
n fact, it is much safer than relying on a scripting language (javascript) which can change URN too. n fact, it is much safer than relying on a scripting language (javascript) which can change URN too.
# FAQ # FAQ
(!FAQ )
**Q:** Why is everything HTTP GET-based, what about POST/PUT/DELETE HATEOS<br> **Q:** Why is everything HTTP GET-based, what about POST/PUT/DELETE HATEOS<br>
**A:** Because it's out of scope: XR Fragment specifies a read-only way to surf XR documents. These things belong in the application layer (for example, an XR Hypermedia browser can decide to support POST/PUT/DELETE requests for embedded HTML thru `src` values) **A:** Because it's out of scope: XR Fragment specifies a read-only way to surf XR documents. These things belong in the application layer (for example, an XR Hypermedia browser can decide to support POST/PUT/DELETE requests for embedded HTML thru `src` values)
@ -1082,18 +1062,18 @@ Doing advanced scripting & networkrequests under the hood are obviously interest
Non-HTML Hypermedia browsers should make browser extensions the right place, to 'extend' experiences, in contrast to code/javascript inside hypermedia documents (this turned out as a hypermedia antipattern). Non-HTML Hypermedia browsers should make browser extensions the right place, to 'extend' experiences, in contrast to code/javascript inside hypermedia documents (this turned out as a hypermedia antipattern).
# authors # authors
(!authors)
* Leon van Kammen (@lvk@mastodon.online) * Leon van Kammen (@lvk@mastodon.online)
* Jens Finkhäuser (@jens@social.finkhaeuser.de) * Jens Finkhäuser (@jens@social.finkhaeuser.de)
# IANA Considerations # IANA Considerations
(!IANA Considerations)
This document has no IANA actions. This document has no IANA actions.
# Acknowledgments # Acknowledgments
(!Acknowledgments)
* [NLNET](https://nlnet.nl) * [NLNET](https://nlnet.nl)
* [Future of Text](https://futureoftext.org) * [Future of Text](https://futureoftext.org)
@ -1109,7 +1089,7 @@ This document has no IANA actions.
* Mark Anderson * Mark Anderson
# Appendix: Definitions # Appendix: Definitions
(!Appendix: Definitions )
|definition | explanation | |definition | explanation |
|----------------------|--------------------------------------------------------------------------------------------------------------------------------------| |----------------------|--------------------------------------------------------------------------------------------------------------------------------------|
@ -1121,8 +1101,7 @@ This document has no IANA actions.
|URN | something at some domain (`me.com/foo.glb`) | |URN | something at some domain (`me.com/foo.glb`) |
|metadata | custom properties of text, 3D Scene or Object(nodes), relevant to machines and a human minority (academics/developers) | |metadata | custom properties of text, 3D Scene or Object(nodes), relevant to machines and a human minority (academics/developers) |
|XR fragment | URI Fragment with spatial hints (which match the name of a 3D object-, camera-, animation-object) | |XR fragment | URI Fragment with spatial hints (which match the name of a 3D object-, camera-, animation-object) |
|the XRWG | wordgraph (collapses 3D scene to tags) | |the hash-events | hashtags map to camera/scene-projections |
|the hashbus | hashtags map to camera/scene-projections |
|spacetime hashtags | positions camera, triggers scene-preset/time | |spacetime hashtags | positions camera, triggers scene-preset/time |
|teleportation | repositioning the enduser to a different position (or 3D scene/file) | |teleportation | repositioning the enduser to a different position (or 3D scene/file) |
|sourceportation | teleporting the enduser to the original XR Document of an `src` embedded object. | |sourceportation | teleporting the enduser to the original XR Document of an `src` embedded object. |

View file

@ -1,614 +0,0 @@
%%%
Title = "XR Fragments"
area = "Internet"
workgroup = "Internet Engineering Task Force"
[seriesInfo]
name = "XR-Fragments"
value = "draft-XRFRAGMENTS-leonvankammen-00"
stream = "IETF"
status = "informational"
date = 2023-04-12T00:00:00Z
[[author]]
initials="L.R."
surname="van Kammen"
fullname="L.R. van Kammen"
%%%
<!-- for annotated version see: https://raw.githubusercontent.com/ietf-tools/rfcxml-templates-and-schemas/main/draft-rfcxml-general-template-annotated-00.xml -->
<!--{
<style type="text/css">
body{
font-family: monospace;
max-width: 1000px;
font-size: 15px;
padding: 0% 20%;
line-height: 30px;
color:#555;
background:#F0F0F3
}
h1 { margin-top:40px; }
pre{ line-height:18px; }
a,a:visited,a:active{ color: #70f; }
code{
border: 1px solid #AAA;
border-radius: 3px;
padding: 0px 5px 2px 5px;
}
pre{
line-height: 18px;
overflow: auto;
padding: 12px;
}
pre + code {
background:#DDD;
}
pre>code{
border:none;
border-radius:0px;
padding:0;
}
blockquote{
padding-left: 30px;
margin: 0;
border-left: 5px solid #CCC;
}
th {
border-bottom: 1px solid #000;
text-align: left;
padding-right:45px;
padding-left:7px;
background: #DDD;
}
td {
border-bottom: 1px solid #CCC;
font-size:13px;
}
</style>
<br>
<h1>XR Fragments</h1>
<br>
<pre>
stream: IETF
area: Internet
status: informational
author: Leon van Kammen
date: 2023-04-12T00:00:00Z
workgroup: Internet Engineering Task Force
value: draft-XRFRAGMENTS-leonvankammen-00
</pre>
}-->
.# Abstract
This draft offers a specification for 4D URLs & navigation, to link 3D scenes and text together with- or without a network-connection.<br>
The specification promotes spatial addressibility, sharing, navigation, query-ing and tagging interactive (text)objects across for (XR) Browsers.<br>
XR Fragments allows us to enrich existing dataformats, by recursive use of existing proven technologies like [URI Fragments](https://en.wikipedia.org/wiki/URI_fragment) and BibTags notation.<br>
> Almost every idea in this document is demonstrated at [https://xrfragment.org](https://xrfragment.org)
{mainmatter}
# Introduction
How can we add more features to existing text & 3D scenes, without introducing new dataformats?<br>
Historically, there's many attempts to create the ultimate markuplanguage or 3D fileformat.<br>
However, thru the lens of authoring, their lowest common denominator is still: plain text.<br>
XR Fragments allows us to enrich/connect existing dataformats, by recursive use of existing technologies:<br>
1. addressibility and navigation of 3D scenes/objects: [URI Fragments](https://en.wikipedia.org/wiki/URI_fragment) + src/href spatial metadata
1. hasslefree tagging across text and spatial objects using [BibTags](https://en.wikipedia.org/wiki/BibTeX) as appendix (see [visual-meta](https://visual-meta.info) e.g.)
> NOTE: The chapters in this document are ordered from highlevel to lowlevel (technical) as much as possible
# Core principle
XR Fragments strives to serve (nontechnical/fuzzy) humans first, and machine(implementations) later, by ensuring hasslefree text-vs-thought feedback loops.<br>
This also means that the repair-ability of machine-matters should be human friendly too (not too complex).<br>
> "When a car breaks down, the ones **without** turbosupercharger are easier to fix"
Let's always focus on average humans: the 'fuzzy symbolical mind' must be served first, before serving the greater ['categorized typesafe RDF hive mind'](https://en.wikipedia.org/wiki/Borg)).
> Humans first, machines (AI) later.
# Conventions and Definitions
|definition | explanation |
|----------------------|-------------------------------------------------------------------------------------------------------------------------------|
|human | a sentient being who thinks fuzzy, absorbs, and shares thought (by plain text, not markuplanguage) |
|scene | a (local/remote) 3D scene or 3D file (index.gltf e.g.) |
|3D object | an object inside a scene characterized by vertex-, face- and customproperty data. |
|metadata | custom properties of text, 3D Scene or Object(nodes), relevant to machines and a human minority (academics/developers) |
|XR fragment | URI Fragment with spatial hints like `#pos=0,0,0&t=1,100` e.g. |
|src | (HTML-piggybacked) metadata of a 3D object which instances content |
|href | (HTML-piggybacked) metadata of a 3D object which links to content |
|query | an URI Fragment-operator which queries object(s) from a scene like `#q=cube` |
|visual-meta | [visual-meta](https://visual.meta.info) data appended to text/books/papers which is indirectly visible/editable in XR. |
|requestless metadata | opposite of networked metadata (RDF/HTML requests can easily fan out into framerate-dropping, hence not used a lot in games). |
|FPS | frames per second in spatial experiences (games,VR,AR e.g.), should be as high as possible |
|introspective | inward sensemaking ("I feel this belongs to that") |
|extrospective | outward sensemaking ("I'm fairly sure John is a person who lives in oklahoma") |
|`◻` | ascii representation of an 3D object/mesh |
|(un)obtrusive | obtrusive: wrapping human text/thought in XML/HTML/JSON obfuscates human text into a salad of machine-symbols and words |
|BibTeX | simple tagging/citing/referencing standard for plaintext |
|BibTag | a BibTeX tag |
# List of URI Fragments
| fragment | type | example | info |
|--------------|----------|-------------------|-------------------------------------------------------------------|
| `#pos` | vector3 | `#pos=0.5,0,0` | positions camera to xyz-coord 0.5,0,0 |
| `#rot` | vector3 | `#rot=0,90,0` | rotates camera to xyz-coord 0.5,0,0 |
| `#t` | vector2 | `#t=500,1000` | sets animation-loop range between frame 500 and 1000 |
| `#......` | string | `#.cubes` `#cube` | object(s) of interest (fragment to object name or class mapping) |
> xyz coordinates are similar to ones found in SVG Media Fragments
# List of metadata for 3D nodes
| key | type | example (JSON) | info |
|--------------|----------|--------------------|--------------------------------------------------------|
| `name` | string | `"name": "cube"` | available in all 3D fileformats & scenes |
| `class` | string | `"class": "cubes"` | available through custom property in 3D fileformats |
| `href` | string | `"href": "b.gltf"` | available through custom property in 3D fileformats |
| `src` | string | `"src": "#q=cube"` | available through custom property in 3D fileformats |
Popular compatible 3D fileformats: `.gltf`, `.obj`, `.fbx`, `.usdz`, `.json` (THREEjs), `COLLADA` and so on.
> NOTE: XR Fragments are file-agnostic, which means that the metadata exist in programmatic 3D scene(nodes) too.
# Navigating 3D
Here's an ascii representation of a 3D scene-graph which contains 3D objects `◻` and their metadata:
```
+--------------------------------------------------------+
| |
| index.gltf |
| │ |
| ├── ◻ buttonA |
| │ └ href: #pos=1,0,1&t=100,200 |
| │ |
| └── ◻ buttonB |
| └ href: other.fbx | <-- file-agnostic (can be .gltf .obj etc)
| |
+--------------------------------------------------------+
```
An XR Fragment-compatible browser viewing this scene, allows the end-user to interact with the `buttonA` and `buttonB`.<br>
In case of `buttonA` the end-user will be teleported to another location and time in the **current loaded scene**, but `buttonB` will
**replace the current scene** with a new one, like `other.fbx`.
# Embedding 3D content
Here's an ascii representation of a 3D scene-graph with 3D objects `◻` which embeds remote & local 3D objects `◻` (without) using queries:
```
+--------------------------------------------------------+ +-------------------------+
| | | |
| index.gltf | | ocean.com/aquarium.fbx |
| │ | | │ |
| ├── ◻ canvas | | └── ◻ fishbowl |
| │ └ src: painting.png | | ├─ ◻ bass |
| │ | | └─ ◻ tuna |
| ├── ◻ aquariumcube | | |
| │ └ src: ://rescue.com/fish.gltf#q=bass%20tuna | +-------------------------+
| │ |
| ├── ◻ bedroom |
| │ └ src: #q=canvas |
| │ |
| └── ◻ livingroom |
| └ src: #q=canvas |
| |
+--------------------------------------------------------+
```
An XR Fragment-compatible browser viewing this scene, lazy-loads and projects `painting.png` onto the (plane) object called `canvas` (which is copy-instanced in the bed and livingroom).<br>
Also, after lazy-loading `ocean.com/aquarium.gltf`, only the queried objects `bass` and `tuna` will be instanced inside `aquariumcube`.<br>
Resizing will be happen accordingly to its placeholder object `aquariumcube`, see chapter Scaling.<br>
# XR Fragment queries
Include, exclude, hide/shows objects using space-separated strings:
* `#q=cube`
* `#q=cube -ball_inside_cube`
* `#q=* -sky`
* `#q=-.language .english`
* `#q=cube&rot=0,90,0`
* `#q=price:>2 price:<5`
It's simple but powerful syntax which allows <b>css</b>-like class/id-selectors with a searchengine prompt-style feeling:
1. queries are showing/hiding objects **only** when defined as `src` value (prevents sharing of scene-tampered URL's).
1. queries are highlighting objects when defined in the top-Level (browser) URL (bar).
1. search words like `cube` and `foo` in `#q=cube foo` are matched against 3D object names or custom metadata-key(values)
1. search words like `cube` and `foo` in `#q=cube foo` are matched against tags (BibTeX) inside plaintext `src` values like `@cube{redcube, ...` e.g.
1. `#` equals `#q=*`
1. words starting with `.` like `.german` match class-metadata of 3D objects like `"class":"german"`
1. words starting with `.` like `.german` match class-metadata of (BibTeX) tags in XR Text objects like `@german{KarlHeinz, ...` e.g.
> **For example**: `#q=.foo` is a shorthand for `#q=class:foo`, which will select objects with custom property `class`:`foo`. Just a simple `#q=cube` will simply select an object named `cube`.
* see [an example video here](https://coderofsalvation.github.io/xrfragment.media/queries.mp4)
## including/excluding
| operator | info |
|----------|-------------------------------------------------------------------------------------------------------------------------------|
| `*` | select all objects (only useful in `src` custom property) |
| `-` | removes/hides object(s) |
| `:` | indicates an object-embedded custom property key/value |
| `.` | alias for `"class" :".foo"` equals `class:foo` |
| `>` `<` | compare float or int number |
| `/` | reference to root-scene.<br>Useful in case of (preventing) showing/hiding objects in nested scenes (instanced by `src`) (*) |
> \* = `#q=-/cube` hides object `cube` only in the root-scene (not nested `cube` objects)<br> `#q=-cube` hides both object `cube` in the root-scene <b>AND</b> nested `skybox` objects |
[» example implementation](https://github.com/coderofsalvation/xrfragment/blob/main/src/3rd/js/three/xrf/q.js)
[» example 3D asset](https://github.com/coderofsalvation/xrfragment/blob/main/example/assets/query.gltf#L192)
[» discussion](https://github.com/coderofsalvation/xrfragment/issues/3)
## Query Parser
Here's how to write a query parser:
1. create an associative array/object to store query-arguments as objects
1. detect object id's & properties `foo:1` and `foo` (reference regex: `/^.*:[><=!]?/` )
1. detect excluders like `-foo`,`-foo:1`,`-.foo`,`-/foo` (reference regex: `/^-/` )
1. detect root selectors like `/foo` (reference regex: `/^[-]?\//` )
1. detect class selectors like `.foo` (reference regex: `/^[-]?class$/` )
1. detect number values like `foo:1` (reference regex: `/^[0-9\.]+$/` )
1. expand aliases like `.foo` into `class:foo`
1. for every query token split string on `:`
1. create an empty array `rules`
1. then strip key-operator: convert "-foo" into "foo"
1. add operator and value to rule-array
1. therefore we we set `id` to `true` or `false` (false=excluder `-`)
1. and we set `root` to `true` or `false` (true=`/` root selector is present)
1. we convert key '/foo' into 'foo'
1. finally we add the key/value to the store like `store.foo = {id:false,root:true}` e.g.
> An example query-parser (which compiles to many languages) can be [found here](https://github.com/coderofsalvation/xrfragment/blob/main/src/xrfragment/Query.hx)
## XR Fragment URI Grammar
```
reserved = gen-delims / sub-delims
gen-delims = "#" / "&"
sub-delims = "," / "="
```
> Example: `://foo.com/my3d.gltf#pos=1,0,0&prio=-5&t=0,100`
| Demo | Explanation |
|-------------------------------|---------------------------------|
| `pos=1,2,3` | vector/coordinate argument e.g. |
| `pos=1,2,3&rot=0,90,0&q=.foo` | combinators |
# Text in XR (tagging,linking to spatial objects)
We still think and speak in simple text, not in HTML or RDF.<br>
The most advanced human will probably not shout `<h1>FIRE!</h1>` in case of emergency.<br>
Given the new dawn of (non-keyboard) XR interfaces, keeping text as is (not obscuring with markup) is preferred.<br>
Ideally metadata must come **later with** text, but not **obfuscate** the text, or **in another** file.<br>
> Humans first, machines (AI) later ([core principle](#core-principle)
This way:
1. XR Fragments allows <b id="tagging-text">hasslefree XR text tagging</b>, using BibTeX metadata **at the end of content** (like [visual-meta](https://visual.meta.info)).
1. XR Fragments allows hasslefree <a href="#textual-tag">textual tagging</a>, <a href="#spatial-tag">spatial tagging</a>, and <a href="#supra-tagging">supra tagging</a>, by mapping 3D/text object (class)names using BibTeX 'tags'
1. Bibs/BibTeX-appendices is first-choice **requestless metadata**-layer for XR text, HTML/RDF/JSON is great (but fits better in the application-layer)
1. Default font (unless specified otherwise) is a modern monospace font, for maximized tabular expressiveness (see [the core principle](#core-principle)).
1. anti-pattern: hardcoupling a mandatory **obtrusive markuplanguage** or framework with an XR browsers (HTML/VRML/Javascript) (see [the core principle](#core-principle))
1. anti-pattern: limiting human introspection, by immediately funneling human thought into typesafe, precise, pre-categorized metadata like RDF (see [the core principle](#core-principle))
This allows recursive connections between text itself, as well as 3D objects and vice versa, using **BibTags** :
```
+---------------------------------------------+ +------------------+
| My Notes | | / \ |
| | | / \ |
| The houses here are built in baroque style. | | /house\ |
| | | |_____| |
| | +---------|--------+
| @house{houses, >----'house'--------| class/name match?
| url = {#.house} >----'houses'-------` class/name match?
| } |
+---------------------------------------------+
```
> The enduser can add connections by speaking/typing/scanning [hashtagbibs](https://github.com/coderofsalvation/hashtagbibs) which the XR Browser can expand to BibTags.
This allows instant realtime tagging of objects at various scopes:
| scope | matching algo |
|---------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| <b id="textual-tagging">textual</b> | text containing 'houses' is now automatically tagged with 'house' (incl. plaintext `src` child nodes) |
| <b id="spatial-tagging">spatial</b> | spatial object(s) with `"class":"house"` (because of `{#.house}`) are now automatically tagged with 'house' (incl. child nodes) |
| <b id="supra-tagging">supra</b> | text- or spatial-object(s) (non-descendant nodes) elsewhere, named 'house', are automatically tagged with 'house' (current node to root node) |
| <b id="omni-tagging">omni</b> | text- or spatial-object(s) (non-descendant nodes) elsewhere, containing class/name 'house', are automatically tagged with 'house' (too node to all nodes) |
| <b id="infinite-tagging">infinite</b> | text- or spatial-object(s) (non-descendant nodes) elsewhere, containing class/name 'house' or 'houses', are automatically tagged with 'house' (too node to all nodes) |
This empowers the enduser spatial expressiveness (see [the core principle](#core-principle)): spatial wires can be rendered, words can be highlighted, spatial objects can be highlighted/moved/scaled, links can be manipulated by the user.<br>
The simplicity of appending BibTeX 'tags' (humans first, machines later) is also demonstrated by [visual-meta](https://visual-meta.info) in greater detail.
1. The XR Browser needs to adjust tag-scope based on the endusers needs/focus (infinite tagging only makes sense when environment is scaled down significantly)
1. The XR Browser should always allow the human to view/edit the metadata, by clicking 'toggle metadata' on the 'back' (contextmenu e.g.) of any XR text, anywhere anytime.
> NOTE: infinite matches both 'house' and 'houses' in text, as well as spatial objects with `"class":"house"` or name "house". This multiplexing of id/category is deliberate because of [the core principle](#core-principle).
## Default Data URI mimetype
The `src`-values work as expected (respecting mime-types), however:
The XR Fragment specification bumps the traditional default browser-mimetype
`text/plain;charset=US-ASCII`
to a hashtagbib(tex)-friendly one:
`text/plain;charset=utf-8;bib=^@`
This indicates that:
* utf-8 is supported by default
* [hashtagbibs](https://github.com/coderofsalvation/hashtagbibs) are expanded to [bibtags](https://en.wikipedia.org/wiki/BibTeX)
* lines matching regex `^@` will automatically get filtered out, in order to:
* links between textual/spatial objects can automatically be detected
* bibtag appendices ([visual-meta](https://visual-meta.info) can be interpreted e.g.
> for more info on this mimetype see [bibs](https://github.com/coderofsalvation/hashtagbibs)
Advantages:
* out-of-the-box (de)multiplex human text and metadata in one go (see [the core principle](#core-principle))
* no network-overhead for metadata (see [the core principle](#core-principle))
* ensuring high FPS: HTML/RDF historically is too 'requesty'/'parsy' for game studios
* rich send/receive/copy-paste everywhere by default, metadata being retained (see [the core principle](#core-principle))
* netto result: less webservices, therefore less servers, and overall better FPS in XR
> This significantly expands expressiveness and portability of human tagged text, by **postponing machine-concerns to the end of the human text** in contrast to literal interweaving of content and markupsymbols (or extra network requests, webservices e.g.).
For all other purposes, regular mimetypes can be used (but are not required by the spec).<br>
## URL and Data URI
```
+--------------------------------------------------------------+ +------------------------+
| | | author.com/article.txt |
| index.gltf | +------------------------+
| │ | | |
| ├── ◻ article_canvas | | Hello friends. |
| │ └ src: ://author.com/article.txt | | |
| │ | | @friend{friends |
| └── ◻ note_canvas | | ... |
| └ src:`data:welcome human\n@...` | | } |
| | +------------------------+
| |
+--------------------------------------------------------------+
```
The enduser will only see `welcome human` and `Hello friends` rendered spatially.
The beauty is that text (AND visual-meta) in Data URI promotes rich copy-paste.
In both cases, the text gets rendered immediately (onto a plane geometry, hence the name '_canvas').
The XR Fragment-compatible browser can let the enduser access visual-meta(data)-fields after interacting with the object (contextmenu e.g.).
> additional tagging using [bibs](https://github.com/coderofsalvation/hashtagbibs): to tag spatial object `note_canvas` with 'todo', the enduser can type or speak `@note_canvas@todo`
The mapping between 3D objects and text (src-data) is simple (the :
Example:
```
+------------------------------------------------+
| |
| index.gltf |
| │ |
| └── ◻ rentalhouse |
| └ class: house <----------------- matches -------+
| └ ◻ note | |
| └ src:`data: todo: call owner | hashtagbib |
| #owner@house@todo | ----> expands to @house{owner,
| | bibtex: }
| ` | @contact{
+------------------------------------------------+ }
```
Bi-directional mapping between 3D object names and/or classnames and text using bibs,BibTags & XR Fragments, allows for rich interlinking between text and 3D objects:
1. When the user surfs to https://.../index.gltf#rentalhouse the XR Fragments-parser points the enduser to the rentalhouse object, and can show contextual info about it.
2. When (partial) remote content is embedded thru XR Fragment queries (see XR Fragment queries), indirectly related metadata can be embedded along.
## Bibs & BibTeX: lowest common denominator for linking data
> "When a car breaks down, the ones **without** turbosupercharger are easier to fix"
Unlike XML or JSON, BibTex is typeless, unnested, and uncomplicated, hence a great advantage for introspection.<br>
It's a missing sensemaking precursor to extrospective RDF.<br>
BibTeX-appendices are already used in the digital AND physical world (academic books, [visual-meta](https://visual-meta.info)), perhaps due to its terseness & simplicity.<br>
In that sense, it's one step up from the `.ini` fileformat (which has never leaked into the physical world like BibTex):
1. <b id="frictionless-copy-paste">frictionless copy/pasting</b> (by humans) of (unobtrusive) content AND metadata
1. an introspective 'sketchpad' for metadata, which can (optionally) mature into RDF later
| characteristic | UTF8 Plain Text (with BibTeX) | RDF |
|------------------------------------|-------------------------------|---------------------------|
| perspective | introspective | extrospective |
| structure | fuzzy (sensemaking) | precise |
| space/scope | local | world |
| everything is text (string) | yes | no |
| voice/paper-friendly | [bibs](https://github.com/coderofsalvation/hashtagbibs) | no |
| leaves (dictated) text intact | yes | no |
| markup language | just an appendix | ~4 different |
| polyglot format | no | yes |
| easy to copy/paste content+metadata| yes | up to application |
| easy to write/repair for layman | yes | depends |
| easy to (de)serialize | yes (fits on A4 paper) | depends |
| infrastructure | selfcontained (plain text) | (semi)networked |
| freeform tagging/annotation | yes, terse | yes, verbose |
| can be appended to text-content | yes | up to application |
| copy-paste text preserves metadata | yes | up to application |
| emoji | yes | depends on encoding |
| predicates | free | semi pre-determined |
| implementation/network overhead | no | depends |
| used in (physical) books/PDF | yes (visual-meta) | no |
| terse non-verb predicates | yes | no |
| nested structures | no (but: BibTex rulers) | yes |
> To keep XR Fragments a lightweight spec, BibTeX is used for rudimentary text/spatial tagging (not JSON, RDF or a scripting language because they're harder to write/speak/repair.).
Applications are also free to attach any JSON(LD / RDF) to spatial objects using custom properties (but is not interpreted by this spec).
## XR Text example parser
1. The XR Fragments spec does not aim to harden the BiBTeX format
2. respect multi-line BibTex values because of [the core principle](#core-principle)
3. Expand hashtag(bibs) and rulers (like `${visual-meta-start}`) according to the [hashtagbibs spec](https://github.com/coderofsalvation/hashtagbibs)
4. BibTeX snippets should always start in the beginning of a line (regex: ^@), hence mimetype `text/plain;charset=utf-8;bib=^@`
Here's an XR Text (de)multiplexer in javascript, which ticks all the above boxes:
```
xrtext = {
expandBibs: (text) => {
let bibs = { regex: /(#[a-zA-Z0-9_+@\-]+(#)?)/g, tags: {}}
text.replace( bibs.regex , (m,k,v) => {
tok = m.substr(1).split("@")
match = tok.shift()
if( tok.length ) tok.map( (t) => bibs.tags[t] = `@${t}{${match},\n}` )
else if( match.substr(-1) == '#' )
bibs.tags[match] = `@{${match.replace(/#/,'')}}`
else bibs.tags[match] = `@${match}{${match},\n}`
})
return text.replace( bibs.regex, '') + Object.values(bibs.tags).join('\n')
},
decode: (str) => {
// bibtex: ↓@ ↓<tag|tag{phrase,|{ruler}> ↓property ↓end
let pat = [ /@/, /^\S+[,{}]/, /},/, /}/ ]
let tags = [], text='', i=0, prop=''
let lines = xrtext.expandBibs(str).replace(/\r?\n/g,'\n').split(/\n/)
for( let i = 0; i < lines.length && !String(lines[i]).match( /^@/ ); i++ )
text += lines[i]+'\n'
bibtex = lines.join('\n').substr( text.length )
bibtex.split( pat[0] ).map( (t) => {
try{
let v = {}
if( !(t = t.trim()) ) return
if( tag = t.match( pat[1] ) ) tag = tag[0]
if( tag.match( /^{.*}$/ ) ) return tags.push({ruler:tag})
t = t.substr( tag.length )
t.split( pat[2] )
.map( kv => {
if( !(kv = kv.trim()) || kv == "}" ) return
v[ kv.match(/\s?(\S+)\s?=/)[1] ] = kv.substr( kv.indexOf("{")+1 )
})
tags.push( { k:tag, v } )
}catch(e){ console.error(e) }
})
return {text, tags}
},
encode: (text,tags) => {
let str = text+"\n"
for( let i in tags ){
let item = tags[i]
if( item.ruler ){
str += `@${item.ruler}\n`
continue;
}
str += `@${item.k}\n`
for( let j in item.v ) str += ` ${j} = {${item.v[j]}}\n`
str += `}\n`
}
return str
}
}
```
The above functions (de)multiplexe text/metadata, expands bibs, (de)serialize bibtex (and all fits more or less on one A4 paper)
> above can be used as a startingpoint for LLVM's to translate/steelman to a more formal form/language.
```
str = `
hello world
here are some hashtagbibs followed by bibtex:
#world
#hello@greeting
#another-section#
@{some-section}
@flap{
asdf = {23423}
}`
var {tags,text} = xrtext.decode(str) // demultiplex text & bibtex
tags.find( (t) => t.k == 'flap{' ).v.asdf = 1 // edit tag
tags.push({ k:'bar{', v:{abc:123} }) // add tag
console.log( xrtext.encode(text,tags) ) // multiplex text & bibtex back together
```
This expands to the following (hidden by default) BibTex appendix:
```
hello world
here are some hashtagbibs followed by bibtex:
@{some-section}
@flap{
asdf = {1}
}
@world{world,
}
@greeting{hello,
}
@{another-section}
@bar{
abc = {123}
}
```
# HYPER copy/paste
The previous example, offers something exciting compared to simple copy/paste of 3D objects or text.
XR Text according to the XR Fragment spec, allows HYPER-copy/paste: time, space and text interlinked.
Therefore, the enduser in an XR Fragment-compatible browser can copy/paste/share data in these ways:
1. time/space: 3D object (current animation-loop)
1. text: TeXt object (including BibTeX/visual-meta if any)
1. interlinked: Collected objects by visual-meta tag
# Security Considerations
Since XR Text contains metadata too, the user should be able to set up tagging-rules, so the copy-paste feature can :
* filter out sensitive data when copy/pasting (XR text with `class:secret` e.g.)
# IANA Considerations
This document has no IANA actions.
# Acknowledgments
TODO acknowledge.

Binary file not shown.

Before

Width:  |  Height:  |  Size: 12 KiB

File diff suppressed because it is too large Load diff

Before

Width:  |  Height:  |  Size: 1,002 KiB

File diff suppressed because it is too large Load diff

File diff suppressed because it is too large Load diff

350
doc/awkdown Executable file
View file

@ -0,0 +1,350 @@
#!/usr/bin/env -S awk -f
BEGIN {
in_paragraph= 0
in_blockquote= 0
in_ul= 0
ul_depth= 0
in_ol= 0
in_italics= 0
in_bold= 0
in_link= 0
in_table= 0
emitted= 0
}
# Init lookahead
FNR == 1 {
getline nextline < FILENAME
getline nextline < FILENAME
}
# Drop setext header marks
/^[=-]+$/ {
getline
getline nextline < FILENAME
}
# Escape all ampersands (HTML rule)
/&/ {
gsub(/&/, "\\&amp;", $0)
}
# Restore ampersands part of HTML character escape
/&amp;[A-Za-z]{2,4};/ {
gsub(/&amp;/, "\\&", $0)
}
# Escape less than (<) (HTML rule)
/</ {
gsub("<", "\\&lt;", $0)
}
# line break
/^.*[ ]{2}$/ {
sub( /[ ]{2}$/, "<br />", $0 )
}
# block quote
/^>/ {
if( (! in_blockquote) && (! emitted) ) {
print "<blockquote><p>"
in_blockquote= 1
in_paragraph= 1
}
sub(/^>[ ]*/, "", $0)
}
# table
/^[ ]*[|]/ {
#print "<!-- table -->"
if( ! in_table ) {
print "<table>"
in_table= 1
in_paragraph= 1
}
if( match($0, /---/) )
emitted= 1
else if( match(nextline, /---/) ) {
sub(/^[ ]*[|][ ]*/, "<tr><th>", $0)
sub(/[ ]*[|][ ]*$/, "</th></tr>", $0)
gsub(/[ ]*[|][ ]*/, "</th><th>", $0)
} else {
sub(/^[ ]*[|][ ]*/, "<tr><td>", $0)
sub(/[ ]*[|][ ]*$/, "</td></tr>", $0)
gsub(/[ ]*[|][ ]*/, "</td><td>", $0)
}
}
# ATX headers
/^#/ {
n= match($0, /^#+/)
header_lvl= RLENGTH
repl= sprintf("<h%d>", header_lvl)
sub(/^#+ ?/, repl, $0)
repl= sprintf("</h%d>", header_lvl)
if( match($0, /#+$/) )
sub(/ ?#+$/, repl, $0)
else
sub(/$/, repl, $0)
print
emitted= 1
}
# unordered list
/^[ ]*[*+-] / {
uld= match($0, /[*+-]/)
if( uld > ul_depth ) {
sub(/^[ ]*[*+-][ ]*/, "<ul><li>", $0)
in_ul++
in_paragraph= 1
} else if( uld < ul_depth ) {
sub(/^[ ]*[*+-][ ]*/, "</ul><li>", $0)
in_ul--
} else {
sub(/^[ ]*[*+-][ ]*/, "<li>", $0)
}
ul_depth= uld
uld= match(nextline, /[*+-]/)
if( uld <= ul_depth ) {
sub(/$/, "</li>", $0)
}
}
# ordered list
/^(([0-9]+)|([A-Za-z])|([iIvVxXlL]{1,4}))[.]/ {
t= "1"
if( $0 ~ /[ivxl]+[.]/ ) {
t= "i"
sub(/^[ivxl]{1,4}[.][ ]*/, "<li>", $0)
} else if( $0 ~ /[IVXL]+[.]/ ) {
t= "I"
sub(/^[IVXL]{1,4}[.][ ]*/, "<li>", $0)
} else if( $0 ~ /^[A-Z]./ ) {
t= "A"
sub(/^[A-Z][.][ ]*/, "<li>", $0)
} else if( $0 ~ /^[a-z]./ ) {
t= "a"
sub(/^[a-z][.][ ]*/, "<li>", $0)
} else {
sub(/^[0-9]+[.][ ]*/, "<li>", $0)
}
if( ! in_ol ) {
printf("<ol type=\"%s\">\n", t)
in_ol= 1
in_paragraph= 1
}
sub(/$/, "</li>", $0)
}
# Links
/\[.*\]\(.*\)/ {
in_link= 1
s = ""
if( match($0, /(\[.*\])(\(.*)( ".*"\))/, tla) ) {
l= substr(tla[2], 2)
match(tla[3], /".*"/)
a= substr(tla[3], RSTART, RLENGTH)
match(tla[1], /\[.*\]/)
t= substr(tla[1], RSTART+1, RLENGTH-2)
s= sprintf("<a href=\"%s\" alt=%s>%s</a>", l, a, t)
} else if( match($0, /(\[.*\])(\(.*\))/, tl) ) {
match(tl[2], /\(.*\)/)
l= substr(tl[2], RSTART+1, RLENGTH-2)
match(tl[1], /\[.*\]/)
t= substr(tl[1], RSTART+1, RLENGTH-2)
s= sprintf("<a href=\"%s\">%s</a>", l, t)
}
sub(/\[.*\)/, s)
}
# bold
/[*_][*_]/ {
if( !in_link && !in_codeblock && !in_code ) {
while( $0 ~ /[*_][*_]/ ) {
if( ! in_bold ) {
sub(/[*_][*_]/, "<b>", $0)
in_bold= 1
} else {
sub(/[*_][*_]/, "</b>", $0)
in_bold= 0
}
}
}
}
# italics
/[*_]/ {
if( !in_link && !in_codeblock && !in_code ) {
while( $0 ~ /[*_]/ ) {
if( ! in_italics ) {
sub(/[*_]/, "<i>", $0)
in_italics= 1
} else {
sub(/[*_]/, "</i>", $0)
in_italics= 0
}
}
}
}
# strikethrough
/~~/ {
if( !in_link && !in_codeblock && !in_code ) {
while( $0 ~ /~~/ ) {
if( ! in_strike ) {
sub(/~~/, "<strike>", $0)
in_strike= 1
} else {
sub(/~~/, "</strike>", $0)
in_strike= 0
}
}
}
}
# code block
/^```/ {
if( ! in_codeblock ) {
sub(/```/, "<pre>", $0)
in_codeblock= 1
} else {
sub(/```/, "</pre>", $0)
in_codeblock= 0
}
}
# code in text
/`/ {
if( !in_link ) {
while( $0 ~ /`/ ) {
if( ! in_code ) {
sub(/`/, "<code>", $0)
in_code= 1
} else {
sub(/`/, "</code>", $0)
in_code= 0
}
}
}
}
# empty line
/^$/ {
if( in_blockquote && (! match(nextline, /^>/)) ) {
print "</p></blockquote>"
in_blockquote= 0
in_paragraph= 0
}
if( in_table ) {
print "</table>"
in_table= 0
in_paragraph= 0
}
if( in_ul ) {
while( in_ul > 0 ) {
print "</ul>"
in_ul--
}
ul_depth= 0
in_paragraph= 0
}
if( in_ol ) {
print "</ol>"
in_ol= 0
in_paragraph= 0
}
if( in_italics ) {
print "</i>"
in_italics= 0
}
if( in_bold ) {
print "</b>"
in_bold= 0
}
if( in_paragraph ) {
print "</p>"
in_paragraph= 0
}
}
# paragraph and/or setext header
$0 !~ /^$/ {
if( match(nextline, /^[=]+$/) ) {
printf("<h1>%s</h1>\n", $0)
emitted= 1
}
if( match(nextline, /^[-]+$/) ) {
printf("<h2>%s</h2>\n", $0)
emitted= 1
}
if( (! in_paragraph) && (! emitted) ) {
print "<p>"
in_paragraph= 1
}
}
# Finally: print the line
{
if( ! emitted )
print
emitted= 0
getline nextline < FILENAME
}
END {
if( in_table ) {
print "</table>"
in_paragraph= 0
}
if( in_ul ) {
print "</ul>"
in_paragraph= 0
}
if( in_ol ) {
print "</ol>"
in_paragraph= 0
}
if( in_blockquote ) {
print "</p></blockquote>"
in_paragraph= 0
}
if( in_italics ) {
print "</i>"
in_italics= 0
}
if( in_bold ) {
print "</b>"
in_bold= 0
}
if( in_strike ) {
print "</strike>"
in_code= 0
}
if( in_code ) {
print "</code>"
in_code= 0
}
if( in_paragraph )
print "</p>"
}

View file

@ -1,10 +1,9 @@
#!/bin/sh #!/bin/sh
set -e set -xe
FILE=RFC_XR_Fragments
TEXT=1 ./meta.awk ${FILE}.md > ${FILE}.txt
HTML=1 ./meta.awk html/template.html > ${FILE}.html
for topic in Fragments Macros; do #xml2rfc --v3 RFC_XR_$topic.xml # RFC_XR_$topic.txt
mmark RFC_XR_$topic.md > RFC_XR_$topic.xml #sed -i 's/Expires: .*//g' RFC_XR_$topic.txt
mmark --html RFC_XR_$topic.md | grep -vE '(<!--{|}-->)' > RFC_XR_$topic.html #convert -size 700x2400 xc:white -font "FreeMono" +antialias -pointsize 12 -fill black -annotate +15+15 "@RFC_XR_Fragments.txt" -colorspace gray +dither -posterize 6 RF6_XR_Fragments.png
xml2rfc --v3 RFC_XR_$topic.xml # RFC_XR_$topic.txt
sed -i 's/Expires: .*//g' RFC_XR_$topic.txt
convert -size 700x2400 xc:white -font "FreeMono" +antialias -pointsize 12 -fill black -annotate +15+15 "@RFC_XR_Fragments.txt" -colorspace gray +dither -posterize 6 RF6_XR_Fragments.png
done

View file

@ -1,489 +1,52 @@
:root { <style type="text/css">
--color-a: black; body{
--color-at: #000000CC; font-family: monospace;
--color-b: #222; max-width: 1000px;
--color-c: #444; font-size: 15px;
--color-d: #888; padding: 0% 10%;
--color-e: #FF0; line-height: 30px;
--color-f: #CCC; color:#555;
--color-g: #FFF; background:#F7F7F7;
--color-gt: #FFF5;
--params-width: 320px;
--font-1: 'Montserrat', sans-serif;
--font-2: monospace, courier;
--font-size-1: 57px;
--font-size-2: 26px;
--font-size-3: 18px;
--font-size-4: 15px;
--gutter-1: 10%;
--gradient-1: linear-gradient(45deg, #dc2454 0%, #944a9d 51%, #4824dc 100%);
--gradient-2: linear-gradient(45deg, #dc2454 0%, #944a9d 21%, #4824dc 50%,#dc2454 70%, #944a9d 88%, #4824dc 100%);
}
body>h1:nth-child(1) {
display:none;
}
body{
position:relative;
width:100%;
height:100vh;
color: var(--color-d);
line-height: 38px;
margin:0;
padding:0;
font-size: var(--font-size-3);
}
* {
font-family: var(--font-1);
font-size: var(--font-size-3);
font-weight:500;
color: var(--color-c);
}
img,
.img{
image-rendering: -webkit-optimize-contrast;
}
#jumbotron{
margin-top:50px;
}
b{
font-weight: 700;
}
h1 {
color: var(--color-c);
font-size: var(--font-size-1);
font-weight:700;
margin: 0;
line-height: 11vh;
padding-right:40px;
}
h2 {
font-size: var(--font-size-2);
font-weight:400;
padding-right:40px;
}
h3 {
background-image: var(--gradient-1);
color: var(--color-g);
display:inline;
border-radius: 5px;
padding: 2px 10px 2px 10px;
font-weight: 600;
font-size: var(--font-size-4);
text-transform:uppercase;
white-space:nowrap;
}
@media only screen and (max-width: 700px) {
body {
font-size: var(--font-size-3);
line-height: 40px;
} }
svg.img{ h1 { margin-top:40px; }
transform: scale(0.8); pre{ line-height:18px; }
} a,a:visited,a:active{ color: #70f; }
.content{ code{
padding-top: 60px; border: 1px solid #AAA;
margin-left: 27px !important; border-radius: 3px;
padding-right: 54px !important; padding: 0px 5px 2px 5px;
}
.heading{
transform:scale(0.7);
} }
} pre{
line-height: 18px;
table { overflow: auto;
border:none; padding: 12px;
box-shadow: 0px 0px 10px #0005;
padding:20px;
background: transparent !important;
border-radius:4px;
}
table tr td,
table tr th {
vertical-align:top;
text-align:left;
border-bottom:1px solid #555;
color: var(--color-d);
}
table tr td a:visited,
table tr td a:active,
table tr td a{
color: var(--color-e);
}
table tr:last-child td{
border:none;
}
table tr th {
border-bottom:2px solid var(--color-d);
}
code{
display: inline-block;
unicode-bidi: embed;
font-family: monospace;
white-space: pre;
background: var(--color-c);
margin-bottom: 5px;
padding: 0px 5px;
font-size:16px;
}
.content {
height:99vh;
max-width: 50em;
width: 100%;
margin: 0 auto;
padding-top:25px;
box-sizing:border-box;
}
a,a:visited,a:active{
color: var(--color-a);
display:inline-block;
text-decoration:none;
}
a:hover{
opacity:0.9;
}
/* lato-regular - latin */
@font-face {
font-family: 'Lato';
font-style: normal;
font-weight: 400;
src: url('/assets/font/lato-v17-latin-regular.eot'); /* IE9 Compat Modes */
src: local(''),
url('/assets/font/lato-v17-latin-regular.eot?#iefix') format('embedded-opentype'), /* IE6-IE8 */
url('/assets/font/lato-v17-latin-regular.woff2') format('woff2'), /* Super Modern Browsers */
url('/assets/font/lato-v17-latin-regular.woff') format('woff'), /* Modern Browsers */
url('/assets/font/lato-v17-latin-regular.ttf') format('truetype'), /* Safari, Android, iOS */
url('/assets/font/lato-v17-latin-regular.svg#Lato') format('svg'); /* Legacy iOS */
}
#sidemenu {
position:absolute;
top:0;
left:0;
}
#sidemenu nav {
width: 300px;
box-shadow: 0px 0px 8px #0005;
background:#FFF;
z-index:10;
position: fixed;
top: 0;
left: 0;
z-index: 99;
height:100vh;
}
#sidemenu .sidemenu__btn {
display: block;
width: 50px;
height: 50px;
top:20px;
left:20px;
background: transparent;
border: none;
position: fixed;
z-index: 100;
-webkit-appearance: none;
-moz-appearance: none;
appearance: none;
cursor: pointer;
outline: none;
}
#sidemenu .sidemenu__btn span {
display: block;
width: 30px;
height: 3px;
margin: auto;
background:var(--color-d);
position: absolute;
top: 0;
bottom: 0;
left: 0;
right: 0;
-webkit-transition: all .4s ease;
transition: all .4s ease;
}
#sidemenu .sidemenu__btn span.top {
-webkit-transform: translateY(-8px);
transform: translateY(-8px);
}
#sidemenu .sidemenu__btn span.bottom {
-webkit-transform: translateY(8px);
transform: translateY(8px);
}
#sidemenu .sidemenu__btn.active .top {
-webkit-transform: rotate(-45deg);
transform: rotate(-45deg);
}
#sidemenu .sidemenu__btn.active .mid {
-webkit-transform: translateX(-20px) rotate(360deg);
transform: translateX(-20px) rotate(360deg);
opacity: 0;
}
#sidemenu .sidemenu__btn.active .bottom {
-webkit-transform: rotate(45deg);
transform: rotate(45deg);
}
#sidemenu .sidemenu__wrapper {
padding-top: 70px;
margin-left:20px;
}
#sidemenu .sidemenu__list {
overflow-y: scroll;
max-height: 73vh;
padding-top: 50px;
list-style: none;
padding: 0;
margin: 0;
}
#sidemenu .sidemenu__item {
padding: 0;
} }
#sidemenu li > a { pre + code {
text-decoration: none; background:#DDD;
display: inline-block;
-webkit-transition: .4s ease;
transition: .4s ease;
cursor: pointer;
}
nav {
-webkit-transition: .2s ease;
transition: .2s ease;
-webkit-transform: translateX(0px);
transform: translateX(0px);
opacity:1;
}
nav.hide {
-webkit-transform: translateX(-300px);
transform: translateX(-300px);
opacity:0;
}
ul, ol {
margin-left:30px !important;
margin-top: 35px !important;
margin-bottom: 35px !important;
}
ul:nth-child(1){
margin:0;
}
ul,li{
text-decoration:none !important;
/*list-style:none;*/
padding-left:10px;
padding-right:10px;
}
li > a,
li > a.visited,
li > a.active{
color:#555;
padding:5px;
}
li > b {
background:#FFF;
padding:5px;
}
.sidemenu__list > li,
.sidemenu__list > ul > li{
display:inline-block;
}
ul > li {
display:block;
}
.content ul > li::before {content: "•"; padding-right:10px;color: #54F;}
li > b {
font-weight:100;
}
.touchscreen {
border:30px solid #aab5bb;
border-radius:20px;
position:relative;
}
.touchscreen:after {
content:"";
display:block;
position:absolute;
border-radius:50%;
width:15px;
height:15px;
background:#FFF;
top:136px;
right:-22px;
}
div.pretty{
border-radius: 4px;
display: block;
background: #372e42;
overflow-x: scroll;
white-space:pre-wrap;
color:#65e;
}
code.pretty,
div.pretty > pre > code{
background: -webkit-linear-gradient(-70deg,#98a7f0,#0d4e50);
background-clip: border-box;
-webkit-background-clip: text;
-webkit-text-fill-color: transparent;
border: none;
text-shadow: 0px 0px 5px #fff9;
filter: brightness(1.8);
font-size:14px;
width:98%;
padding:0px 15px;
margin:0;
box-sizing:border-box;
line-height:20px;
}
blockquote{
box-sizing: border-box;
background: transparent !important;
border-radius: 7px;
padding: 20px;
width: 100%;
margin: 30px 0px 20px 0px;
color: var(--color-f) !important;
font-weight: bold;
}
blockquote a {
color:#000 !important;
}
blockquote a:hover {
color:#FFF !important;
background:#000;
}
img {
width:100%;
filter: brightness(0.97)
}
/* GRID SYSTEM */
.block{
display: block;
text-align: left;
margin-bottom: var(--gutter-1);
min-height:55vh;
}
.block .img{
border-radius:15px;
width:100%;
height:35vh;
margin-bottom:15px;
background-size: cover;
}
p{ margin:0; padding:0; }
//the grid:
.grid{
width: 90%;
max-width: 900px;
margin: 0 auto;
background-color: $grid-color;
//just for styling:
padding-top: var(--gutter-1);
}
.gutter{
/*
margin-left: calc( var(--gutter-1) /2 );
margin-right: calc( var(--gutter-1) /2 );
*/
margin-right: var(--gutter-1);
}
.col-33{
width: 33.3%;
float: left;
}
.col-50{
width: 50%;
float: left;
}
.clear{
clear: both;
display: block;
}
//responsive
@media all and (max-width:800px) {
.col-33{
width: 50%;
} }
} pre>code{
border:none;
@media all and (max-width:600px) { border-radius:0px;
.col-50, .col-33{ padding:0;
width: 100%;
float: none;
} }
h1 { blockquote{
font-size: 50px; padding-left: 30px;
line-height:70px; margin: 0;
} border-left: 5px solid #CCC;
h2{
font-size: var(--font-size-3);
} }
.block.gutter{ th {
margin-right:0; border-bottom: 1px solid #000;
text-align: left;
padding-right:45px;
padding-left:7px;
background: #DDD;
} }
}
.darken{ td {
filter: brightness(0.8); border-bottom: 1px solid #CCC;
} font-size:13px;
}
button{ </style>
cursor:pointer;
padding: 10px;
border-radius: 6px;
background-image: var(--gradient-1);
border: none;
border-radius: 20px;
display:inline-block;
color: #FFF;
border: none;
opacity:1.0;
font-size: var(--font-size-4);
font-weight:600;
}
button:hover{
opacity:0.8;
}
.gradient{
background-image: var(--gradient-2);
-webkit-background-clip: text;
-webkit-text-fill-color: transparent;
}

8
doc/html/template.html Normal file
View file

@ -0,0 +1,8 @@
<html>
<title>XR Fragments spec</title>
<body>
% system("cat html/style.css")
% system("./meta.awk RFC_XR_Fragments.md > /tmp/out")
% system("cat /tmp/out | ./awkdown")
</body>
</html>

33
doc/meta.awk Executable file
View file

@ -0,0 +1,33 @@
#!/usr/bin/env -S awk -f
# see https://codeberg.org/coderofsalvation/meta.awk.lua
BEGIN {
trigger = (ARGC > 2) ? ARGV[2] : "%";
delete ARGV[2];
cmd = "mktemp"
cmd | getline generator
close(cmd)
print "BEGIN {" > generator;
trigger_esc = trigger;
gsub(/[[\]{}()*+?^$|.\\]/, "\\\\&", trigger_esc);
pattern = trigger_esc ;
}
{
if ($0 ~ "(^|[ ])" trigger_esc) {
line = $0;
sub(".*"pattern, "", line);
print line >> generator;
} else {
gsub(/\\/, "\\\\", $0);
gsub(/"/, "\\\"", $0);
print "print \"" $0 "\"" >> generator;
}
}
END {
if (NR > 0) {
print "}" >> generator;
system("awk -f " generator " ; rm " generator);
}
}

View file

@ -1,3 +0,0 @@
\#static allow client to ignore lower-prio objects in the renderloop, to compensate frame-drop/cpu/gpu-overload scenario’s
Q: should `-` be used to indicate 'lowering' priority (css's `z-index` 0-??? range is a bit confusing in that sense)