Re: Marking/highlighting text temporarily

[Nicolas Goaziou <mail@nicolasgoaziou.fr>]

Hello,

Eric Abrahamsen <eric@ericabrahamsen.net> writes:

> We're just talking about annotations-plus-metadata here, right? Not
> actual in-text TODOs?

I'm not convinced in-text TODOs would be interesting, because they would
make building the agenda an order of magnitude slower.

My concerns about syntax are:

  - it should not cripple readability of the document
  - it needs to mark both objects (inline) and elements, even multiple
    elements (e.g., two paragraphs)

In particular, the last point is difficult to handle for the parser.
Indeed, any syntax is either contained in a paragraph or stops one, so
this syntax should be a bit "outside" the parser.

Anyway, here we go for another proposal.

In-text markers:

  [@:ID]...[@]

ID is expected to be unique, and consists of alphanumeric characters
only. Markers are allowed anywhere standard syntax is (e.g., paragraphs,
verse blocks, table cells, captions, parsed keyword).

Both makers have to be found within the same section, i.e, one cannot
annotate across headlines. Annotations can be nested but cannot
partially overlap.

From the parser point of view, Element can recognize such markers, but
will not be able to "associate" them since they exist above structure of
the document.

One important limitation is that example or source blocks cannot be
annotated, Therefore I also suggest creating a new affiliated keyword,

  #+ANNOTATE: ID

which will annotate the whole element it is applied to.

Some examples:

  [@:1]Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
  tempor incididunt ut labore et [@:2]dolore magna[@] aliqua.

  Ut enimad minim veniam, quis nostrud exercitation ullamco laboris nisi
  ut aliquip ex ea commodo consequat.[@]

  #+ANNOTATE: foo
  #+BEGIN_SRC emacs-lisp
  (+ 1 1)
  #+END_SRC

Then references are collected in a dedicated section, much like
footnotes (e.g., `org-annotation-section'), although it cannot be nil.

Annotations start at column 0

  [@:ID:AUTHOR-ID] OTHER-AUTHOR-ID
  CONTENTS

where:

 - ID obviously refers to in-text markers' ID, 

 - AUTHOR-ID consists of word and blank characters only. If empty, it
   may default to `user-login-name'.

 - OTHER-AUTHOR-ID is also optional. It is meant for empty contents.
   During export, it could be possible to select annotation from
   a single source, e.g.,

     #+OPTIONS: @:student1

 - CONTENTS consists of either comments and non-comments. Any
   non-comment is considered as data to replace (if in-text markers are
   not sticked to each other), or insert (when they are) during export.

   Comments will be displayed as a conversation thread by a special
   function in "org-annotate.el".
   
This syntax allows to copy annotation from another author, e.g.

   [@:1:teacher]
   # This is wrong, it should be "foo".
   foo

   [@:1:student1] teacher

   [@:2:teacher]
   # Please reformulate.

   [@:2:student1]
   # What about "bar"?
   bar

Timestamps, if needed, can be inserted in comments.

WDYT?

-- 
Nicolas Goaziou