Skip to main content
Known Participant
February 16, 2023
Answered

Which is the best diff/merge application for use with GitHub?

  • February 16, 2023
  • 6 replies
  • 1620 views

The RoboHelp user guide mentions registering an external diff/merge application - doesn't RoboHelp include one?
If you're using GitHub to manage version control, which is the best application for comparing the current version of a file with a proposed replacement?

This topic has been closed for replies.
Correct answer Amebr

The idea is that the condition tags, if you don't condition them out in the preset, make it into the output, and you can create a css selector to apply a background colour (or other formatting as you wish) to text with that condition tag. It is manual and won't tell your reviewers exactly how something has changed, but allows you to mark the text that has changed. In RH2019 when I tested the concept it survived into Responsive/Frameless and Word output, but I haven't checked in RH2020+.

 

There are a few parts to set up first.

 

1. Create a draft output preset so you can generate (and potentially publish) without affecting your production output.

2. Create a condition tag that you'll use to mark your changed text. You could potentially get creative and have multiple with different types of formatting (for deleted vs changed for example), but in my opinion that's too much work, so I only opted for a single one. e.g. Group: Review. Tag: Changes.

3. Create a draft stylesheet that imports your main stylesheet (so all the formatting will look right) and includes only the following style definition:

[data-condition="<GroupName>:<TagName>"] { <formatting> }

e.g.

@1552174 url('main.css'); /* this assumes both stylesheets are in the same folder otherwise include relative path */
[data-condition="Review:Changes"] {
    background-color: pink;
}

(You might be able to skip the import bit as I think New UI allows multiple stylesheets now, but this was how I had my test project set up.)

4. Create a draft master page and select the draft css as the stylesheet. 

(I think if you go the multiple stylesheet route, you attach your main stylesheet here too, if you haven't attached it to every topic individually. But you might have to test as I haven't tried this and am not quite certain it works how I think.)

5. Select the draft master page in your draft preset. This ensures your draft stylesheet is applied to every topic in the draft output. We don't want to attach to each topic individually as then the formatting would show in the production output. 

 

As you edit the topics, you mark the changed text with the condition tag.

 

Or you could choose to duplicate paragraphs, and mark the new paragraph only, so your reviewers can compare the old and new text on the same page. If you go this route, I'd recommend also creating a condition expression that excludes the review tag, and apply that to your production output preset. That will ensure your draft content can't accidentally make it in to production.

 

When your draft content is approved, you can publish without doing anything if you chose to apply the condition tag just to the changed text, but I generally recommend removing the tags from your content, so everything is clean for the next review.

 

If you chose the duplicated paragraph method, then you'll need to go through and delete the old paragraph, so it makes sense to remove the review tag at the same time.

 

It sounds a bit daunting initially, but actually works quite smoothly once everything is set up and you're used to the workflow.

 

