Keep different medium styles in same stylesheet or separate?

This forum is for all Flare issues related to styles, stylesheets and XML.
Post Reply
Boone
Propeller Head
Posts: 44
Joined: Thu Jan 31, 2008 10:24 am

Keep different medium styles in same stylesheet or separate?

Post by Boone »

I'm looking for best practice, pros and cons, advice regarding print and html styles. I am working in an department that will be producing multiple Flare projects in several outputs: HTML, PDF, print version of HTML, etc.
What are the pros and cons of: 1) using a single stylesheet with all the needed medium (e.g. print, html) in each style within the stylesheet, vs 2) putting all the print styles in a dedicated stylesheet and all the HTML stylesheets in another dedicated stylesheet.

Does MadCap have a recommended best practice? What factors should be considered when making the decision?
:?:
devjoe
Sr. Propeller Head
Posts: 337
Joined: Thu Jan 23, 2014 1:43 pm

Re: Keep different medium styles in same stylesheet or separ

Post by devjoe »

If your users' workflow includes printing topics from the HTML output, then putting the mediums in the same stylesheet will allow the browser to format the page using the print medium when the user prints the topic.
However, it's more work in some cases specifying the print medium to override little fixes that may apply to the HTML output but are unnecessary in print.
ajpeck123
Propeller Head
Posts: 37
Joined: Tue Mar 07, 2017 6:01 am

Re: Keep different medium styles in same stylesheet or separ

Post by ajpeck123 »

I'm doing something similar, but I'm guessing mine is a later version of Flare (2017 r3) in case that makes a difference. I will try to remember to come back and report on any issues I find... if I don't update, it's working fine. :D

I've decided to separate into 2 css files containing the actual styles and 1 linking them:
  • help.css for the online help pages - the online help targets reference this stylesheet
  • manuals.css for the printable PDFs - the PDF targets reference this stylesheet
  • main.css that simply "imports" the two others - the project references this one.
Rationale:
  • The styles in the HTML output are pretty fixed: h1, h2, p, ul, ol, li, p.notes and some MadCap stuff (expanding text, glossary items and drop-down text) and a simple table without borders. The only images in the help are icons. This product (and help) is subject to rebranding, so only included used styles in the stylesheet saves the developers' time (internal and third-party) as they don't have to understand and convert styles that can safely be ignored. Rebranding can be done without access to Flare, simply by changing fonts, font sizes and colours in help.css. Our help files are single topics linked to from a web page in the application. No navigation, no ToC, no index, no search, no cross-referencing. If you're on a page in the application, the help explains what you need to enter to configure the product.
  • The styles in the PDF output are more likely to require changes... particularly in complexity of tables and in auto-numbering for figures/tables. This stylesheet (especially in the early days of using Flare) is likely to change each time I import a new project with some different tables, etc. If this is also rebranded, it's likely to either be done in-house (by me) or by an external technical author using Flare.
  • Separating the style sheets makes it very easy to see that no changes have been made (accidentally or deliberately) to anything affecting the HTML output (so testing can concentrate on content changes).
  • I believe (I'll find out soon) that linking the project to the stylesheet that imports both will enable me to see both sets of styles by switching between mediums and layouts as I do now. Obviously, to do that, I still need to start the print-based stylesheet with the media query to indicate it should be print (or the styles will simply overrule the online ones, which will confuse me...).
Alison
Lone technical author - Flare user since March 2017
Currently using Flare 2020
Boone
Propeller Head
Posts: 44
Joined: Thu Jan 31, 2008 10:24 am

Re: Keep different medium styles in same stylesheet or separ

Post by Boone »

Let me know how that works out. I found that if I used a single style sheet and just imported the other 2 (my HTML and PDF stylesheets), I was not able to see both sets of styles in the stylesheet editor. If I opened the .HTML stylsheet in the editor, I could see the .HTML styles. If I opened the .PDF stylesheet in the editor, I could see the .PDF styles. If I opened the styelsheet that merely imported both, I could see the HTML and PDF styles - but if I modified them, they did not actually get modified in the source HTML and PDF stylesheets.

Ultimately, I decided that a single stylesheet would be best in my case, because I like being able to open the medium styles side-by-side in the stylesheet editor.
ajpeck123
Propeller Head
Posts: 37
Joined: Tue Mar 07, 2017 6:01 am

Re: Keep different medium styles in same stylesheet or separ

Post by ajpeck123 »

So far so good. I struggled a little in that no matter what medium I picked in the editor, I only saw the HTML stylesheet styles. Appearance wasn't a problem, but lack of classes that didn't exist in the HTML was - I couldn't select p.caution (for example) nor the .keepWithNext or .keepWithPrevious, which I use a lot for the printed output.

A quick email to tech support and I discovered that the editor shows the primary target's stuff... which I didn't expect. I've switched the primary target to the PDF (as that's the superset) and all is well, although I would like to be able to switch between them more easily.

