Mystery Image Insertion Using Attribute in Structured Element

Report · Jun 20, 2012

I'm working in FM10 on Windows XP Pro. However, the templates at the corporation where I'm currently contracting have been developed over the years, since FM 7 or 8, with different authors and developers tweaking them. That makes them difficult to decipher at times.

Currently, I'm trying to figure out how our notes elements works so I can fix it to work when linking the FM source files to RoboHelp. When you choose the parent element "Note," you can choose from four different attributes (as shown below from the EDD): note, tip, caution, and warning.

When you choose one of these attributes, it automatically inserts a graphic symbol (exclamation point, star, pencil, etc.). Then you choose the next child element, which creates a paragraph directly to the right of graphic symbol.

The problem is, I can't figure out where this graphic is coming from in the parent element and associated attributes. I thought it must be pulled in from the paragraph style, either as a frame from the reference page and or symbols from the numbering section of the paragraph designer. But I can't find either of those things anywhere. For what it's worth, the graphic symbols do look like they come from a font (see screenshot).

The word "note" comes in from the next child element and associated paragraph style, it is designated in the Numbering/Autonumber Format: box with an associated font. The lines above and below it similarly come from Advanced/Frame Above/Below Pgf: setting. All of that is pretty easy; the attribute image...not so much.

Can anyone please tell me where to hunt for the source of this attribute image insertion?

------------------------------------------------------

EDD

Element (Container): Note

General rule: NoteHead, NoteBody

Attribute list

Name: Id Unique ID Optional

Control flags: Read-only, Hidden

Name: Type Choice Optional

Choices: Note, Tip, Caution, Warning

Default: Note

Automatic insertions

Automatically insert child: NoteHead

Element (Container): NoteBody

General rule: Para, (Para | List)*

Automatic insertions

Automatically insert child: Para

Element (Container): NoteHead

General rule: <EMPTY>

Text format rules

If context is: * < ParagonGuide

If context is: Note[Type = "Note"]

Use paragraph format: Note.Icon

Else, if context is: Note[Type = "Caution"]

Use paragraph format: Note.Caution.Icon

Else, if context is: Note[Type = "Tip"]

Use paragraph format: Note.Tip.Icon

Else

Use paragraph format: Note

Prefix rules

If context is: * < ParagonGuide

If context is: Note[Type = "Warning"]

Prefix: Warnings not permitted in Paragon documents.

Text range.

Font properties

Color: Red

Else...

Report · Jun 21, 2012

We do something very similar to what your template does.

When you insert a Note element, the EDD automatically inserts a NoteHead element. Look at the definition of the NoteHead element. It is an empty container, so you do not and cannot enter anything into it. It is a paragraph whose paragraph format is determined by the value of the Type attribute in the Note element. The possible formats afre Note.Icon, Note.Caution.Icon, Note.Tip.Icon, or Note. So, look at the definitions of those paragraph formats.

My guess is that they are set to be in the headings column (that is, outside the text column). These paragraph formats are the ones adding the icon, probably from a frame above (look on the reference pages). Then the paragraph is set to align, probably at the top) of the next paragraph, which holds the text of the note. The word Note is added by the NoteBody element, which adds the word as a prefix.

Hope this helps,

Van

Report · Jun 21, 2012

Van:

I follow all of what you're saying and also thought for sure that the graphic was in Note.Icon, but I can't find it there. I checked the frame reference and auto-numbering possibilities in that paragraph style before I posted yesterday.

I went back now after reading your post, but I don't understand where the headings column that you referred to is in paragraph designer. If that is where it is? I found a topic about it in FM help and also located the headings table in the reference page, but that seems to be only section headings.

I wondered, would it be possible to share the FM file with you so you could take a quick glance? I've been at this impasse for a day and a half and can't proceed with my work until I unravel the mystery.

Also, I did find something else on the reference pages that I suspect might be contributing to this. There is a section there that talks about templates for Structure Tools autoinsertion, but I have never seen anything like this in a structured template. In this section, there are anchored frames that are supposed to be specific templates, one of which has the note icon (but none have the caution, warning, or tip, icons). I have no idea how this works, could not find it in FM help, which is why I thought maybe I could share a file with you? In the meantime, maybe the text from this section, written by one of the previous developer's, might lead to the solution:

This is the WS_AutoInsetions flow, where all templates for Structure Tools autoinsertion are stored. This flow can actually reside anywhere in the document, but this is the most logical place to store it.

In this flow, there are a set of anchored frames, each of which contains a single text frame. Each text frame contains a single autoinsertion template. To see the full details of each template, open the Structure View and click inside one of the frames. Because the templates are frequently just empty elements, there may not be much to see without the Structure View.

