Adjust section level in included markdown files

[olowo726]

Consider the following markdown

# Software components
## Platform

!include J1939Tp/J1939Tp.md

J1939Tp.md:

# J1939Tp

Implements the Transport Protocol (TP) 
.
.
.

Then I would like the heading J193Tp to be on level 3 in the merge output. "Software components" is level 1, "Platform" is level 2. The filter should know the heading level at the point of include and adjust heading levels in included file accordingly. This makes it possible to reuse included .md files in several documents.

[DCsunset]

I believe you could use the incrementSection option to specify how many levels you want to increment. The reason for not detecting it automatically is that it will make it impossible to add some level 1 sections at the end (like the appendix)

[olowo726]

incrementSection helps some but doesn't solve all cases. Consider for example nested includes. When writing a document which might be included the author doesn't know the current level and hence doesn't know desired increment.

How about incrementSection="auto"?

[DCsunset]

For incrementSeciont, the author of the included document doesn't need to know how many levels to increment. It's the responsibility of the author who wants to include other documents. Maybe I misunderstood your question. If so, could you provide an example to explain why the author doesn't know the current level?

[olowo726]

Consider the case of document1.md which includes document2.md which includes document3.md. The author of document2.md cannot know the appropriate absolute level of document3.md since he/she doesn't know in which context document1 will include document2.

Den fre 21 apr. 2023 kl 18:15 skrev DCsunset @.***>:

For incrementSeciont, the author of the included document doesn't need to know how many levels to increment. It's the responsibility of the author who wants to include other documents. Maybe I misunderstood your question. If so, could you provide an example to explain why the author doesn't know the current level?

— Reply to this email directly, view it on GitHub https://github.com/DCsunset/pandoc-include/issues/33#issuecomment-1518055988, or unsubscribe https://github.com/notifications/unsubscribe-auth/AGK2BOC2JQICW2WKLD7HGITXCKXCRANCNFSM6AAAAAAXFHKY5U . You are receiving this because you authored the thread.Message ID: @.***>

[DCsunset]

Is it necessary for doc2 to know the the absolute level in doc1? incrementSection works by incrementing all the section levels. So as long as doc2 knows the how to set doc3's level relatively, it should work because doc1 can increment the levels of both doc2 and doc3 altogether

[olowo726]

You mean that the total increment sections in doc3 will be the sum of incrementSection from doc1 and doc2?

On Sat, Apr 22, 2023, 00:30 DCsunset @.***> wrote:

Is it necessary for doc2 to know the the absolute level in doc1? incrementSection works by incrementing all the section levels. So as long as doc2 knows the how to set doc3's level relatively, it should work because doc1 can increment the levels of both doc2 and doc3 altogether

— Reply to this email directly, view it on GitHub https://github.com/DCsunset/pandoc-include/issues/33#issuecomment-1518391971, or unsubscribe https://github.com/notifications/unsubscribe-auth/AGK2BOBEOBJSHF2X2FLL43TXCMDARANCNFSM6AAAAAAXFHKY5U . You are receiving this because you authored the thread.Message ID: @.***>

[DCsunset]

Yes I think so. It's based on the nature of recursive include. You can always try it easily to verify it when you doubt it.

[olowo726]

I've tested now and it works as you say. So current functionality works but I still think incrementSection="auto" would be a nice feature (saving me some thinking and make it easier to rearrange).

[DCsunset]

Yes I think that may help. However, it's hard to define the auto behaviour as there's no end boundary for sections.

For example, if we have the following markdown:

# Sec 1

Section 1

# Sec 2

Section 2

!include file.md

What would you expect the incrementSection to be? It's reasonable to use either 0 or 1 here.

[olowo726]

I would use 1 since "Section 2" would be a normal text under hedline Sec 2

On Wed, May 3, 2023, 18:22 DCsunset @.***> wrote:

Yes I think that may help. However, it's hard to define the auto behaviour as there's no end boundary for sections.

For example, if we have the following markdown:

Sec 1

Section 1

Sec 2

Section 2

!include file.md

What would you expect the incrementSection to be? It's reasonable to use either 0 or 1 here.

— Reply to this email directly, view it on GitHub https://github.com/DCsunset/pandoc-include/issues/33#issuecomment-1533425396, or unsubscribe https://github.com/notifications/unsubscribe-auth/AGK2BOFTAJDB6OQVH6STVBDXEKH3VANCNFSM6AAAAAAXFHKY5U . You are receiving this because you authored the thread.Message ID: @.***>

[DCsunset]

I see. It makes sense now. auto is a kinda confusing name as I originally thought you were suggesting a more intelligent approach. I would vote for current as it always needs to match with the current level.

[olowo726]

Ok

On Wed, May 3, 2023, 20:37 DCsunset @.***> wrote:

I see. It makes sense now. auto is a kinda confusing name as I originally thought you were suggesting a more intelligent approach. I would vote for current as it always needs to match with the current level.

— Reply to this email directly, view it on GitHub https://github.com/DCsunset/pandoc-include/issues/33#issuecomment-1533611696, or unsubscribe https://github.com/notifications/unsubscribe-auth/AGK2BODPMZSGYNHX7WA3SJDXEKXV7ANCNFSM6AAAAAAXFHKY5U . You are receiving this because you authored the thread.Message ID: @.***>