MadCap Software Forums

I'm trying to use change bars for my PDF output to show changes from the previous version of the PDF.

is this possible? I can't find any information in the forums.

What is a "change bar"?

Maybe the coloured lines at the side of paragraphs that changed?

A change bar is a bar in the margins of the page showing lines that changed in a rewrite.

Any method of showing changed text will do. But since I use the term "change bars," I don't recognize whatever term Flare uses and can't find the answer.

There is nothing comparable out-of-the-box in Flare, not that I'm aware of. You can submit a feature request at http://www.madcapsoftware.com/bugs/submit.aspx.

However, you can do something similar easily enough with CSS. Create an image that you'd like to act as the change bar and save the image to the Resources\Image folder in the project. Create a custom paragraph class. Set its background image to the image you created and set it to no-repeat. Set the paragraph's left margin to a negative value and set its padding-left to the same amount but as a positive value. So if your image is .25 inches wide, then set the margin-left to -.5in and the padding-left to .5in. This will position the left edge of the image to .5 inches to the left of the main body text. You then apply that custom class to any paragraph you want.

Note that if your image is too tall for the paragraph it won't all appear, so you might also want to set the height of the paragraph to an amount that will allow the entire height of the image to show, or at least the minimum amount. For instance, if you have text in the image that says "New in this version" and that takes up approximately one inch, make the actual image file four inches in height in case you have a long paragraph. Then set the height of the paragraph class to 1in. That way the paragraph will always be at least tall enough to show the "New in this version". If your paragraph ends up being longer, it will show more of the image because the default option is to allow for overflow, so it actually ignores the one inch height parameter if it needs more space to display the paragraph.

Do a "diff" on the Flare source files? Easy if you're using source control.

I think the absence of automatic change indicators is an even bigger problem if using X-Edit for reviewers - which we've given up using because of this lack of functionality.

I've logged it as a change request on the website (I know I'm not the only one), face-to-face with a senior MadCap person at a conference and by follow-up email to them. That was a while ago. No joy yet.

I agree that change bars are important for reviewers. I will have to submit a feature enhancement request.

Would it be possible to do this in CSS by modifying the border settings (add an outside paragraph border) instead of an image?

ksoltys wrote:Would it be possible to do this in CSS by modifying the border settings (add an outside paragraph border) instead of an image?

Ooh, that's a good one. I was trying to think of a way to do that and include text, but couldn't. If you don't need text (color bar is fine), then this will work. You'll want to create a custom paragraph class, set its margin-left value to -.5in (negative), set its padding-left value to .5in (positive), then specify its border-left properties, with the border-left-width set to something like .25in.

LTinker68 wrote:

ksoltys wrote:Would it be possible to do this in CSS by modifying the border settings (add an outside paragraph border) instead of an image?

Ooh, that's a good one. I was trying to think of a way to do that and include text, but couldn't. If you don't need text (color bar is fine), then this will work. You'll want to create a custom paragraph class, set its margin-left value to -.5in (negative), set its padding-left value to .5in (positive), then specify its border-left properties, with the border-left-width set to something like .25in.

Any creation of a custom paragraph class seems like a non-starter to me, unless all you ever use is a bog-standard p element. Otherwise, how do you indicate that a p.Tip element (for example) has been modified? p.TipChanged? And what happens if you want to change the style of the elements -- you have to change it in multiple places? If it's for review, IMHO, you're much better off outputting to Word and using merge to show all the places where the doc changed. If it's for customers, you are probably better off with some kind of New Features Guide or What's Changed topic (depending on the exact type of docu this is) -- customers don't want to read through the entire guide to see what's changed. They want to see all the new / modified stuff in one place.

