lierdakil / pandoc-crossref

Pandoc filter for cross-references
https://lierdakil.github.io/pandoc-crossref/
GNU General Public License v2.0
924 stars 74 forks source link

only last two levels of sections references displayed #277

Open Myo-e opened 3 years ago

Myo-e commented 3 years ago

with the minimal following input.md file:

---
sectionsDepth: 1
---

# Debug1 
## debug1.1

This is a reference to section debug1.2 @sec:debug121. 

This is a reference to section debug1.2.1 @sec:debug121. 

This is a reference to section debug1.2.2 @sec:debug122. 

This is a reference to section debug1.2.2.1 @sec:debug1221. 

## debug1.2{#sec:debug12}
### debug 1.2.1{#sec:debug121}
### debug 1.2.2{#sec:debug122}
#### debug 1.2.2{#sec:debug1221}

and with the inline command: pandoc -F pandoc-crossref -F pandoc-citeproc ./input.md -o ./debug2.pdf --number-sections

I get the pdf output linked, in which the references only contain the last two depth levels of the total expected reference (e.g. for @sec:debug122, I would expect the output "sec. 1.2.2" but just get "sec. 2.2" debug2.pdf

Additionally, the YAML sectionsDepth: 1 seems to be totally ignored (passing it to the inline as -M --sectionsDepth=1 does not work either.

My system (windows 10):

lierdakil commented 3 years ago

Right. So v0.4 is marked as "alpha"/"prerelease" on the downloads page for a reason. Among other quirks, I didn't find time to update the docs. sectionsDepth isn't an option in v0.4, at least not until I try to implement some semblance of backwards compatibility (and it's debatable whether I should)

Thanks for testing, by the way, this early feedback can be really helpful.

Anyway, v0.4 operates on a more abstract level: you have abstract trees of elements, all of which are differentiated by label prefix and path in the tree only. Textual references can be constructed from sequential numbers of all (or some) elements in the tree branch, and numbering of individual elements can be "scoped", i.e. restarted based on parent changes.

Long story short, here's a quick fix:

prefixes:
  sec:
    referenceIndexTemplate: '$$i$$$$suf$$'
    captionIndexTemplate: '$$s.i%.$$$$ri$$'

I don't remember why exactly the default behaves like it does, perhaps it is simply an oversight.

As for sectionsDepth, the easiest way to emulate it is to define a separate prefix for sections that you want to be excluded from reference numbers, e.g.

---
scope:
- sec
captionIndexTemplate: '$$s.i%.$$$$ri$$'
prefixes:
  sec:
    referenceIndexTemplate: '$$i$$$$suf$$'
  subsec:
    from: sec
    scope:
    - sec
    - subsec
---
# Debug1 
## debug1.1

This is a reference to section debug1.2 @sec:debug12. 

This is a reference to section debug1.2.1 @sec:debug121. 

This is a reference to section debug1.2.2 @sec:debug122. 

This is a reference to subsection debug1.2.2.1 @subsec:debug1221. 

This is a reference to subsection debug1.2.2.1.1 @subsec:debug12211. 

## debug1.2{#sec:debug12}

![A figure](img.png){#fig:121}

### debug 1.2.1{#sec:debug121}

![A figure](img.png){#fig:1211}

### debug 1.2.2{#sec:debug122}
#### debug 1.2.2.1{#subsec:debug1221}
##### debug 1.2.2.1.1{#subsec:debug12211}

![A figure](img.png){#fig:1221}

here, all items will be scoped under sec, but not under subsec, although for other intents and purposes, subsec behaves similarly to sec.

Perhaps I need to think about limiting nested scoping to a user-defined depth, e.g. scope: ["sec[2]"] or something to approximate sectionsDepth more closely. I'm a bit busy right now though, so likely won't have time to implement anything like that in the near future.

lierdakil commented 3 years ago

Okay, since I had to look at the code anyway, the default behaviour of section references is changed in 19935fb5bf4784e02cb41e1029f6e176293b1c67 which should hopefully be available on BinTray in an hour or so (notice it'll be built against pandoc 2.10.1)

As for limiting scoping depth, I need to think about it, so it will take a while. Feel free to share your opinion.