If we have two files v1.adoc and v2.adoc which is newer version of v1.adoc, is there a way to generate a target v2.html, for example, which will contain clearly identified (for example with background colors),
- what had been removed from v1,
- what remains in v2 but that had been changed and
- what had been added to v2.
That would help a lot to follow the changes done to a document by a team.
Thanks for the feedback
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.
To build on what Abel suggested, code management tools like GitHub offer numerous views for comparing changes. On GitHub, append /compare to any repository URL to bring up the interface. The following article explains how to use it: https://help.github.com/en/articles/comparing-commits-across-time
Here's an example of comparing content changes across versions in the Couchbase Java SDK docs.
(click on "Files Changed" to see the actual file changes)
Using buttons in the upper right corner of any file entry, you can view both the source and prose (rendered) differences for that file. Here's an example of how the prose diff looks.
Similar views are available when submitting a pull request (aka merge request).
This the main tool we recommend for conducting this sort of analysis.
On Tue, May 14, 2019 at 11:44 PM abelsromero [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Welcome to the forum :)
In reply to this post by 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
was how changes between documents could be made visible in an output document
with the intent to visualize to the reader what has changed.
[*] 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
> 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.
On Wed, May 15, 2019 at 12:23 AM Patrick Ben Koetter [via Asciidoctor :: Discussion] <[hidden email]> wrote:
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:
In reply to this post by mszmurlo
Thanks to all for your replies.
I was indeed looking for an external tool the would generate document v2 along with the deletions, additions and changes identified, for exemple with colors, so that I can give this v2 to my colleagues and they will see what has changed. I'll definitely give a try to https://github.com/danyill/htmldiff
Thanks again for your time
|Free forum by Nabble||Edit this page|