document restying advice needed

[alansinclair]

I'm tasked with getting good-looking printed document from Robohelp sources, and need advice, please, on the order in which to work. Peter Grainge's Printed Documentation is helpful, but I'm thrashing around in the details.

Our document began as a Word doc, which was imported into RoboHTML to create .CHM online help. It's been hacked around in RH and now the generated printed doc is a bit of a mess, but I have to work with what we've got -- the RH sources (which are .htm files of course.) The doc organization is ok, just the format/styles are a problem.

I have the Word template which the original document came from, but the import into RH seems to have changed most, removing spaces from the style names. So it does not work well when used as the template for "Printed Document Appearance"

When I generate, it seems impossible to map all the project's CSS styles to MS Word styles, because for example the MS Word List Bullet styles are simply not shown in the mapping dialog pulldowns.

Can anyone recommend a strategy for getting to grips with this? I'm less-than-expert with styles & formatting, but understand a bit (my little knowledge no doubt being the dangerous thing here.) I don't mind working topic by topic through the RH source, fixing the styles for each item (should I add missing styles to the CSS?) , but would it be more effective to approach it differently?

[Peter Grainge]

Alan

I have just finished a fourteen hour day so I will not be answering your question tonight. I will try to look at it tomorrow or over the weekend. However, it does not help to start a second thread as I will now have to switch between two posts to answer one problem.

Please consolidate all the information into one post and then I will try to help as soon as I can.

[alansinclair]

Peter

very many thanks for offering help, and my apologies for the duplication. I'll try to summarize here, and hope you can advise me a bit over the weekend, or some other time when you're not overloaded.

1. what the final printed doc needs:

1a. numbered headings in body and TOC, e.g.
1. Header1
1.1 Header2

1b. two-level bullets, e.g.
o Item One
o Item One A
o Item One B
o Item Two

1c. TOC single-spaced (preference, not critical)
1d. Tidied-up styles

2. Problems
2a. mapping e.g Inline Bullets
2b. illegal mapping from paragraph style to list style


3. Possibilities
3a. create new template or modify an existing one
3b. add to or change the RH style sheet


Comments:

1: A week ago the generated Word doc had properly numbered headings, unless I imagined it. But later formatting experiments lost the settings and I haven't found them. (This was why I wanted to find the style mapping template, so I could delete it and start over.)

This evening, using an old Word template, level numbers are ok in the TOC, but there are still no numbers in the body text headers. If I can get headers numbered, without breaking the TOC numbering, then I'll start going through the document styles one by one.

2: The "Map Non-Heading Styles" dialog seems to limit the targets of mapping. If I select the project's InlineListBullet CSS style in the left pane, the right pane pulldown shows various Bullet and List Bullet options. But with the CSS InlineListBullet1 selected, the pulldown shows no bulleted styles at all.

Some templates give multiple messages "illegal mapping from paragraph style to list style", but i can probably eliminate these in the mapping dialog pulldowns.

3: Where to start? Is there a logical way to deal with this, one step at a time? I'm groping for solutions but breaking what I've already done. Any ideas for a systematic approach would be wonderful.

Thanks again. If this is all too vague, well, please excuse it and move on to better entertainment!
Alan

[Kathy_T_Casey]

Alan

I use RoboHELP for two different projects. The first is to generated the online help for our application and I create a .chm for this. As I don't ever need to generated printed documentation from this project, I can use bullets and numbering in RoboHelp styles within any fear of reprisals.

The second project I work with is used to generate training material for the same application which we supply it in a Word format to our clients. I use RoboHELP because we want to be able to generate customised training material for clients using a single source where possible (and the build-tags are great for this). Again, as I'm going to be generating straight to Word, I don't need to worry about the way the style looks in RoboHELP as long as the template I publish to is OK.

Now Word and RoboHELP are both rather bossy when it comes to bulleting and numbering, so if you have bullets in the .css for RoboHELP, it will get pretty messed up hitting a mapped style in a Word template that also has bullets or numbering.

How I get around this is to publish to a Word template which has the appropriate styles (minus any formatting for bullets and numbering). Then I've created a macro that takes all the content of that document and neatly plonks it onto another Word template that has the appropriate formatting in the styles. This works really well for me.

As you need the style for both the RoboHELP format and the published Word format, I would suggest having two style sheets secreted away - both with the relevant styles that will be mapped to Word - one with formatting for online generation (i.e. bullets, numbering, etc) and another with the style (minus bullets and numbering).

You can copy the online .css into the project when you're going to generate the .html side of things and then replace it when you're going to generate the printed documentation.

This should work - just don't try looking at the .html format while you've got the 'vanilla styled' .css in place or you may think things are broken.

Clear as mud, isn't it?

Regards

