Identifying TOC books as chapter title pages

[nsemple]

Is there any way to in a print TOC to automatically have all your top-level books that are not associated to Help topics converted to chapter title pages using the book title as the title of the chapter page.

I would like to be able to link all these top-level chapter pages to a single mini-toc proxy topic that uses some type of variable settings in the header to insert a chapter number, the name of the book title as the chapter title in the printed output, and a mini-toc for all the topics in that associated chapter. The resulting printed page for each chapter title page would look like this:

<Chapter_number> <Chapter_title>

In this chapter:

<mini_toc>

Looking at Flare's Help content and Printed Output Guide, I cannot determine if there is a way to do this.

Currently, it appears as though I have to create a mini-toc proxy topic for each of the top-level books in my print TOC. In addition to inserting a TOC proxy in each of these individual chapter proxy topics, I have to type the chapter number and type out the name of the book title that I want to use for the chapter title. Then I have to link each top-level book in the print TOC to the corresponding chapter proxy topic.

There does not seem to be a way (either from the properties page of the top-level books in the print TOC itself or from the use of any type of variables in the mini-toc proxy topic) to automatically pick up the title of the top-level book in the print TOC so that I do not have to create a mini-toc proxy page for each of the chapter title pages in the printed output.

Am I correct or am I missing something...?

[Eric Lachance]

nsemple,

Though there are variables that display things like the first H1 on the page, or the first keyword and such, I don't know of any that will display the name of the topic from the TOC file, so you may have to suck it up and create individual topics for each chapter, just like everyone else does.

You can ask Madcap to change that by submitting a feature request here:
https://www.madcapsoftware.com/bugs/submit.aspx

[NorthEast]

Eric's right, you'd need to create a topic page for your chapter headings.

There is a setting to Inject headings for unlinked books in TOC; which would insert the headings from your unlinked books into the document itself and list them in the print TOC (or a mini-TOC).

However, if you also want to include a mini-TOC for each chapter, then you physically need a include a topic that will contain the mini-TOC.

[nsemple]

Thanks Eric,

I'm having a bit of trouble doing this and am not able to a mini toc to appear in the printed output...

Do each of the chapter title page topics (that contain a mini-toc proxy) have to be stored:

- at a top-level in the Help project content explorer pane (at the same level as all the folders that I want to have serve as chapter title pages)
- Within the individual folder to which the mini-toc will be applied
- or can I have a folder called "ChapterTitlePages" that contain all the individual chapter title topics?

Once they are set as source in the content explorer pane, do I have to physically add the title page topics to the print TOC or do I just need to link the folders in the print TOC to the topic files that contain the mini TOCs from the Help content explorer pane? If I have to physically add each chapter title page topic to the print TOC, should the location of the topic be on the same level as the folder that I want to associate it to?

[LTinker68]

The mini-TOC proxy only works with topics located below the topic containing the mini-TOC proxy. So if you have a book called "Configuring the Software", for example, you'd create a topic called configIntro.htm or something like that, and that topic would contain the mini-TOC proxy. That topic would then be linked to the book called "Configuring the Software". Within that book would be topics and perhaps sub-books containing more topics, so the topics and sub-books are "below" the topic containing the mini-TOC. If you set the mini-TOC to 1, then it will list the topics one level down from the mini-TOC topic. If you set it to 2, then it will list the topics one level down plus topics two levels down (i.e., topics inside a sub-book). For example, if your structure is like the following...

Code: Select all

Configuring the Software (book) -- linked to configIntro.htm containing mini-TOC proxy
   - Topic A
   - Topic B
   - Book (linked to Topic C)
        - Topic D
        - Topic E
   - Topic F

... Then a mini-TOC of 1 would list Topic A, Topic B, Topic C, and Topic F. A mini-TOC set to 2 would pretty much replicate the above structure, except for the top-most book.

To modify the appearance of those listings, you modify p.MiniToc1, p.MiniToc2, etc.

[Eric Lachance]

nsemple,

