index problems

[garyjgeoaccess]

Okay. So I prepared a Flare project for output to PDF. I've done everything and worked through numerous problems. But I'm now getting good output for both WebHelp and PDF. I'm training staff on how to set up a project for PDF output. I've done everything except one thing: I still need to set up an index.

So I thought this would be easy, right?

Well, I'm running into some problems.

Problem #1: so it's called "p.IndexHeading"?
When you set up an index, you learn the paragraph class for the alphabetic character (A, B, C, etc.) that starts each section of the index is named "p.IndexHeading". Okay, great. I'll now format these headings as I see fit. Hmm ... Well, I can change the font, yes. And I can change the font size. Looks good. But wait ... I can't change the margin-top. Whatever I do, the margin-top is stuck at 0in. I even tried padding-top and still no extra white space above the heading. How can this be? Are other people seeing the same thing? I wish I could see the generated HTML for this page. Something else is going on, maybe another style, maybe a DIV, maybe a table (gasp!), maybe ... who knows what?

Problem#2: so p.IndexHeading is centered?
So it looks like p.IndexHeading comes with "text-align: center" by default ... and it won't let me change it! I'm trying to make the heading left aligned, but no go. It's ALWAYS centered. How can that be?

Problem#3: mystery padding on left of index proxy
Somewhere Flare is picking up about 10px of padding on the left side of the index. Everything is indented by 10px. No, I don't want the padding-left or margin-left of 10px. So I tried to nuke it. I added "padding-left: 0in" and "margin-left: 0in" to the MadCap|indexProxy in the stylesheet. No go. There must be a container--but I don't know what it is. I don't know what the element name is. I wish I could see the generated HTML for the index!

Problem#4: long index entries don't wrap
Okay, so most of my own index entries are just a word or two or three. They are rarely long enough that the line needs to wrap, but other people on my team have long index entries, maybe 5 or 6 words long (as many as 10). These lines need to wrap. And they should wrap, right? But guess what? These lines refuse to wrap. All the text fits on one line, pushing the page number off to the right, maybe off the page. What's going on here? See the sample PDF screenshot below. Warning: I turned on pink as the background-color for indexProxy so I could see the location of the proxy container.

indexproxy.png

Note: this same screenshot also illustrates the other problems described above.

So what's going on with index entries not wrapping? I tried setting the width for indexProxy. Didn't make any difference. I wish I could see the generated HTML for the index!

Has anyone seen any of these problems before? I'd search the forum but ... you know what? You can't search for "index"! This word is not allowed by the search engine.

Anyone have any ideas how to solve any of these problems? Thanks.

[garyjgeoaccess]

So I'm starting to find answers for my own questions. For anyone keeping score at home ...

I grabbed the temporary index.htm file that is created during the build process and opened it up. I found a reference in the head section to a new stylesheet. This stylesheet is called MadCapBlaze.css. While Flare does in fact delete all the temporary HTM files that are created during the build process, it does NOT delete the output files in the references folder. And this folder contains the stylesheets subfolder, which contains ... YES! MadCapBlaze.css. Within index.htm, the reference to MadCapBlaze.css is placed AFTER the topic level stylesheet, so any styles in the topic stylesheet are subject to being overwritten.

So I opened up MadCapBlaze.css. It contains styles for ... guess what? A table that is used for the index entries. A table? Yep. Same for the Table of Contents. Now this is starting to make sense.

I'll continue to investigate this situation (not that ANYONE really cares) and report the findings here.

[garyjgeoaccess]

In MadCapBlaze.css, "white-space: nowrap" is applied to many of the TD styles. Yikes! That's what's causing the long index entries to stray outside their columns. I'll isolate these styles, add them to the topic stylesheet, and see if they get picked up when MadCapBlaze.css is generated during the build process.

[garyjgeoaccess]

No. I cannot turn off "white-space: nowrap" by adding these TD styles to the topic stylesheet. Flare insists on writing "white-space: nowrap" to MadCapBlaze.css. Why would "nowrap" be turned on for table cells? This makes no sense.

[garyjgeoaccess]

So can MadCapBlaze.css be removed from the Flare program files?

Nope. It's required for PDF output. Remove it and you get this message:

Compiler (Internal Error): Could not find file 'C:\Program Files\MadCap Software\MadCap Flare V4\Flare.app\Resources\BlazeTargetCompiler\MadCapBlaze.css'.

[garyjgeoaccess]

But I CAN write the "white-space: normal" styles to the MadCapBlaze.css file in the Flare program files. And Flare does pick up these styles during the build. This allows me to turn "white-space: nowrap" (which is written to MadCapBlaze.css by default) into "white-space: normal". I'm now getting wrapping text in the index.

