How to show changes between two docs in the new version

classic Classic list List threaded Threaded
7 messages Options
Reply | Threaded
Open this post in threaded view
|

How to show changes between two docs in the new version

mszmurlo
Hello,

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

Maurycy
Reply | Threaded
Open this post in threaded view
|

Re: How to show changes between two docs in the new version

abelsromero
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.
Reply | Threaded
Open this post in threaded view
|

Re: How to show changes between two docs in the new version

mojavelinux
Administrator
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.

prose-diff.png

Similar views are available when submitting a pull request (aka merge request).

This the main tool we recommend for conducting this sort of analysis.

Cheers,

-Dan

On Tue, May 14, 2019 at 11:44 PM abelsromero [via Asciidoctor :: Discussion] <[hidden email]> wrote:
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.


If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/How-to-show-changes-between-two-docs-in-the-new-version-tp6915p6916.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: How to show changes between two docs in the new version

Patrick Ben Koetter
In reply to this post by abelsromero
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.

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
 
Reply | Threaded
Open this post in threaded view
|

Re: How to show changes between two docs in the new version

mojavelinux
Administrator
> 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
was how changes between documents could be made visible in an output document
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
 



If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/How-to-show-changes-between-two-docs-in-the-new-version-tp6915p6918.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: How to show changes between two docs in the new version

danyill
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
was how changes between documents could be made visible in an output document
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
 



If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/How-to-show-changes-between-two-docs-in-the-new-version-tp6915p6918.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



If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/How-to-show-changes-between-two-docs-in-the-new-version-tp6915p6919.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML


--

--
Private or confidential message? Public Key available here

Reply | Threaded
Open this post in threaded view
|

Re: How to show changes between two docs in the new version

mszmurlo
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