coderofsalvation
/
xrfragment
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

update documentation

This commit is contained in:
Leon van Kammen 2023-09-08 16:57:49 +02:00
parent 275589a691
commit fca70041cb
1 changed files with 78 additions and 55 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

133
doc/RFC_XR_Fragments.md
View File

@ -109,7 +109,7 @@ Their lowest common denominator is: (co)authoring using plain text.<br>
XR Fragments allows us to enrich/connect existing dataformats, by recursive use of existing technologies:<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. 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 [bibs](https://github.com/coderofsalvation/tagbibs) / [BibTags](https://en.wikipedia.org/wiki/BibTeX) as appendix (see [visual-meta](https://visual-meta.info) e.g.) 1. hasslefree tagging across text and spatial objects using [bibs](https://github.com/coderofsalvation/tagbibs) / [BibTags](https://en.wikipedia.org/wiki/BibTeX) appendices (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 > NOTE: The chapters in this document are ordered from highlevel to lowlevel (technical) as much as possible
@ -319,6 +319,8 @@ This allows recursive connections between text itself, as well as 3D objects and
+---------------------------------------------+ +---------------------------------------------+
``` ```
> 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: This allows instant realtime tagging of objects at various scopes:
| scope | matching algo | | scope | matching algo |
@ -345,18 +347,23 @@ The XR Fragment specification bumps the traditional default browser-mimetype
`text/plain;charset=US-ASCII` `text/plain;charset=US-ASCII`
to a green eco-friendly: to a hashtagbib(tex)-friendly one:
`text/plain;charset=utf-8;bib=^@` `text/plain;charset=utf-8;bib=^@`
This indicates that [bibs](https://github.com/coderofsalvation/tagbibs) and [bibtags](https://en.wikipedia.org/wiki/BibTeX) matching regex `^@` will automatically get filtered out, in order to: This indicates that:
* automatically detect links between textual/spatial objects * utf-8 is supported by default
* detect opiniated bibtag appendices ([visual-meta](https://visual-meta.info) e.g.) * [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.
It's concept is similar to literate programming, which empower local/remote responses to: > for more info on this mimetype see [bibs](https://github.com/coderofsalvation/hashtagbibs)
* (de)multiplex human text and metadata in one go (see [the core principle](#core-principle)) 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)) * no network-overhead for metadata (see [the core principle](#core-principle))
* ensuring high FPS: HTML/RDF historically is too 'requesty'/'parsy' for game studios * 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)) * rich send/receive/copy-paste everywhere by default, metadata being retained (see [the core principle](#core-principle))
@ -365,9 +372,6 @@ It's concept is similar to literate programming, which empower local/remote resp
> 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.). > 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> For all other purposes, regular mimetypes can be used (but are not required by the spec).<br>
To keep XR Fragments a lightweight spec, BibTeX is used for text/spatial tagging (not a scripting language or RDF e.g.).
> Applications are also free to attach any JSON(LD / RDF) to spatial objects using custom properties (but is not interpreted by this spec).
## URL and Data URI ## URL and Data URI
@ -391,7 +395,7 @@ 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'). 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.). 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/tagbibs): to tag spatial object `note_canvas` with 'todo', the enduser can type or speak `@note_canvas@todo` > 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 : The mapping between 3D objects and text (src-data) is simple (the :
@ -405,8 +409,8 @@ Example:
| └── ◻ rentalhouse | | └── ◻ rentalhouse |
| └ class: house <----------------- matches -------+ | └ class: house <----------------- matches -------+
| └ ◻ note | | | └ ◻ note | |
| └ src:`data: todo: call owner | bib | | └ src:`data: todo: call owner | hashtagbib |
| @owner@house@todo | ----> expands to @house{owner, | #owner@house@todo | ----> expands to @house{owner,
| | bibtex: } | | bibtex: }
| ` | @contact{ | ` | @contact{
+------------------------------------------------+ } +------------------------------------------------+ }
@ -421,7 +425,7 @@ Bi-directional mapping between 3D object names and/or classnames and text using
> "When a car breaks down, the ones **without** turbosupercharger are easier to fix" > "When a car breaks down, the ones **without** turbosupercharger are easier to fix"
Unlike XML or JSON, the typeless, unnested, everything-is-text nature of BibTeX tags is a great advantage for introspection.<br> 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> 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> 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): In that sense, it's one step up from the `.ini` fileformat (which has never leaked into the physical world like BibTex):
@ -435,7 +439,7 @@ In that sense, it's one step up from the `.ini` fileformat (which has never leak
| structure | fuzzy (sensemaking) | precise | | structure | fuzzy (sensemaking) | precise |
| space/scope | local | world | | space/scope | local | world |
| everything is text (string) | yes | no | | everything is text (string) | yes | no |
| voice/paper-friendly | [bibs](https://github.com/coderofsalvation/tagbibs) | no | | voice/paper-friendly | [bibs](https://github.com/coderofsalvation/hashtagbibs) | no |
| leaves (dictated) text intact | yes | no | | leaves (dictated) text intact | yes | no |
| markup language | just an appendix | ~4 different | | markup language | just an appendix | ~4 different |
| polyglot format | no | yes | | polyglot format | no | yes |
@ -453,57 +457,68 @@ In that sense, it's one step up from the `.ini` fileformat (which has never leak
| terse non-verb predicates | yes | no | | terse non-verb predicates | yes | no |
| nested structures | no (but: BibTex rulers) | yes | | 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 ## XR Text example parser
1. The XR Fragments spec does not aim to harden the BiBTeX format 1. The XR Fragments spec does not aim to harden the BiBTeX format
2. However, respect multi-line BibTex values because of [the core principle](#core-principle) 2. respect multi-line BibTex values because of [the core principle](#core-principle)
3. Expand bibs and rulers (like `${visual-meta-start}`) according to the [tagbibs spec](https://github.com/coderofsalvation/tagbibs) 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=^@` 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: Here's an XR Text (de)multiplexer in javascript, which ticks all the above boxes:
``` ```
xrtext = { xrtext = {
decode: (str) => {
// bibtex: ↓@ ↓<tag|tag{phrase,|{ruler}> ↓property ↓end
let pat = [ /@/, /^\S+[,{}]/, /},/, /}/ ]
let tags = [], text='', i=0, prop=''
var bibs = { regex: /(@[a-zA-Z0-9_+]+@[a-zA-Z0-9_@]+)/g, tags: {}}
let lines = str.replace(/\r?\n/g,'\n').split(/\n/)
for( let i = 0; !lines[i].match( /^@/ ); i++ ) text += lines[i]+'\n'
bibtex = lines.join('\n').substr( text.length ) expandBibs: (text) => {
bibtex.replace( bibs.regex , (m,k,v) => { let bibs = { regex: /(#[a-zA-Z0-9_+@\-]+(#)?)/g, tags: {}}
tok = m.substr(1).split("@") text.replace( bibs.regex , (m,k,v) => {
match = tok.shift() tok = m.substr(1).split("@")
tok.map( (t) => bibs.tags[match] = `@${t}{${match},\n}\n` ) match = tok.shift()
}) if( tok.length ) tok.map( (t) => bibs.tags[t] = `@${t}{${match},\n}` )
bibtex = Object.values(bibs.tags).join('\n') + bibtex.replace( bibs.regex, '') else if( match.substr(-1) == '#' )
bibtex.split( pat[0] ).map( (t) => { bibs.tags[match] = `@{${match.replace(/#/,'')}}`
try{ else bibs.tags[match] = `@${match}{${match},\n}`
let v = {} })
if( !(t = t.trim()) ) return return text.replace( bibs.regex, '') + Object.values(bibs.tags).join('\n')
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}
}, },
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) => { encode: (text,tags) => {
let str = text+"\n" let str = text+"\n"
for( let i in tags ){ for( let i in tags ){
let item = tags[i] let item = tags[i]
if( item.ruler ){ if( item.ruler ){
str += `@${item.ruler}\n` str += `@${item.ruler}\n`
continue; continue;
} }
@ -511,7 +526,7 @@ xrtext = {
for( let j in item.v ) str += ` ${j} = {${item.v[j]}}\n` for( let j in item.v ) str += ` ${j} = {${item.v[j]}}\n`
str += `}\n` str += `}\n`
} }
return str return str
} }
} }
``` ```
@ -523,8 +538,12 @@ The above functions (de)multiplexe text/metadata, expands bibs, (de)serialize bi
``` ```
str = ` str = `
hello world hello world
here are some hashtagbibs followed by bibtex:
#world
#hello@greeting
#another-section#
@hello@greeting
@{some-section} @{some-section}
@flap{ @flap{
asdf = {23423} asdf = {23423}
@ -535,18 +554,21 @@ tags.find( (t) => t.k == 'flap{' ).v.asdf = 1 // edit tag
tags.push({ k:'bar{', v:{abc:123} }) // add tag tags.push({ k:'bar{', v:{abc:123} }) // add tag
console.log( xrtext.encode(text,tags) ) // multiplex text & bibtex back together console.log( xrtext.encode(text,tags) ) // multiplex text & bibtex back together
``` ```
This outputs: This expands to the following (hidden by default) BibTex appendix:
``` ```
hello world hello world
here are some hashtagbibs followed by bibtex:
@greeting{hello,
}
@{some-section} @{some-section}
@flap{ @flap{
asdf = {1} asdf = {1}
} }
@world{world,
}
@greeting{hello,
}
@{another-section}
@bar{ @bar{
abc = {123} abc = {123}
} }
@ -601,4 +623,5 @@ This document has no IANA actions.
|(un)obtrusive | obtrusive: wrapping human text/thought in XML/HTML/JSON obfuscates human text into a salad of machine-symbols and words | |(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 | |BibTeX | simple tagging/citing/referencing standard for plaintext |
|BibTag | a BibTeX tag | |BibTag | a BibTeX tag |
|(hashtag)bibs | an easy to speak/type/scan tagging SDL ([see here](https://github.com/coderofsalvation/hashtagbibs) |