(I think I actually read this method from the Flare forums years ago, but it's only just become a workable option in New UI.)

6 replies

AmebrCommunity ExpertCorrect answer
Community Expert
February 22, 2023

The idea is that the condition tags, if you don't condition them out in the preset, make it into the output, and you can create a css selector to apply a background colour (or other formatting as you wish) to text with that condition tag. It is manual and won't tell your reviewers exactly how something has changed, but allows you to mark the text that has changed. In RH2019 when I tested the concept it survived into Responsive/Frameless and Word output, but I haven't checked in RH2020+.

 

There are a few parts to set up first.

 

1. Create a draft output preset so you can generate (and potentially publish) without affecting your production output.

2. Create a condition tag that you'll use to mark your changed text. You could potentially get creative and have multiple with different types of formatting (for deleted vs changed for example), but in my opinion that's too much work, so I only opted for a single one. e.g. Group: Review. Tag: Changes.

3. Create a draft stylesheet that imports your main stylesheet (so all the formatting will look right) and includes only the following style definition:

[data-condition="<GroupName>:<TagName>"] { <formatting> }

e.g.

@1552174 url('main.css'); /* this assumes both stylesheets are in the same folder otherwise include relative path */
[data-condition="Review:Changes"] {
    background-color: pink;
}

(You might be able to skip the import bit as I think New UI allows multiple stylesheets now, but this was how I had my test project set up.)

4. Create a draft master page and select the draft css as the stylesheet. 

(I think if you go the multiple stylesheet route, you attach your main stylesheet here too, if you haven't attached it to every topic individually. But you might have to test as I haven't tried this and am not quite certain it works how I think.)

5. Select the draft master page in your draft preset. This ensures your draft stylesheet is applied to every topic in the draft output. We don't want to attach to each topic individually as then the formatting would show in the production output. 

 

As you edit the topics, you mark the changed text with the condition tag.

 

Or you could choose to duplicate paragraphs, and mark the new paragraph only, so your reviewers can compare the old and new text on the same page. If you go this route, I'd recommend also creating a condition expression that excludes the review tag, and apply that to your production output preset. That will ensure your draft content can't accidentally make it in to production.

 

When your draft content is approved, you can publish without doing anything if you chose to apply the condition tag just to the changed text, but I generally recommend removing the tags from your content, so everything is clean for the next review.

 

If you chose the duplicated paragraph method, then you'll need to go through and delete the old paragraph, so it makes sense to remove the review tag at the same time.

 

It sounds a bit daunting initially, but actually works quite smoothly once everything is set up and you're used to the workflow.

 

(I think I actually read this method from the Flare forums years ago, but it's only just become a workable option in New UI.)

Known Participant
February 23, 2023

Thank you for the detailed workflow

Community Expert
February 23, 2023

I think I got all the steps in there, but if you hit problems when trying it, post back with where you got stuck 🙂

Community Expert
February 21, 2023

I don't know what a pull request in github is. 😛

 

More seriously though, if it's for SMEs to review the changes perhaps a condition tag trick with a generated draft output would work. Let me know you're interested in this idea and I'll run through it.

Known Participant
February 22, 2023

That sounds like a great idea @Amebr . I'm still choosing between RoboHelp and MadCap at the moment, so I maight take you up on that offer 🙂 

Community Expert
February 20, 2023

Out of curiosity what's your use case for the diff? Usually is the "developer" (in this case the tech writer) comparing any conflicts when they check in a file. Or are you wanting to mark the changes for SMEs reviewing an update?

Known Participant
February 21, 2023

Most of the time it'll be someone comparing the proposed and current versions of content. Equivalent to reviewing a Pull Request in GitHub - we're using Restructured Text currently, and GitHub compares the files line-by-line, sometimes  showing two groups of multiple lines, indicating that there's a change in there somewhere. It's really painful, especially if the content is a table.

 

Known Participant
February 21, 2023

sometimes we generate the before and after web pages so we can see the differences properly

Community Expert
February 20, 2023

If you find one, post back. I've only ever seen code diff tools and would be interested to see what a wysiwyg one looks like

Known Participant
February 20, 2023

For me, the lack of WYSIWYG comparison is a show-stopper - I'm not going to ask people to learn HTML to understand changes in document content

Inspiring
February 17, 2023

I guess there are several good options out there. We use P4 Merge for diff/merge - works fine and it's free. Just set it up in your Preferences -> Version Control and you're good to go. 

Known Participant
February 17, 2023

From a quick look at their web site, P4 Merge appears to be designed for comparing code files; when comparing two versions of a RoboHelp topic, how does it present the differences? Does it show HTML diffs (relying on my knowledge of HTML to know what that means), or does it show a WYSIWYG difference, more like comparing two documents in MS Word?

Inspiring
February 17, 2023

It's showing HTML diffs in the source code, yes. As we have to do a lot of stuff in the source view of Robohelp anyways, it's working fine for us.

Jeff_Coatsworth
Community Expert
Community Expert
February 16, 2023

RH doesn't include one anymore (AFAIK) - used to be Robosource, but I don't think that's still there. I don't use version control, but I suspect you'd use the tools within it to do compares.