Generic class for marking reviewed text

[RiverMonster]

Hi,

I have seen a few posts recommending using a generic class for marking text as reviewed (e.g .REVIEWED). The idea is that you set a coloured background for the class and then you can apply it to either paragraphs or individual words. Unless I am missing something this works okay if whatever you apply it to doesn't already have a class; otherwise it replaces it.

For example, suppose you have p.bullet applied to three sentences. You select the sentences and click the .REVIEWED class. When you do this the three sentences become p.REVIEWED and show up with the colour that you set...but the bullets will disappear because the class has been replaced. It seems that the only way to apply the .REVIEWED class without removing the bullets would be to add a space at the end of each paragraph and then select each paragraph individually, up to but not including the space and then apply the .REVIEWED class. In other words, to apply the class as if I was applying a span class. This is a pain. Furthermore, if the text has a span class applied (e.g. span.smallcaps) then any generic class that you apply will replace it.

The only way I can see around this is to create a separate generic review class to mimic every standard class in the project (e.g. p.bulletsREVIEWED, span.smallcapsREVIEWED) and this would be a mess.

Am I doing something wrong or is this really as good as it gets with generic classes?

Thanks,

Adrian

[helen]

Hi Adrian

Sorry you're already doing what I would suggest (and use - I don't have many custom classes). I'm not sure if you can use conditions to apply formatting - that would be my other thought.

[enricosavazzi]

Conditions would also be my suggestion. Create a "Revised" condition, select a background colour that is not used by any other condition, and you should be able to see in Flare's editor which text has the "Revised" condition.

[RiverMonster]

Thanks for the replies. I thought I might have been missing something with the generic classes, but it seems that's just the way it is.

Our review process is based on shared PDF reviews and changing to X-Edit or anything else for reviews is not really an option for us right now; our reviewers need to see the text highlighted in a PDF output. Using conditions doesn't really help because (unlike a FrameMaker output) condition markers are not preserved in the PDF output, they are only visible in Flare.

The two workarounds using conditions that I know of aren't really that helpful to us either (workraround 1: create a Word output with conditioned text showing and another without the conditional text then use Word's compare docs feature to produce a doc with only the changes; workaround 2: use the MadCap|conditionalText entry in the CSS that I discussed in another post (http://forums.madcapsoftware.com/viewto ... 155#p43510)...but this has the same problems as the generic class.).

It would be good if MadCap could come up with their own reviewed text functionality (preferably something like FrameMaker's change bars). Failing that, if they could implement one of the following it would be great:

i. An option to allow generic classes to be applied to multiple elements simultaneously without replacing existing tags.
ii. An option to preserve conditonal text indicators in direct PDF output so we dont need to go via FrameMaker.

I will put in an enhancement request...

Thanks,

Adrian

[KevinDAmery]

Well, depends what you're after. Conditions will be visible in Flare, but not in your output, so if you're giving review copies to SMEs in Word for example they won't see what has changed. So if you want people to review using Word docs, I think you're stuck with Spans.

(I'm not sure if the conditions would show up in X-edit - if they do, that would be another option, as long as you can get your SMEs to use it.)

[KevinDAmery]

i. An option to allow generic classes to be applied to multiple elements simultaneously without replacing existing tags.

That won't work, because it isn't valid HTML or XML. Each tag can only have one class applied to it. If you need two classes there also have to be two tags (for example, p tags could be nested in a Div, and each could have its own class applied).

ii. An option to preserve conditonal text indicators in direct PDF output so we dont need to go via FrameMaker.

This might work.

Another option for you since you're using PDF is you could apply a Div to the text that needs to be reviewed. Give the Div a background colour to make it stand out. Then when the review is over, remove the Div. This is an option for PDF since the PDF output does take Divs into account: it wouldn't work if Word was your review format, since when we output to Word the Divs are not carried over.

[RiverMonster]

Thanks Kevin.

I didnt explain that very well. What I had in mind would mean losing any span class you have applied but does not involve having more than one class per tag or breaking xml rules. I should have clarified that with this suggestion I realize that any span classes that have been applied will be wiped out but as these are used infrequently (at least in our projects) it would be something we could live with (e.g. whereever span.smallcaps appears we could add our own text string to be able to find the instances and set them back later). To clarify what I meant, it is the ability to have the .generic class applied to all the text within a selected paragraph just as if I were applying a span class to all that text and being able to do so with multiple paragraphs selected. You can do this manually now by selecting the pgfs individually so it is clearly not breaking any rules on xml validity...I just didnt explain it very well.

That said, I think the PDF option would be better.

Adrian

[KevinDAmery]

Ok - Divs would work for that scenario as well though.

1) Select a group of paragraphs.
2) Hit the Tab key. This brings up the grouping dialog.
3) Select Div from the list. If you create a review class for Divs it will also appear in the list and you can select it directly.
RESULT: the selected paragraphs are all contained within a single Div which can have whatever formatting you want to use for review purposes.

