Delineator/separator in TOC - chapter without text?

[Dave Gehman]

I'm looking to create delineators / separators in WebHelp TOC, something like this:

Topic A
Topic B
-----------------
Topic x
Topic y
Topic z
-----------------
Topic J
Topic K

Is this a potential use for the "Convert to chapter without text option" when right-clicking on a TOC entry? I see that this is 'deprecated' and 'not recommended' so I hesitate to experiment.

Or is there another way to achieve a separator?

[Tim Green]

Hi Dave,

There isn't currently a way to insert separators like that in the WebHelp TOC. You might be able to hack the TOC CSS to achieve it, but you'd need a trigger in the topic ID that you could access with a CSS3 selector. For example, if you started or ended the ID of each topic after which you wanted a divider with "ncp_" or "_ncp" then you could access that with these CSS3 selectors:

Code: Select all

Start string:
a[href^="ncp_"] { CSS configuration here }

That would select topics with IDs like "ncp_introduction" and so on.

Code: Select all

End string:
a[href$="_ncp.htm"]

That would select topics IDs like "introduction_ncp", and here you also have to include the extension because that is included in the reference.

If you're doing this with the V3 skins they don't use a tags or href references. There you need to write it differently:

Code: Select all

Start string:
li[hf^="ncp_"] { CSS configuration here }

You can find a good reference to CSS3 selectors here:

https://www.w3schools.com/cssref/css_selectors.asp

You need to put your CSS in the TOC template or in the CSS file(s) used for the TOC if there is one. No guarantees here -- I've never played with this, that is just the basic approach you'd need to take.

Is this a potential use for the "Convert to chapter without text option" when right-clicking on a TOC entry? I see that this is 'deprecated' and 'not recommended' so I hesitate to experiment.

Definitely not, because those are only nodes in the TOC that don't have any topic references, and there would be nothing there that you could "grab" as an identifier to select them with CSS. The reason topics without text are discouraged is because they create a bad interface experience for the user in layouts with a separate table of contents. When they are selected either nothing happens in the topic pane -- the user just goes on seeing the topic that was already displayed -- or the first topic of the chapter represented by the chapter without text is displayed. Both are equally confusing. In addition to this, there are formats where they are literally forbidden, such as ePub/iBooks and Kindle eBooks. On the other hand, they do make sense in paper formats like PDF and Word, where there aren't any separate topics, just one long scroll of virtual paper or printed pages.

On a more general note, you'll find that with time you will do less and less of these "cool additional details". I can absolutely understand the enthusiasm, because it's a lot of fun to do things like this when you first discover all the possibilities. However, they also have drawbacks that become more apparent with time. Every custom solution you create is one more thing that you are going to have to maintain and keep updating for a long time, in addition to all the time it takes to create it in the first place. Sometimes it's worth it, but you need to weigh the overheads against the real benefits. As a general rule, the simpler everything is, the better.

[Dave Gehman]

On a more general note, you'll find that with time you will do less and less of these "cool additional details". I can absolutely understand the enthusiasm... As a general rule, the simpler everything is, the better.

Thanks. It's not my enthusiasm. I work for engineers, and engineers are masters of 'creeping featurism,' the addition of bells and whistles to toys (e.g., automobiles).... and for most engineers, simple is rarely an objective.

But in our case, we are not really looking to add a cool feature. We h ave 3 distinct sections of our help file (training; concepts; reference) and a visual means of delineating them would be useful.

Would we be best served by creating 3 help files? If so, can a discrete "training" help directly link to words / phrases / topics in discrete "concepts" or "reference" help files?

[Tim Frost]

Have you considered only having three main topics and making all your current topics their children?

[Simon_Dismore]

engineers are masters of 'creeping featurism,' ...and simple is rarely an objective.

What a glorious slur on engineering!

Joking aside, there might be a genuine UX argument for distinguishing "concepts", "training", and "reference". But if that's worth doing, you should carry it through everywhere as a unifying design principle, not just have a line separating the TOC sections. You might want different icons or text/background colour, in all the content links as well as in the TOC, with a matching colour scheme for topic headers etc. That would give you flexibility to interleave concept, training and reference material, rather than divide it into three monolithic sections.

I think Tim's topic naming CSS could take care of almost all that. And if you went for the full version of Zoom indexer, you could index the search text by category.

[Dave Gehman]

Thanks, Tim. We've done that from the first, but our help file is getting complicated. Once people open a number of child topics, the TOC gets hard to read quickly.

If I could show the highest level in a contrasting color, that would help. If I could separate/delineate the parent topics, that would help... but at the same time, I'm not eager to futz with the WebHelp TOC file code for the reasons that Tim Green raised -- you have to go into it with every new publish action.

[Dave Gehman]

What a glorious slur on engineering!

Ah, it's more to do with marketing and time pressures. Ever more cool new features are in demand thanks, I firmly believe, to the failure of education to draw out the rare ability to discern fashion from substance. But that's a different topic, centuries old, and never solved.

Elegant, simple design - a mark of superior engineering - takes time that's no longer available in most markets.

Joking aside, there might be a genuine UX argument for distinguishing "concepts", "training", and "reference". But if that's worth doing, you should carry it through everywhere as a unifying design principle, not just have a line separating the TOC sections. You might want different icons or text/background colour, in all the content links as well as in the TOC, with a matching colour scheme for topic headers etc. That would give you flexibility to interleave concept, training and reference material, rather than divide it into three monolithic sections.

