PDF output gotchas?

[Centauri27]

I'm taking the big plunge and am attempting to output directly to PDF. I've been told by MadCap that refining their PDF output is their primary focus and I've grown tired of the Word limitations. But as I experiment, I've discovered a host of issues that worked in Word...but not in PDF! Has anyone experienced these issues?

Issue 1: Images aren't resized to fit text boundaries.

The style used for the screen shots have "max-width" set to 4 inches, to ensure that all screens fit within the text boundaries. The Word output dutifully resizes all the bigger screen shots to conform, but the PDF seemingly ignores this setting, allowing large images to flow right off the page.

Issue 2: List style allows page break after.

I use an unordered list style to introduce numbered procedure steps. I outdent the unordered list and use an arrow graphic to set off the procedure. To prevent awkward page breaks, I've set "page-break-after" to "Avoid". Word observes this setting, but PDF seems to ignore it: many page breaks occur right after this list intro.

Issue 3: TOC ignores negative indents.

My user manual uses a wide left margin. First level headings and their corresponding TOC entry is outdented by 1 inch. I have set "text-indent" to -1 inch. The Word output reflects this negative indent, but it is ignored in PDF.

Issue 4: Bold text not appearing in PDF.

My body text is Franklin Gothic Book, while the tables are Arial. Bolded Arial text displays correctly in the PDF, while bolded Franklin Gothic Book is ignored--just appears as plain text. Both bolding worked in Word. Is there a way to embed the fonts used in the PDF output?

There are other issues, but these are my most pressing ones. Can anyone share their own PDF gotchas? I'm told by MadCap that Flare 6 will have beefed up PDF capabilities. I just hope I can hold out for that long.

Thanks.
Carl Lum

[LTinker68]

Issue 1: Images aren't resized to fit text boundaries.

I could be mistaken, but I'm pretty sure that worked for me. Is that max-width defined in the print medium or in the default medium (and therefore being inherited by the print medium)? And did you set the max-width on the img tag or the paragraph tag containing the img tag?

Issue 2: List style allows page break after.

Is the page-break-after set on the li tag or on the ul tag?

Issue 3: TOC ignores negative indents.

Don't use text-indent -- set the margin-left for that p.TOC1 or whatever to -1in.

Issue 4: Bold text not appearing in PDF.

My body text is Franklin Gothic Book, while the tables are Arial. Bolded Arial text displays correctly in the PDF, while bolded Franklin Gothic Book is ignored--just appears as plain text.

Not sure about this one. I'd submit a bug, but there is a workaround. Create a span class, call it something like boldedText, and set it to use Franklin Gothic Heavy instead of Franklin Gothic Book. Select the text you want to bold and apply that span class. When you build the PDF output it'll appear bolded (well, heavy, but similar appearance). Or you could use Medium, but that may not appear bold enough for what you want.

[Centauri27]

I could be mistaken, but I'm pretty sure that worked for me. Is that max-width defined in the print medium or in the default medium (and therefore being inherited by the print medium)? And did you set the max-width on the img tag or the paragraph tag containing the img tag?

The max-width is defined only for the print medium, for the paragraph tag. I tried applying it to the img tag as well, with no effect.

Is the page-break-after set on the li tag or on the ul tag?

The page-break-after is set on the li tag. I don't want to put it in the ul tag because then it would affect all my other bulleted lists.

Don't use text-indent -- set the margin-left for that p.TOC1 or whatever to -1in.

Putting the negative indent in margin-left has no effect either. BTW: The content is added by the TOC Proxy--does that make a difference?

Not sure about this one. I'd submit a bug, but there is a workaround. Create a span class, call it something like boldedText, and set it to use Franklin Gothic Heavy instead of Franklin Gothic Book. Select the text you want to bold and apply that span class. When you build the PDF output it'll appear bolded (well, heavy, but similar appearance). Or you could use Medium, but that may not appear bold enough for what you want.

Yes, that would work. But then it would require me to go back and reapply that span class to all existing bolded text. That's a last resort I'll keep in my back pocket.

Thank you for the suggestions, Lisa. It's too bad that none of them worked. I guess I have to keep hunting.

Carl

[KevinDAmery]

Is the page-break-after set on the li tag or on the ul tag?