The only limitation is, as mentioned before, the Div will be ignored in Word output. If you output to any of the HTML formats or directly to PDF using Flare 4.x, though, it should work.

[RiverMonster]

Hi Kevin,

I'm sorry, I didn't see the second part of your reply before about DIVs. Sounds like a great idea. I will check it out.

Thanks!

Adrian

[scott]

Hi all,
You can apply more than one class to an element. The class names must be separated with a space. For example:
<p class="centered red">text text text</p>

An element can only have one ID, however.

I haven't found a way in the XML Editor to apply multiple classes, but you can do it in the Text Editor. The XML Editor also doesn't display the formatting. They -do- appear correctly in the preview and in WebHelp.

Here's more info about using multiple classes in an element:
http://webdesign.about.com/od/css/qt/ti ... ticlas.htm

[RiverMonster]

Thanks for the extra info Scott. Shame it doesnt work in the editor, but a good trick to know.

As for Kevin's DIV suggestion that works well for our purposes with only a few issues...

i. You can apply a DIV to paragraphs but not strings within a paragraph. E.g. if only a few words in a long pgf changed and you want the actual changes to be made clear. This is a really minor issue though and certainly something we can live with. (In fact, in this respect this method is similar to change bars in FrameMaker which is what we have used till now anyway).

ii. After a document is released we make a copy of the Flare project and then use it as a basis for next version. This means that our project would start off full of DIV tags that were relevant to the previous release. We could just set the class for these tags to a white background colour and then use new (coloured) tags for the new version, but that gets kinda messy and after a few projects we could be several DIV tags deep in some places. Ideally, there would be an easy way to globally remove all DIV tags of a specified class in Flare. I thought this might be possible via Find/Replace with regular expressions...I worked out a regular expression that could be used to find each incidence (without hitting the DIVs we use for other purposes) but the "replace" would still be manual. However, it does seem that we can strip out the DIV tags easily using FrontPage as it includes a search function to find a specified tag with specified attributes (in this case a DIV tag with a certain class) and automatically remove the tag while leaving the contents. A simple test over a handful of html files worked well. So, unless someone tells me this can actually be done in Flare globally (rather than unbinding each DIV one by one) I think we will be using FrontPage to clear up at the start of new projects.

Thanks,

Adrian

[KevinDAmery]

Thanks for the extra info Scott. Shame it doesnt work in the editor, but a good trick to know.

As for Kevin's DIV suggestion that works well for our purposes with only a few issues...

i. You can apply a DIV to paragraphs but not strings within a paragraph. E.g. if only a few words in a long pgf changed and you want the actual changes to be made clear. This is a really minor issue though and certainly something we can live with. (In fact, in this respect this method is similar to change bars in FrameMaker which is what we have used till now anyway).

For this scenario you'd have to use Span tags. This would also be the case if you were using paragraph classes.

