Invisible comments

[cayennep]

I want to make comments in topics - these are for my use only, eg 'do not publish'

Can anyone make suggestions as to best way to do this? It seems a vital part of single-sourcing, to be able to annotate without leaving the content in an unpublishable state (or rely on going back later) but I don't see offhand a way to do this.

I could use conditions, but wonder if I'm missing something??

Any help appreciated, thx

[SteveS]

I use conditional tags...

[Robotman]

I use conditional tags as well. With a p class to make it standout when included in the build.

[NorthEast]

Or, Flare does already have an annotation feature... Insert > Insert Annotation.

[ChoccieMuffin]

I have a span class and a p class that I use to insert comments. I want to keep them in there until I've fixed them and intend deleting them as the problems are resolved. Haven't yet tried hiding them by changing them in the stylesheet - sounds like a really good thing to experiment with. I'll get back to you if that works.

A difficulty with keeping comments in the topic file with a condition might be when you come to translate, as the translators might not have an easy way to differentiate between text that is to be translated and text that isn't, as well as the localisation company's software not being able to tell the difference so you might end up being charged for translating the comments.

[NorthEast]

I have a span class and a p class that I use to insert comments. I want to keep them in there until I've fixed them and intend deleting them as the problems are resolved. Haven't yet tried hiding them by changing them in the stylesheet - sounds like a really good thing to experiment with. I'll get back to you if that works.

If you mean set the span class property to display: none then do not do that.

Although it will be invisible when you open the topic normally, if you search for a term that's in hidden text, then Flare will display the hidden text if you open the topic via the search results. (Presumably it's related to how the Flare search needs to display hidden text in togglers and drop-downs.)


Anyway, considering Flare already has an annotation feature - is there some advantage to using extra conditions or classes to mark annotations?
I guess if you want to see the annotations in the output, then you can't do that I suppose.

[ChoccieMuffin]

Again my iggerance makes itself very obvious, I didn't realise there was an annotation feature!

Cayennep, looks like we should both look at annotations...

Can anyone tell me whether annotations can be easily differentiated when localising, so the translators don't translate them, or charge for them? Thanks.

[NorthEast]

Can anyone tell me whether annotations can be easily differentiated when localising, so the translators don't translate them, or charge for them? Thanks.

In the editor, they appear in their own separate pane (which can be displayed or hidden).
In the source page code, they're enclosed in <MadCap:annotation ... > tags.

[ChoccieMuffin]

Cheers, Dave. I suppose that's a question I'd just have to ask the specific localisation company. Ta.

[cayennep]

This is not working as expected.

annotations DO publish in output, which is what I don't want. I'm back to conditions, but it's two steps - apply the formatting so I can visually see where the comments are, and apply a condition to the text.

not the easiest...

[alt_jennifer]

As someone who works with Flare in a translation company, I can tell you that we can filter out Annotations from our word count and translation files, without removing them from the Flare project. But we cannot filter out <span> or <p> tags that have simply been conditioned a certain way, at least not unless the tags are exactly the same every single time (no extra styles included every now and then, etc.). But this is a customized process that we've made ourselves, so not every translation company can do this, and most probably won't even try.... But Annotations would be a better choice on our end!

[cayennep]

Thanks Jennifer, this is very good information going forward.

I've also found the condition + style to not work as expected. Even setting it to Exclude from my target, it's still publishing. Haven't had time to troubleshoot it yet but may try annotations as well.

What I really want is something that 1) is obvious in the editor (different color, etc) and 2) I can find all the instances of, to address the comments. Again, in author-it, these were quite easy, as Show Relationships would show every instance of when something's used.

I'll have a look at annotations but any tips to speed me up or looking in the right direction much appreciated!

thx
Cayenne

[esangregory]

I'm surprised to see you have had difficulty with a condition + style approach, because I have found that method to work wonderfully. I initially started doing it to mark questions that I wanted to be visible for SMEs in the PDFs I sent for review and invisible in the final .chm output, but I have also used it with a different condition to mark comments for myself.

