variable toclevels

[janicesignalfx]

I'd like to be able to switch my toclevels so that different sections of a document include different levels of toc.

Basically, I have two types of content: conceptual discussion and reference entries. It's helpful to have toclevel set to 3 or 4 for the conceptual bits as those headings are typically specific and meaningful but doing so means that I also get all of the substructure of the reference calls which is a lot of extra, almost identical stuff for entry after entry. It looks like toclevels definitions are only valid in the document heading (which is not unexpected from the documentation). Is there a way to do this? If not, I'd like to request one be added in the future.

Here's an example of what I'd like to be able to do in part of an API Reference (for example):

• Foo Object Overview
  -- Types of Foo Objects
  --- Foo Object Type 1
  --- Foo Object Type 2
  --- Foo Object Type 3
  -- Foo Object Section 2
  --- Blah
  --- Blah
• Create Foo Object
  -- Request
  -- Response
  -- Notes
  -- Examples
  etc

Right now if I want to have the meaningful headings in Foo Object Overview I also have to take the API, function, method, etc subheadings. For instance, I have to choose between:

• Foo Object Overview
  -- Types of Foo Objects
  -- Foo Object Section 2
• Create Foo Object
  -- Request
  -- Response
  -- Notes
  -- Examples
• Update Foo Object
  -- Request
  -- Response
  -- Notes
  -- Examples
  etc

and

• Foo Object Overview
  -- Types of Foo Objects
  --- Foo Object Type 1
  --- Foo Object Type 2
  --- Foo Object Type 3
  -- Foo Object Section 2
  --- Blah
  --- Blah
• Create Foo Object
  -- Syntax
  -- Request
  --- Headers
  --- Path Parameters
  --- Query Parameters
  --- Payload
  -- Response
  --- Headers
  --- Status Codes
  --- Payload
  --- Errors
  -- Notes
  --- Note 1
  --- Note 2
  -- Examples
  --- Example 1
  --- Example 2
  --- Example 3
• Update Foo Object
  -- Syntax
  -- Request
  --- Headers
  --- Path Parameters
  --- Query Parameters
  --- Payload
  -- Response
  --- Headers
  --- Status Codes
  --- Payload
  --- Errors
  -- Notes
  --- Note 1
  --- Note 2
  -- Examples
  --- Example 1
  --- Example 2
  --- Example 3

Being able to go directly to a type of object entry is useful. Having to scroll through headers, payload, etc for every single API call not so much and the TOC gets ridiculously long very quickly.

[elextr]

You can have multiple tables of contents of differing levels and titles using the toc::[] macro:

= foo

:toclevels: 1
toc::[]

== blah
blah

=== f00
foo

:toclevels: 3
:toc-title: the detailed one
toc::[]

(with -a toc=macro on the command line)

Although I personally would like to see toclevels, toc-title etc be parameters to the macro rather than attributes set outside the macro.

Then also add the ability to specify partial TOCs by parameters in the macro, so for example chapter TOCs at the start of the chapter, or for @janicesignalfx use-case per object TOCs at the start of the object description.

[janicesignalfx]

I think you misunderstood my use case (perhaps I wasn't clear; I apologize if that's the case). Per-object tocs would be a perfectly reasonable thing to do. However, I want my main table of contents to use a different number of levels depending on which section's headings are being displayed. See the attached example for how out of hand using level 3 or 4 is with a repeating reference structure but level 2 makes it difficult to find important information in the conceptual bits. And that's just for two reference entries.

toclevels.zip

[janicesignalfx]

Basically what I want is to combine these two:

An alternate approach would be a way to tag certain headings as "do not put in TOC" - I looked for such an option without success (and in doing so I found other requests for this on Stack Overflow with replies indicating it could not currently be done)

[elextr]

I think I might not have explained the proposal clearly.

If I understood correctly you wanted to have differing parts of the same TOC having differing levels, no you can't do that now. But my proposal was to be able to specify partial TOCs so you could have differing levels for differing parts of either, the same TOC (your use-case), or separate individual TOC parts (my use-case).

So a possible future specification for your example above would be:

toc::[until="create foo object", levels="2"]
toc::[from="create foo object", levels="4"]

The syntax for the selection needs to be determined though, thats the tricky part.

[janicesignalfx]

Ah, I see. Thanks for clarifying. I see benefit to having both options, actually (toc::[from="A", to="B", levels=N] or similar plus something like !=== Heading or whatever meaning "omit this heading from all TOC")

[elextr]

Syntax for presentational purposes such as !=== heading violates one of the primary tenets of Asciidoc, its semantic markup, not presentation markup, so I don't think this is a good way. And having more than one set of level markups makes it more difficult to change heading levels with your editor.

(currently an editor that replaces regexen can be move a part of a document up or down by selecting that part and changing ^= to == or nothing in the selection)

However excludes lists (either global and/or local to a toc::[] macro) would be fine.

It should be noted that this sort of functionality is likely to only work for backends that generate the TOC themselves.

[janicesignalfx]

I could argue that it's specifying what to include, not how to present what's included. That said, I wouldn't want you to violate any set standards or break existing behavior.