Add support for number_offset metadata with number-sections.lua

[atusy]

number-sections.lua enables numbering sections for formats without it.
However, current implementation lacks the support for --number-offset.
Unfortunately, there is no way to tell Lua filter the value of --number-offset.
Thus, this PR reads number-offset metadata as an alternative.

Reprex:

---
output:
  md_document:
    number_sections: true
number_offset: 3
---

# foo

[atusy]

Maybe we should consider consistent behaviors on formats with native --number-sections option.

---
output:
  html_document:
    number_sections: true
number_offset: 3
---

# foo

[atusy]

Maybe we should consider consistent behaviors on formats with native --number-sections option.

done

[yihui]

I'm okay with this PR, and will let @cderv decide whether to merge it. Thanks!

Unfortunately, there is no way to tell Lua filter the value of --number-offset.

Yes, that's unfortunate. It will be great if we don't have to introduce a new field in YAML.

[cderv]

I took time on this one because I needed to think about it.

I really don't like adding a new YAML field, all the more not under a format function but at the first level in the YAML. This usually is to pass variable to pandoc. It is already not quite easy to follow which field will be processed by which tool so I am not sure about this.

But even considering that, I thought deeper about the why we would need this.
Is --number-offset often used with rmarkdown project ? I never had the need for this command line flag, and not sure to see in which case it would be useful. Pandoc itself only supports it for HTML document
From https://pandoc.org/MANUAL.html#option--number-offset

Offset for section headings in HTML output (ignored in other output formats).

This means that --number-offset is ignored for LaTeX conversion and number-sections.lua is not used in pdf_document(). So even if we support this, one format would still lack the feature, unless we use number-sections.lua for pdf_document() also, but we are redoing Pandoc feature in Lua in this case, aren't we ?

Maybe this option to offset the numbering is only useful when producing HTML documents ?

Is there a use case behind this PR @atusy or just a quest of completeness ?
As @yihui taught me, sometimes it is better to wait for a feature to be asked even if we have the idea to do it in the first place.

If we were to do it, I would prefer having the field be at the same level of number_sections

---
output:
  md_document:
    number_sections: true
    number_offset: 3
---

I may be wrong but I assume that field under output are mainly processed by R, whereas other field are mainly for Pandoc to use directly.

I would also add this in html_document(), but it would still be missing for PDF outputs.
I leverage the fact that metadata can be passed to Lua filter at command line and not necessarily to be set in YAML header in the first place.

What are your thoughts on all this ?

[atusy]

Thanks @cderv for your insightful comments.

I understand completeness is not always the priority and am fine to close this PR.
Yet, let me tell you my minor use case.

I am currently co-authoring a book with R Markdown, and each authors render .md files per their chapters.
There, we need section numbers and cross reference with number_offset, and I implemented the features with Lua filter.

[cderv]

Oh that is interesting. So you are running pandoc on each file ? and not on all separate file at once ?
I see that this can be useful in this case. I am surprised that Pandoc itself does not cover this.

How does it work with PDF ? Do you use the Lua filter instead of the --number-sections support from Pandoc ?

[atusy]

Yes, we run pandoc on each file.

Actually, conversion to PDF is not author's scope.
We just submit markdown files to our editor.
I do not know his ecosystem in detail.
I know that he at least uses Adobe InDesign.

[cderv]

ok. Thanks for sharing!

[cderv]

FYI Pandoc 2.17 has now added a Global Variable PANDOC_WRITER_OPTIONS that contains the writer options, among them number_offset.

• https://pandoc.org/lua-filters.html#global-variables
• https://pandoc.org/lua-filters.html#type-writeroptions

Table of the options that will be passed to the writer. While the object can be modified, the changes will not be picked up by pandoc

Maybe this would prevent us for adding a new first level YAML field for the Lua Filter to work. Which is mainly why I am holding merging this PR for now, waiting for a better solution. That may be it.

[atusy]

@cderv

Thank you for good news! I think it is okay to support number_offset only with Pandoc >= 2.17.
I'll update the implementation.

[cderv]

Cool ! Let me know if this enough - I never used this variable before. Hopefully it will work well for this ! And open room for other feature in Lua!