Master Stylesheets

[betelgeuse]

Hey All,

I've been working with Flare for about 4-5 months now, solely in print outputs (PDF). I am now at the stage in my project where I am looking at producing HTML5 output.

However, I'm a little confused by Flare's use of stylesheets on each target. I want to use two different stylesheets, one for Print and one for HTML5. I have a User Manual with two Targets: a HTML5 Target and a PDF Target. On each of the Targets, I have specified different master stylesheets;

- On my PDF Target, I have the master stylesheet set to my Print Stylesheet
- On my HTML5 Target, I have the master stylesheet set to my HTML stylesheet

However, when I view a topic in my User Manual, it will display the topic in the style of the HTML5 (this is my primary target) stylesheet on BOTH Print Layout and Web Layout views.
I was expecting that when I switched to Print Layout, it would display the topic in the style of the Print Stylesheet, and when I switched to Web Layout, it would display the topic in the view of my HTML5 Stylesheet.

Am I missing something very obvious??

Thanks

Matt

[Msquared]

No, you're not missing anything obvious. Print layout just displays your output as pages, with margins, headers, footers etc, whereas Web layout shows it as continuous full-width text.

If you have a single stylesheet with different mediums for your different outputs, then you can select the medium you want from the Medium drop-down. But if you have separate stylesheets (as I do) then the only way to view the topic in Flare's XML editor in the output style is to switch your primary target to that style. As you correctly say, the stylesheet used in the Flare editor comes from the primary target. If you are doing a lot of work in one target, you may like to switch the primary target . . .

But there is another way to preview your work. Just to the left of the Web Layout/Print Layout button is what looks like a "Print Preview" button. It's actually "Preview As" and if you select the drop-down beside that you can select a target and preview the output as that target, complete with variable substitutions, conditions applied etc. That is one of Flare's better kept secrets and I use that a lot.

[betelgeuse]

Thank you Marjorie, that's very helpful.

Do you think that Flare SHOULD display different stylesheets depending on whether you have the Layout (web) or Layout (print) selected?
For those of us who use two stylesheets (one for Print and one for HTML5), it would be handy to be able to associate the relevant stylesheet with the appropriate view.

I'm thinking that I may log this as a feature request if others agree it would be helpful.

Many Thanks,

Matt

[ChoccieMuffin]

I think Flare assumes that the default is to have a single stylesheet with multiple mediums, so it's doing what it's supposed to do. It does make the workflow a little bit simpler if you have properties that apply to both mediums as you can edit them in the default, but that's a personal choice and having separate stylesheets does have advantages too.

[doc_guy]

Help me understand the use case for separate style sheets. I really like that Flare uses the same style sheet for printed and web-based targets. I also like that with one style sheet, if people print a topic from the webhelp output, the printed output's format looks similar to the PDF target.

Clearly you have a good reason for separating... that's why you are doing it but I'd love to learn what advantages you see in separate style sheets.

[betelgeuse]

Hey ChoccieMuffin, I see your point.

Hey Paul,

I'll be honest, I'm far too inexperienced to be able to provide the pros and cons of working with two stylesheets over one stylesheet, maybe someone could outline those for me?

The only reason we have two stylesheets is because the author who managed this project before me, created two stylesheets - one for Print, one for HTML5. Our focus until now has been Printed output, but now we are in a position to develop our online content. We will be re-skinning our online content, so that it will not look like typical Flare output, I believe this was initially the reason why the stylesheets were kept separate, although I'm beginning to realise that having two stylesheets is not necessary for our particular user case.

Thanks

Matt

[NorthEast]

The Layout option in the XML editor basically just sets the medium - to '(Default)' for Web layout, and 'print' for Print layout.
So it'll only reflect what your project looks like if you use mediums in your stylesheet(s), and those particular mediums for your targets.

I use several mediums in my projects, but I don't use either '(Default)' or 'print' for any of them, so the Layout option is pretty much useless to me; it effectively just lets me show/hide the print page layouts.

Regarding the stylesheet, the XML editor shows the stylesheet(s) linked in the topic, or the master stylesheet if one has been set in the primary target or project. It won't take into account any stylesheet links that are in the master page used by the target.

So in summary, the Layout option will only represent what your web/print targets look like if you configure your project in that very particular way.


Anyway, the way you've described your scenario, it would seem to make more sense to have the styles used for each target in different mediums, then you don't have to switch between stylesheets.

