Allow user to specify maximum depth at which section numbering occurs in both the main document and the TOC.

[phelps-sg]

When --number-sections is specified, there is no way to specify that sections below a certain depth should not be numbered. The intuitive expectation is that --toc-depth should control this, but this does not work. The problem occurs with both pdf and html output.

Example

# section 
## subsection

# another section
## another subsection

Compiling with:

pandoc --number-sections --toc --toc-depth=1 example.md -o example.html
pandoc --number-sections --toc --toc-depth=1 example.md -o example.pdf

In the former case, the html that I expect is:

<h1 id="section"><span class="header-section-number">1</span> section</h1>
<h2 id="subsection">subsection</h2>
<h1 id="another-section"><span class="header-section-number">2</span> another section</h1>
<h2 id="another-subsection">another subsection</h2>

What is actually produced is:

<h1 id="section"><span class="header-section-number">1</span> section</h1>
<h2 id="subsection"><span class="header-section-number">1.1</span> subsection</h2>
<h1 id="another-section"><span class="header-section-number">2</span> another section</h1>
<h2 id="another-subsection"><span class="header-section-number">2.1</span> another subsection</h2>

Pandoc version:

pandoc --version
pandoc 2.2.3.2
Compiled with pandoc-types 1.17.5.1, texmath 0.11.0.1, skylighting 0.7.2
Default user data directory: /home/sphelps/.pandoc

[mb21]

can you try with the latest pandoc version? see https://pandoc.org/installing.html

[jgm]

TOC depth and numbering depth are really two separate issues. In some cases one wants numbering to continue into subsections even if these aren't being included in the TOC.

In pandoc (at least recent versions) you can create an unnumbered section thus:

## Section {.unnumbered}

or for short:

## Section {-}

You can also indicate that a section should not appear in the TOC by using the unlisted class:

## Section {.unlisted}

And of course you can use unnumbered and unlisted together.

If it is tedious to add these manually, you could always use a simple lua filter to add a class (say) to all headings below a certain level.

[phelps-sg]

I agree that in some cases one wants numbering to continue into subsections when these aren't in the TOC. I have amended the title of the issue accordingly.

However, I disagree that section numbering and TOC depth are separate issues.

Sometimes one wants to limit section numbering to a maximum depth in the main document. For consistency, this should automatically be reflected in the TOC numbering.

Currently, to implement a maximum section numbering depth in the main document, I therefore have to do all the following:

• specify a TOC depth of n
• create a lua filter for html targets, and pass n to the filter
• similarly for all other desired output formats

This is problematic because it results in violation of the once-and-only-once principal since n has to be specified in multiple places for consistency.

It would be much simpler if pandoc had a separate option to limit section numbering to a max depth in the main document, which implicitly also resulted in the same depth being applied to the TOC.

[jgm]

I don't understand how these two statements are consistent:

1. Sometimes one wants to limit section numbering to a maximum depth in the main document. For consistency, this should automatically be reflected in the TOC numbering.
2. I agree that in some cases one wants numbering to continue into subsections when these aren't in the TOC

If we want the flexibility described in 2, then we don't want changing the toc-depth to automatically set section numbering depth. These are independent parameters.

We could add another option --secnum-depth or something like that.

[phelps-sg]

We seem to be in broad agreement. Where we seem to disagree is that I believe that both statements 1. and 2. are consistent. With respect to statement 2, yes, I agree that you don't want changing the toc-depth to automatically set the section numbering depth, and this is why I changed the title of the issue. Statement 1 is a new feature request; there should be an option to specify the maximum depth in the main document. When this option is specified, it should be reflected in the TOC without having to re-specify the depth for the TOC.

If we want the flexibility described in 2, then we don't want changing the toc-depth to automatically set section numbering depth. These are independent parameters.

Yes, I agree! This is why I changed the title of the issue.

We could add another option --secnum-depth or something like that.

Yes, this would make sense, and is what I suggested at the end of my previous post. This separate option should change the maximum section numbering depth in the main document, and also by implication in the TOC (as per the issue title ;-)).

[jgm]

Seems like you want changing the section numbering depth to automatically change the toc depth. That's not consistent with these being independent parameters. It should be possible, for example, to have only 2 levels numbered while including 4 levels in the TOC.

[phelps-sg]

No. I would like two independent parameters. The original parameter --depth-toc does not need to be changed. The new parameter, --secnum-depth, should change both the TOC section numbering depth and the section numbering depth in the main document.

So to be clear, under the proposed feature, there would be two different parameters for controlling section numbering. However, if we change the section numbering depth in the main document using the new parameter, then it should also automatically specify the toc-depth.

The rationale for this is that if you specify a maximum section numbering depth in the main document, but a larger depth in the TOC, then you will have section numbers in the TOC that do not exist in the main document, and this will be very confusing for the reader.

Edit: Perhaps it would make sense to keep the parameters entirely separate, but to add a consistency check. If any optionally-specified TOC section numbering depth is larger than the specified section numbering depth, then a warning can be displayed, and then the section numbering depth can override the TOC depth.

[jgm]

I'm sorry, I must be missing something. You have two command-line options, but they aren't truly independent, if one of them sets the parameter set by the other.

As I said, it should be possible, for example, to have only 2 levels numbered while including 4 levels in the TOC. Isn't this ruled out by your proposal?

Note: I'm not talking about having the same section numbered in one context (TOC) and not in another. That's entirely off the table. The TOC should of course include whatever number (or lack of number) the section itself has.

[raminudelman]

Any news regarding this issue?

[tarleb]

I'm not sure I fully understand the request, so to clarify: Does the following Lua filter do what you need?

-- adjust as needed
local max_numbering_level = 3

function Header (h)
  if h.level > max_numbering_level then 
    h.classes:insert 'unnumbered'
  end
  return h
end

Test the above by saving it to a file; then pass that file to pandoc via the --lua-filter/-L command line option.

[AdamCoulterOz]

Hi @tarleb, that works well. Thank you! Could I suggest you slightly update it to just > max_numbering_level? Currently, if you want three levels, you need to set it to 4 (one more than you want).

if h.level > max_numbering_level then 

It would be awesome if we could get this filter added to pandoc as a CLI parameter! --number-sections-depth

[tarleb]

Good point @AdamCoulterOz, I updated the snippet.

I guess this is one of those cases where it's not entirely clear whether adding another option benefits enough people to justify the complexity, documentation requirement, and additional code that'd come with a new command line option. It's for @jgm to decide.

[lastoCHka42]

I have similar issue converting from HTML to DOCX on pandoc 2.17.1.1 compiled with pandoc-types 1.22.2.1, texmath 0.12.4, skylighting 0.12.3.1, citeproc 0.6.0.1, ipynb 0.2.

I run pandoc with options:

pandoc myfile.html \
  --standalone \
  --verbose \
  --from html \
  --to docx \
  --output myfile-en.docx \
  --metadata lang=en \
  --metadata toc-title='Table of content' \
  --filter pandoc/filter-espd.py \
  --table-of-contents \
  --toc-depth=2

I expect to see two-leveled TOC, like this:

1. Header 
1.1. Subheader
2. Another header
2.1 Another subheader ...

But instead I see TOC like this:

1. Header
1.1. Subheader
1.1.1. Subsubheader
1.1.1.1.Subsubsubheader
1.1.1.1.1 Subsubsubsubheader

[jgm]

@lastoCHka42 you're using a very old version of pandoc. Try with the latest version. If you still get the same results, then it looks like a bug -- --toc-depth should restrict depth of the TOC as advertised. If you reproduce it with pandoc 3.1.9, then report it as a separate issue.