Best way to handle a composite manual?

[chris were]

We have a set of manuals for our software product, loosely defines as Tutorials, Application Notes, and Reference Guide. All in the one hxmp file, using different tables of contents therein.
We also publish the "mother-of-all-manuals" which contains all 3, and we publish to multiple target formats (pdf, chm and webhelp) but we are not sure we are going about this the right way:

We have a main table of contents, as well as separate tables of contents for each "sub-manual".
We are also using build tags, and there's a bit of inconsistency i think how we have approached this, leading to a few problems:

• The Title property is down in common properties... frequently we forget to change this before publishing, so we publish a Tutorials manual with the "Admin Guide" title on the titlepage etc. How can we set the title by either build tags or table of content selection?

• Also, sometimes we have links from one submanual to chapters in another- this works when we publish the combined manual, but the links are broken when we publish the individual sub-manuals. We have developed a workaround for this using a "complete manual" build tag and conditional text, but its a bit messy.

• When we add new topics, we usually need to refernce it from two TOCs, and of course we often forget ...

Any suggestions on how we could better structure this? Our thinking is to ditch the multiple ToC's as a starting point, and rely on the build tags exclusively; is this a better approach? (doesn't solve the title problem though)

Thanks,
Chris

[Tim Green]

Hi Chris,

The Title property is down in common properties... frequently we forget to change this before publishing, so we publish a Tutorials manual with the "Admin Guide" title on the titlepage etc. How can we set the title by either build tags or table of content selection?

I would suggest using either command line publishing or the integrated Publishing Task Manager. In both cases you can define different values for any variables in your project for each build you define. In this case you would put a variable you define in the Title field in the project configuration, for example <%PROJECT_TITLE%>, and then put a different definition of that in each build configuration. You would define the variable in Configuration > Common > Text Variables. Don't try to redefine the default TITLE variable there because it is actually defined by the contents of the Title field.

See these two sections in the help for command line and Publishing Task Manager details:

https://www.helpandmanual.com/help/hm_a ... dline.html
https://www.helpandmanual.com/help/hm_w ... tasks.html

Also, sometimes we have links from one submanual to chapters in another- this works when we publish the combined manual, but the links are broken when we publish the individual sub-manuals. We have developed a workaround for this using a "complete manual" build tag and conditional text, but its a bit messy.

That's not really messy -- it's the correct way to do it. You can then use the same build options for all the differences between your individual builds so that everything gets switched automatically. You can also integrate this in command line or publishing task manager publishing.

When we add new topics, we usually need to refernce it from two TOCs, and of course we often forget ...

That's one of the difficulties of working with multiple TOCs. You do need to have a certain amount of discipline when creating and managing topics that are shared between the TOCs.

I'm not quite clear on whether you have everything in one monolithic project or in separate project modules loaded into a small master project. If you're not using the modular project structure this might give you some additional flexibility. Have a look at this chapter:

https://www.helpandmanual.com/help/hm_a ... dular.html

[chris were]

Thanks Tim, yes I think the tasks and setting of variable there should basically solve our problems; i think we will be able to reduce to a single main TOC and do everything through the build tags and variables. I can see why different tocs may be useful if we were wanting to structure/order the content differently, but in our case i don't think we will need to.

Sorted!

Chris