Making a hash of #, or...

Sectioning and titles

The gemtext format is nearly perfect, but one thing I've been unhappy about for a while is what seemed to me to be a conflict between two different uses of '#' lines: top-level sectioning of the document, and specifying the document's title. Today I discussed the issue with Ben K and got only more worried about it, until eventually I thought to load Lagrange and my worries evaporated.

Today, I bring you this exciting tale of piteous perplexity and eventual enlightenment.

The "problem"

According to the spec, header lines

> provide a machine-readable representation of the internal structure of the document.

However, also

> CMS-style tools automatically generating menus or Atom/RSS feeds for a directory of text/gemini files can use first heading in the file as a human-friendly title.

(The gmisub companion spec modifies this slightly by having it refer

only to '#' lines:

> The contents of the first header line in the document beginning with a single # serves as the feed's required "title" element.

so I'll assume that's what was intended in the main spec too.)

But then, what is the meaning of that first '#' line? It sets the title, but doesn't it also start a section? But then that section would have the same title as the whole document, despite these being two separate layers. Or does '#' only ever start a title, and multiple uses of it are meaningless? But then we only have two levels of sectioning, which is painful. And what about lines before the title? Are they untitled??

This may sound abstruse, but it has real consequences. I realised that, without really thinking about it, I have been using only one '#' in my gemini documents, jumping down to '##' if I want to section. I get the impression that many others do the same.

The solution

We discussed various possibilities, and I composed a mail to the list on the subject. Just before sending, I thought to check that Lagrange behaved the way I seemed to remember it did. Instead, it had what in retrospect is clearly the correct solution. EDIT: However, after writing this article, I realised that I'd completely misread what Lagrange was doing. Actually it doesn't number sections at all! So it seems the solution below is one I saw in the clouds. Which I'll count as an argument in itself for its naturality.

The first '#' only sets the title and does not start a new section. However, the start of the document until the first section (i.e. until the second '#' line) comprises a special "0th" section of its own. This may have '##' subsections (0.1, 0.2, ...), which may have '###' subsubsections. The title is displayed wherever it appears in the document, so you can have some preamble to the title if you want.

Latex also uses this "0th section" trick.

The gemini spec and the help page of Lagrange also follow this numbering scheme (these were the aforementioned clouds), though without explicit numbering in section 0.

Argument from authority.

Upshot

Use '#' for your sections as well as for your title! You can think of the title as starting an introductory section, if you like, but it sets the title for the whole document rather than just that section.