Implementation Notes

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).

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 the introduction ‘boilerplate’ text, heading and the BibTeX of the document to allow the document to be cited. Beyond this, any Extended Visual-Meta is optional. This allows for flexible choice of what BibTeX is relevant for producers of documents.

Basic Parsing

It is worth noting that parsing software will parse the PDF from the back, looking for @{visual-meta-end} in order to determine if the document has Visual-Meta and if so, then looking for @{visual-meta-start} and using everything in-between.

Copy As Citation

The Visual-Meta as an Appendix is slightly different from Visual-Meta as a copy (clipboard) payload since the act of copying text from a document with Visual-Meta should not only include the selected text but also the page number it was found on, to enable linking to that page.

Interactions to Support

Initial Visual-Meta Use Cases.

An overview of the interactions Visual-Meta should support.

Code

Code for parsing Visual-Meta will be made available when ready, summer 2021. Initially for Apple Platforms: macOS and iOS.

@{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 PDF External

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.

Custom Elements

Custom 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.

Issues with Font Rendering

The Visual-Meta should be presented in monospaced font to avoid ligatures which interfere with parsing. Please also beware of how special characters are handled: bibtex.org/SpecialSymbols

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.

The vm_id in the header of the document is used to help reader software easily know what document is what document.

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?

Extended Provenance

It is also possible that the document has a mention on the first page that Visual-Meta is appended, with a hash of the Visual-Meta.

Who We Are + Join Us

Notes from the core design team of Frode Hegland with 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.

 

Leave a Comment

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