(Note that the mediums don't necessarily have to be in the same stylesheet; my standard project set up has 11 stylesheets and 6 mediums, as I like to keep different parts of the CSS separate.)

[betelgeuse]

Dave, thanks. My entire time with Flare up until this point has been PDF printed output only, so I'm entering uncharted territory, but you have helped clarify it.

I just have one question if I may.
You said;

(Note that the mediums don't necessarily have to be in the same stylesheet; my standard project set up has 11 stylesheets and 6 mediums, as I like to keep different parts of the CSS separate.)

If I decide to separate my CSS into multiple stylesheets (for each medium), and then I point my targets at said stylesheets, will my Medium view only show the css relevant to the Primary target? Hope that makes sense.

Thanks

Matt

[Msquared]

@doc_guy. In a word, ease of maintenance.

I have separate stylesheets for each "medium". This was a carefully considered decision (admittedly made when I was a Flare newbie) but I'm so glad I did it. I single source for two different styles (our own and a reseller that needs our documentation rebranded to their corporate style). I also single source web and print content. So I have four stylesheets. I have over 100 styles (I know some would say that's too many, but believe me, most are necessary). I edit my stylesheets using Notepad++ as I find the Flare stylesheet editor too restrictive and fiddly to use (except when I'm seeking inspiration and want to see what properties are available for a style. I have set my stylesheets up with plenty of comments and they can be easily be compared using a file comparison utility to spot differences. So when I'm adding and modifying styles as I am today, I just get them correct in one stylesheet, then I can easily see where changes need to be applied to the others.

This may not be so relevant to authors in big teams where there are probably people whose sole job it is to maintain stylesheets, but here there is only me, and I like to keep things simple and set things up so errors and omissions are minimised and easy to spot when they occur.

@betelguese - as I said, either use Preview As to see what my output is like, or if I'm doing a lot of work on a particular stylesheet (as you obviously are), I temporarily set my primary target to a target that uses that stylesheet. In fact, the primary target per se isn't that useful a concept to me - I have multiple targets in a project, and there is nothing I do where having a primary target defined would be helpful, except when viewing files in the Flare editor. So I'm happy to use it to control that.

[NorthEast]

If I decide to separate my CSS into multiple stylesheets (for each medium), and then I point my targets at said stylesheets, will my Medium view only show the css relevant to the Primary target? Hope that makes sense.

If you want to keep the mediums in separate stylesheets, then I'd suggest using this kind of structure (which is what I use):

1) Put styles for each medium in separate stylesheets; e.g. medium_default.css, medium_pdf.css, medium_help.css.

2) Create a main stylesheet; e.g. main.css, and use this to import the other stylesheets; e.g.:

Code: Select all

@import url('medium_default.css');
@import url('medium_pdf.css');
@import url('medium_help.css');

3) Set your topics to use the stylesheet main.css.
Styles from all the imported stylesheets will be available in the editor, according to the medium you have selected.

[NorthEast]

@doc_guy. In a word, ease of maintenance.

I'd agree with this. Whilst I don't have 100s of 'selectable' styles, I do have about 3000 lines of CSS. So I partition this into separate files; such as for different mediums (I have 6), or CSS that does a particular job such as font-face definitions, or fixes to MadCap-specific styles.

I find it makes it a lot easier to find/maintain styles. It also makes it very easy to include/exclude each of these sections of styles from a target.

[betelgeuse]

Marjorie, Dave, thanks for explaining it to me, makes a lot of sense.
You've been a big help, appreciate it.

Matt

[Msquared]

I like your idea of using one stylesheet that imports the others Dave. I will consider doing something similar one day. The two stylesheets that I have open in Notepad++ at present are 1600 and 2000 lines respectively, but some lines are comments.

Your approach of having a single overall stylesheet is tidier for another reason too. That's the way that table stylesheets work, because they have to. Unlike an ordinary stylesheet which can be applied at target level, and hence can be different for each target if required, the table stylesheet is specified when a table is placed in the topic. So if you want different table styles to be used for the same table in different targets, then you have to use mediums within a single table stylesheet because you cannot specify table stylesheets at the target level.

So I do use mediums in my table stylesheets as I have to. So that means if I want to view a topic in the Flare editor as it would (sort of) appear in the output I currently have to set the layout, the medium, the page layout/master page AND the primary target. Your solution would mean there would be no need to switch the primary target.

And, in principle, I could use the same method to split a table stylesheet up into separate files for each medium. That would make the maintenance of table stylesheets a bit easier (although I don't edit them often), and would lessen the chances of Flare breaking the stylesheets when it upgrades them for each release (Flare always seems to want to upgrade the table stylesheets for each release - the last time it kept the same styles, but redistributed them around the various mediums and row styles, so for example, Medium A sub header style become medium B's body style etc. Hours of fun fixing that . . . ).

[pdenchfield]

As long as we’re talking about CSS best practices, here’s a question for those of you who translate content.

Do you separate the localizable text as a separate stylesheet? Strings “Chapter,” “Figure,” “Table,” “on page” for xrefs, and so on.