[Peter Grainge]

Alan

The only way I have got bulleting and numbering to work is, as per my topic, to use the toolbar icons in RH and map to Normal style. The bulleting and numbering carries across better than any other way. You mention that you cannot see the list styles in Word but in my topic I specifically indicate that will not work satisfactorily.

Second I would emphasise the use of the Style Mapping template doing it as covered in the topic. I am not saying other templates will not work but they are the first thing to suspect when things go wrong, no matter how good their provenance.

I wonder if you are reading my topic online. I really would recommend printing that one. It's lengthy so a slow read and making plenty of annotations is the best way to get your mind around it.

Kathy's idea of a macro so that you can apply the bulleting and numbering afterwards to named styles sounds like a good solution too.

Take some time out to work through the problem and the advice slowly. It should fall into place as what you cover is covered in my topic and Kathy's reply. If you are stuck after that, do post back.

[alansinclair]

Thanks Peter -- you're right:

quote:

---

Originally posted by: Peter Grainge I wonder if you are reading my topic online. I really would recommend printing that one. It's lengthy so a slow read and making plenty of annotations is the best way to get your mind around it.

---

I had missed some of your points. Now working more carefully through a printed copy!
I'm still wondering if the Style Mapping template is no longer pristine, and how to get an "original", but maybe that's silly?

many thanks
alan

[Peter Grainge]

It will be dated 21/9/2002 if it has not been modified.

If it has, you could always uninstall and reinstall RoboHelp!

[MergeThis]

See if this thread can help. Setting the OL & UL list styles and using the list toolbar icons seems to wotk better than creating list styles in the RH WYSIWYG.


Leon

[Kathy_T_Casey]

Alan

Being of the 'old' age writing where most of my early documentation was produced and distributed in Word, I use Style for everything.

The training documentation I produce has a lot of How do I? topics and if I use RoboHELP icons and map it to a normal style in Word, it does produce bullets etc but without hanging indents. I really think hanging indents make for better readability of the content, so that's why I experimented and came up with the double-handling of the content using the macro to move it all onto my final template. The output is generated to a Word template that contains the same style names but no bullets or numbering and then the macro moves it onto a template with the proper styles. (I found that when the output was generated directly to a Word template with the proper styles, it just didn't quite work - but when I take that exact same output and move it to the second template it styled really well.)
With regards to the .css, when bullets are applied to a paragraph using the RoboHelp toolbar icons, it doesn't actually change the style in the css - it just changes the style attributes for that paragraph. To get around this, I never use the bullet or numbering buttons - I apply styles instead. (One of the reasons I'd love to be able to use my own keyboard shortcuts for styles other than Heading 1,2, 3 and Normal.)

So if you were going to use the two template idea, you'd have to be really careful that you defined styles in the .css for the online output with bullets and then removed the 'list-style' attribute for the printed output.

There's no reason why you can't edit your style sheet outside of RoboHELP if you're confident in HTML. I find it just as easy to format my styles in RoboHELP and let the application update my style sheets. The .css for the online styles would have a line similar to 'list-style: square;' or 'list-style: decimal' and the .css for the printed output would have the same style name without this attribute.

Just one more thing I use to help me identify what's what - I use colour in the styles of the printed output .css and the first template. I'm so used to the colours now, that when I see blue font in the WYSIWYG pane, I'm actually visualising a bullet point and when I see green font, I'm visualising numbered steps.

Hope this helps.

Regards

[alansinclair]

lots of great help, thanks Peter, Kathy and Leon! I've still a long way to go but your help has got me out of the starting gate.

A couple of difficulties:

1. In the generated .DOC (using the Style Mapping template) somehow the graphics are getting smooshed. Even the width/height ratio is wrong. E.g. Word shows the properties of a graphic as height 72% of original, width 102% of original. Is there some switch or setting needed to preserve graphic properties?

2. Copying the "all-but-the-last-pillcrow document" from the generated template to a new template works to get the format styles better, but loses the graphics entirely. This could be the same problem as 1? Is there any option to set which will make graphics "embedded" in the document?

[Kathy_T_Casey]

Alan

On the very first screen of the Printed Documentation wizard there's a radio set Embed in documents (images are inside the document). If you select this, the graphics should move from the initial output into the new template with no problems.

With the sizing issue, Word will automatically resize graphics to fit into the document margins, so you may want to look at that.

Regards

[alansinclair]

thanks Kathy, that's helpful

quote:

---

Originally posted by: Kathy T Casey
I would suggest having two style sheets secreted away - both with the relevant styles that will be mapped to Word - one with formatting for online generation (i.e. bullets, numbering, etc) and another with the style (minus bullets and numbering).

---

