Snippet formatting in tables

[spinningrachel]

Hi all.

I'm new to Flare …

I created snippets for terms that repeat themselves in several topics. For one snippet I didn't have the information, so I created it with one word inside, inserted it in all the relevant topics and then intended to go back and update later. These snippets mostly appear in tables.

This morning I updated it with the correct content, and included in it a bulleted list.

Much to my dismay, the content did update correctly, but the formatting did not. Fortunately, for now, the snippet only appeared in two topics, so I opened them both, deleted the snippets and re-inserted. The formatting then showed up correctly.

Obviously this is not much of a solution if I have more than two topics that share the snippet.

Any suggestions?

Thanks,
Rachel

[NorthEast]

What sort of formatting are you talking about - something like a paragraph style, or inline formatting?

I'm guessing it's to do with how you inserted the snippet - you can insert them as text or block snippets.

For example, say you have a snippet that includes a paragraph style like p.note. If you insert the snippet in the middle of an existing paragraph, then it'll be inserted as a text snippet, so only the text is inserted and the p.note style won't be applied. If you insert the same snippet on a blank line, it'll be inserted as a block snippet, which will include the p.note style.

See the help here: http://webhelp.madcapsoftware.com/flare ... ippets.htm

[spinningrachel]

I'll give it a try. Thank you!!

[Nita Beck]

Ha ha! I responded to your same question on LinkedIn (http://linkd.in/1ij85ri). Dave and I gave essentially the same answer, even with the same link.

[spinningrachel]

Hi guys. The Help isn't really helping me.

I checked out your advice and this is where I am: it is true that inside the tables, like anywhere else, the snippet keeps it's own formatting if it's a block snippet.

BUT I can't seem to figure HOW to insert it as a BLOCK on the first try inside a table.

These are my steps to create the snippet:
1. Write the text in the table cell in the p class. When I try to create it in the td instead of adding the p class, the Create Snippet is disabled.
2. Select the text and click Create Snippet.
3. Allow the selected text to be replaced with the snippet.
4. Delete the snippet from the table.
5. Delete the p from the table.
6. Stand in the td and Insert Snippet.

This is the only way it's working. Any suggestions?

[Nita Beck]

When I get a chance today, I'll try your steps and see what I can figure out.

[spinningrachel]

Great. Looking forward to hearing from you!

[Nita Beck]

It seems to me that MadCap just hasn't programmed Flare to allow one to create a snippet from content entered within a table cell that is not further wrapped in a p block (or other block; I didn't test further). That's why you had to invent a workaround.

A quicker workaround might be this:

1. Enter the text OUTSIDE of the table so that you can use the Create Snippet feature. Replace the text with the snippet.
2. Right-click the snippet block and select Cut.
3. Position the cursor in the td and paste the snippet.

This is the best that I can think of.

[spinningrachel]

Thanks for checking it out and for the help!

[LTinker68]

It seems to me that MadCap just hasn't programmed Flare to allow one to create a snippet from content entered within a table cell that is not further wrapped in a p block (or other block; I didn't test further).

Actually, that kind of makes sense. A <td> tag can't exist outside of a <tr> tag which can't exist outside of a <table> tag. A <p>, div, blockquote, etc., can exist by itself or be inserted in a table, which is why a snippet's contents should at least be inside of some type of single-level container tag (i.e., one that doesn't require a parent tag). You'd probably have the same problem trying to create a snippet from an <li> tag, since it would require a <ul> or <ol> parent tag.

(Single-level tag is my term.)

[Nita Beck]

Thanks, Lisa, for your always-spot-on insights.

[Phlawm53]

------
By the by, is there a recommended way to convert a Snippet from Text to Block or vice versa?

I'm not sure if this is a real basis for concern for anyone else, but I find myself worrying that Snippets might have internal characteristics that surprise an unwitting maintenance writer working on an existing project…(?)

In an attempt to better understand the differences between the two types of Snippet, I performed a few experiments with single-line Snippets wherein I inserted a Snippet of a particular type in the "wrong" context to see what happens. The results seem a bit ambiguous, at least for single-line Snippets. So in the back of my mind is that concern that an innocent appearing Snippet of the "wrong type" may become a sort of booby trap that goes off in response to one or another change to the content that surrounds it(?)

In the meantime, I've figured out a couple of clumsy ways to convert a Snippet from one type to another:

• One way involves simply copying a particular sort of Snippet's text and recreating it such that Flare structures the new instance as the desired type.
• A second approach is to go spelunking in the Snippet's XHTML with a text editor and figuring out how to restructure the XHTML tagging.

I consider both of these methods to be circumventions rather than true solutions. The second method, using a text editor, also presumes that one knows the rules for converting one type of Snippet (Text or Block) to another.

I also submitted an Enhancement Request to Madcap asking them to expand the documentation about converting one type of Snippet to another.

Again, I admit I may be overthinking this. On the other hand, if Snippets can be one of two types, and the Snippet's type may not be readily apparent to a writer not in on the secret, might Snippet typing lead to unwanted surprises…(?)

Cheers & thanks,
Riley
SFO

[LTinker68]

It's not a matter of converting it, it's more a knowing of which version Flare will insert, which depends entirely on where the cursor is when you insert the snippet.

If the cursor is in an empty tag with absolutely no other content, then when you insert the snippet, it's inserted as a snippetBlock.

If the cursor is in a tag containing other content (can't remember if a single blank space is enough content, or if it needs at least a single character), then when you insert the snippet, it's inserted as snippetText and inherits the formatting of that parent tag. For example, if you have a paragraph with text that says "Hello, world" and the cursor is in the space following "word", then it inserts the snippet as snippetText.

I don't have Flare open at the moment to test it, but if I recall correctly, when you insert a snippet into a child tag (e.g., insert it in an <li> tag that's child to an <ol> tag), then I think it inserts it as snippetText. I might be remembering that incorrectly, and inserting a snippet into a child tag is no different from the two situations above.

