Posted by snowolfe on Oct 15, 2013; 6:09am
URL: https://discuss.asciidoctor.org/How-to-track-changes-with-text-files-tp453p806.html

Moved this post here to add my comments in-line.

I think some kind of plugin or extension that works during the conversion process (asciidoctor > output) would be great - assuming we want to add support for this markup format.

I see four output options needed:
1. Generate output with all critic markup shown in the visible output. Output clearly identifies critic's.
Maybe: --cm-showall

2. Generate output with just the latest critic markup clearly identified, embed the history of critic markup as comments in the output, alternatively output the history as linked footnotes.
Maybe: --cm-latest

3.  Generate output with accepted critic, as it should be shown in completed doc, embed the history of critic markup as comments in the output.
Maybe: --cm-history or --cm-embed

4. Generate final output, after critic applied. No embedded history in final output. One potential output option for this, could be to generate "clean" asciidoc" output; that is, remove all critic markup from adoc file, useful for distribution of clean adoc source file (in case it needs to be processed by another tool, and to maintain compatibility).

A variation on the first two options maybe to toggle the 'display' of any associated critic comments, i.e. show just the critic markup for add, change, delete (I think highlight {== ==}{>> <<} always needs the comment, as it probably does not make sense without it) or show the add, change, delete with any immediately trailing comment.

Two things occur to me in relation to the above:
Which is the latest critic? - my suggestion is that it be purely an ordered analysis, last entry is the most recent. This avoids issues with date and time (particularly if you have to manage cross timezone editing).

How to identity accepted/rejected entries? - I think there needs to be an accepted marker, any other markers would depend on all sorts of use-case variations, e.g. definitely rejected, still under consideration, consensus needed.

Suggestions for accepted and rejected:
 These make it possible to use without interfering with the current critic markup spec, but would not be understood by other tools...
   {&&} Accepted, placed in front of the winning entry.
   {!!} Rejected, optional - placed in front of the rejected entry.
 Alternatively, add one of the above to the opening bracket entry, breaks the spec...
  {++& , {++!
  {--& , {--!
  {~~& , {~~!
 Use a special Comment entry, will not break current spec and will not affect other tools, benefits from being able to add additional commentary in the same entry...
  {>>&<<} Accepted, before the winning entry - with comment {>>& @snowolfe This is perfect <<}
  {>>!<<} Rejected, before the entry - with comment {>>! @snowolfe Not a good edit <<}

Comments?