This should not be so difficult. This is certainly a flaw in the reasoning behind how styles are generated for the index table. I'll be submitting this as a bug.

[garyjgeoaccess]

For anyone keeping score ...

Above, I documented a solution for problem#4.

What about the other problems?

Problem #3? I don't know yet. I have to go searching for a stray margin-left in MadCapBlaze.css. Could be hardcoded in the table (i.e., <table cellpadding=10>, in which case I may never see it.

Problem 1 & Problem #2? Well, while I had zeroed out margin-left, Flare was picking up another style in my stylesheet when it generated MadCapBlaze.css for output. It picked up "margin: 0in 0in 6pt 1.5in", which had been applied to <p>. It added this to all paragraph styles in MadCapBlaze.css. The effect? Margin-top was changed to 0in (problem #1) and Margin-left was changed to 1.5in (problem #2--so p.IndexHeading wasn't being centered, it just sort of looked like it because it was being indented 1.5 inches_.

[SteveS]

Hi Gary?

You seem to have researched the problem. Time for a bug reportmethinks

[doc_guy]

Very interesting things you are finding. I'm learning lots just reading this thread.

I knew that the index and TOC were being built inside tables, because in a beta version of Flare 4, I had table borders applied to my topics, and I was getting borders around the elements of my TOC and index. This makes me think that the solution MadCap discovered was to add the styles to the MadCapBlaze.css file and then call the MadCapBlaze.css file AFTER the default style sheet. Which is what is causing your problems. Since MadCapBlaze.css is being called AFTER your style sheet, the settings in there overwrite your settings.

Of course, (and you probably already realize this, but I'll say it anyway) remember that any changes you make to MadCapBlaze.css will apply to every project you create (which sounds like what you want anyway), and they will be lost any time you upgrade Flare, especially between versions (so when Flare 5 comes out, you'll have to make the changes to MadCapBlaze.css all over again).

Here are the styles I've put into my Index that seem to make the spacing not too horrible:

Code: Select all

p.Index1
	{
		margin-bottom: 6pt;
		page-break-after: avoid;
		font-weight: normal;
		font-family: '' Trebuchet MS '', ' Arial', ' sans-serif';
		margin-top: 10pt;
	}

	p.Index2
	{
		margin-bottom: 6pt;
		font-family: '' Trebuchet MS '', ' Arial', ' sans-serif';
	}

	p.Index3
	{
		margin-bottom: 6pt;
		font-family: '' Trebuchet MS '', ' Arial', ' sans-serif';
	}

	

With this, the margin between index items is the same space before the next letter/section, but the spacing is enough that they don't totally run together.

This doesn't appear to be overwritten by the MadCapBlaze.css file.

[garyjgeoaccess]

This makes me think that the solution MadCap discovered was to add the styles to the MadCapBlaze.css file and then call the MadCapBlaze.css file AFTER the default style sheet. Which is what is causing your problems. Since MadCapBlaze.css is being called AFTER your style sheet, the settings in there overwrite your settings.

Yes, this is exactly what is happening. When the temporary file index.htm is created during the build process, I opened it up and confirmed that MadCapBlaze.css is placed after the topic stylesheet, therefore overwriting the styles that I thought I had declared.

Of course, (and you probably already realize this, but I'll say it anyway) remember that any changes you make to MadCapBlaze.css will apply to every project you create (which sounds like what you want anyway), and they will be lost any time you upgrade Flare, especially between versions (so when Flare 5 comes out, you'll have to make the changes to MadCapBlaze.css all over again).

Exactly. The only way to fix the problem is through adding the styles to MadCapBlaze.css in the program files. Initially, this file is empty. Any additions you make to this file are in fact maintained during the build process, when a new MadCapBlaze.css is generated on the fly, using a combination of style settings mysteriously applied by Flare (that determine how the index and toc will look) AND settings that it draws from the topic stylesheet. This is a problem with how Flare generates PDFs. I shouldn't have to edit my program files because this affects ALL projects. If a stylesheet exists for the creation of indexes and tocs, I should have direct access to it so that I can make changes on a project-by-project basis. As is, the process behind the creation of indexes and tocs is hidden from the user. This process needs to be opened up.

Yes, I'll be submitting a bug/enhancement report.

[Andrew]

Problem #1: so it's called "p.IndexHeading"?
When you set up an index, you learn the paragraph class for the alphabetic character (A, B, C, etc.) that starts each section of the index is named "p.IndexHeading". Okay, great. I'll now format these headings as I see fit. Hmm ... Well, I can change the font, yes. And I can change the font size. Looks good. But wait ... I can't change the margin-top. Whatever I do, the margin-top is stuck at 0in. I even tried padding-top and still no extra white space above the heading. How can this be? Are other people seeing the same thing? I wish I could see the generated HTML for this page. Something else is going on, maybe another style, maybe a DIV, maybe a table (gasp!), maybe ... who knows what?

