Sanity check -- Heading levels in Snippets don't follow TOC?

[Phlawm53]

I'm pretty sure I've already answered my own question, but want to sanity check this.

IF I create a Snippet, AND that Snippet has a heading of a certain level, THEN when Flare generates a print target (PDF in this case), the Snippet's heading level doesn't obey the setting "Using TOC depth for heading levels" option.

That is to say, that IF the Snippet begins with an H1, but the Snippet has been positioned in the TOC as an H2, THEN when Flare generates the content the Snippet appears as an H1-headed topic in the target; including a potentially unwanted preceding page break if so specified for the heading level.

The fix is of course obvious -- remove the heading from the Snippet so that the Snippet contains only the textual content below the heading. Everything works just fine…

But I wonder if this isn't a "bug". Or is there a logic to this behavior that makes what I've described "correct"?

Cheers & thanks,
Riley

[LTinker68]

IF I create a Snippet, AND that Snippet has a heading of a certain level, THEN when Flare generates a print target (PDF in this case), the Snippet's heading level doesn't obey the setting "Using TOC depth for heading levels" option.

No, I would expect it to follow the rules of that option. You can't reference a snippet directly into a TOC -- it has to be put into a topic. When Flare builds the output, it basically copies everything from the snippet into the topic then puts the topic in the output and it's during that process that the heading would change (if you had that option enabled and if the topic was inserted as a second-level topic instead of a top-level one, that is).

Are you saying that's not happening with a snippet that has a heading in it? Or you just wanted to figure out ahead of time if it would still work if you included the heading in the snippet?

BTW, I recommend against putting the heading into the snippet. The reasons being that if you use that snippet more than once, then A) it would have to be inserted at the same location (top) in all topics so the heading makes sense, and B) when users search your help they'll see two topics with the same heading, which could be confusing. Personally, I think it's better to not include the heading so that you have more flexibility on where you place the snippet in a topic and have more flexibility in what you type as the main heading for each topic.

[Phlawm53]

Are you saying that's not happening with a snippet that has a heading in it?

That's exactly what I'm saying. More specifically:

1. I created a Snippet that began with an H1 title for the content.

2. I created a topic file at TOC level 2, then inserted the snippet into that topic file.

3. I gen'ed a PDF target.

Flare built the topic as a Level 1 topic, including inserting the page break specified for my H1s.

As I said, I remedied the situation by putting the H1 in the topic file, removing the H1 from the snippet, and re-gen'ing. The topic now appears at the correct TOC level in the document, and demonstrates the correct page-break logic.

The current behavior isn't a big deal, just an observation that I wanted to sanity check. If that's how Flare is *expected* to work, so be it. But if others see it as a problem, then maybe -- only maybe -- it wants to be submitted as an enhancement or bug...(?)

Cheers, thanks, & hope this helps,
Riley

[LTinker68]

If that's how Flare is *expected* to work, so be it. But if others see it as a problem, then maybe -- only maybe -- it wants to be submitted as an enhancement or bug...(?)

Yeah, submit it as a bug at http://www.madcapsoftware.com/bugs/submit.aspx.

[ajpeck123]

Does anyone know if this ever got fixed?

I've got a snippet that in one manual should be at H3, and in another at H2. I created it with the title at H1, and that's where it went in the PDF - and its sibling sections (other h2 or h3, depending on manual) appeared to be subsections of it. Really broke the hierarchy.

Yes, I can put the heading on the main page (and I have) - but in this case, the heading is exactly the same each time, just at a different level.
This particular snippet is a small procedure, but I didn't want to put it as a separate topic for various reasons - not least because I've have to create multiple small topics for *each* manual to contain the sections above and below it in the TOC just so I could slot this particular bit of information in the right place. A simpler split into <top part> <snippet><bottom part> would also work but wouldn't be logical because <top part> and <bottom part> each contain multiple (small) subsections in their own right - and to split them ALL out for all manuals would be a fiddly bit of work.

Workaround possible, I know, but as I hadn't seen any more on this and it was raised a LONG time ago.

Alison