Skip to main content
T
Trevor-Nicholls
Inspiring
May 4, 2023
Answered

XML comments in Structured Frame 17, how to manage

  • May 4, 2023
  • 2 replies
  • 1139 views

After checking in both the Structured Frame reference and user guides, I got the impression that the default handling of comments would be adequate for my needs, and it would not be necessary to create additional import/export rules (such as I already have for cross references). This does not seem to be the case.

I have an XML document which is conformant with my XML schema and with the associated EDD. I added an XML comment in the middle of the file with a text editor:

<!-- this is a test comment -->

and loaded the file into FrameMaker. There is a pre-processing XSL script - which copies comments through - and a post-processing script which does likewise.

Viewing the document in FrameMaker I could not see the comment in either the structure view or the document view, and if I ran Find looking for markers it did not find any comments.

I inserted a marker, type comment, with marker text "this is a Frame comment", and created it. I also made a separate edit to the document content so I could verify that the document had been saved with my changes. I could not see any indication that I had added a comment, and another Find > Marker still did not find any comments 

Then I saved the document: it had my text edit, it retained my original comment, it did not have the Frame comment.

I would appreciate some guidance on (a) how to see the incoming XML comments in FrameMaker (b) how to add similar comments in the Frame session and have them saved in the XML document on exit.

It's possible that I missed something crucial in the developers guide, but I have checked again and come to the same conclusion as before.

Cheers, T

This topic has been closed for replies.
Correct answer frameexpert

Choose View > Pods > Markers to see the Markers Pod (Panel in FrameMaker 2020 or above). When you click on a Marker in the Pod, it will scroll the document to the Marker location. This is about the best you can do.

2 replies

L
Lynne A. Price
Inspiring
May 9, 2023

   Another approach is to represent the comments in FrameMaker as elements instead of markers. Since you are using XSLT already, it should be trivial to change comments to elements when you open an XML document and to change those elements back to comments when you save a FrameMaker document as XML. You can format such comments as you prefer, adding a prefix such as "Comment:", changing color, making them text ranges within a paragraph, or using a unique paragraph format if they fall between paragraphs.

   Users can choose whether to hide or show the comments. If the syntax of the comments identifies categories such as the author of the comment, version of the document or whatever it describes, or date the comment was written, users can selectively display some but not all comments.

   These options come with Filter by Attribute, which allows a document to:

1. Show or hide an element, assign a color, or assign a condition tag based on the values of one or more of its attributes

2. Change the settings based on an applicable attribute expression

   As its name implies, this feature does require an attribute to be defined. If you don't need the attribute except to use Filter by Attribute, you can define an attribute which could be called, say, CommentDisplay, which is a choice attribute with one possible value, perhaps also called CommentDisplay. Make the attribute optional with the only possible value the default. And make it Hidden so that users never need to see it.

   Then in the template use View > Filter by Attribute. This dialog box supports two functions: editing filter expressions and applying one of the defined filter expressions. As the maintainer of the template, you would edit the filter expressions. In the simple case where you want either to show all comments or hide them all, you would define two expressions. For example, you might define an expression called Show to show them all and one called Hide to hide them all. Users can then use the same dialog box to choose one of the two expressions.

       --Lynne

    T
    Trevor-NichollsAuthor
    Inspiring
    May 9, 2023

    Hi

    Thank you for this. As you suggest, I am already folding the comments to an element (authornote) on load, and turning them back into comments on save. The comments are displayed rather prominently for my liking but could not possibly be mistaken for normal document flow 🙂

    I'd have liked to put them in a box in the margin but that exceeded my capabilities.

    Depending on the reaction of the technical authors, I expected to have to return to this question to find out if there was any way of making the comments appear and disappear. You have nicely pre-empted that, so thank you again!

    L
    Lynne A. Price
    Inspiring
    May 9, 2023

    A box is a table with one row and one column. If you are not using sideheads, you could put that table in a sidehead. If you are using sideheads, you could put it in an anchored frame, but the programming is more complicated. You could use XSLT to create a MIF file. You could use the FDK during import to move the table into the anchored frame. Or script moving an imported table into an anchored frame.

      frameexpert
      Community Expert
      frameexpertCommunity Expert
      Community Expert
      May 4, 2023

      One possibility that I haven't tested: In your import XSL, you could transform your comments into processing-instructions that will create a FrameMaker marker. Here is an example processing-instruction that will create a Comment marker:

       

      <?FM MARKER [Comment] This is the comment?>

       

      The markers will NOT show in the Structure View but because they are saved as processing-instructions, they should survive on input/output. You can transform them into XML comments with your export XSL transform.

      T
      Trevor-NichollsAuthor
      Inspiring
      May 4, 2023

      Thank you frameexpert, whoever you are, you have solved half of the problem (what I thought would be the trickier half).

      So I can turn xml comments into PI's, and I have successfully turned an inserted comment marker back into an xml comment, and everything roundtrips.

      However... the main point of these comments is so that the technical author will see them when they are editing, and at the moment they are just invisible. Is there a way to expose them to the edit session?

      cheers, T

      frameexpert
      Community Expert
      frameexpertCommunity ExpertCorrect answer
      Community Expert
      May 4, 2023

      Choose View > Pods > Markers to see the Markers Pod (Panel in FrameMaker 2020 or above). When you click on a Marker in the Pod, it will scroll the document to the Marker location. This is about the best you can do.

      Terms & ConditionsAccessibility statement
      Using the community Terms of use Privacy Cookie preferences Do not sell or share my personal information ad choicesAdChoices