That's odd...I was able to change the p.IndexHeading style's margin-top with no problem at all. I just changed it in my style sheet from 20pt to 100pt, and here is what it looks like in the PDF:

Problem#2: so p.IndexHeading is centered?
So it looks like p.IndexHeading comes with "text-align: center" by default ... and it won't let me change it! I'm trying to make the heading left aligned, but no go. It's ALWAYS centered. How can that be?

Again, I'm not seeing this same thing. I changed text-align to left, and I get this:

Problem#3: mystery padding on left of index proxy
Somewhere Flare is picking up about 10px of padding on the left side of the index. Everything is indented by 10px. No, I don't want the padding-left or margin-left of 10px. So I tried to nuke it. I added "padding-left: 0in" and "margin-left: 0in" to the MadCap|indexProxy in the stylesheet. No go. There must be a container--but I don't know what it is. I don't know what the element name is. I wish I could see the generated HTML for the index!

I removed the padding-left (set it to 0px) from my MadCap|indexProxy style, and the indent you see in the screen shots above disappeared from my index.

Problem#4: long index entries don't wrap
Okay, so most of my own index entries are just a word or two or three. They are rarely long enough that the line needs to wrap, but other people on my team have long index entries, maybe 5 or 6 words long (as many as 10). These lines need to wrap. And they should wrap, right? But guess what? These lines refuse to wrap. All the text fits on one line, pushing the page number off to the right, maybe off the page. What's going on here? See the sample PDF screenshot below. Warning: I turned on pink as the background-color for indexProxy so I could see the location of the proxy container.

Also can't reproduce this. Set white-space property to normal (instead of nowrap) and it works as the screen shot below shows:


I did all of the edits I've shown in the style sheet I created for this project. I'm not sure what problem you may be having, but the styles themselves work.

[Andrew]

Incidentally, I feel your pain. I'm not able to get my index into a multi-column layout, no matter what settings I change, despite the fact that I've seen others do it just fine.

[garyjgeoaccess]

Hey, Andrew:

Regarding Problem #1:

That's odd...I was able to change the p.IndexHeading style's margin-top with no problem at all. I just changed it in my style sheet from 20pt to 100pt ...

Yes, you can change the margin-top for p.IndexHeading. In my case, in the topic stylesheet, I had added "margin: 0in 0in 6pt 1.5in" for <p> (as described in a previous post). While it makes sense to combine multiple style settings on one line (thus reducing the stylesheet bloat created by Flare), Flare doesn't always handle these styles correctly. Case in point. Regardless of how I set margin-top in p.IndexHeading, it was being overridden by "margin: 0in 0in 6pt 1.5in" in <p>--because of how the MadCapBlaze.css file was being generated. The mysterious generation of MadCapBlaze.css is somewhat problematic because users have no control over this file from within Flare--and it controls the look of indexes and tocs .

Regarding Problem #2:

Again, I'm not seeing this same thing.

Same thing as Problem #1.

Regarding Problem #3:

I removed the padding-left (set it to 0px) from my MadCap|indexProxy style, and the indent you see in the screen shots above disappeared from my index.

Not working for me. I need to investigate this further.

Regarding Problem #4:

Also can't reproduce this. Set white-space property to normal (instead of nowrap) and it works

How did you know where to set "white-space: normal"? I figured it out eventually, but I'm a bit surprised at your response because you seem to indicate ho-hum it's a no brainer. I don't mean to sound facetious, but it took me a long time to figure out that "white-space: nowrap" was being set in MadCapBlaze.css. Was there an easier way to figure this out?

And yes, I'm using a column layout. I've got it working--less a tweak for Problem #3.

Thanks.

[Andrew]

garyjgeoaccess,

My apologies for the rather poor response I made above -- I didn't fully understand the issue you described.

In short, let me say:
I reproduced the issues you have with the top margins/centering when I added "margin: 0 0 6pt 1.5in;" to the p element in my stylesheet. So as far as that goes, it appears to be a problem there. I was wondering, if you set all those separately (using margin-top, etc.), does that resolve many of these issues?

How did you know where to set "white-space: normal"? I figured it out eventually, but I'm a bit surprised at your response because you seem to indicate ho-hum it's a no brainer. I don't mean to sound facetious, but it took me a long time to figure out that "white-space: nowrap" was being set in MadCapBlaze.css. Was there an easier way to figure this out?

