MadCap Software Forums

In a previous life, I used FrameMaker and WebWorks to single-source PDF and HTML from Frame docs. Webworks allowed you to automatically break up a single .fm file into multiple HTML files based on heading level. For example, you could instruct Webworks to break up each chapter at the h2 level, such that a separate file was created for each h2 "topic" in the chapter. This was an extremely efficient and simple method to single source HTML and PDF from the Frame source. All I ever had to do was edit the Frame source. Everything else was automatic.

I want to do the same in Flare. I created a PDF template in which I create old-school books with chapters that contain h1 to h4 headings. As before, I want to automatically break each "chapter" into a series of "topics" at the h2 level for the HTML output. So, I attempted to use the auto-generate feature in the TOC editor to do this. The outcome was NOT as expected. Instead of automatically generating a Flare TOC that contains the h2 topics, the Flare TOC remains untouched, with just the original listing of the chapter titles. All the "auto-TOC feature" seems to do is define the heading levels contained in the HTML TOC in the output. Rather than generating multiple topic files per chapter, you still get only one file per chapter.

The output HTML TOC lists the h2 topic headings and clicking on one of these h2 entries simply causes the browser to scroll to the h2 topic heading in the file. This is almost identical to PDF output, which makes the autogenerate TOC feaure pretty much useless.

Is there any way to do this in Flare, or am I stuck manually regenerating my TOC in the TOC editor and creating separate files for each topic?

The one thing I really hate about Flare is the need to manually create TOCs. Why do I need to do this even though I have perfectly good TOC in the structure of my content (isn't that what h1, h2, h3 etc are for?). It's time consuming, error prone, and requires verification of the output, not to mention the mind-bending numbness of comparing the contents of the TOC Editor and Content Explorer to ensure that all of the content is in included in the output, and is in the right place. Also, having to specify the behavior of each little topic file (of which there are many) in the TOC properties dialog is a complete waste of time. There should be some default where this is derived from the structure of the TOC.

Someone will reply shortly, telling you that you have simply misunderstood, due to the pre-conceptions you brought from the Frame - WebWorks flow, and telling you how to do what you want in Flare in two simple steps.

For PDF target files, there are a couple of options that you might want to investigate:

- Generate multiple documents for native XPS/PDF output:
From the help file: "If you are generating PDF output directly (rather than going through FrameMaker or Microsoft Word to produce it), you can split the generated output into multiple documents, rather than using the default, which results in only one document. To create multiple PDF documents, you must also specify chapter breaks at the appropriate places in the TOC (not the TOC that displays in the PDF output, but in the "outline TOC" used to determine the printed manual content and structure). This can be done on the Printed Output tab of the TOC Properties dialog. By specifying chapter breaks, you are letting Flare know where you want to split the output into new PDF documents. Then in the Advanced tab of the Target Editor, select the "Generate multiple documents for native XPS/PDF output" option."

- Use TOC depth for heading levels: To use this option, you'd want to change all headings in your content to H1, then the depth of the TOC entry will dictate the heading that's applied in the generated PDF. http://webhelp.madcapsoftware.com/flare ... Levels.htm

So far - several years - I have been creating content in the form of individual Help topics, within Flare. There has been little need for output other than WebHelp.
Now, I might want to author White Papers and quick-start-guides and other monolithic documents, intended for output as PDF or other single-file outputs.
So, LesNoiz' query caught my attention. The answer, above, assumes a different flow than mine, and probably different than Les' as well.

For me, the starting point would be a single big document, authored in Flare. Then, months or years later, I might want to convert such a source document to a bunch of separate html topics all held together by a ToC (perhaps to import into some existing WebHelp, etc.) I would not create a new ToC for that purpose, because the document already has H1 and H2 headings, so it should be automatic to generate a help-ish ToC from them, and to split the document in separate topics at each H1 or H2 (creating the filenames by replacing the spaces in each H1 heading with underscores).

As a seprate motivator, I don't want to author in Word. Everybody here has that, and thinks it gives them license to tinker with my stuff.
Without paying for a license, they feel less free to tinker with project source in Flare.

In summary:
Often I want to create topics for direct use in webhelp and perhaps later generate a PDF version... or not.
BUT equally as often, I need to START with a non-help document, like a white paper or quick-start-guide, and only later might I decide to turn that into multiple webhelp topics or whatever.
LesNoiz can say whether or not we appear to have similar aims.

-k

Yeah, in the last few years I've converted all our FrameMaker manuals and InDesign QSGs to Flare. When we converted, the main goal was to single-source content in order to save time and reduce translation costs. When developing the Flare projects, I've taken the approach of assuming that at a moment's notice we may need to generate the same content into another medium - and with translation costs being a consideration - we need to do this with as few (if any) modifications to the content as possible. As we develop new content, we just ensure that it works for all outputs.

A few of the methods we've used to do this:
- Use a single stylesheet with the various mediums defined (manual, QSG, onlinehelp, etc.)
- Create modular topics.
- Each topic contains a heading.
- (Recent addition) Each topic heading is an H1 and we enable the "Use TOC depth for heading levels" option in the PDF targets. This allows us to have much more flexibility when creating one-off PDFs that are a subset of our larger help file, without having to manually adjust any heading levels.
- Using the TOC to specify page breaks rather than using styles with page-break attributes.
- Inject headings for unlinked TOC entries. This accomodates the scenario where we have a heading directly followed by another heading.
- Create "print-only" and "web-only" conditional tags for elements that are specific to these output types.
- Because the topics are modular, they may not contain a lot of text and can look odd in web outputs, so we created a master page with a breadcrumbs proxy and mini-TOC proxy for web outputs.
...

You say "Use a single stylesheet with the various mediums defined (manual, QSG, onlinehelp, etc.)"

I'm not convinced that there is any benefit to this approach, and was actually going in the opposite direction (creating a PDF stylesheet and copying it to create HTML.css etc and then editing as required). What is your rationale for using this functionality?

For me, it's just easier to maintain all styles in one style sheet. It ensures I use consistent styles in all outputs and I only have to make changes in one location.

I forgot to mention that we also use Global Project Linking. We have a master style sheet that is stored in the global "parent" project. I make any necessary edits to the Global.css file in the parent project and then import the updated file into the local "child" projects. I also created translated versions of the Global.css that contain all the translated auto-text (notes, cross-refs, etc.) so that we don't have to retranslate this text, and any language-specific formatting (e.g., no italics in Japanese). In the translated style sheets, I use the style sheet import feature to link to the English style sheet, and only include the differences between the two in the translated style sheets. When I generate the target, I just specify the appropriate language's style sheet as the Master Stylesheet in the target file.

- Because the topics are modular, they may not contain a lot of text and can look odd in web outputs, so we created a master page with a breadcrumbs proxy and mini-TOC proxy for web outputs.

The small topics do look odd in web outputs. To me, that is the essence of the request: to be able to use modular topics and still be able to create scrollable topic output instead of forcing the user to keep navigating from one small topic to the next. This would essentially require that we could control what makes a topic break for HTML5 output similar to how we can control what makes a new chapter or page break for PDF output, (and similar to what we could do in FrameMaker-->WebWorks single-sourcing for help output).

I have used the breadcrumb tool also, as a workaround for this. However, I don't think that resolves the requirement. I would still like to have the ability to control at what level the topics break or be able to define them via a setting in the FLTOC, similar to the options for PDF output. Presently, you can control what level appears in the TOC panel, but you cannot control at what level the topics actually break.

If there has been an update on this functionality, I'd like to hear about it.

Thanks