Annotating code via the code-body template?

#1

I was wondering if any of our skilled CSS or other community members would know how to design a way to annotate code viewed via code body?

Just imagine if we could annotate key code in the core, not touch the tiddler, for documentation or our own research projects, and to do this to specific pieces of text.

  • We could even indicate where to make changes to hack or customise.

When viewing a tiddler with code-body=yes we see the “code” of the tiddler, in a simple text form. It would be great if we could select a piece of unique code (used as the key) then annotate it, write a sentence or paragraph relating to the code piece. Then display an icon showing it is annotated and along with the mouse over the text display the content of the annotation on mouse over.

  • An option to hide the annotation icon(s) would be good

I have some ideas how to achieve this but not enough to bring it to fruition.

I see value in creating an annotation tiddler containing the source tiddler, the string you are annotating so we can use the text field as the annotation and use search and tagging against the annotation tiddlers.

  • The annotation tiddler could also optionally display within it the code tiddler and only this annotations selected code.

Requirements;

While viewing or editing code on any tiddler select some code and click to create the annotation tiddler, accept details of the annotation. Allowing this from both the view template and editor toolbar would be helpful.

While viewing the code highlight/icon indicate the presence of the annotation on mouse over display the annotation text field (rendered) and on click open the annotation tiddler.

Both of the above could be designed for use in other use cases if generalised, such as;

  • A writer/reviewer annotating a draft (in view mode, no code formatting?)
    • Send the resulting annotations to author

[Late note]

Yes, my mistake I am looking at the <$dynannotate> now.

  • Its awefully complex so I do need help
1 Like
#2

Hey Tony,

Not sure about the dynanotate approach - as it would be hard to set the search strings for selection for each annotation and to reverse engineer a unique search term from a selected piece of text… some code that you want to annotate may be repeatedly used in a codeblock (think function & variable names), so hard to set a specific annotation to

Instead - I think you could create a clone of the code-body cascade and view template - i.e $:/config/ViewTemplateBodyFilters/code-body and $:/core/ui/ViewTemplate/body/code, so that individual lines of code are separated into actionable widgets… The following gives you the basics for this ( ie using a filter to split each line)

\whitespace trim

<$vars text="""const a = 10;
const b = 20;
console.log(a + b);""" >

<pre class="codeblock" id="code">
  <code>
    <$list filter="[<text>splitregexp[\n]]" counter="line-num" join="<br/>">
       <<line-num>> &nbsp; <$link to="" > ><<currentTiddler>></$link>
    </$list>
  </code>
</pre>

</$vars>

This gives you the following :

1 const a = 10;
2 const b = 20;
3 console.log(a + b);

You could replace the line numbers with icons based on whether an annotation is found with that specific tiddler and line number combination, and you could replace the link reference to a value that a linkcatcher or an eventcatcher widget could interpret as actions for adding or showing an annotation…

Hope that helps you get started :smile:

#3

Thanks for your suggestions @Christian_Byron

Actually there are three things to consider here;

  • Perhaps we would be happy to annotate once every instance of the same search string (in the current tiddler)
    • We could also have a highlight “first only, or all option”
  • Users would learn to make such selections unique, however…
  • dynanotate also allows pre and post text to help make it unique. Even before allowing an annotation we can check for uniqueness.

The technology and tools already exists for the suggested solution, its just a matter of putting it all together. For example see the freelinks plugin for highlighting text matching existing tiddlers, and I have even made (but lost) the trick to copying a tiddlers content while viewing/selecting text in view mode.