The page-break-after is set on the li tag. I don't want to put it in the ul tag because then it would affect all my other bulleted lists.

You mentioned that you're using a custom LI style. I think the solution would be to instead use a custom UL style to do the same job. The UL will probably handle the page break better, and by using a custom style you avoid applying it to every other list.

Basically, what you need to do is change the class from being an LI class to a UL class, then apply that class to the appropriate lists.

[LTinker68]

Don't use text-indent -- set the margin-left for that p.TOC1 or whatever to -1in.

Putting the negative indent in margin-left has no effect either. BTW: The content is added by the TOC Proxy--does that make a difference?

Then how about doing the reverse. Create a new page layout for just the generated TOC, assuming you're not already doing that. Position the left edge of its body frame to where you want the p.TOC1 to appear and set the margin-left for the p.TOC1 to 0. For p.TOC2, set its margin-left to 1in, set p.TOC3 to 1.5in, or however you want your headings positioned.

BTW, did you enable the option to have the TOC structure use the headings to determine the structure of the TOC? If you did, then I believe it automatically indents p.TOC2, p.TOC3, etc. Or maybe if it's disabled then it does that. Don't have Flare running at the moment. You might try it with that field enabled or disabled to see if that has any affect on the positioning of the TOC items.

[Centauri27]

You mentioned that you're using a custom LI style. I think the solution would be to instead use a custom UL style to do the same job. The UL will probably handle the page break better, and by using a custom style you avoid applying it to every other list.