dumb newbie questions: Looking at the CSS, I don't see anything (except the style name) that specifically says "bullet", so does the second CSS (with style, minus bullets and numbering) include named styles such as "inlinebullet" that are just vanilla format, or are those named styles eliminated from the CSS file entirely? And can/should the CSS files be edited directly in a text editor to remove the bullet styles, or does this need to be done from within RH?

thanks again for the help
alan

[alansinclair]

Hi Kathy

thanks so much -- I just found it and came back here with a red face to admit it!

Alan

[Kathy_T_Casey]

Alan

Not to worry - RoboHELP is very powerful with lots of different permeations available - however, once you've got it jumping the way you want, I find I seldom have to fiddle - it becomes a fairly automated process.

Good luck!

[alansinclair]

Our doc is getting into better shape now, thanks to all the help, but there's a problem in the TOC which I'd appreciate advice about. I'm using the (unchanged) Style Mapping template.

The TOC is ok except for the header 1 items, which come from the book names; the books don't have linked topics.
For each line of the TOC except H1 lines, there's the level number, then the name, then dots and finally the page number. But the H1 levels have the level number twice, then the dots, then the name and page number. On the H1 lines, there are too many dots, so the page number (but none of the words of the name) is pushed onto the next line.

It looks something like this:

3. 3. ..........................................Understanding the Manager
19
__ 3.1 The FairShare Manager .......................................... 20
__ 3.2 Opening the Manager

