Insert Annotation

[Niels]

What is the great mystery behind the simple functionality "Insert Annotation"?

When I read the online documentation carefully, it should be very simple to use. There is no complex workflow described e.g. that I need to activate any special edit mode else beforehand. I don't see any further notes about why this functionality may not be enabled. Look here: https://help.madcapsoftware.com/flare20 ... ations.htm

In my Flare GUI the functionality is disabled. What I can do instead, is to delete annotations. Simply awesome )-: The topic files are not set to read-only. I can work with them normally.

Annotations_Flare2018.png

[awinnefeld]

This option needs something it can be pasted onto - it should be active as soon as you've selected some text that you want to annotate:

annotation.png

If you click "Insert Annotation", the selected text will be enclosed in an <MadCap:annotation> element, with the comment itself stored as a MadCap:comment attribute.

[Folkie]

As above - just click into or select the text you want to annotate then the button should become active - but also note that you can't annotate an image (I usually just annotate the text immediately before).

[Niels]

Thanks. However, I am afraid to tell you that the suggested solution does not work for me.

annotations-2019-06-04 07_55_05-imagemaster.flprj - MadCap Flare 2018.png

annotations-2019-06-04 07_55_45-imagemaster.flprj - MadCap Flare 2018.png

[Niels]

A colleague of mine cannot even activate the "Show changes" checkbox, even if she has opened a topic, and much more functionality is disabled:

2019-06-04 08_34_45-Review.png

[Nita Beck]

This is a wild guess. Are these topics locked from changes? See the Lock button to the right of the Insert Annotation and Delete Annotation buttons? I never use the Lock button myself, but might it have anything to do with your situation?

[Niels]

Thanks Nita,
any wild guess is appreciated these days in a Mad World...
No, I don't think it is involved. Even if it was, I would feel like a character in a horror movie because I would not know who ever presssed this button for me

LockButton.png

[doc_guy]

That is really weird behavior, both you and your colleague.

This may not be helpful to you, but to others who read this post later. (I say that because from your screen shot, I don't think my suggestion will apply.)

You have to be careful what you select in order to annotate it. From a code perspective, Flare won't allow you to insert an annotation if the resulting XML would be invalid. For example, if you select from the middle of one paragraph into the middle of another paragraph, you can't do this:

Code: Select all

<p>Lorem ipsum dolem something or other<madcap:annotation>Yada Yada blah blah </p>
<p>Boom bada bing </madcap:annotation> Smish smash</p>

So I try to only click on a single word in the paragraph that needs the annotation. Just double-clicking the single word makes the Insert Annotation button enabled for me on my system. But sometimes when I try to select multiple things the annotation button is not available if the resulting XML would be invalid.

As for your colleague, make sure she has clicked INTO the XML Editor in the topic that is open. It is not enough to just have the topic open. You have to be in the WYSIWYG editor for the Show Changes option to be open. If you are in the code view, it is disabled. If the active window is the Content Explorer, the option is disabled. You to have the XML Editor as the active window. Maybe that will help. It is all I can think of.

[Niels]

Thanks Paul for the detailed observations. Indeed, I cannot verify my colleague's reports. However, I am sure that my observed behaviour is not caused by some unaccepted click selection. I tried all kinds of selections: One word, a whole <p>, a whole page etc.
I am about to prove Murphy's law soon by support of MadCap
https://en.wikipedia.org/wiki/Murphy%27s_law

MadCapBlocks.png

[Niels]

... 3,5 years later - That's pretty steep!

Why on Earth is there an undocumented feature to disable GUI elements in Flare via the CSS and who could have set the default of the annotation feature to be disabled? We certainly did not decide to disable this feature in Flare when we started out as absolute newbies in 2016 and only very carefully handled the CSS. Of course, it might have been set by our third-party provider who helped us with the initial migration from MS Word in the beginnings. However, the fact that you cannot find a solution by searching the Flare documentation seems sad to me, or am I missing a very specific documentation source by MadCap here?

Setting the corresponding option to "false" solved the issue...

MadCap|annotation
{
mc-disabled: false;
}

[ChoccieMuffin]

The only thing I could find that was relevant when I searched for "mc-disable" was this topic:
https://help.madcapsoftware.com/flare20 ... c-disabled

specifically the note at the end:

"Warning Even if you have some styles that you never modify, you may want to avoid disabling them in your stylesheet. The reason for this is that disabling a style in a stylesheet also disables its use in the rest of the interface. For example, let's say that you have inserted several images in your project. When you do this, an <img> tag is used. Therefore, although you may never edit the properties for the img style, you still require it in order to insert images in the future. Otherwise, features such as the option to insert images become disabled in the interface. The bottom line is that you should use caution when disabling styles, making sure that you truly will not need to use those styles."

[Niels]

Yes, that's what I also found the said 3,5 years later by pure interest of reverse engineering. The actual solution came to me beforehand by analytical reasoning.
However, it is a very sad state of any product that issues like this can occur and I always want to trace back to the root cause also because of my own documentation mission in our software that we are describing with Flare.

To me this experience was another failure. How can it be, again, that I only want to start using a very simple feature but end up in a mess that no one could even answer here nor MadCap support...

I often like to present the situation in analogies. Just imagine, you have installed a new door knob but can't use it and have to wait 3 years instead

[Niels]

and this experience keeps repeating with MadCap Flare for me at least - the Murphy of Laws

recently we decided to use the new 2020 feature of syntax highlighting but wanted to change the font size, which is very simple according to the documentation. Guess what we encountered first! A new bug that in our situation we were not able to change the font size.

Luckily this is being handled and was accepted as a bug, yet now I am in a borderline kind of state.

My current experience with MadCap Flare is the following:

If you ever try any new 'action' for the first time, be prepared that it does not work as expected. For example, if I decided to turn the colour of a specific letter into red, do NOT expect that this works. You need a PoC and test carefully if this operation succeeds...

[doc_guy]

We just discovered that you can't use a code snippet (using Flare's native code snippet tool) in CHM files. And Flare doesn't tell you this. Instead, when you build, Flare presents you with this lovely error message:

Code: Select all

The node to be removed is not a child of this node

So, yes, It's amazing to me how often new features don't completely work. And we are stuck with a CHM, because one of our help targets is for our Windows Server product for a security application. And apparently, many of our customers won't let the Windows Servers have web browsers, at least on the servers our software is installed on. (At least that is what I'm told. Of course, I don't get to validate these kinds of things with actual customers.)