Functionality to split up a document into parts

[ramobis]

Description

As a user I would like to split up my documents into parts. A part shall be listed in the outline and is displayed as a cover page inside the document at the corresponding location.

A part can be thought of a superior element of a level 1 heading giving additional structure possibilities.

Use Case

Consider a document containing exercises for university students. All exercises shall be in the same document but the exercises of each week shall be grouped together inside a part. Two parts are separated using a cover page for each part. Additionally parts shall be listed inside the outline together with headings.

Imagine a table of contents like this:

Table of Contents

Introduction.............................1

I. Week 1 <-- this is a part
1. Heading...............................3
2. Heading...............................6

II. Week 2 <-- this is a part
1. Heading...............................7
2. Heading...............................8

III. Week 3 <-- this is a part
1. Heading...............................10
2. Heading...............................12

So this feature would provide the users a more flexible way to structure their documents.

[Enivex]

A part can be thought of a superior element of a level 1 heading

There's nothing stopping you from treating level 1 headings like parts

[ramobis]

Good point.
That's actually the first thing which came in my mind too but then I thought it might be kind of a hack and the template might lose some interoperability.
I am currently working on a template for the university I am in and it should be as clean as possible.

But thinking again about interpreting level 1 headings as parts is not that bad actually.

I'll implement it and I'll post my solution here.

[ramobis]

Hmm... But doing this would lead to the fact that I have to treat the following headings as heading(level-1).
So level 2 would then have to be interpreted as level 1.

Another approach I followed was specifying the part as a custom figure kind. Which worked absolutely fine until the point I wanted to add it to the table of contents. I failed to combine headings and figures in the same outline. As stated in #907 the outline customization options are currently quite limited.

[tingerrr]

I'm glad I found this in my testing bin of a document, it still has a few comments that were from when I was writing a proposal to improve outline, but I never got around to it.

#let chapter = figure.with(
  kind: "chapter",
  // same as heading
  numbering: none,
  // this cannot use auto to translate this automatically as headings can, auto also means something different for figures
  supplement: "Chapter",
  // empty caption required to be included in outline
  caption: [],
)

// emulate element function by creating show rule
#show figure.where(kind: "chapter"): it => {
  set text(22pt)
  counter(heading).update(0)
  if it.numbering != none { strong(it.counter.display(it.numbering)) } + [ ] + strong(it.body)
}

// no access to element in outline(indent: it => ...), so we must do indentation in here instead of outline
#show outline.entry: it => {
  if it.element.func() == figure {
    // we're configuring chapter printing here, effectively recreating the default show impl with slight tweaks
    let res = link(it.element.location(), 
      // we must recreate part of the show rule from above once again
      if it.element.numbering != none {
        numbering(it.element.numbering, ..it.element.counter.at(it.element.location()))
      } + [ ] + it.element.body
    )

    if it.fill != none {
      res += [ ] + box(width: 1fr, it.fill) + [ ] 
    } else {
      res += h(1fr)
    }

    res += link(it.element.location(), it.page)
    strong(res)
  } else {
    // we're doing indenting here
    h(1em * it.level) + it
  }
}

// new target selector for default outline
#let chapters-and-headings = figure.where(kind: "chapter", outlined: true).or(heading.where(outlined: true))

//
// start of actual doc prelude
//

#set heading(numbering: "1.")

// can't use set, so we reassign with default args
#let chapter = chapter.with(numbering: "I")

// an example of a "show rule" for a chapter
// can't use chapter because it's not an element after using .with() anymore
#show figure.where(kind: "chapter"): set text(red)

//
// start of actual doc
//

// as you can see these are not elements like headings, which makes the setup a bit harder
// because the chapters are not headings, the numbering does not include their chapter, but could using a show rule for headings

#outline(target: chapters-and-headings)

#chapter[Chapter]
= Chap Heading
== Sub Heading

#chapter[Chapter again]
= Chap Heading
= Chap Heading
== Sub Heading
=== Sub Sub Heading
== Sub Heading

#chapter[Chapter yet again]

I'll add this to hydra:0.3.0 soon.

EDIT: forgot to say why I even posted this here, you can use this for now, outline could be improved though. Maybe I'll get around to writing the proposal if nobody else will. And if somebody else does, feel free to mention me, so I can chime in!

[tingerrr]

I was skimming issues and I think this can be closed, with the addition of heading.offset one can interpret = Blah Blah as level 2 headings and use the explicit heading(level: 1)[...] for the much rarer chapters/parts and outlines can be configured using outline.entry.

[wrzian]

Maybe this would be a good pattern to mention in the docs? I personally didn't fully see how heading.offset was helpful before reading this.

[tingerrr]

Offset has an example for this particular use case, but parameter examples are collapsed by default.