Re: How to show changes between two docs in the new version
Posted by
danyill on
May 15, 2019; 7:17am
URL: https://discuss.asciidoctor.org/How-to-show-changes-between-two-docs-in-the-new-version-tp6915p6920.html
For prose difference, I've been using my own fork of a Python htmldiff program (upstream no longer active) which seems to be working moderately well. I use this in CI to automatically generate html differences between tagged versions of Asciidoc documents. Occasionally it just doesn't cope but it's quite an improvement on git diff.
Strictly speaking we need a tool which produces a visual diff based on a semantic comparison of either the html or the asciidoc bsaed on the AST. The state-of-the-art algorithm for AST comparisons (I believe) is the tree edit distance algorithm of
https://github.com/DatabaseGroup/apted. I've hacked around with various implementations of this (e.g.
https://github.com/JoaoFelipe/apted) but have been unable to get something working reasonably well for a non-trivial case. I also don't fully understand the algorithm. We really need to find/develop a good Ruby equivalent and have a play with this.
Part of the problem is that for a reasonable number of nodes in the AST the time/memory implications grows. It may be that another algorithm is also needed to ensure the full AST comparison doesn't have to be done (maybe?). Mediawiki's Visual Diff which is reasonably performant is based on treeDiffer.js (
https://github.com/Tchanders/treeDiffer.js) which is in turned based on the Zhang-Shasha algorithm which was a slightly less optimal predecessor of APTED but still seems to be pretty good.
There's various implementations of Zhang-Shasha in the npm registry which might also be an interesting thing to play with asciidoctor.js with. And there's also a Ruby version for Zhang-Shasha here
https://github.com/wdhongtw/zhang-shasha
One day when I find the time I'd like to look into this further. For now the Python script is doing OK for me.
On Wed, May 15, 2019 at 6:29 PM mojavelinux [via Asciidoctor :: Discussion] <
[hidden email]> wrote:
> the question was how changes between documents could be made visible in an output document
with the intent to visualize to the reader what has changed.
I believe I addressed that question in my answer (specifically GitHub's prose diff).
I'd love to say that prose diff is available as an offline tool, but I have yet to be able to find one that comes anywhere close to what GitHub is showing.
Cheers,
-Dan
On Wed, May 15, 2019 at 12:23 AM Patrick Ben Koetter [via Asciidoctor :: Discussion] <
[hidden email]> wrote:
abelsromero,
* abelsromero [via Asciidoctor :: Discussion] <[hidden email]>:
> Welcome to the forum :)
>
> For those features the recommendation is to store the source documents in a
> version control system like git (
https://git-scm.com/). Git provides these
> features and you can use services like GitHub or GitLab for collaborative
> workflows and review the changes on a nice website.
> I personally prefer GitLab, it even includes an online editor.
>
> If you are not familiar with such tools just google for some quickstarts and
> definitely give them a try.
I think the OP asked a different question. As I understood it, the question
with the intent to visualize to the reader what has changed.
p@rick
--
[*] sys4 AG
https://sys4.de, +49 (89) 30 90 46 64
Schleißheimer Straße 26/MG,80333 München
Sitz der Gesellschaft: München, Amtsgericht München: HRB 199263
Vorstand: Patrick Ben Koetter, Marc Schiffbauer, Wolfgang Stief
Aufsichtsratsvorsitzender: Florian Kirstein
--
--
--
Private or confidential message? Public Key available
here: