Doc vs Chapter Titles

[tajmone]

@pml-lang, you might have noticed that the latest Sublime PML 0.7.1 update adds support for inline nodes within [title nodes (which wasn't yet supported due to the recent migration from PML 1.5.0).

You might also have noticed how [doc[title and [ch[title titles are handled differently:

• Only Chapter titles are indexed as symbols (and transformed, etc.), whereas the Document title is not.
• Document and Chapter titles are scoped differently, and also colored differently by our color scheme (Chapter titles have a light-on-dark background, whereas the document title hasn't).
• At the source-code level, the [title node is implemented separately for [doc and [ch, due to titles having been attributes of these nodes with PML 1.5.0.

I was thinking that since PML 2.x replaced the title attribute with the [title node, there's no longer a need to differentiate between Document and Chapter titles, and that we could simply treat them alike — i.e. just re-use the same [title syntax from [ch for [doc, so they are highlighted and indexed in the same away.

In other words: instead of having two distinct title contexts (one for [doc and another one for [ch), make [title an independent node in its own right in Sublime PML, and just reuse it for both [doc and [ch.

Do you see any reasons why document titles should be treated differently from chapter titles in the package? If not, I think I should go ahead with the above changes, which will make the syntax lighter, less entangles and closer to how PMLC treats these two nodes.

[pml-lang]

In PMLC, a distinction is made between doc and ch titles, via function isDocumentTitle() in ChapterTitleNode.java.

It's used, for example, to not include doc titles in the TOC.

And the HTML writer uses two different CSS classes to enable users to style doc and ch titles differently.
doc nodes use class pml-doc-title, while ch nodes use pml-chapter-title.

Hence, for consistency reasons you might want to keep the distinction in Sublime-PML. However there is also YAGNI (I'm a big fan of it). But if you remove the distinction, users might later ask for it. There is no clear-cut answer, but I would probably keep the distinction, as it's done already.

[tajmone]

Interesting, and worth considering. I can see there are pros and cons with both approaches.

It's used, for example, to not include doc titles in the TOC.

Indeed, if I join the current context into a single [title node which is shared, also document titles will be indexed. Sublime PML doesn't really deal with the TOC, but it does list chapter headings in the Goto Symbol panel, so fusing the two context would mean that the document title will be treated just like a chapter title in that respect — I don't see this as a big deal, really.

The advantage in keeping them separate might be if we wanted to index chapter titles locally and doc titles globally — i.e. the former only show up for the current document (as they already do), whereas doc titles show up for the whole project, which would make sense since it would provide a quick way to find or open up a document by its title, rather than its filename. If I join the two contexts this possibility is most likely lost (although there might be a hack to work around it, i.e. by checking the parent scope, but not entirely sure until I test this).

And the HTML writer uses two different CSS classes to enable users to style doc and ch titles differently. doc nodes use class pml-doc-title, while ch nodes use pml-chapter-title.

In Sublime PML this might affect only our custom color scheme, but we can still control their different stiles by including the parent scope, since a title node is always nested in either [doc or [ch, and you can fine-tune styles with scopes in ST color schemes. But then, it's not as if editor styles are all that rich, it's just a matter of colors since CSS properties are limited.

Hence, for consistency reasons you might want to keep the distinction in Sublime-PML.

My worries are more concerning maintenance, since the syntax is subject to frequent changes at this stage, and in this case it would mean having around six almost-duplicate contexts, which basically do the same stuff but using document scope instead of chapter, plus all the syntax tests which needs to be doubled in efforts.

So, I was looking at it more from the DRY angle, really.

However there is also YAGNI (I'm a big fan of it).

Do we need? That's the true question, and the reason why I wanted to ask you. Ultimately, we have them just because they were inherited from the old syntax where titles were attributes, and for the PML 1.5 to 2.0 migration work it was simpler for me to just keep it (even if redundant, I knew it worked).

I'm so used to working with them as distinct entities that it now seems unnatural to look at them as "just titles" — but then, from a pure syntax point of view, the [title node is just a node in its own right. Surely, its context changes its meaning in the final document, but that holds true for any formatting node, really (a paragraph within a quote differs from a plain paragraph, or one within a list, or an admonition, etc.).

My worry right now is that I also need to implement [subtitle, and if I keep the separate context than I'll also need to keep separate subtitles probably — even if I could technically avoid it, it would break consistence to have titles scopes as doc or chapter titles, but subtitles not having the same distinction. The addition of subtitles would make the syntax contexts grow even more, and the syntax tests would bloat even more.

But if you remove the distinction, users might later ask for it.

Users would ask for it only if it was meaningful, i.e. in terms of text editing (not in the final HTML docs). Right now I'm trying to understand whether there are practical benefits in keeping the distinction within the editor, besides the few one already mentioned. The problem is that I'm currently biased due to having worked for over a year with Sublime PML making the distinction, so it makes it look natural.

At the same time, I've never really explored the potential of this distinction between the obvious (i.e. TOC exclusion, different styles, etc.). Maybe from the editing point of view, we could exploit it in some creative way — can we? I simply don't know. But if keeping this distinction would be crucial to achieve some (future) advanced editing feature, I'm all in for keeping it, regardless of the duplicate work it requires (I want a smart editing experience).

There is no clear-cut answer, but I would probably keep the distinction, as it's done already.

I'd rather drop it unless there's a good reason to keep it, simply because of the extra maintenance work and how it would complicate implementing subtitles. But either way, keeping or removing it is going to result in some extra work, so I prefer to make the right choice based on need — the problem is that I need to implement [subtitle next, since I'm trying to finish covering the fundamental PML nodes, hence I can't really procrastinate too much.

Also, bear in mind that in the future we might introduce advanced functionality, e.g. for title-casing (in English), and if we keep them separate it would either mean that only chapter titles are checked for correct casing, or that the plug-in has to duplicate efforts to handle both scopes. As you can see, whichever decision we make it will affect everything else in the package (good or bad).

[pml-lang]

I'd rather drop it unless there's a good reason to keep it, simply because of the extra maintenance work and how it would complicate implementing subtitles.

Ok. That makes sense, and complies with DRY and YAGNI.

[tajmone]

Done!

The new shared context has been implemented, and will be delivered on next ST launch since I've merged it into main branch right now.