Subtitles

[coemgenuslcp]

With the current converter, is there a recommended way to have a subtitle (or two ... or three) under a title? Or must we support "subtitle", "subtitle2" attributes or the like in the section tags? This code, for instance, is not really ideal for tables of contents:

[ch title = "La Mélopée antique dans le chant de l'Église latine" \
    subtitle = "par François Auguste Gevaert" \
    subtitle2 = "Suite et complément de l'Histoire et théorie de la musique de l'antiquité"
]

though it might be better than a hacky workaround like this:

[ch title = "La Mélopée antique dans le chant de l'Église latine"
    [b "par François Auguste Gevaert"]
    [b "Suite et complément de l'Histoire et théorie de la musique de l'antiquité"]
]

For the time being, in my documents, I have to simply keep the subtitles in the titles, which is worst for tables of contents:

[ch title = "La Mélopée antique dans le chant de l'Église latine, par François Auguste Gevaert. Suite et complément de l'Histoire et théorie de la musique de l'antiquité"
]

Are there better ways?

[pml-lang]

I am myself not happy with the title attribute in ch nodes (and other nodes), for two reasons:

• It is currently not possible to embed markup code in a title. For example, if we write title = "An [i awesome] idea", then "awesome" is not rendered in italics.
• Attributes should exclusively be used for meta-data, not for text that appears in the final document.

My idea is therefore to make the following changes:

• Remove the title attribute
• Add a title node that must be the first child of the ch node. The node can contain inline nodes. Example:

[ch [title An [i awesome] idea]
    ...
]

is there a recommended way to have a subtitle (or two ... or three) under a title?

No. The best you can currently do is to use a hack like inserting a b tag (as you did in your example), or maybe a span tag with some specific CSS.

Subtitles are quite common. Therefore we should add dedicated subtitle and subtitle2 nodes. Hence, in the future you will be able to write:

[ch [title La Mélopée antique dans le chant de l'Église latine]
    [subtitle par François Auguste Gevaert]
    [subtitle2 Suite et complément de l'Histoire et théorie de la musique de l'antiquité]
    ...
]

I don't think it makes sense to add more levels (subtitle3, etc.). However, if needed they could very easily be added later. (BTW: This could also be achieved by user-defined nodes, a powerful feature I intend to add later in PML.)

By default, only title nodes should be included in the table of contents (TOC). There could also be a parameter to enable displaying subtitles in the TOC.

Moreover, I want to add a smalltitle (or stitle) node. An stitle can be inserted anywhere a paragraph break is allowed. It can contain inline nodes, and it is never displayed in the TOC.

Feedback on these ideas is very welcome.

[coemgenuslcp]

I like your ideas. Especially user-defined could handle for a document with all kinds of metadata under the title.

What is the small title for? You can mimic sections with [ch], though I haven't checked whether the HTML makes article within article. In that case, is not the title associated with the nested [ch] sufficient?

[pml-lang]

I like your ideas

Thank you very much and welcome on board !!!

What is the small title for?

Suppose we have a chapter containing some sections. We don't want to use sub-chapters for the sections, because we don't want these sections to appear in the table of contents. But we do want a title above each section.

I encountered this situation several times. As a hack, I simply used b nodes for my titles, e.g.

[ch title = Advantages
    [b Advantage 1]
    
    Text

    [b Advantage 2]
    
    Text

    [b Advantage 3]
    
    Text
]

With a dedicated node stitle we can write:

[ch title = Advantages
    [stitle Advantage 1]
    Text
    [stitle Advantage 2]
    Text
    [stitle Advantage 3]
    Text
]

A first benefit is that the empty lines which were required in the first example, now become optional in the second example (because stitle is a block node, while b is an inline node).

More importantly, now we have a dedicated node that can be styled individually for this kind of titles (styling node b to have more appealing small titles would probably be a very bad idea).

Semantically it is better too, because stitle denotes the meaning of the node.

[coemgenuslcp]

Very nice! However, it doesn't much facilitate the ability to manage sections within sections well, and you're also talking about styling by tag type. I myself like to nest content (all nestings considered, including the include node), and the article-section distinction in HTML appeals to me. So I would rather have a nestable section equivalent to pair with the top-level ch node, and manage my styles by classes or whatever. Something like this perhaps:

[ch
    [title ...]
    [sec
        [title ...]
        Content
    ]
    [sec
        [title ...]
        Content
        [sec
            [title ...]
            Inner content
        ]
        [sec
            [title ...]
            Inner content
        ]
    ]
]

Actually, I see three problems here to deal with, that have to be kept balanced in the mind: (1) nestability of content blocks (sections or chapters or whatever — what if an include inside a ch also contains a ch?), (2) styling different levels dynamically (versus, say, the horrid h1, h2, etc.), and (3) selectability on which chapters/sections/whatever appear in the Table of Contents. Eh, it's tricky.

This might be worth forking into a new discussion thread, to avoid that green box, since I had opened this one as a Q/A.

[pml-lang]

manage sections within sections

So far I avoided to support sections (and sub-sections) within chapters. I am a very big fan of "Everything should be as simple as possible, but not simpler". Having sections (besides chapters) increases complexity. For example, users must know their differences (chapter/section), and decide which one to use. But maybe I'm disregarding some compelling advantages of sections.

(1) nestability of content blocks (sections or chapters or whatever — what if an include inside a ch also contains a ch?)

This is already supported for chapters, without restrictions as to the number of levels (chapters within chapters).

(2) styling different levels dynamically (versus, say, the horrid h1, h2, etc.)

Different levels are styled dynamically in PML. When you embed a chapter within a chapter, you simply use a nested ch node, without specifying a level. When the whole AST is created, PML automatically assigns a level to each chapter. This level information is used by the HTML writer to use the right h tag (i.e. h1 to h6). Chapter levels greater than 6 all use h6 (because that's the limit in HTML).

(3) selectability on which chapters/sections/whatever appear in the Table of Contents

I was thinking already about adding two parameters:

• a doc parameter that specifies the maximum level of chapters to be included in the table of contents (TOC).

• a ch parameter (yes_no value) that allows to explicitly exclude individual chapters (and their sub-chapters) from the TOC.

Another useful feature could be a doc parameter that specifies auto-numbering of chapters (e.g. 1, 1.1, 1.2 or 1, 1.a 1.b, etc.)

[pml-lang]

My idea is therefore to make the following changes:
Remove the title attribute
Add a title node that must be the first child of the ch node.

This is now done in version 2.0.0. See Chapter Title.

we should add dedicated subtitle

Done in version 2.0.0. See Chapter Subtitle Node.

add a smalltitle (or stitle) node.

Done in version 2.0.0. See Header Node.