ConTeXt Writer: Start and Stop Section Levels

[ghost]

Background

Using Pandoc 2.7.2, consider the following document:

# Inflation Theory
## 13,813 ± 58
Time did not start with an explosion...

### Relevance
Our Universe's first three minutes produced vast amounts of protons...

This results in a document similar to the following:

\chapter[title={Inflation Theory},reference={inflation-theory}]

\section[title={13,813 ± 58},reference={section}]

Time did not start with an explosion...

\subsection[title={Relevance},reference={relevance}]

Our Universe's first three minutes produced vast amounts of protons...

Problem

By generating \chapter, \section, and \subsection, etc., it puts constraints around embedding documents within documents. As Hans Hagen wrote on the ConTeXt mailing list:

I don't know as I never use these coding methods. But it might make sense to check all these mappings onto context, for instance I think that pandoc uses \section and such while in fact it should use \startsectionlevel[title={}] ... \stopsectionlevel so that one can embed documents in other documents.

Expected Output

The expected outputs include a standalone document and a document fragment.

Standalone Document

The relevant portions of the standalone document might resemble:

\definestructureconversionset
  [documentstructure]
  [numbers, numbers, numbers]
  [numbers]

\setupheads [sectionconversionset=documentstructure]

\starttext

\startsectionlevel [title={Inflation Theory},reference={inflation-theory}]
  \startsectionlevel [title={13,813 ± 58},reference={section}]
    Time did not start with an explosion...

    \startsectionlevel [title={Relevance},reference={relevance}]
      Our Universe's first three minutes produced vast amounts of protons...
    \stopsectionlevel
  \stopsectionlevel
\stopsectionlevel

\stoptext

The [numbers, numbers, numbers] code reflects the depth of heading levels in the document. If the document has 5 levels, then [numbers, numbers, numbers, numbers, numbers] may be necessary.

Document Fragment

A document fragment could look as follows:

\startsectionlevel [title={Inflation Theory},reference={inflation-theory}]
  \startsectionlevel [title={13,813 ± 58},reference={section}]
    Time did not start with an explosion...

    \startsectionlevel [title={Relevance},reference={relevance}]
      Our Universe's first three minutes produced vast amounts of protons...
    \stopsectionlevel
  \stopsectionlevel
\stopsectionlevel

Discussion

Could detecting when to stop the current sectionlevel be beyond Pandoc's ability in certain circumstances?

[mb21]

Have you tried the --section-divs option?

But yes, this should be documented better (was added in 751b5ad)...

The expected outputs include a standalone document and a document fragment.

Sounds exactly like pandoc templates.

[jgm]

Detecting when to stop the current `sectionlevel` could be beyond Pandoc's ability in all circumstances.

Not at all. We already have a hierarchicalize function that does this, which we use for e.g. docbook.

[ghost]

Using the following command:

$ pandoc -t context --section-divs test.md

Produces the following document:

\startsection[title={Inflation Theory},reference={inflation-theory}]

\startsubsection[title={13,813 ± 58},reference={section}]

Time did not start with an explosion\ldots{}

\startsubsubsection[title={Relevance},reference={relevance}]

Our Universe's first three minutes produced vast amounts of
protons\ldots{}

\stopsubsubsection

\stopsubsection

\stopsection

Would subsections and sub-subsections interfere with embedding documents? (I suspect so because there'd be no way to distinguish an embedded document's startsubsection from its parent document's startsubsection.) As opposed to startsectionlevel, which relies on the nested hierarchy to determine the level heading.

[ghost]

Regarding the documentation: yes, having a section that describes additional output formats beyond HTML could be useful.

[denismaier]

I would opt for using the \startsectionlevel (not \startsection, \startsubsection, etc.) as this allows for maximal flexibility.

[denismaier]

The following code maps those sectionlevels to chapter, section, subsection, etc.

\definesectionlevels
   [default]
   [chapter,
    section,
    subsection,
    subsubsection,
    subsubsubsection,
    subsubsubsubsection]

[tarleb]

Here's a somewhat hacky approach to this: we could return \startsectionlevel ... \stopsectionlevel for all headings below level six. The desired result could then be produced by calling pandoc with --section-divs --shift-heading-level-by=6.

[denismaier]

What about using the same approach as with JATS XML?

[tarleb]

Could you expand on that? The JATS model has no concept of explicit section levels, the <sec> element is equivalent to the sectionlevel environment.

A cleaner approach than what I suggested above might be to make the behavior depend on --top-level-division, with --top-level-division=default giving the behavior proposed here, and --top-level-division=section producing the current behavior.

[denismaier]

Could you expand on that? The JATS model has no concept of explicit section levels, the <sec> element is equivalent to the sectionlevel environment.

That's basically my suggestion: Just use sectionslevels throughout. Then, when building a standalone document add something like this to the preamble:

\definesectionlevels
   [default]
   [section,
    subsection,
    subsubsection,
    subsubsubsection,
    subsubsubsubsection]

Or, with --top-level-division=chapter:

\definesectionlevels
   [default]
   [chapter,
    section,
    subsection,
    subsubsection,
    subsubsubsection,
    subsubsubsubsection]

[adityam]

I don't use pandoc + context too much these days, but I'll chime in to say that I support the default output being \sectionlevel. FWIW, that's what the Hans Hagen's m-markdown module (which is a markdown parser written in Lua and distributed as part of context distribution) does.