Multiple document support

[dirkschulze]

I am not sure if the SVG WG is even willing to switch to Bikeshed with the whole spec. I could imagine that there is resistance from Doug and Cameron. However, something that would help is support for multiple documents.

I could imagine that there is an index.bs with a <h1> section and a <pre class='metadata'> block. The different documents are then added in order into the metadata block:

Page: intro.bs
Page: painting.bs

and so on.

Bikeshed could then merge the specs into a single document to process it. Then we already have the single document version. This could then be split before each <h2> section and each section is added to an HTML template with navigation control. The index.html would have the normal header and the TOC.

[tabatkins]

Interesting. I've been thinking on/off about multi-page specs. Your approach sounds pretty reasonable.

[brgnepal]

+1 for this requirement. Much needed feature.

[tabatkins]

Okay, designing out loud.

Multipage inputs is already handled, that's just a <pre class=include>. (Using a Page metadata as suggested might be nice as a shortcut that automatically sets up the page-breaks to match the input files, but that's an enhancement.)

Multipage output is the thing needing solving here. In general, I need you to tell me which h2s should cause a page-break, and what filename each page should have. (Splitting on lesser headings needs to be supported eventually - HTML does it, for example - but can be an enhancement, as it complicates the problem space.)

• After processing is done, but before header/footer is applied, need to split the document accordingly.
• Need a new set of boilerplates to handle this - first page head/foot, later pages head/foot. Do I need more? Hm, or do the existing boilerplates already do something necessary I guess, like define which indexes to include in the footer? Yeah, I suppose so. So I need a different set of boilerplates, then - per-page headers and footers. Or maybe I can just auto-gen these for now?
  • I wonder how opinionated I can be here in autogeneration. CSS, SVG, and HTML all have slightly different structures, but they're all pretty close to each other:
    • CSS puts the nav structure on every page, including the first. ToC fragment is on top.
    • HTML doesn't put the nav structure on the first page. ToC fragment is on top.
    • SVG doesn't put the nav structure on the first page. Nav structure also contains links to important appendixes.
  • Ah, this suggests I don't want to use the existing header/footer boilerplates actually. Indexes will just be put in manually. Instead, you do want first/rest as the division.
• Once split, iterate each sub-document to find all the IDs, tagging them with the page they're in. Then iterate again to find all the local links, fixing them if they're to an anchor that's now on a different page.
• Generate a per-page ToC fragment as well, unless a page already generate a ToC. Probably this is just part of the boilerplate, you'd request, then?

Are there more multipage specs I could look at? Hm.

---

So anyway, splitting should be fairly trivial, link fixup should be fairly trivial. Figuring out the header/footer situation is mildly difficult.

[alerque]

Includes are traditionally not parf of base Markdown syntax (although many processors implement them in their own flavors), and at this point CommonMark doesn't have support either. But pandoc might sonn! See jgm/pandoc#553. It's probably work keeping an eye on that implementation and keeping the number of new novel include syntaxes used in the greater Markdown ecosystem to a minimum.

[fantasai]

If you have single-page input, maybe something like <section page=subpagefilename> or <section page id=subpagefilename> (with the file extension automated, filename taken from ID if not otherwise specified) would work for identifying sub-pages.

[simoncozens]

What I would love to see is each n-th level header (where "n" is set in metadata) in its own page, with a ToC on each page providing external links to the higher-level headers and internal links to lower-level headers. i.e.

<h1 id="stuff"> Stuff </h1>
<h1 id="nonsense"> Nonsense </h1>
<h2 id="gibberish"> Gibberish </h2>
<h3 id="Balderdash"> Balderdash </h3>
<h2 id="gallimaufry"> Gallimaufry </h2>

When n=1 this should produce two pages, stuff.html and nonsense.html. The ToC in stuff.html should be:

<li> 1 <a href="#">Stuff</a></li>
<li> 2 <a href="nonsense.html">Nonsense</a></li>

while the ToC for nonsense.html should be:

<li> 1 <a href="stuff.html">Stuff</a></li>
<li> 2 <a href="#">Nonsense</a>
  <ul>
    <li>2.1 <a href="#gibberish">Gibberish</a>
        <ul><li>2.1.1 <a href="#balderdash">Balderdash</a></li>
    </li>
    <li>2.2 <a href="#gibberish">Gallimaufry</a></li>
  </ul>
</li>

[frivoal]

In practice, given that h1 is used for the title of the whole document, I suspect that if the feature is used at all, n would always be 2. If that's the case, we just need an on/off switch, not a numerical parameter. Or do you have use cases for n > 2?

[simoncozens]

Yes, I’d like to be able to split on h3 (and possibly h4).

[domenic]

FWIW (which might not be much considering HTML is not using Bikeshed), HTML has non-uniform splits. Some second-level sections are small enough to get merged together, and some are big enough that they need to split on intermediate h3s within them.

[tabatkins]

The fact that the splits happen all at one level or not won't matter for the underlying tech; it'll just be a convenience feature so people don't have to annotate every split. Splitting at arbitrary headings should be just fine.

Not splitting at particular headings, so that a page consists of multiple headings of the same level, will be a little more difficult, but should be doable. (It just makes the ToC generation for the page more complicated.)

Splitting at non-heading points would be rather more complicated, I think.

---

As before, the only real blocker here is me figuring out the boilerplate structure for a multipage spec. The actual mechanics of it should be relatively straightforward.