The actual physical location of the topic doesn't matter - that is, wherever it is in the /Contents/ folder has no impact on the contents or the output of the topic. It's their location in the TOC (Tables of Contents), as well as the contents of the rest of the chapter inside that TOC Chapter (aka "Book"), that matters.

The MiniTOC can generate a list of topics for the current chapter only if you have proper headings for each topic. For example, my Chapter headings are always <h1> , my topics are <h2> and sub-sections either in the same topic or in topics in sub-branches are <h3>, <h4>, etc.

So, again, this has nothing to do with the structure in the /Contents/ folder (or "Content Explorer"), that's only for convenience and to help manage topics more easily. It's all about the TOC file and your topic headers!

Hope that helps...

[LTinker68]

The MiniTOC can generate a list of topics for the current chapter only if you have proper headings for each topic. For example, my Chapter headings are always <h1> , my topics are <h2> and sub-sections either in the same topic or in topics in sub-branches are <h3>, <h4>, etc.

Unless you've populated the <title>...</title> tag in the topic by filling in that field in the topic's Properties screen. If you did, then I believe that title is what shows up in the mini-TOC. If you didn't fill in that field, then it'll use the headings in the topics.

[Eric Lachance]

Oh, didn't know that! I never bothered because the titles don't show up in either the print output or the WebHelp anyway, so there was no point

