In-line annotation guidance sought

I am in early planning for a project that will both involve heavy knowledge building in the application, and also export to experimental presentations, some graphical, some experimental hypertext. Because much work will be done in-app on a desktop, and require ‘being in the zone’ of the subject at hand, I want it to be delightful, where key annotative information is clean, clear, elegant. I’ll be using named links extensively and likely have lots of information in Text that breaks the flow.

The last time we did something like this, I used rich text. I’ve been working with written documents with complex ideas for too long to leave good old text with fine fonts and layout. That is to say that I find markdown/asciidoc/MIF just frikken ugly and in the way of the ideas. I know I will get responses from folks who use MD like breathing and can ignore the inline metacharacters placed there to help the real reader. But that’s not me.

My choices are:

— stick with my cranky boomer notion and use styled text in clever ways to capture the annotative information, and possibly hiding local interpretive information in attributes, plus use stamps and highlighters and other tricks. This could involve different faces, styles, even bespoke fonts. At some point this becomes lumpy and itself obscures real reading.

— go with some MD-like convention, taking advantage of the community’s skills. That is, embrace, extend, and leverage the junk… and somehow ‘hide’ it or make it less prominent.

— do something radical, on top of all the other radical things we are attempting, maybe hiding annotative information at the end of named links, maybe even in notes that execute external code internally, like the JS map items.

Much depends on what my helpers have the patience to support for my peccadillo, but much will be governed by the publishing strategy (and other export to code), and whether we rely on Export Code, one of the clever Pandoc or similar pipelines, some bespoke exporter, or a combination.

In anticipation of the expected ‘what are you trying to accomplish?

  1. The primary rationale for Tinderbox is as a knowledge enrichment environment, the best on the planet for this requirement, with a lot of very clever folks engaged. I’ll spend a ton of money scouring the scientific literature and building a pipeline to get neurobiological information fed in. I want to use this to understand what is known well enough to refine and structure that in a formal hyperstructured model that reveals what is not known. I’ll have a few experts on board as well, so collaboration is a separate problem. We should be able to browse and enrich what’s there as if it were a superwikipedia. So I can’t be stumbling over the noodlemaker when what I want is to eat.

  2. All of that is to create both: a) a human-readable model that can be exported for experimental browsing on the web, with some display experiments long in incubation. b) a machine readable model to feed a reasoner that our startup is building, now at MVP, for reasoning over unknowns and across domains.

These will conflict. Wisdom humbly requested.

1 Like

Speaking to the end-goal of a human-readable document that can be disseminated over the web, it would seem more practical to stay within html/md than move to rtf, which must be styled in order to draw attention.

A lot also hinges on your source/intake apps and environment. For outliners I would try to stay within apps that support OPML and so on, and keep things as close to common standards all the way to point-of-publishing. Generally I would prefer to bring content into Tbx in as plain-text a condition as possible.

From within Tbx, much can bedone to build a project while staying within common parameters (html/md). Posters/Mermaid offer graphical/visual drawing/charting capabilities, and href links to images and other content are straightforward. Previewing presentable annotated/styled md real-time is possible via Marked2 (you can also switch between the Preview and Text views in Tbx). I feel one can build a pretty comprehensive paper/study within Tbx while avoiding Rich Text, and it would be all the more flexible for web dissemination if it were developed in html/md. Tinderbox also allows some mix and match of the formats, so I guess it’s not really a “this or that” decision, but more related to smooth workflow and flying content between users, environments, and Tinderbox project files?

One idea: you can use highlighting for your annotations—different color for different categorical thought. You can then use action code, specifically the .highlighs operator, to extract and parse your inline annotations. I have extensive workflows around exactly this.

Michael, any restriction on the flavour of markup? Does that extend to asciidoc?

Being unfamiliar with asciidoc it looks like convergent evolution to Markdown, towards a more structured aim. Thus books, or book-style long-form structured content for the former vs. webpages for the latter. From that perspective not a better/worse zero-sum comparison. I found this page in getting a feel for difference. helpful Compare AsciiDoc to Markdown | Asciidoctor Docs

@eastgate, I wonder if the existing Markdown integration might already wholly or partly support asciidoc, as it does various ‘flavours’ of Markdown?

I don’t see any barrier to grabbing one of the asciidoctor processors and using it as an HTMLPreviewCommand. I’d rather not build in another processor until we’re sure people will use it. (I was easily persuadable on MultiMarkdown because of Jacob’s amazing demo, and also because I’d made a previous run at MultiMarkdown that didn’t work.)

1 Like

Have not tested, but there does seem to be a asciidoc homebrew libriary: asciidoc — Homebrew Formulae.

1 Like

Absolutely, makes sense. I was checking my presumption that, called from the install location via its OS path (i.e. for other Markdown flavours on the user’s Mac) it ought to work.

@satikusala thanks for the Homebrew link . As I use the latter to keep all sorts of CL libraries installed/updated I’ll likely go that route for an intall.

†. Clearly that now needs deliberate user testing (me, I guess!) but it’s good to know there are no obvious hard-stop impediments to trying a test.

No worries, as we say here. I’m happy to go with plain old markdown.

The markup is not dissimilar and if asciidoc can ‘masquerade’ as and Markdown flavour then this potential option seems useful for more nuanced and structured mark-up.

FYI, after using a Homebrew install, the path for asciidoc use via $HTMLPreviewCommand is /opt/homebrew/bin/asciidoc

1 Like