Delineator/separator in TOC - chapter without text?
Moderators: Alexander Halser, Tim Green
-
- Posts: 575
- Joined: Sat Sep 23, 2017 9:05 pm
Delineator/separator in TOC - chapter without text?
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?
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
- Site Admin
- Posts: 23189
- Joined: Mon Jun 24, 2002 9:11 am
- Location: Bruehl, Germany
- Contact:
Re: Delineator/separator in TOC - chapter without text?
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:
That would select topics with IDs like "ncp_introduction" and so on.
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:
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.
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.
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 }
Code: Select all
End string:
a[href$="_ncp.htm"]
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 }
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.
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.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.
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.
Regards,
Tim (EC Software Documentation & User Support)
Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
Tim (EC Software Documentation & User Support)
Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
-
- Posts: 575
- Joined: Sat Sep 23, 2017 9:05 pm
Re: Delineator/separator in TOC - chapter without text?
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.Tim Green wrote: 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.
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?
Re: Delineator/separator in TOC - chapter without text?
Have you considered only having three main topics and making all your current topics their children?
-
- Posts: 206
- Joined: Thu Jul 13, 2017 2:57 pm
Re: Delineator/separator in TOC - chapter without text?
What a glorious slur on engineering!Dave Gehman wrote:engineers are masters of 'creeping featurism,' ...and simple is rarely an objective.
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.
-
- Posts: 575
- Joined: Sat Sep 23, 2017 9:05 pm
Re: Delineator/separator in TOC - chapter without text?
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.
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.
-
- Posts: 575
- Joined: Sat Sep 23, 2017 9:05 pm
Re: Delineator/separator in TOC - chapter without text?
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.Simon_Dismore wrote: What a glorious slur on engineering!
Elegant, simple design - a mark of superior engineering - takes time that's no longer available in most markets.
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.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.
Meanwhile, I'll look in to Zoom indexer.
Thanks,
Dave
-
- Posts: 206
- Joined: Thu Jul 13, 2017 2:57 pm
Re: Delineator/separator in TOC - chapter without text?
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):Dave Gehman wrote:Do I have color available in the WebHelp TOC?
(1) Create project with distinct prefixes for sections. In the case concept, training, and reference (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) (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) Continue with my next post (only three attachments are allowed per posting here).
You do not have the required permissions to view the files attached to this post.
Last edited by Simon_Dismore on Thu Feb 07, 2019 2:05 pm, edited 3 times in total.
-
- Posts: 206
- Joined: Thu Jul 13, 2017 2:57 pm
Re: Delineator/separator in TOC - chapter without text?
(5) Add the same CSS to the TOC template (6) Save and republishSimon_Dismore wrote:continued from my previous post
(7) Output will look like this: (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: 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.
You do not have the required permissions to view the files attached to this post.
-
- Posts: 206
- Joined: Thu Jul 13, 2017 2:57 pm
Re: Delineator/separator in TOC - chapter without text?
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:
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.You do not have the required permissions to view the files attached to this post.
-
- Posts: 575
- Joined: Sat Sep 23, 2017 9:05 pm
Re: Delineator/separator in TOC - chapter without text?
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.
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.
-
- Posts: 206
- Joined: Thu Jul 13, 2017 2:57 pm
Re: Delineator/separator in TOC - chapter without text?
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.Dave Gehman wrote:The process might be a step too far if it has to be redone with each new Publish sequence or H+M revision update
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.Dave Gehman wrote:I yearn for simple UI-based switches available on a right-click on the TOC
- Tim Green
- Site Admin
- Posts: 23189
- Joined: Mon Jun 24, 2002 9:11 am
- Location: Bruehl, Germany
- Contact:
Re: Delineator/separator in TOC - chapter without text?
Hi Simon,
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).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.
Regards,
Tim (EC Software Documentation & User Support)
Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
Tim (EC Software Documentation & User Support)
Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
- Martin Wynne
- Posts: 2656
- Joined: Mon May 12, 2003 3:21 pm
- Location: West of the Severn, UK
Re: Delineator/separator in TOC - chapter without text?
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.
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.
-
- Posts: 575
- Joined: Sat Sep 23, 2017 9:05 pm
Re: Delineator/separator in TOC - chapter without text?
Thanks, Martin. Sad to say, I have mastered how to make an EXE run, but actually creating one... it's not in my repertoire...Martin Wynne wrote:.... Which means you can write a Windows utility exe...
Indeed yes. It would greatly enhance our (unfortunately) complicated help output for our (unfortunately) extremely complex program.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.
Many thanks,
Dave