Thanks for the suggestion, Kevin. But unfortunately, a custom ul tag handles the page break no better than the li tag: the page-break-after 'Avoid' is still ignored. Plus, using the ul tag causes Flare to ignore my custom bullet and all other bulleted list characteristics. (I guess that's because the custom bullet is defined under the "List" property, and if you're not using the li tag, Flare assumes you're not working with a list?)

As a workaround, I'm going to convert all those paragraphs back to the p class, give it a negative margin and then manually insert the bullet image. At least the page breaks work correctly for the p class.

Carl

[LTinker68]

As a workaround, I'm going to convert all those paragraphs back to the p class, give it a negative margin and then manually insert the bullet image. At least the page breaks work correctly for the p class.

You don't need to manually insert the bullet image. If it's the same image for each line item, then you can insert the image as a background image with no repeat set, and use padding to separate the text from the background image. See this post for details --> http://forums.madcapsoftware.com/viewto ... 68&p=48690

[Andrew]

Issue 1: Images aren't resized to fit text boundaries.

The style used for the screen shots have "max-width" set to 4 inches, to ensure that all screens fit within the text boundaries. The Word output dutifully resizes all the bigger screen shots to conform, but the PDF seemingly ignores this setting, allowing large images to flow right off the page.

This happens to me sometimes when a stylesheet is not applied to a TOC page that doesn't have a page layout applied to it (or the wrong page layout); it's some kind of bug in Flare, but not one I've been able to reliably reproduce. Try assigning a page layout to that topic in the TOC and see if that fixes it. However, the max-width setting definitely works in PDF (aside from when I encounter this bug).

Issue 2: List style allows page break after.

I use an unordered list style to introduce numbered procedure steps. I outdent the unordered list and use an arrow graphic to set off the procedure. To prevent awkward page breaks, I've set "page-break-after" to "Avoid". Word observes this setting, but PDF seems to ignore it: many page breaks occur right after this list intro.

This has been a problem with Flare since it produced PDF output: it doesn't properly respect page-break-after: avoid or page-break-before: avoid in all cases. There are a bunch of workarounds people have come up with regarding divs, if memory serves...if you search the forum for page-break-after (or page-break-before) you can probably find them.

I don't have any experience with the other two issues you mentioned...sorry.

[Centauri27]

After working with MadCap Tech Support and re-trying everyone's suggestions (thanks, Lisa, Kevin, and Andrew), I'm happy to say that I've almost solved all my issues. I'd like to share my solutions here; hopefully it'll save someone else some agony. I was really skeptical initially about going direct to PDF for a project of my size (several hundred topics; resulting PDF nearly 700 pages). But I think I almost have it licked.

Issue 1: Images fitting into text boundaries. Turns out that modifying the <img> tag (rather than the custom <p> tag) did the trick. Don't know why it didn't work initially.

Issue 2: List style allows page break after. It was discovered that all the problematic breaks occurred only in instances where the list style immediately follows an <h1> heading. Seems the "page-break-after-avoid" of the <h1> was overriding the list "avoid break" attribute. For some reason, Flare just would not push the <h1> onto the new page. I finally solved this by creating a new custom <ul> class with "avoid" for BOTH page-break-before and page-break-after. Don't know why both were required, but now the problematic breaks have been resolved.

Issue 3: TOC ignores negative indents. This was tricky--turns out I had to set a negative indent for the output TOC proxy, not for the TOC styles. After giving the proxy the largest negative indent I need, I simply used positive indents to push over all the other TOC entries as necessary.

Issue 4: Bold not appear in PDF. This is a confirmed bug in Flare. Seems Flares plays nice with OpenType fonts, but not with Postscript fonts. Hopefully this will be fixed in a future version of Flare.

Here is a bonus gotcha I'd like to share:

There are many tables in my project, with some being quite lengthy (>1 page). I have a caption at the top of the table. The caption is a custom <p> class, not the <caption> class. The <p> style has "page-break-after-avoid". When I was outputting to Word, I discovered that adding the caption to the table itself caused extraneous blank paragraphs to be created before the table, but placing the caption as a standalone paragraph before the table didn't. So I went through all my tables and moved the captions out of the table.

When I switched to outputting to PDF, I discovered (to my dismay) that captions before the table caused Flare to (apparently) "ripple" (for lack of a better term) the "page-break-after-avoid" attribute across all the rows! In other words, there's plenty of space on a page to put half the table on it before it's forced to break. But what was happening was that the entire table was being shoved to the next page, leaving an ugly half page gap on the previous page! I then discovered that captions inside of the table does not cause this problem! So I must go through my 100+ tables and move all the captions back.... <sigh>

[LTinker68]

So I must go through my 100+ tables and move all the captions back.... <sigh>

You might be able to have it one way for Word output and one way for PDF output, if you have to produce both types of output. Add a caption to one of the tables for the PDF output and leave the one outside the table for the Word output. Create condition types for Word output and PDF output. Apply the Word condition to the caption outside the table and save the topic. Open the topic in the Internal Text Editor and copy the conditional tag from the outside caption and paste it into the caption tag that's inside the table, then change the condition tag to be the one for the PDF output. I don't think there's a way to apply a condition tag to a caption inside the table, but if there is, you can apply the condition tag directly from the GUI instead of going into the page code. Anyway, what you're doing is applying a conditional tag to each caption, so the Word version uses one caption in one location and the PDF output uses the other caption. You'll have to modify the two targets so the Word output includes the Word condition and excludes the PDF condition and vice versa.

Try that with one table first and see if it works for both outputs. It's a bit more work, but if you want to have both outputs appear correctly, then it's a workaround you can use until MadCap fixes the bug(s).

[Centauri27]

You might be able to have it one way for Word output and one way for PDF output, if you have to produce both types of output.

Fortunately, once I get the PDF version perfected, I can dispense with the Word output once and for all. It's a lot of work whipping the Flare topics into shape, but it will save me much time and headache in the future (single click 700-page PDF user manual--I thought that was impossible ). So short term pain for long term pain I guess.

Carl

[forfear]

That's what we've done in some cases as well.

[Jessa]

Something I didn't see in the list that I have noticed is that bookmarks in Flare (the kind that are created whenever you create a hyperlink or cross-reference) are showing up as bookmarks in the left column of the PDF. This is very annoying. Is it supposed to work this way? Meaning, do we just have to live with it and clean up the PDF afterward OR is there a setting on some screen in the PDF Target that fixes this?

Thanks!

[pdenchfield]

In version 5, Flare targets have an option for including or excluding these non-TOC bookmarks. In the Basic tab of the target, there is an "Options" button to the right of the "Output Type" list. This button is grayed out unless PDF is selected for the output type. Click the "Options" button and then clear the check box for "Include non-TOC bookmarks in the bookmarks pane."

If you have an earlier version of Flare, I think you're limited to cleaning these up afterwards.

Hope this helps!
Pamela

[ccardimon]

One of the many reasons I love Flare 5, and look forward to even more improvements in the future.

[Jessa]

Thank you, Pam!
That works great!!