Does <title></title> also affect cross-referencing? (sorry if I'm hijacking your thread for a second, nsemple)

[LTinker68]

I believe so. I don't use that field at all, but from other threads I've read, I believe it affects pretty much anything that displays the topic's title, whether the title is gleaned from the heading or the title tag. The title tag takes precedence if it's populated. If it's not populated then the first heading is used, and I believe it's regardless of which heading tag you use and where the heading tag appears in the topic. In other words, the first heading doesn't have to be h1 and it doesn't have to be the first tag block in the topic. I don't think. There just has to be a heading, period.

If the title tag isn't populated and there are no headings, then the topic's file name is used.

Correct me if I'm wrong, Dave Lee. I think you're the one whose posted previously about the title tag.

[nsemple]

Hi Eric,

Yes. Thanks. That does help. Knowing that the location of the chapter title page topic that contains the mini TOC in the source Help structure (content explorer pane) does not matter made me try a few other things.

In order to get chapter numbers to appear to the left of the chapter title on the chapter title pages in the printed output, I was using a list style rather than a H1 style for my chapter titles in the topics that contained the mini TOCs.

I was setting the numbering for each chapter title so that it would state the correct number for a specific chapter rather than always inserting "1" as the number before each chapter title (using Format > List > List Actions > List Start Number).

It appears as though my using a list number style for the chapter titles rather than a H1 style messed things up somehow and I could never get the mini toc content to appear in the printed output. Once I changed the list number style I was using for the chapter titles to an H1 style and regenerated the output, the mini toc content now appears. Yea! Finally.

To follow up, got one more question for you... If I can't use a list number style to include chapter numbers to the left of the chapter titles on the chapter title pages in my printed output, do you know what I can do to get the numbers? Do I actually have to type them in the source file as part of my chapter title text? (The topic titles for these mini-toc chapter title page topics has never been set. The topic title on the topic properties dialog box has always said to Always use first topic heading".)

[Eric Lachance]

nsemple,

From the menu, try going into Insert, then Variables. Click the System section, then double-click on Chapter Number. This inserts the current chapter number.

To make sure that the numbering is ok, right-click on each of your chapters ("books") in your TOC, and in the Printed Output section, check the Start a new chapter document.

That should give you a good start

BTW, always remember that the flare documentation is online and searchable at:
http://webhelp.madcapsoftware.com/flare6/Default.htm

In our business of writing manuals, it's always a good idea to RTFM ourselves

[ChoccieMuffin]

I swear I have read all 3000+ pages of TFM, but there's just so much of it I can't find things again when I'm looking for them.

I also find that although the docs explain the "what", they aren't terribly good on the "how" and are even worse on the "why". And don't even think about looking for suggestions about the "when", as in the order you should do things in.

Just as well the ropes for scaling that learning cliff are available on these forums! (Dave, Steve, Lisa etc, did you ever think you'd be likened to a rope?)

[nsemple]

Eric,

Your suggestion as written does not work.

As for your implication, that I have not read the Flare documentation - I find that laughable.

I have scoured Flare's online Help regarding printed output, reading it over and over again until I am numb. I have read, reread, and then read again the entire 388 page printed manual guide.

The documentation Madcap provides on this subject matter is, plainly speaking, "not good".

I have been in the technical writing industry for nearly 30 years and have provided templates for writing departments in more than half a dozen authoring tools. The Flare documentation for printed output has had me repeatedly at my wits end. ChoccieMuffin is correct. Flare's documentation is convoluted and complex. The links in it are endless. You can never get a complete answer in one place, it is difficult to put the pieces together, and they've taken snippets to a whole new level (as in what not to do with snippets).

I have been extremely frustrated, and as a result have come to the Flare forums in the hope that someone out there will be familiar with what I am trying to do and be able to help. The only time I use the forums is when I have exhausted your documentation trying to look for answers. This is most likely the case with the vast majority of people who use the forums, so we don't need to be lectured to about first reading the online documentation before posting questions on the forums.

I find that the information I learn from those who respond on the forums is often very valuable. As with your previous post (for which I am very grateful), I have often found help with issues I am experiencing when searching through your forums or posting questions on it when I cannot find the answers elsewhere.

I also believe that if I am having trouble doing something, someone else out there might be experiencing the same kind of problems and could be searching the forums looking for answers as well, so as opposed to a Technical Support response that I may receive to a query from me (that only goes to me), a forum response can be viewed and shared among all who care to read it. Someday, the response I receive may be as valuable to others as it is to me.

Thanks for your help...

[LTinker68]

To follow up, got one more question for you... If I can't use a list number style to include chapter numbers to the left of the chapter titles on the chapter title pages in my printed output, do you know what I can do to get the numbers? Do I actually have to type them in the source file as part of my chapter title text? (The topic titles for these mini-toc chapter title page topics has never been set. The topic title on the topic properties dialog box has always said to Always use first topic heading".)

You can add an auto-number format to your heading styles. The numbers will appear in the topic, in the mini-TOC, and the generated TOC. There's not a way that I know of to have the number appear in the heading in the topic but not appear in the generated TOC, but it sounds like you want it to appear in both places anyway.

To use auto-numbering, open the Stylesheet Editor. If you just want the auto-number for print output, then switch the Editor to the print medium view. I use the Editor in Advanced view, so for that view, click on a heading to select it, then expand the auto number category (when the Editor is set to Show: Property Groups). You can set fairly complex auto-number formats, so if you need some help setting up the format, post back with how you want your numbering to appear. You can also have no auto-number specified in the heading style for online output and have an auto-number specified for print output. If you use the Editor in Simple view, then select the auto-number category from the drop-down list or keep scrolling to the right until you get to the mc-auto-number-format and similar fields.

One note about auto-numbering... I don't use the {chapnum} option in the format, but if you do, you have to remember to set chapter breaks in the TOC Editor, as that's what the {chapnum} variable uses to determine the chapter numbers. Even if you use one page layout throughout the TOC, you still have to create chapter breaks, which means you have to respecify that page layout.

[nsemple]

Hi Lisa,

THANK YOU! That worked! Yea!

I had tried to set the autonumber format using the Properties dialog box that was associated to the book entries in the print TOC, but it wasn't working and I was stumped. (On the Printed Output tab of the Properties dialog box, I had specified to start a new chapter document. In the Chapter Number area on the Auto Numbers tab of this same dialog box, I set the autonumber format.)

I have now set things up so that:
- The H1 style has {chapnum} as the mc-auto-number-format for the AutoNumber setting in the .css for printed output only as you described.
- The chapter title page topics that contain the mini-tocs each use the H1 style for the chapter title text on the line before the mini toc proxy.
- Each book in the print TOC is linked to a corresponding chapter title page topic that I have stored in a content explorer folder named ChapterTitlePagesForPrintedDocuments. (For example, the first book in the print TOC that I want to be converted into a chapter title page in the printed output is linked to a topic named Chapter_1.htm that contains the desired chapter title text and the mini toc proxy. The second book in the print TOC that I want to be converted into a chapter title page in the printed output is linked to a topic named Chapter_2.htm that contains the desired chapter title text and the mini toc proxy.)
- On the Printed Output tab of the Properties dialog box for each book in the print TOC, I have selected the checkbox to start a new chapter.

When I generate the printed output, the correct chapter number appears to the left of the chapter title text on the chapter title pages. The correct numbers for each chapter are also reflected in the book's TOC.

All of our topics, which begin with a H1 style for the topic title, do not display a number as they are contained within books and drop down to a H2 level during the printed output conversion process. If I want a top-level topic (not contained within a book) to appear in the printed output without a number before the topic title text, I have to use a style other than H1 for the topic title. (For example, for a topic titled "Preface" that is going to be used only in printed output, do not use the H1 style for the "Preface" text or a number will appear to the left of the topic title text and TOC entry in the printed output.)

Thanks so much for your help. I really appreciate it!

[LTinker68]

If I want a top-level topic (not contained within a book) to appear in the printed output without a number before the topic title text, I have to use a style other than H1 for the topic title. (For example, for a topic titled "Preface" that is going to be used only in printed output, do not use the H1 style for the "Preface" text or a number will appear to the left of the topic title text and TOC entry in the printed output.)

Or, you could create a class of h1 that doesn't have an auto-number format. If your base h1 tag has an auto-number format, then you have to set the mc-auto-number-format for the h1 class to be blank. To do that, you have to enter a space in the mc-auto-number-format field. However, that means there will be a space before the text in that heading, so you have to have an empty string in the format, which you can't enter via the Stylesheet Editor. Instead, you have to modify the stylesheet file manually. To do so, right-click on the stylesheet file in the Content Explorer and select Open with > Internal Text Editor. Type something similar in the stylesheet file, then save it. (That's two single quotes ' ' next to each other without any space between them -- it's not a single double quote ").

Code: Select all

h1.headingNoNum
{
   mc-auto-number-format:'';
}

You now have an h1 class that inherits all properties from the base h1 tag except for the auto-number format. Apply that class to any heading that shouldn't have a number before it.

[nsemple]

Very nice. I like it. Thanks so much. Once the class is created, I just have to right-click on the H1 block in the XML editor and select the H1 style class h1.HeadingNoNum.

One thing I did not notice before though is that the Table of Contents for the book that is automatically generated by the printed documentation process has the "table of contents" title text inserted on a H1 style, so a number is coming across to the left of the table of contents heading text and is messing up the chapter numbering of the TOC entries. (Rather than the chapter numbers starting with "1", they are starting with "2".)

I am looking at the information for "Determining the levels and look of your print TOC" as well as the target editor settings on the tabs for the target output, but I do not see anything that allows me to specify what style should be used for the table of contents heading text in the resulting output. It is defaulting to H1...

[lacastle]

How are you getting the TOC in your print output? In my project, I have a topic called TOC.html that contains an H1 title and a toc-proxy. I had to make a special class for this H1 so that it is not included in the TOC (set mc-heading-level to 0 in the style editor).

i think you can also set the properties in the TOC for the TOC.html topic so that it doesn't start a new chapter auto-number.

[nsemple]

Hi Laura,

Thanks! You jogged my memory. I have a proxy topic file set up for the printed TOC output as well. I assigned the h1. HeadingNoNum class to the h1 style in that file and it fixed the issue with the Table of Contents title having a number to the left in the printed output.

Sigh...

I guess sometimes you get so tired of trying to make something work that you stop thinking with a clear head.

Appreciate your help!

[lacastle]

I guess sometimes you get so tired of trying to make something work that you stop thinking with a clear head.

When I get to this point, I turn it off and go home

[nsemple]

Thank goodness its Friday. I'm all set . The chapter title numbers are working and the TOC in the printed output now looks great.

Thanks to everyone who helped. You're all great!