Once the styles have settled down, I may re-merge the stylesheets... but for now, I can *guarantee* that I'm not affecting the HTML ones by mistake.
Alison
Lone technical author - Flare user since March 2017
Currently using Flare 2020
doc_guy
Propellus Maximus
Posts: 1979
Joined: Tue Nov 28, 2006 11:18 am
Location: Crossroads of the West
Contact:

Re: Keep different medium styles in same stylesheet or separ

Post by doc_guy »

In working with many Flare clients over the years, I will say it is very rare that I recommend people use multiple style sheets to deal with media types. It adds an unnecessary layer of complexity for marginal benefit for most people. Especially since in later versions of Flare you can have display multiple media types simultaneously in the stylesheet editor, as you can see in this screen shot: https://www.screencast.com/t/ml6aVOoZEv1D
Paul Pehrson
My Blog

Image
Boone
Propeller Head
Posts: 44
Joined: Thu Jan 31, 2008 10:24 am

Re: Keep different medium styles in same stylesheet or separ

Post by Boone »

Thanks again doc_guy! I believe you also provided insight on my global linking vs template post. I'm glad I'm on your radar!
ajpeck123
Propeller Head
Posts: 37
Joined: Tue Mar 07, 2017 6:01 am

Re: Keep different medium styles in same stylesheet or separ

Post by ajpeck123 »

@doc_guy... Yes, I understand what you're saying. And I think I may well end up merging them once everything is more stable (a simple copy-paste exercise). While I'm still at the stage of getting stuff into Flare (I've done 1 1/2 projects out of a dozen or so various FM / RoboHelp / Word sets), it's easier to keep them separate for the sake of the others in the company rather than me. The help styles are more stable, because although the projects were in separate RoboHelp projects, I'd already standardised the stylesheet. This gives the release engineer a nice cosy feeling - if the help.css file has not altered from the last time it was checked out, there is no need to do any testing of the help output look and feel.

On the other hand, the FM styles are all over the place. They started out as a consistent set (I implemented it 12 or so years ago) but I left and others have added/modified/removed styles to fit the actual document they've been working on. I keep coming across stuff that necessitates a variation to do something someone had previously altered an existing style to do. :-)

The other thing that is slightly different is that the help is actually bundled up as part of the product - I can't alter it unless there is a product release (a side-effect of the environments the products are used in). As the product (and the help) is rebranded by the company, and this is done as a post-build task (replacing some of the colours and so on with variables) not giving them an updated css every 5 minutes is helping keep them feeling that using Flare for all their documentation is less complicated than the mix-and-match they had. On the other hand, (so far) others just get the documentation as-is and choose what to do with it (some only implement a very small subset of the system, so don't want all the configuration options, for example), it makes sense for now to keep them separate.

I'll review this regularly... and will post back if I hit any major snags. Switching the primary target between a PDF one and an HTML5 one sorts out what I see in the editor, and I find I'm not using the Flare CSS editor - I'm opening the file in a text editor instead, so the like to keep all the list styles (for example) together.
Alison
Lone technical author - Flare user since March 2017
Currently using Flare 2020
doc_guy
Propellus Maximus
Posts: 1979
Joined: Tue Nov 28, 2006 11:18 am
Location: Crossroads of the West
Contact:

Re: Keep different medium styles in same stylesheet or separ

Post by doc_guy »

Sounds like you have a good use case for it at this point.

I also agree with your comment at the end about keeping styles together. I usually edit my stylesheet manually, but occasionally I'll use Flare's built-in editor--especially for MadCap specific styles. Keeping like styles together helps understand the cascade inheritance of style properties, and helps you not override styles by defining them in multiple places by accident!
Paul Pehrson
My Blog

Image
NorthEast
Master Propellus Maximus
Posts: 6359
Joined: Mon Mar 05, 2007 8:33 am

Re: Keep different medium styles in same stylesheet or separ

Post by NorthEast »

In my projects I have a large amount of CSS, and I keep this in separate stylesheets.
I do this because it means the styles are 'modular' and I can choose which styles to include with a particular project/output.

The main stylesheet used by each target is simply a container, and contains multiple @import links to all the stylesheets required for that output.

So my 'modular' stylesheets contain styles for a specific purpose, like:
* styles for a particular medium (PDF, HTML5)
* styles for different types of help (help websites, embedded help)
* styles to customise skins (top nav, tripane, side nav)
* styles for use with custom plug-ins/scripts
* custom styles for a particular output (i.e. used in this output only)

I like doing this because it makes it very easy to manage and edit, and I can customise which set of styles I need for a particular output.
ajpeck123
Propeller Head
Posts: 37
Joined: Tue Mar 07, 2017 6:01 am

Re: Keep different medium styles in same stylesheet or separ

Post by ajpeck123 »