[Nita Beck]

Riley, your question about maintenance of snippets is a good one.

I know that there have been times when I've edited a snippet that had been just one p block so that now it had more than that one, or perhaps I put a list or a table after the p block. Unless I looked at the snippet within the context of a topic that used it as snippet text, I would not have noticed that the formatting of the snippet now looked all wonky. Therefore, my best practices are these: I either open the snippet from within the topic, so that I know how I've used it OR if I plan to edit the snippet by selecting it from the Content Explorer, I make sure that I "view links" to see where it's used. There have been times when I've needed to adjust how the snippet was being used (text vs. block) so that the formatting would be correct.

I also know that it would be very easy for a less experienced Flare user to not think about any of this, but to just edit the snippets without validating how they were being used. So if you bring in other authors to share authoring of your Flare project, or if you're handing a Flare project off to someone else (e.g., a client) for upkeep, I think it's important to discuss best practices for the maintenance of snippets.

Sorry for being long-winded. I'm thinking out loud...

[Phlawm53]

Thanks Lisa and Nita.

I don't want to overthink the issue — really I don't.

But if Snippets have attributes (they currently have two, Block or Text), and a Snippet's Block / Text attribute affects how it behaves (it evidently does), then is not there the potential for something to get muddled?

At this point I'm simply thinking through the possible consequences of someone using the "wrong type" of Snippet on the assumption that Snippets are "one size fits all" interchangeable parts. That is, IF Snippet attribute problems manifest themselves in my project's output, THEN do Snippets now become an additional "make sure there are no errors" thing to check when someone is rushing to meet a content delivery deadline?

I admit that I may be imagining Snippet goblins where none exist.

That said, does anyone else think there would be any benefit in Flare's XML editor doing some sort of Snippet attribute checking when Snippets are inserted? If a Snippet of a particular type is inserted in the wrong context, perhaps a message explaining the issue to the user would help minimize if not eliminate Snippet-type problems…?

I also think that, per my aforementioned enhancement request, the Flare documentation needs to more fully explain what happens when a Snippet of one type is mistakenly inserted in the wrong context(?)

But that's just me trying to, if you will, "drive defensively"…

Cheers, thanks 'gain, & hope this helps,
Riley
SFO

[docudramaqueen]

Here's my two cents. Ultimately, for me, the difference is simply (as described in Flare's help topic) whether the snippet stands alone (in its own paragraph, etc.) or whether it is a short phrase that appears in line with other text.

And, as Nita says, what Flare defaults to depends entirely on where you have your cursor located. On the occasion that I've accidentally created a text snippet rather than the desired block (the opposite has never occurred, so far as I can remember), I've simply replaced the word "text" with the word "block" in the text editor.

My biggest frustration with snippets has been the inability to plug one into an OL or UL. I don't know if manually converting a snippet with several separate lines (say several steps in a procedure) from a block to text snippet would solve that issue (having never thought of it until reading this thread), but am about to go test it.

My end goal would be the ability to create a snippet with multiple steps that I know I'd always use as part of an OL or UL, format the snippet that way, and then, when I insert the snippet, it would "read" where it is in the target list, and adjust its numbers (bullets, whatever - though numbers seem the trickier by far) to fit, AND allow me to continue the list. It might be that this aspect of it would have to be manually worked by creating the "next" step, then going back one step and inserting the snippet. My gray matter has stored some vague memory of submitting a feature request for this, but vague is vague.

I'll report back on the results. Anybody else run up against this?

Henry

[ChoccieMuffin]

I have nothing useful to add to the discussion, other than my amusement at the mental picture of all the little snippet goblins cavorting around my computer, dancing a merry jig with the Flare imps that mischievously swap things round in my XML code when I'm not looking.

[NorthEast]

My biggest frustration with snippets has been the inability to plug one into an OL or UL. I don't know if manually converting a snippet with several separate lines (say several steps in a procedure) from a block to text snippet would solve that issue (having never thought of it until reading this thread), but am about to go test it.

My end goal would be the ability to create a snippet with multiple steps that I know I'd always use as part of an OL or UL, format the snippet that way, and then, when I insert the snippet, it would "read" where it is in the target list, and adjust its numbers (bullets, whatever - though numbers seem the trickier by far) to fit, AND allow me to continue the list. It might be that this aspect of it would have to be manually worked by creating the "next" step, then going back one step and inserting the snippet. My gray matter has stored some vague memory of submitting a feature request for this, but vague is vague.

I'll report back on the results. Anybody else run up against this?

Create the snippet so it includes the whole ol/ul tag (not just the li tags), and place it before/after the list section it will be 'joined' with (i.e. before/after the ol/ul tag in the topic).

If the snippet section always needs to continue the list numbering, then set the snippet list section to Continue sequence.

You can use CSS to automatically control the snippet list style according to the level in the list where it's been inserted; see http://forums.madcapsoftware.com/viewto ... 83&start=0


The snippet won't look correct in the XML editor, but numbering and styles will be ok in the preview and output.

[Chris B]

I too have experienced some funky formatting issues with Snippets. Sometimes the formatting would work and sometimes the formatting was absent. This thread and related links cleared things up and I now understand why Snippets were behaving badly for me.

I'm wondering if you were to create the formatted snippet text inside a <Div> and create a snippet if that would mitigate potential formatting issues. Basically is Flare smart enough to recognize that since the snippet is from <div> to </div> that the snippet is a block and will therefore always be inserted as a snippetblock ensuring proper formatting wherever it is placed?