I created a paragraph class that has a red background so it is hard to miss. I also begin every comment or question with the text "Question:" or "Note to self:" so I can quickly do a find/replace, both in Flare and in the PDF. My conditions are a bit complicated, but I have one general one that I apply to topics that contain questions. This condition does not exclude any content from any target - it just gives me a visual reminder in the Content Explorer that I have a comment or question that needs to be followed up. I apply a "PrintOnly" condition to question paragraphs, which includes the question in the PDF target for review, but excludes it from the HTML target. Then, for comments I want no one else to see but myself, I use a "WritersReference" condition that excludes a paragraph from all targets. It's a bit clunky, but it's the best way I've found so far to handle comments and questions not intended for final output.

[cayennep]

ok, confused...

I finally used annotations as my conditions were still publishing, even tho I'd set them to be excluded.

BUT, they publish to the output, which was my original question/intent to address.

guess I'll go back to trying conditions, but contrary to what I'd thought from these posts, annotations do appear in the output.

[NorthEast]

ok, confused...

I finally used annotations as my conditions were still publishing, even tho I'd set them to be excluded.

BUT, they publish to the output, which was my original question/intent to address.

guess I'll go back to trying conditions, but contrary to what I'd thought from these posts, annotations do appear in the output.

Ok, I'm not sure how, as annotations don't (or at least shouldn't) appear in the output.

Can you reproduce this in a test project? Sounds like one for MadCap support.

[Steveman]

What I really want is something that 1) is obvious in the editor (different color, etc) and 2) I can find all the instances of, to address the comments. Again, in author-it, these were quite easy, as Show Relationships would show every instance of when something's used.

You can use Project/Reports to find your annotations. Create a report looking for "project annotations" and it will list all of the instances. It won't solve your problem of them appearing in the output but it will make them easier to find and remove.

[cayennep]

yikes, just knowing they're not supposed to publish tells me that many things in flare are happening for me that should not be!

It's just regular html output so don't know why this would be but yes, completely reproducable. Unfortunately, don't have the time right now to do bug report.

thx all

[livetoski]

So far our annotations haven't shown up, but I find that the reasons for using annotations are in conflict. Invisible comments, if it works, that's good. But if you have the same file reviewed through X Edit (should we ever try to figure that out again), and you accept annotations, then don't your "invisible comments" become integrated into the output?

Formerly, we used ***commented text here. We then could track our concerns within the text by searching on ***, and we could expose the comments to reviewers, or not through the condition. Also, if annotations work, I can't expose the comment to reviewers when I am using Word or PDF. Can someone give me a better use case for annotations?

[cayennep]

I am now using conditional text for my comments, plus a character style to easily see it in the editor.

However, they STILL APPEAR in the output!!
Does this need to be set anywhere besides the Target? I've set this condition to Exclude, is there something else I need to do? Others seem to have different results so curious....

thx

[livetoski]

Cayennep, Do you have more than one condition on your comments?
Linda

[cayennep]

Hi there

No, I have a condition and a style - I'm wondering if the style is what's making it publish, but the condition should override it, else conditions are not very useful.

thx

[livetoski]

I can't imagine that the style is making it visible. Forgive me for asking, but have you looked at the code?

[LTinker68]

I second livetoski's suggestion. Open the topic in the Internal Text Editor and look at that block of text. There used to be an issue where deleting a condition from a condition set would remove the condition name, but everywhere it was used there would be a condition tag with nothing defined. That was enough to throw off the use of conditions. I can't remember what version that was fixed in (I think it was fixed), but you might check to see that you don't have any condition tags with an empty value. And double-check that your tags are book-ended properly -- make sure it's not condition tag, span tag, text, condition tag, span tag, for example.

[livetoski]

while you are there, Lisa, can you look at my comment

So far our annotations haven't shown up, but I find that the reasons for using annotations are in conflict. Invisible comments, if it works, that's good. But if you have the same file reviewed through X Edit (should we ever try to figure that out again), and you accept annotations, then don't your "invisible comments" become integrated into the output?

Formerly, we used ***commented text here. We then could track our concerns within the text by searching on ***, and we could expose the comments to reviewers, or not through the condition. Also, if annotations work, I can't expose the comment to reviewers when I am using Word or PDF. Can someone give me a better use case for annotations?

I'd really like someone else's opinion on this before I succumb to the enthusiasm of others for annotations.

[LTinker68]

I haven't played with the new annotation feature at all and don't use X-Edit, so I'm afraid I can't offer any suggestions. We don't even call out changes in the documentation, generally, other than adding some info to a "Revision History" table.