ii. After a document is released we make a copy of the Flare project and then use it as a basis for next version. This means that our project would start off full of DIV tags that were relevant to the previous release. We could just set the class for these tags to a white background colour and then use new (coloured) tags for the new version, but that gets kinda messy and after a few projects we could be several DIV tags deep in some places. Ideally, there would be an easy way to globally remove all DIV tags of a specified class in Flare. I thought this might be possible via Find/Replace with regular expressions...I worked out a regular expression that could be used to find each incidence (without hitting the DIVs we use for other purposes) but the "replace" would still be manual. However, it does seem that we can strip out the DIV tags easily using FrontPage as it includes a search function to find a specified tag with specified attributes (in this case a DIV tag with a certain class) and automatically remove the tag while leaving the contents. A simple test over a handful of html files worked well. So, unless someone tells me this can actually be done in Flare globally (rather than unbinding each DIV one by one) I think we will be using FrontPage to clear up at the start of new projects.

To the best of my knowledge Flare doesn't have this capability. However, it sounds like a great feature request. If you haven't made one already...

http://www.madcapsoftware.com/bugs/submit.aspx

[KGaetz]

Hi Adrian,

Did you ever resolve this? We are going through this same discussion here.
My thought is to just use the Text Background button on the toolbar. The color appears in both WebHelp and PDF. To remove the formatting, search for:' style="background-color: #ffd700;"' in the code and replace it with ' '.

Has anyone tried this and it didn't work?

Kathy

[KGaetz]

Let me amend that last post: this seems to work if you apply it to an entire paragraph. If you select text, it creates a <span>, and that makes the cleanup a bit more difficult. (Unless you don't mind having empty tags in your topics.)

[KevinDAmery]

.... (Unless you don't mind having empty tags in your topics.)

Empty tags can cause unpredictable things to happen: for example, sometimes Flare makes decisions about where to break lines and pages based on where tags are, even if they shouldn't have any affect on the flow of text. As a general rule, I would try to keep extraneous tags to an absolute minimum (preferably none at all).

[RiverMonster]

Hi Adrian,

Did you ever resolve this? We are going through this same discussion here.
My thought is to just use the Text Background button on the toolbar. The color appears in both WebHelp and PDF. To remove the formatting, search for:' style="background-color: #ffd700;"' in the code and replace it with ' '.

Has anyone tried this and it didn't work?

Kathy

Hi Kathy! Glad to hear you are still in Flare-land!

Nope, we never resolved the issue of marking up individual words. Your idea of using the plain 'ole text background button sounds like a good solution and is probably okay for most folk but in our case we want to preserve the info about what changes are marked for review in each (Agile) development iteration. We can do this well using DIV tags (authors set them to white in the CSS for the final output but the info on each iteration is preserved) so for this we are prepared to put up with the minor inconvenience of not being able to highlight individual words in the same way.

By the way, a note that may be of interest to you and others reading this thread...during our trials we discovered that DIV tags cannot be used within a table. I believe W3C disallows it because DIV was really not intended for situations like this. One exception is within <td> elements but for this you need to go to the code - Flare doesn't let you add a DIV tag there in the GUI. So, instead of using DIV tags for tables we created another set of review classes for <td> and <tr> that have identical colors to the DIV classes. Applying them is different than applying the DIV tags but just as easy. (The only minor issue comes when a table already has a background color (it overrides the class applied) but this is only an issue during the review cycle.)
[Comment added June 9 - we found a number of bugs related to applying tr and td styles to tables that already have a table style. Because of this we decided to go instead with the manual (toobar button) markup method for tables]

As for our other issue about how to remove DIV tags at the start of a new project, MadCap development confirmed this cannot be done using the regular expression functionality in Flare but it is really easy to do with FrontPage so not a big deal.

Cheers,

Adrian

[SuzieQ]

Well, it's August and Flare 5 is here-- is there a better method for showing conditional text in output for reviewer purposes? I have tried div tags, which works, but is an extra manual step that is inelegant for the reasons already stated in this thread.
Anyone?