(underscores are not in the TOC, they're just here to show spacing)
where Understanding the Manager is a book / heading 1

Where might I begin to tweak things to fix this?

thanks
alan

[Peter Grainge]

Maybe you need to adjust the margins to stop the wrapping but style mapping.dot is usually OK.

I suspect the cause is the double numbering you describe. Not sure why that is happening. Have you tried right clicking and selecting Update Field?

[alansinclair]

Update field / Entire table does change the TOC appearance, but not quite to what's wanted! It fixes the wrong line wrapping, but it removes the level numbers that were beside each TOC entry, except for the initial numbers beside the book items. Incidentally, the book items are all style TOC 1, the rest are TOC 2 or TOC 3.

I.e fresh from generation the TOC looks like

3. 3. ..........................................Understanding the Manager
19
__ 3.1 The FairShare Manager .......................................... 20
__ 3.2 Opening the Manager
(underscores not in the TOC, just show spacing)

and after Update entire table TOC looks like this now:

3. Understanding the Manager.......................................... 19
__ The FairShare Manager ............................................... 20
__ Opening the Manager (etc)

After Update entire table, does the TOC have format from the TOC n styles in the Style Mapping.dot template? Where would the TOC n style come from before doing Update entire table? (Update field / Page numbers doesn't make any difference, btw.)

The initial number on the book items (e.g the first '3' above) is unlike the other numbers in the TOC, in that it doesn't have a grey background when the field is active. All the rest of the TOC has grey background, so it's as if the initial numbers are not actually part of the TOC at all.

Would the Style Mapping styles be the place to try changing this behaviour? I'd hate to break what's working by hacking the wrong template.

thanks!
alan

[Peter Grainge]

That is the correct template. You need the copy in your project as that is the one now being used. Take a backup copy first.

This behaviour though is unusual so I am not convinced it is the template, unless you played around with it earlier!

Create a new project with a few topics and see what happens there. It is often easier to figure what is going wrong in a small project that is clean. Plus if you break it, it doesn't matter.

I won't be posting much over the next couple of days so don't think I am ignoring any reply you post. I'll catch it later if no one else steps in.

[alansinclair]

thank you Peter

The same does happen in a fresh, new project, even to the extent ot Update / entire removing the level numbers except the Books' (TOC 1) duplicated numbers. As suggested I'll experiment some more with the new midget project.

Maybe the TOC 1 style has some kind of numbering associated with it, which I'll try and change (not sure how yet, because although the Normal view sidebar shows the style as TOC 1, when I click on the item, Word's style toolbar shows the style as being 'hyperlink' not TOC 1.)

[Kathy_T_Casey]

Alan

I don't know what's going on with the double numbering of Heading 1, but it looks like the TOC1 style needs a second tab set. If you look at the style for TOC1, you'll probably find that there's a tab set somewhere towards the right-hand side of the page (e.g. 13.00 cm) with the following attributes: Alignment = Right, Leader = 2......
It should also have a tab set somewhere towards the left-hand side of the page (e.g. 2.5 cm) with the following attributes: Alignment = Left and Leader = 1 None.
If you update the style to set the tabs correctly, it should format OK.
Just out of iinterest, how does the Heading 1 look in the actual document? Does it only have the outline numbers appearing once? It seems pretty bazaar behaviour.

Regards

[Kathy_T_Casey]

Alan

I don't use outling numbering for my current projects and all my books are linked to topics. But as you mentioned, it's worth looking at the Numbering attributes assigned to the TOC style. There should be no auto numbering assigned to any of the TOC styles if you are using outline numbering in your document. Therefore, if you look at Modify > Style > Numbering for TOC1 (and all the other TOC styles), it should be set to 'None'.

I just thought of another circumstance that causes this sort of behaviour with the TOC entries.

If the left hand tab is too small, this can happen. So, if both tabs are set in the style, it probably means that the left tab is set for a position smack-bang in the middle of where the double-numbering is happening. If you dragged the left hand tab out a bit (past the auto numbering), you'd find that Word can then use it for placing the text.

I've been changing things in my doco to try to replicate this issue and I can't make it happen. However, like Peter, I tend to think that the style problem in the TOC is more likely to be occuring due to the double numbering.

Regards

[alansinclair]

quote:

---

Originally posted by: Kathy T Casey
However, like Peter, I tend to think that the style problem in the TOC is more likely to be occuring due to the double numbering.

---

The tabs in TOC 1 style are ok. The problem is definitely due to the TOC1 style having outline numbering (only TOC1, not the lower levels). If I change TOC1 style to have no numbering, it looks fine.

quote:

---

Just out of interest, how does the Heading 1 look in the actual document? Does it only have the outline numbers appearing once? It seems pretty bazaar behaviour.

---

Headings in the generated document have no outline numbering (though it's needed so I'll add numbering later, with a macro.)

I've put a clean copy of the original Style Mapping.dot template into the new project's directory:
09/21/2002 04:04p 94,208 Style Mapping.dot

Looking inside the new Style Mapping.dot template, the TOC1 style is shown as having outline numbering! No idea why! But anyway, I changed Style Mapping's TOC1 style to have no numbering, and generated the small new project document again -- and once again it gets TOC1 style that includes numbering. aarrggh.

I'm getting confused. Any ideas where the style could be coming from? I checked in Style Mapping again, and TOC1 definitely does NOT have numbering there now. Robohelp's "Print Document Appearence - Printed Documentation" dialog has Style Mapping.dot as the Word template. Could RH be picking up Style Mapping.dot from some other directory? Tomorrow I'll pursue this line...

thanks!
Alan

[Kathy_T_Casey]

Alan

I just created a very small project trying to replicate this issue (as I don't use Style Mapping.dot) for my output - I also have topics assigned to each of my books).

So in the new project, I created a book in the TOC with no link to a topic, then added topics under that. I changed the TOC1 style in the Style Mapping.dot template so that it didn't have Outline numbering and then I changed the styles for Heading 1, 2, 3 etc so that they did. I also made sure that each of the topics under the book started at Heading 2 (as the Book will be Heading 1).

When I publish to the template, the TOC doesn't have any numbering at all but the headings in the document do. So if I regenerate the TOC, it's brings in the correct outline numbering.

Regards

[alansinclair]

Kathy

Thank you so much for all the help, and all time you've spent on my problem. It's very kind of you.

I repeated the steps you took with making a new project. At first attempt, the TOC was still wrong, but after removing and reinstalling Robohelp X5 the new project generated the TOC correctly. (Outline numbering in Style Mapping.dot's header styles isn't being carried through into the headers in the generated doc, but I can handle that later) So it seems something was broken in RH before.

Unfortunately the newly-installed RH has a different problem generating the project that must be single-sourced: The generated doc shows a lot of what look like field codes on all heading3 items. They aren't real field codes, because pressing Alt+F9 reveals the actual field codes (and the non-real ones are still visible.)

I started from a saved copy of the project (saved before trying printed doc generation using any templates or style mapping, so hopefully free of my bodges) and the Style Mapping.dot template was copied (by RH) from the newly installed RH directory into the project directory. The generated doc looks like this:

1. Undertanding FairShare
__ 1.1 FairShare Overview & Key Concepts
____ 1.1.1 { XE "QoS " \* MERGEFORMAT }{ XE "NetworkJustice FairShare " \* MERGEFORMAT }{ XE "FairShare " \* MERGEFORMAT } FairShare Overview

These "unreal field codes" are not visible on when printed on paper, nor after converting to PDF, but they now appear in the doc even when generated without a template ("none" - use projects CSS styles). We ship in PDF form, but it's a bit too freaky a problem to ignore -- my reviewers work with soft copy and really won't like seeing it like this!

Should I start a new thread to ask about this new problem?

again, grateful thanks to Kathy and to Peter and Leon for all the help
Alan

[Kathy_T_Casey]

Alan

It just gets curiouser and curiouser doesn't it?

Do the fields disappear when you hide the formatting marks using the Show/Hide button on the toolbar in Word?

Regards