My apologies if my tone made it seem like it was ho-hum, no brainer -- that was never my intent. Rather, I was trying to point out that I can use my own stylesheet to fix it, rather than MadCapBlaze.css (as I explained above, I had misunderstood the problem you faced).

Sorry for the misunderstanding,
Andrew

[garyjgeoaccess]

No problem, Andrew.

I'm just trying to understand what you did. If I understand what you did, maybe I'll save myself time. Maybe this isn't as complicated as I thought it was.

I was trying to point out that I can use my own stylesheet to fix it, rather than MadCapBlaze.css

Where did you apply "white-space: normal" in your own stylesheet? I tried this and it didn't work (applying it to p.Index1 and p.Index2, as well as the additional MadCapBlaze.css styles, such as td.GenIndexText1 and a.GenIndexText1:link)--because white-space was being overwritten in MadCapBlaze.css.

How did you know to apply "white-space: normal"? I'm sort of mystified that you knew to apply this style if you didn't see it in MadCapBlaze.css.

I was wondering, if you set all those separately (using margin-top, etc.), does that resolve many of these issues?

Yes, it does ... I think (I need to test it again). Flare carries over "margin: 0 0 6pt 1.5in;" to MadCapBlaze.css AND it applies the margin-left that I applied to p.Index1 and p.Index2, but it placed "margin: 0 0 6pt 1.5in;" below margin-left. So it effectively overwrote the settings that I thought I had set. Best NOT to use a one-line margin setting--exactly because Flare doesn't know where to place it in MadCapBlaze.css (and thus it can cause conflicts).

To confuse matters further, I've got styles attached to the body tag (to set the margins, background-color, default font, etc.), and it looks like these styles are somehow being picked up by MadCapBlaze.css and applied ... I'm not sure how yet. But they're overriding the p.Index1 and p.Index2 styles and throwing off the margins!

Arrrrrrrrrggggggghhhhhhhhhhhhhh!

[doc_guy]

The problem that I have in WebHelp, and I assume the problem is similar in PDF output is that you can't control whether MadCap will call your style sheet last, or whether they will call THEIR style sheet last. It doesn't seem universal. In this case, I assume that Andrew's build is calling his normal style sheet last. In Gary's case, I assume that MadCap's css is being called last. That is why Andrew can change the settings in the style sheet, but Gary has to modify the program files.

The same thing is happening with my WebHelp builds. In my builds, MadCap.css is being called last, which overwrites some of my settings (around breadcrumb display and MiniTOC display), so I have to muck around in the MadCap.css file in the program files to get my output to display correctly.

There doesn't seem to be rhyme nor reason to this. In LTinker's case (if I remember correctly), her style sheet was called last. In my case, MadCap.css is called last. We were both using the same version of Flare.

[garyjgeoaccess]

Paul:

I can indeed confirm that my stylesheet is coming before MadCapBlaze.css. You may be right about this. This would explain a lot.

In the case of MadCapBlaze.css and indexes, however, new styles are created on the fly during the PDF output process. These styles are used when the index table is generated. I can see these styles in MadCapBlaze.css, but I don't know what they represent. So even if I get my stylesheet to load after MadCapBlaze.css, it doesn't affect some of the settings, such as the margins, because the styles get renamed.

If I muck around with this long enough, I'll figure out what the new styles represent in MadCapBlaze.css, and maybe I'll figure out how to override these styles with my own settings. But I shouldn't have to do this. This is very frustrating. Indexes should NOT work like this.

[Andrew]

I'm just trying to understand what you did. If I understand what you did, maybe I'll save myself time. Maybe this isn't as complicated as I thought it was.

Let's hope not!

Where did you apply "white-space: normal" in your own stylesheet? I tried this and it didn't work (applying it to p.Index1 and p.Index2, as well as the additional MadCapBlaze.css styles, such as td.GenIndexText1 and a.GenIndexText1:link)--because white-space was being overwritten in MadCapBlaze.css.

How did you know to apply "white-space: normal"? I'm sort of mystified that you knew to apply this style if you didn't see it in MadCapBlaze.css.

Aha, maybe this is one of the issues...I applied it under p.Index1 class, to the whitespace property. The reason I knew to apply it there was that I saw, when looking through my styles, that all the p.Index entries were set to nowrap in the whitespace property under "Block" in the Advanced View of the Stylesheet Editor. Does that help?

