Asciidoc diffs

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
10 messages Options
Reply | Threaded
Open this post in threaded view
|

Asciidoc diffs

pepijnve
I've been asked to investigate if it would be possible to generate documents with Word-like 'track changes' in the final output. I was thinking of diff'ing the asciidoc source code and then generating strikethrough text and highlighted text for deletions and additions resp. Is there any syntax that is universally applicable in asciidoc that I could use for this? Is it valid to use something like [line-through]*bold blue and line-through* anywhere in asciidoc?

Thanks,

Pepijn
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoc diffs

mojavelinux
Administrator
Pepijn,

The topic of diffs / track changes has come across the list a couple of times (clearly an interesting challenge). Perhaps you can draw on some of the discussions in those threads for ideas about how to approach it. Here's the entry point:


My feeling is that git should be used to manage changes because it happens automatically and is perfectly true to the history. What we're really missing is an offline (or at least open source) version of the "rich diff" that GitHub displays. It's certainly a reasonable thing to implement if someone is willing to dedicate time to it.

The other suggestion that came up is Critic Markup {1}. It's a generic syntax for expressing inline changes in a document that could fit with AsciiDoc. There's even an open issue to implement it in Asciidoctor {2} (or as an extension). If we do take this route, I'd like to leverage existing syntax & tools like Critic Markup.

I hope that gives you a good starting point!

Cheers,

-Dan



On Fri, Dec 12, 2014 at 2:44 PM, pepijnve [via Asciidoctor :: Discussion] <[hidden email]> wrote:
I've been asked to investigate if it would be possible to generate documents with Word-like 'track changes' in the final output. I was thinking of diff'ing the asciidoc source code and then generating strikethrough text and highlighted text for deletions and additions resp. Is there any syntax that is universally applicable in asciidoc that I could use for this? Is it valid to use something like [line-through]*bold blue and line-through* anywhere in asciidoc?

Thanks,

Pepijn


If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Asciidoc-diffs-tp2533.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML


--
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoc diffs

CodeGnome
In reply to this post by pepijnve

Use Word-Diff

You can use a word-diff to compare AsciiDoc source files. For example:

$ git diff --word-diff
diff --git a/file b/file
index 1aeaedb..332dbc2 100644
--- a/file
+++ b/file
@@ -1 +1 @@
foo [-bar-]{+quux+} baz {+wiffle+}

Simply color-coding changes with git diff --word-diff=color may be useful, too.

Using Word-Diff with Attribution

Attributing a change to the person who made it isn't really the job of the diff tool. The job of attribution actually belongs to your revision control system, and most SCM tools have a feature named "blame" or "annotate" that performs this function. With Git, you can't really use git-blame with Git's word-wise diff feature, but you can get a reasonable approximation with something like this:
git log --patch --word-diff
You can also customize the output of git-log by modifying the format string. See man git-log | less --pattern="^PRETTY FORMATS" for a thorough reference.

Other Options

AsciiDoc source text can be compared using a wide variety of diff tools. For example:

  • If you're using Git, you can use normal, unified, or word (as opposed to line) diffs right out of the box.
  • You can use external diff tools like sdiff, kdiff3, tkdiff, or kompare for side-by-side comparisons of the asciidoc source files.
  • You can use diffpdf to compare PDF files rendered from Asciidoctor sources.
Comparing rendered HTML is generally less useful than comparing the source, though; markup can change wildly while still rendering the same, and vice versa. However, there are use cases for this, so your mileage may vary.
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoc diffs

mojavelinux
Administrator
Super useful information. Thanks for posting!

-Dan