To create a new template, you should copy and paste one of the existing templates, then edit it. That is, copy the entire anchored frame and the paragraph containing it. This way, you’ll ensure that the general frame architecture required by the Structure Tools plugin remains intact. Anchored frames and the embedded text frames may be resized, but do so carefully and maintain the general scheme of embedding.

When you create a new template, it automatically becomes active for autoinsertion. You do not need to adjust any other settings. Remember that templates can include any valid content, including elements, text, and graphics.

As you can see, this flow supports the addition of comments. The only content that matters for autoinsertion is the templates inside the anchored frames. All other content is ignored and you can generally place anything here you want.

---------------------------

TEMPLATES

----------------------------

Here is the template for Note elements. When inserted, a Note element should initially contain NoteHead and NoteBody elements.

Report · Jun 22, 2012

I am not sure I can answer all your questions, but....

I went back now after reading your post, but I don't understand where the headings column that you referred to is in paragraph designer. If that is where it is? I found a topic about it in FM help and also located the headings table in the reference page, but that seems to be only section headings.

Sorry, but I did not have FrameMaker open when I wrote my response. So, I was not sure of the terminology. The correct term is "room for side heads". This is a property of the text frame. If you allow the text frame to have room for side heads, then some headings can be placed in the side head area (the left side of the frame) and align with the text on the right side of the frame. The side head are is NOT the same as a text frame column. I recall that another name for side head area is an author's column. You SHOULD be able to find information about side heads in the user manual.

I have little to answer about the rest of your post, namely the templates on the reference page. I have only used reference pages to create frames that hold graphics, which are then inserted into the main text using frame above/below settings. Apparently, one can create frames that hold some content (the basic structure of the template), which are then inserted (auto insertion?) into the main text flow by the writer. But I do not know how one inserts them into the main text (a text inset? but that does not sound correct, because a text inset is not editable where it is inserted). Again, try to read more about reference pages in the user manual. Maybe someone else might have more information about how this is working.

BUT the end result should be independent of how one does it. That is, ultimately, the EDD has to do the formatting. If it assigns paragraph formats, then those paragraph formats hold the clues. Any graphics are likely located somewhere on the reference pages.

Keep looking,

Van

Report · Jun 26, 2012

Thanks again all. I've looked in all the places mentioned and don't see the graphics produced in any of the suggested ways.

I can't spend anymore time looking for the cause and I've decided to move on; really creating new styles was the solution to my problem, anyway.

However, intellectually, the fact that I can't figure this out is bothering me. I want to understand what is going on...

Would anyone be willing to take a gander at my file so we could have closure on this thread for the future benefit everyone on the forum?

Report · Jun 27, 2012

I'll look at it. Please send it to

russ AT weststreetconsulting.com

BTW, I'd like to address you by name, but I don't know what it is

Russ

Report · Jun 28, 2012

Russ,

When you figure it out, please let us know.

Thanks,

Van

Report · Jun 28, 2012

My name is Douglas. Apologies, I usually at least sign off using it in the first entry of a forum post.

I'll be sending you the file in just a few minutes. It will be coming from a daimler dot com address, so be on the lookout.

I am hoping that this doesn't turn out to be user error, but I'd still like to know the answer, even if it is my own bumbling.

Thanks again, Russ.

Report · Jun 28, 2012

Hi Douglas,

I believe I have figured it out, although I can't prove it, but perhaps my inability to prove it is proof itself. I know that makes no sense, so please read on...

In summary, I believe the images are caused by textual prefixes inserted by the EDD for the <NoteHead> element, using the Zapfdingbats font.

To review/sum up the structural architecture, your notes consist of

<Note>

<Para> ... etc.

</NoteBody>

<Note>

...Where it is the <NoteHead> element that is containing the image, and the <Para>, etc. elements that contain the note text.

My first clue was that when I open your file, I don't see the images; however, instead of a missing images message, I get a missing fonts message (and I don't have Zapfdingbats). Here are the prefix rules for the <NoteHead> element (rough paste):

Prefix rules

If context is: * < ParagonGuide

If context is: Note[Type = "Warning"]

Prefix: Warnings not permitted in Paragon documents.

Text range.

Font properties

Color: Red

Else

Text range.

Else, if context is: * < (List | Procedure)

If context is: Note[Type = "Note"]

Prefix: \t/

Text range.

Font properties

Family: Zapfdingbats

Size: 22.0 pt

Offset vertical: 28.0%

Else, if context is: Note[Type = "Tip"]

Prefix: \tH

Text range.

Font properties

Family: Zapfdingbats

Size: 16.0 pt

Offset vertical: 22.0%

Else, if context is: Note[Type = "Caution"]

Prefix: \t!

Text range.

Font properties

Family: TheSansExtraBold-Plain

Size: 32.0 pt

Offset vertical: 48.0%

Else, if context is: Note[Type = "Warning"]

Prefix: \t6

Text range.

Font properties

Family: Zapfdingbats

Size: 16.0 pt