Yes, it does ... I think (I need to test it again). Flare carries over "margin: 0 0 6pt 1.5in;" to MadCapBlaze.css AND it applies the margin-left that I applied to p.Index1 and p.Index2, but it placed "margin: 0 0 6pt 1.5in;" below margin-left. So it effectively overwrote the settings that I thought I had set. Best NOT to use a one-line margin setting--exactly because Flare doesn't know where to place it in MadCapBlaze.css (and thus it can cause conflicts).

To confuse matters further, I've got styles attached to the body tag (to set the margins, background-color, default font, etc.), and it looks like these styles are somehow being picked up by MadCapBlaze.css and applied ... I'm not sure how yet. But they're overriding the p.Index1 and p.Index2 styles and throwing off the margins!

Arrrrrrrrrggggggghhhhhhhhhhhhhh!

Ugh. Well, it sounds like maybe the body tag stuff could be causing problems, but I don't know which (I'd guess margins, but only because that was the problem in the previous case).

[Andrew]

Oh, and in the off-chance it's an alphabetical thing: have you tried to rename your stylesheet so that it falls after M alphabetically (assuming that it doesn't already)? Just a shot in the dark as to why some stylesheets appear after, while some appear before....

[doc_guy]

that is interesting, though my style sheets are all named "style.css". So unless it is reverse-alphabetical....

[Andrew]

that is interesting, though my style sheets are all named "style.css". So unless it is reverse-alphabetical....

Must not be, because the project I tested this under was Style Workbook.css, where I was able to edit in my stylesheet. Ah well, so much for crazy ideas.

I was able to reproduce the most of the problems by using the margin: property values for the p element that garyjgeoaccess used, so I am guessing there is some kind of bug in Flare that reacts to certain locutions in the stylesheet.

[garyjgeoaccess]

Okay. I just figured out how to get the index to behave regarding margins (Problem #3 first described in my original post), and I am now getting a multi-column index that is formatted as I want. This involves editing MadCapBlaze.css. Not sure this will work the same for everyone, but here is the gist of what you need to do.

First, be careful what you put in styles that can be inherited. In my case, I had declared styles for <p> and <body>. And these styles were being inherited when the index was generated in ways that I hadn't anticipated.

I went back and changed the margins and paddings so all directions (left, right, top, bottom) are specified on separate lines in my topic stylesheet. Don't use single lines to specify multiple directions for base level styles like <p> or <body> or <td>. Flare doesn't know what to do with these lines when generating MadCapBlaze.css during the PDF output process. It uses these lines, yes, but it may put these lines in places that cause conflicts.

Second, you can override the styles that Flare (during output) puts into MadCapBlaze.css. You can override these values by adding these values to the version of MadCapBlaze.css in your program files. But because Flare creates an index table and RENAMES your styles for use within this table, this requires figuring out the names of the new styles.

Here is how the style renaming worked in my case.

1) my original style for p.Index1 became td.GenIndexText1.
2) my original style for p.Index2 became td.GenIndexText2.
3) you can prevent any style from being written to the output version of MadCapBlaze.css by including an empty class in your program files MadCapBlaze.css. For example, if you want to prevent Flare from writing bogus margin values to each of your index styles, just include (for example) "table.GenIndexTable1 {}". [There are several other classes also. Check the generated MadCapBlaze.css file for the complete list.]

It's only taken about three days to figure this out and solve all the problems that I originally saw when generating an index.

[garyjgeoaccess]

Well, you know, this would've been easier if I had checked the Flare stylesheet editor. I'm a web designer. I work in stylesheets all the time. I don't typically bother with the Flare stylesheet editor. I just edit the stylesheet on my own.

But you know what? Andrew is right. I never set "white-space" in my stylesheet for the p.Index# styles, but when I opened the stylesheet in the Flare stylesheet editor, what did I see? "white-space: nowrap" is turned on by default, regardless of whether it's actually specified in the stylesheet! What sadistic #$%@*&$# at MadCap did that?

[garyjgeoaccess]

All problems solved. Some of the descriptions and solutions are pretty esoteric. Most people won't give a rat's #$%.

For those people who want to take control of formatting the index, however, I hope this thread helps.

That's a wrap. I think ...

[Andrew]

but when I opened the stylesheet in the Flare stylesheet editor, what did I see? "white-space: nowrap" is turned on by default, regardless of whether it's actually specified in the stylesheet! What sadistic #$%@*&$# at MadCap did that?

While I understand why that would frustrate a web designer, for humble help authors (like myself), it's actually much much easier. It means that my stylesheet is pretty clean, aside from what I myself add to it. Granted, it also means that if things aren't working right in Flare with the behind-the-scenes-switch like the errors you found, troubleshooting becomes a complete nightmare. Maybe there's some kind of happy medium...?

In any case, glad you resolved your problems! Hope the rest of your Flare experience is a breeze.