I think Tim's topic naming CSS could take care of almost all that. And if you went for the full version of Zoom indexer, you could index the search text by category.

Do I have color available... with or without the superfluous 'u' ... in the WebHelp TOC? That is, without rummaging around in the published TOC code? I may have missed a big solution.

Meanwhile, I'll look in to Zoom indexer.

Thanks,
Dave

[Simon_Dismore]

Do I have color available in the WebHelp TOC?

Yes, you can use Tim's technique to add color to hyperlnks in the TOC and in topic content pages. Here's how I tested that (click on each screenshot so it is fully displayed):

(1) Create project with distinct prefixes for sections. In the case concept, training, and reference

Creating section styles project.png

(2) Publish and use developer tools in your browser to see what markup H&M adds to links (which might vary if you are using Premium Pack features)

Markup in browser.png

(3) Use Tim's technique to define CSS that targets these links

(4) Add this CSS to the topic template (assuming you aren't using Premium Pack features)

Topic CSS to detect beginning of href.png

Continue with my next post (only three attachments are allowed per posting here).

[Simon_Dismore]

continued from my previous post

(5) Add the same CSS to the TOC template

TOC CSS to detect beginning of href.png

(6) Save and republish

(7) Output will look like this:

Browser output with modified CSS.png

(8) Unfortunately this doesn't help color the topic title ("Concepts" in this case). If you only have three categories you could create three separate HTML page templates for them, or you could link the topic title to its own entry in the TOC, like this:

Browser output with modified CSS plus topic title links to topic in TOC.png

Hope this helps. You can extend the technique to distinguish different levels too (using a class selector for "heading1" etc). Obviously you could (should) use more subtle styles in your project. I tested this with vanilla webhelp, it will probably need tweaking if you are using Premium Pack skins.

[Simon_Dismore]

And just for completeness here's an example of topic-based coloring being used in a TOC that's organised by theme rather than type of content:

TOC organised by theme rather than type of content.png

All I had to do to achieve that was create a duplicate TOC and move the links around: the coloring followed automatically without any need to modify the CSS. That's the great advantage of the technique Tim suggested.

[Dave Gehman]

Thanks for the very detailed documentation. Believe me, I'll be revisiting my work to see if it's anywhere near your thoroughness.

I'll pass this along to our CSS experts, who are currently buried amid constant changes to both the UI of the program I'm documenting and the graphic design of marketing materials. Yes, we are constrained to document it long before even a decent beta stage has occurred. The changes should ease off by summer.

The process might be a step too far if it has to be redone with each new Publish sequence or H+M revision update, mainly because documentation creation may soon be spread across two (or more) people.

I have to admit, I yearn for simple UI-based switches available on a right-click on the TOC...

But, at any rate, many thanks for taking the time to show me all the steps.

[Simon_Dismore]

The process might be a step too far if it has to be redone with each new Publish sequence or H+M revision update

That's not necessary. Once the CSS is working (it can be a separate style sheet so your CSS experts can maintain without needing access to H&M) it will continue working so long as you continue a standard convention for topic names.

I yearn for simple UI-based switches available on a right-click on the TOC

Entirely agree. It should be possible to apply custom classes and/or data-attributes to mark up any object in H&M, e.g. TOC captions (Topic Status should be published as a class too), media, tables, linked snippets, styles.

[Tim Green]

Hi Simon,

It should be possible to apply custom classes and/or data-attributes to mark up any object in H&M, e.g. TOC captions (Topic Status should be published as a class too), media, tables, linked snippets, styles.

The reason this isn't done more is the desire to maintain consistency across the different output formats, along with simplicity. It would be another matter if HTML was the only output format, but with multiple formats as soon as you provide something like that for HTML you create the expectation that it will also look like that in PDF and DOCX and eBooks (which are also HTML, but still different in sometimes shocking ways).

[Martin Wynne]

You can do almost anything you like with H&M, if creating HTML output. And make it relatively easy to maintain/update.

For example, the Publishing Task Manager includes an option to add Build Events to a publishing task. Which means you can write a Windows utility exe to parse/edit any of the H&M created files any way you wish after compilation.

I'm currently writing a utility to add mouse-over tooltips from a text file to the TOC items. It would be possible to add functions to provide coloured backgrounds, separators, section headings, etc.

For example, a TOC tooltip containing the string !%sep:yes bgnd:pink hdng:BEFORE YOU START%! could insert a separator, a heading BEFORE YOU START, all on a pink background until it reaches a TOC tooltip containing the string !%bgnd:end%!. The trigger strings being removed from the tooltip in the process.

Other stuff could be added, maybe !%high:yellow%! to highlight a TOC entry with a back colour.

It will be useful for my own work. I will post it here when I'm done if anyone is interested. I know Dave wants the mouse-overs.

cheers,

Martin.

[Dave Gehman]

.... Which means you can write a Windows utility exe...

Thanks, Martin. Sad to say, I have mastered how to make an EXE run, but actually creating one... it's not in my repertoire...

I'm currently writing a utility to add mouse-over tooltips from a text file to the TOC items. It would be possible to add functions to provide coloured backgrounds, separators, section headings, etc.... It will be useful for my own work. I will post it here when I'm done if anyone is interested. I know Dave wants the mouse-overs.

Indeed yes. It would greatly enhance our (unfortunately) complicated help output for our (unfortunately) extremely complex program.

Many thanks,
Dave