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 should 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.
Please also note that you can use ¶ to indicate a line break for parsing, using more of the horizontal space.
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
The most basic interaction is for citing, since being able to refer to a document is core to document relationships. Visual-Meta was designed for is to allow a user to copy text from a PDF and paste it as a full citation since the clipboard payload can have the copied text plus the full BibTeX payload from the Visual-Meta.
Basic view controls such as being able to fold the document into a Table of Contents.
Alternative views, such as concept maps of the text and graph views.
Paratexts, including letting the reader software understand where the References, Glossary and Endnotes are and how they are formatted
More custom/niche interactions are server based, where documents can surface their contents, from Dublin Core metadata to what values tables and charts contain, for instant access externally to internal data.
Code
Code for parsing Visual-Meta will be made available when ready, summer 2023. 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).
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?
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.