Flat versus hierarchical ToC in a Command Reference

[kevinmcl]

If a command-line tool has command sets that are nested two-and-three levels deep (a hierarchy), should a Command Reference Guide's table of contents mimic that hierarchy, or should the ToC be flattened to a single layer alphabetical list, with no signposts? I'm being told that "flat like a dictionary" is "the standard". I never knew of such a standard.

Is it possible to have ONE ToC be structured/indented for HTML5 output, and also flattened (all the same entries, but stripped of hierarchy) for PDF output?

I want to let the cow-orker have his way with the flat ToC in the PDF output, but for the HTML5 output, I want to keep my indented, hierarchical ToC.... but I absolutely don't want us maintaining two separate ToCs if we can automate the stripping of hierarchy when PDFs are generated.

Any suggestions to manage that? Any votes on which way you would prefer to see a Help ToC if you were trying to use a command-line tool that had at least three levels of hierarchy?

[Nita Beck]

I can't answer your question about how to maintain different hierarchies with the same TOC, other than to say that for the PDF target, be sure not to use TOC depth and be sure to have all topics start as h1's. (Hmmm, was that an answer? Perhaps, but I think probably not a practical one...)

I've seen command reference guides that were indeed arranged like "dictionaries" or "encyclopedias". I've also seen command reference guides that were arranged into hierarchical structures, perhaps different chapters for different categories of commands. I don't think there's any hard rule; it depends on which arrangement you think will better serve the intended audience.

[kevinmcl]

Hmm. When you said ",,, for the PDF target, be sure not to use TOC depth ..." was that meant specifically in my situation, or is that for ToCs going to PDF in general?

[Nita Beck]

Hmm. When you said ",,, for the PDF target, be sure not to use TOC depth ..." was that meant specifically in my situation, or is that for ToCs going to PDF in general?

The former, but I don't think it's a practical solution. If you needed to create a totally flat PDF, where all topics were at the same level, regardless of how they might be nested in the TOC associated with the PDF target, you would need to do two things: (1) have every topic begin with an h1 and (2) NOT use the "TOC depth" option so that the nesting within the TOC is ignored in the PDF output (but not in the online output that uses the same TOC). But practically speaking, is this what you would want in the PDF?

[Nita Beck]

Hmm. When you said ",,, for the PDF target, be sure not to use TOC depth ..." was that meant specifically in my situation, or is that for ToCs going to PDF in general?

Specifically in your situation, but I don't think it's a practical solution. If you needed to create a totally flat PDF, where all topics were at the same level, regardless of how they might be nested in the TOC that is shared with your online target, you would need to do two things: (1) have every topic begin with an h1 and (2) NOT use the "TOC depth" option in the PDF target so that the nesting within the TOC is ignored in the PDF output (but not in the online output that uses the same TOC). But practically speaking, is this what you would want in the PDF?