Offset vertical: 24.0%

Else

If context is: Note[Type = "Note"]

Prefix: /

Text range.

Font properties

Family: Zapfdingbats

Size: 22.0 pt

Offset vertical: 28.0%

Else, if context is: Note[Type = "Tip"]

Prefix: H

Text range.

Font properties

Family: Zapfdingbats

Size: 16.0 pt

Offset vertical: 22.0%

Else, if context is: Note[Type = "Caution"]

Prefix: !

Text range.

Font properties

Family: TheSansExtraBold-Plain

Size: 32.0 pt

Offset vertical: 48.0%

Else, if context is: Note[Type = "Warning"]

Prefix: 6

Text range.

Font properties

Family: Zapfdingbats

Size: 16.0 pt

Offset vertical: 24.0%

There are a whole bunch of text prefixes in there, but most are using the Zapfdingbats font. That font is just a bunch of little icons like the pencil image your screenshot shows. For example, the line:

Prefix: \t/

...will insert a tab, then a forward slash in Zapfdingbats. I bet if you apply Zapfdingbats to one of you paragraphs, then type a forward slash, you'll get one of those images that you've been seeing.

The proof would be to alter these characters in the prefix rules and see if the images change. Because I don't have the font, I can't do that. But because I can't do that, it proves to me that the source is indeed the font and those prefix characters. Make sense now?

Russ

Report · Jun 29, 2012

Russ is right.

In the prefix rules you have these definitions for prefixes:

note = \t/

tip = \tH

caution = \t!

warning = \t6

The "/t" is shorthand for a tab space. Then the Zapfdingbat fonts map out as follows, (almost) exactly as in the template:

/ = pencil icon

H = star

! = pen nib?! (doesn't map in Zapfdingbats because this prefix uses another font, SansExtraBold-Plain)

6 = X icon

Firslty, Thank you, Russ! And everyone else who contributed, of course.

Secondly, and lastly, a question: is setting up an element like this a best practice? Have you authored or seen templates authored in this style before? As I had mentioned, to me our EDD seems unecessarily long for what it does. Not sure if whoever did it was just clever, or too clever for their own good.

Many thanks again to all.

Douglas

Report · Jul 01, 2012

Douglas,

I believe that the use of attribute-based context rules for this type of formatting is indeed best practice. It really is a good example of allowing the computer to do work for you, based on a few simple choices of structural metadata. And, while a long EDD may not be good, it also may not be bad. If it is long because it is doing a large amount of automatic formatting that would otherwise be busywork for the author, then that length is good. I would say that length becomes a concern only if 1) maintenance becomes unmanageable or 2) FM performance is unacceptably compromised or 3) the structure and rules are so complex that it slows down authors, defeating a primary advantage of properly-designed structured content.

Now, whether the use of special fonts to generate images (versus actual graphics) is best practice, I don't really know. It seems to me that if you are sure that the font will be present on any computer where the files will be used, then that might be OK. Somehow, though, a dependency on weird fonts just to generate images seems a bit suboptimal... graphic files are readily portable, but fonts sometimes are not. I would have to defer to someone with more expertise on fonts to provide more insight. Certainly, it appears to work well in your current environment, so I think the question is more about portability, rather than operability, if portability is of any concern.

Russ

Report · Jun 21, 2012

I've continued to dig through this problem and I noticed that the reference page documentation that I included above mentions a plug-in called "Structured Tools," which I found googling:

http://www.weststreetconsulting.com/WSC_StructureTools.htm

Russ had mention that the mystery might be caused by a plug-in and this product talks about "Attribute auto-population and better defaults handling." Could this be the cause of the mystery? Can plug-ins create such functionality that can not later be edited without the plug-in?

Report · Jun 21, 2012

It's a bit of a coincidence that Structure Tools is my plugin, so I can answer these questions with some authority . Structure Tools can be used to automatically set attribute values during certain activities, among other features related to the enhancement of attribute management. However, it doesn't have any freaky functionality that would cause that image to appear, at least without any other explanation. If Structure Tools was used to render that image, it would only be indirectly, perhaps used to set an attribute which the EDD subsequently used to control formatting.

Plugins can do some quirky stuff, but in general they don't do anything you couldn't undo afterwards. And for sure, Structure Tools doesn't have any functionality directly related to image rendering.

Russ

Report · Jun 21, 2012

FWIW, it seems to me that an autoinsertion has to come from one of three places:

- A graphic on the reference page, applied by the template paragraph format -OR- applied by a paragraph format override in the EDD.

- Autonumber text, applied by the template paragraph format -OR- applied by a paragraph format override in the EDD

- An EDD-applied prefex, as defined by the <Prefix> element.

You imply that you have looked in these areas, but I would think that maybe you need to look again. Unless I'm wrong (or you have some kind of wierd plugin running), it has to be in there somewhere.

Russ