@Paul - yes, I had huge problems with styles appearing at odd places. I'd wonder why something wasn't looking the way I expected, would open the .css in a text editor (which is how I'm used to working) and couldn't see anything. Then would find that I'd updated the style at several different times and the *same class* was in more than one place... most of the definitions together (the first pass), then I'd added borders/increased spacing... and that was somewhere else. I found it very confusing. I also didn't like that that editor seemed to put in a lot of (to me) unnecessary stuff. I seemed to get a lot of repetition (border specified all in one, then each border separately...). Maybe it is the way I'm using the editor, but for my own sanity while "tweaking", I prefer the text editor. I *do* use the built in stylesheet editor for the more complex stuff - but almost immediately open the stylesheet, find what I've just added/changed, and put it in the right place. :)

@Dave - the only issue I've had (and it's workable, but annoying) is that the cascade doesn't work so well in Flare's own editor. The project is linked to the top-level stylesheet, which only contains two (so far) import statements. The styles are "read" but based on the primary target. And the problem isn't the visual appearance (although can be a tad disconcerting at times) but the availability of styles. I have far more in the print-based documentation (stuff like the build in .keepWIthNext, .keepWithPrevious and other related concepts, so I'm keeping my primary target as one of the PDF ones. But I've also got a few in the help.css that aren't in the print-based (so .beforeList, which reduces the padding-bottom of text that introduces a list). Depending on the primary target, it's not that I can't see the _effect_ of the medium-specific classes - it's that they aren't there to select! I can see me having to put all in both, even with blank definitions, so I can apply them.
I'd also like to be able to select more than one class to apply from the editor, but haven't found a way to do that (which means at the moment that my .beforeList also contains the instruction to avoid page break after, whereas for true cascade, I'd just have the spacing difference in that class and apply both it and the keepWithNext class to the same paragraph.

Alison
Alison
Lone technical author - Flare user since March 2017
Currently using Flare 2020
NorthEast
Master Propellus Maximus
Posts: 6359
Joined: Mon Mar 05, 2007 8:33 am

Re: Keep different medium styles in same stylesheet or separ

Post by NorthEast »

ajpeck123 wrote:Depending on the primary target, it's not that I can't see the _effect_ of the medium-specific classes - it's that they aren't there to select!
Yep, that'll be the same if you use one stylesheet or multiple stylesheets. The problem is that the editor only shows styles available in the primary target's medium.

One workaround is to include empty copies of these print-only styles to your default/help medium, so they appear for the primary target (but do nothing).
ChoccieMuffin
Senior Propellus Maximus
Posts: 2630
Joined: Wed Apr 14, 2010 8:01 am
Location: Surrey, UK

Re: Keep different medium styles in same stylesheet or separ

Post by ChoccieMuffin »

Dave Lee wrote:
ajpeck123 wrote:Depending on the primary target, it's not that I can't see the _effect_ of the medium-specific classes - it's that they aren't there to select!
Yep, that'll be the same if you use one stylesheet or multiple stylesheets. The problem is that the editor only shows styles available in the primary target's medium.

One workaround is to include empty copies of these print-only styles to your default/help medium, so they appear for the primary target (but do nothing).
I do that, and it works really well. I also make sure that both my Print and Non-Print mediums have things in the same order so I can find them when I open them in a text editor. (I gave up on the Flare stylesheet editor years ago and never went back to it.)
Started as a newbie with Flare 6.1, now using Flare 2023.
Report bugs at http://www.madcapsoftware.com/bugs/submit.aspx.
Request features at https://www.madcapsoftware.com/feedback ... quest.aspx
robdocsmith
Sr. Propeller Head
Posts: 247
Joined: Thu May 24, 2018 3:11 pm
Location: Queensland, Australia

Re: Keep different medium styles in same stylesheet or separ

Post by robdocsmith »

@Paul - viewing multiple media side by side in Flare's stylesheet editor is now officially my favourite thing. Thanks for the tip!

I still find it clunky and non-intuitive for me to edit in the stylesheet editor (my brain just gets how styles work more easily in a text editor), but for seeing what things Flare's defaults are throwing in the mix and how different mediums control those default styles it is invaluable.

My only gripe is it isn't infallible. For example, a <p> element inherits from its parent <body> tag. It's common to set an overall font style in <body> to avoid making the same declarations to all the tags that might live within it. Flare handles the inheritance perfectly of course when displaying or outputting (and even within the display part of the stylesheet editor), but the characteristics aren't shown as inherited in the list of properties in the stylesheet editor.

Rob
NorthEast
Master Propellus Maximus
Posts: 6359
Joined: Mon Mar 05, 2007 8:33 am

Re: Keep different medium styles in same stylesheet or separ

Post by NorthEast »

Flare's stylesheet editor only displays the properties that are set for that element (HTML tag), from the current or imported stylesheets.

The stylesheet editor can't show inheritance from other tags, because that depends on the structure of your topic - which you don't know in the stylesheet editor.
For example, a paragraph tag might be positioned inside multiple tags in that topic - li tags, div tags, etc.

If you want to check inherited styles for a particular item in a topic, select Home > Formatting, and use the Style Inspector tab.
robdocsmith
Sr. Propeller Head
Posts: 247
Joined: Thu May 24, 2018 3:11 pm
Location: Queensland, Australia

Re: Keep different medium styles in same stylesheet or separ

Post by robdocsmith »

Awesome thanks Dave, another thing I didn't realise was there!

Rob
Post Reply