I don't think there's going to be an easy way to do this (Andrew's idea above is good).

You could mark changes using condition markers if the revisions only had to be visible inside Flare, but if they need to be visible in the output then you need some way to use a style. As mentioned above, using a class is no good as you can't apply it to tags that already have a class.

If you have to use a style, the only solution I can think of is to use the ID attribute -although it might be a bit tedious to use in practice.

To do this, define the attribute to your stylesheet, e.g.:
Then using the Attributes pane in Flare (press Shift + F12), set the ID of the tag to the same name - i.e. edit.

Like I said, this would be pretty tedious, as you have to type in the ID name to mark each tag - you can't just easily apply an attribute like a style/class.
Maybe call the attribute 'e' to make typing it in a bit quicker.

Dave Lee wrote:Then using the Attributes pane in Flare (press Shift + F12), set the ID of the tag to the same name - i.e. edit.

How on EARTH did I not know about the Attributes pane? THANK YOU for mentioning this. I love it.

Frankly, I don't bother with trying to style something in Flare. We have the full version of Adobe Acrobat so I just use the highlight tool to highlight text (this allows me the option of only highlighting a few words in a paragraph rather than a whole paragraph). Then I use the line tool to draw a red
line down the right margin next to graphics. I will also use the call out tool if there was some text that was deleted. I do this only to the PDF copy I send for review, then I don't have to muck with the actual xml files in Flare (and remember to reset the styles before publication or the next review cycle).

Back when I was working in the UNIX world and writing documents in troff (yes, I know, I'm dating myself), we could automate the diff marking of files so you didn't have to keep track of what was changed. Of course, it requires a good CMS, an editor that doesn't randomly change the line breaks and the ability to compare approved changes from unapproved ones. Once we moved to SGML for documentation, that functionality went away in part because the editor being used at the time would reposition the line breaks for no good reason and because someone deemed the company's CMS (which was ECMS - extended change management system) as "too difficult" to comprehend for mere tech writers. Bozos.

Anyway, sans, a decent CMS, the automation of diff marking/change bars went away and we were forced to do something akin to what's been discussed here. All I can say is that it was a huge headache to maintain long term. With CMS and a good tool that can ignore white space changes, it should, theoretically, be possible to come up with a means of auto-generating change markup in an output. I have yet to see that anyone's come up with such a beast.

navoff wrote:With CMS and a good tool that can ignore white space changes, it should, theoretically, be possible to come up with a means of auto-generating change markup in an output. I have yet to see that anyone's come up with such a beast.

I'm not sure why a Word merge won't fit your needs. As much as I may consider Word a very poor tool for a lot of techcomm needs, when it comes to tracking changes / differences, it's quite good (there are some weaknesses with colors not being consistent from user to user, but otherwise, it's pretty strong).

navoff wrote:With CMS and a good tool that can ignore white space changes, it should, theoretically, be possible to come up with a means of auto-generating change markup in an output. I have yet to see that anyone's come up with such a beast.

Andrew wrote:I'm not sure why a Word merge won't fit your needs. As much as I may consider Word a very poor tool for a lot of techcomm needs, when it comes to tracking changes / differences, it's quite good (there are some weaknesses with colors not being consistent from user to user, but otherwise, it's pretty strong).

I avoid using Word whenever possible. I prefer to keep the number of headache triggers to a minimum. Currently, there isn't enough need for me to use Word to diff mark files. The manual highlighting of the PDF file works just fine for the number of reviews I have to deal with. Plus, I can delete unchanged pages from my review copy easily without affecting the remaining pieces. It's simple, headache free and it works.

Manually editing each PDF would certainly trigger major headaches for me, but if it works for you, so much the better!

Andrew wrote:outputting to Word and using merge to show all the places where the doc changed.

How do I use merge to show all the places the doc has changed? I was hoping to use the X-Edit Reviewer, but my reviewers are used to Word, and if I can't use change bars to show diffs, Word output will have to do.

Rachel

In Office 2003, it's Tools > Compare and Merge Documents (select the Legal Blackline checkbox on the Open dialog, I think...it's been a long time on Word 2003). In Office 2007, it's Review > Compare > Compare.

Select the two documents you want to compare, and it will show you the differences between the original and the newer version. Looks something like this (sorry for the large screen shot):


Changes show up however you set them to -- in my case, I set them to show up with my name. They show up in color (red, in this case), just like they would if you set it to Track Changes: a colored text means inserted text, colored but strikethrough text means text was removed.

The process we use takes a little longer to set up initially, but once the styles are created it is a pretty simple system to use.
First, we create a second style for every element in our stylesheet called 'x.x_new.' For example, a new paragraph would be called 'p.body_new, a new graphic would be called img_new, etc.' The style is using a light blue shading. We tag all new text, tables, graphics, cross refs, etc. with it's corresponding _new style so it is highlighted blue in the editor and output.

After the project has gone through editing and review, we open all the topics in Notepad++ (you can drag all the topics in your project to Notepad++, and have them open all at once) and do a find and replace for' _new' and replace it with nothing. This removes the _new and replaces it with the original style. Do a' save all open documents' in Notepad++ and the track changes will now be turned off.

Notepad++ is a free application.

Here is an example in the styles viewer: