Implementation Notes

Notes from the core design team of Frode Hegland, Stephan Kreutzer, Adam Wern, Peter Wasilko, Christopher Gutteridge, David Millard, Mark Anderson and Günter Khyo.

Please feel free to join the discussion on future-of-text.circle.so. Our dialog continues there as well as on the open weekly calls we call Open Office Hours.

Guiding Principle

The guiding principle is to preserve as much useful metadata in a human-readable form in an appendix at the back of a document in order for reader software to parse it to allow for advanced interactions, including citing with just copy and paste. The includes citation information as well as preserving structural data such as what text is a heading and so forth. If a competent programmer can read this and figure it out, we’ve succeeded. If not, there is a problem so please feel free to get in touch should you have any problems so we can make an effort for the next implementation information to be better. Therefore please feel free to email frode@hegland.com and we can discuss it via email or Zoom (or equivalent).

Interactions to Support

Initial Visual-Meta Use Cases.

An overview of the interactions Visual-Meta should support.

Approach

It is important to note that Visual-Meta is only an approach and as such, not all implementation of authoring and reading software will support all BibTeX content. The minimum is author, title and date. This allows for flexible choice of what BibTeX is relevant for producers of documents.

The Be-All and End-All of Visual-Meta @{visual-meta-start} & @{visual-meta-end}

‘ @{visual-meta-start}’ and ‘ @{visual-meta-end}’is not valid BibTeX, they are the external wrappers for Visual-Meta. Implementations are of course open but parse documents from the end so that the end page is what marks the inclusion of Visual-Meta. They could have looked like anything but Visual-Meta started as simply a BibTeX embed so this is early legacy.

Extending Visual-Meta : Wrapper around Sections

Extending Visual-Meta is in principle as simple as stating with the the ‘@{visual-meta-start}’ and ‘ @{visual-meta-end}’ markers, though preferably after the BibTeX basic information, what the wrappers contain, using the this format ‘@{Dublin-core}’, ‘@{augmented-text-author-mind-map}’ where the syntax is to specify the contents but also its origin (as in the case of the Author Mind Map) unless generally known (such as Dublin Core).

Extensions Outside

Visual-Meta can potentially also support metadata to bind the document(s).

Method of Writing

Visual-Meta is never indented and line breaks matter for parsing.

An outline of the sections of Visual-Meta is described below. You can also see Visual-Meta Example with Headings or Visual-Meta Plain.

Well Formed Visual-Meta

A well formed Visual-Meta Appendix includes the Minimum Requirements and any optional elements.

Minimum Requirements

Visual-Meta must have the Intro and Descriptive including author, title and year, where further BibTeX fields can be added but not all Readers will parse them. You are strongly encouraged to include the full Description to make the Visual-Meta useable by anyone who wants to parse the data, today on in a thousand years.

Optional Elements

Everything else is optional, including Structural information. Optional element sections must be enclosed with a start of a line of ‘@name of section{‘ followed by a line of ‘}’, as shown below, where the line breaks are important for parsing:

@name of section{
specific contents
}

For example, to add metadata in Dublin Core format you need to specify ‘@dublin-core{‘ at the start of that section.

External References

You may also choose to reference external resources, though this has not been specified yet.

Connecting Documents

Reader software can use the Visual-Meta to ‘know’ what documents are in the user’s system (hard drive/cloud etc.) and therefore provide affordances for clicking on a cited document which they have and opening the document, straight to the cited page, without having to go through a web portal.

Experimental Variables

Experimental: If the value you are adding is not fully accurate, place a ? after that field. 
For example: year = {2020},?

If you are not sure about the spelling, you can append ‘sp?’. 
For example author = {Frode Alexander Hegland},sp?

 

Leave a Comment

Your email address will not be published. Required fields are marked *