On Sat, Jan 24, 2015 at 11:09 AM, CodeGnome [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Use Word-Diff

You can use a word-diff to compare AsciiDoc source files. For example:

$ git diff --word-diff
diff --git a/file b/file
index 1aeaedb..332dbc2 100644
--- a/file
+++ b/file
@@ -1 +1 @@
foo [-bar-]{+quux+} baz {+wiffle+}

Simply color-coding changes with git diff --word-diff=color may be useful, too.

Using Word-Diff with Attribution

Attributing a change to the person who made it isn't really the job of the diff tool. The job of attribution actually belongs to your revision control system, and most SCM tools have a feature named "blame" or "annotate" that performs this function. With Git, you can't really use git-blame with Git's word-wise diff feature, but you can get a reasonable approximation with something like this:
git log --patch --word-diff
You can also customize the output of git-log by modifying the format string. See man git-log | less --pattern="^PRETTY FORMATS" for a thorough reference.

Other Options

AsciiDoc source text can be compared using a wide variety of diff tools. For example:

  • If you're using Git, you can use normal, unified, or word (as opposed to line) diffs right out of the box.
  • You can use external diff tools like sdiff, kdiff3, tkdiff, or kompare for side-by-side comparisons of the asciidoc source files.
  • You can use diffpdf to compare PDF files rendered from Asciidoctor sources.
Comparing rendered HTML is generally less useful than comparing the source, though; markup can change wildly while still rendering the same, and vice versa. However, there are use cases for this, so your mileage may vary.


If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Asciidoc-diffs-tp2533p2702.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



--
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoc diffs

metro
In the past, I have used Delta-XML to generate a delta document from two docbook files. This delta document can be rendered to pdf with changes highlighted.

Works quite well.

MT
--
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoc diffs

Gunnar Morling
Hi,

I was wondering whether there has been any news on this topic, i.e. is it possible to generate output which contains colored diffs to a given previous version? Essentially I'm looking for a way to render output from AsciiDoc similar to the rich diff view on GitHub.

My use case is the Bean Validation 2.0 specification (which we've just converted from DocBook to AsciiDoc, yeah!). It'd be great for reviewers if we could produce a version which has any new/changed colored nicely. We can use the rich diff on GitHub for individual spec chapters as an alternative, but it'd be nicer to have single diff-colored document for offline use etc.

Thanks for any hints,

--Gunnar
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoc diffs

mojavelinux
Administrator
Gunnar,

Not to my knowledge. But understand this is no small task. That's one of the reasons GitHub hasn't open sourced their library for it. In fact, there was a GSoC effort around this a few years ago (for MediaWiki) and what they learned is that it is much more difficult that it appears at first glance.

If such a library / tool was created  / stabilized, we'd be a consumer of it. It's unlikely it will be part of the Asciidoctor ecosystem given that it's a research effort all in and of itself.

Here are a few existing solutions (or at least the beginnings of them):

https://libraries.io/bower/angular-rich-text-diff (based on a Google diff library)
https://github.com/tnwinc/htmldiff.js

I'd be interested to hear if any of those work out.

-Dan

On Fri, Aug 19, 2016 at 1:34 AM, Gunnar Morling [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Hi,

I was wondering whether there has been any news on this topic, i.e. is it possible to generate output which contains colored diffs to a given previous version? Essentially I'm looking for a way to render output from AsciiDoc similar to the rich diff view on GitHub.

My use case is the Bean Validation 2.0 specification (which we've just converted from DocBook to AsciiDoc, yeah!). It'd be great for reviewers if we could produce a version which has any new/changed colored nicely. We can use the rich diff on GitHub for individual spec chapters as an alternative, but it'd be nicer to have single diff-colored document for offline use etc.

Thanks for any hints,

--Gunnar



If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Asciidoc-diffs-tp2533p4893.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



--
Dan Allen | @mojavelinux | https://twitter.com/mojavelinux
msc
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoc diffs

msc
I think coming at this from the approach of solving the HTML diff problem is wrong. A diff should be done between 2 versions of the Asciidoctor source for the document, generating markup which can then be used during generation of the final output format, e.g, converted to spans in HTML output with appropriate class ids.

Kind of like --word-diff in git diff but you need the entire document output not just parts that have changes and delimiters that don't conflict with existing Asciidoctor markup.  I suspect those currently used by --word-diff do conflict.
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoc diffs

mojavelinux
Administrator
I would agree. An AsciiDoc diff is going to give you a much more true result.

-Dan

On Mon, Feb 12, 2018 at 4:16 PM, msc [via Asciidoctor :: Discussion] <[hidden email]> wrote:
I think coming at this from the approach of solving the HTML diff problem wrong. A diff should be done between 2 versions of the Asciidoctor source for the document, generating markup which can then be used during generation of the final output format, e.g, converted to 's in HTML output with classes that can be styled.

Kind of like --word-diff in git diff but you need the entire document output not just parts that have changes and delimiters that don't conflict with existing Asciidoctor markup.  I those currently used by --word-diff do conflict.


If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Asciidoc-diffs-tp2533p6178.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



--
Dan Allen | @mojavelinux | https://twitter.com/mojavelinux
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoc diffs

oddhack
In reply to this post by msc
This is a "perfect is the enemy of good enough" problem - while having a diff tool that works on arbitrary semi-structured content would be nice, people have been asking after it for decades and there don't seem to be any robust answers yet. OTOH the code underlying the W3C HTML diff tool (http://services.w3.org/htmldiff) generally works to compare sufficiently-close revisions of two asciidoc documents, and is available today. We use that internally when shipping documents to IP lawyers for review purposes, though they're cautioned it's only a guideline. Instrumenting the document with hand-written change markup may also be workable - I do that in the LaTeX-based OpenGL spec but it's less tractable for our asciidoctor-based specs for several reasons. If you're willing to surround all the changed regions with asciidoc conditionals, extensions can do the color markup for you - we have use cases for that in the Vulkan spec.