Replies: 1 comment 4 replies
-
I've locally updated the documentation (description of node
IMO this is allowed, because of the "equal to" in the specs.
That would preclude users from using different styles for titles/subtitles, and would have other diasadvantages.
Thanks for mentioning this. PML should always comply with the HTML specs. Hence, we should indeed use the I suggest to do this: For the document title/subtitle, generate the following code: For the subtitle we could also use a For a chapter title/subtitle, the new code would be: PML allows to define several subtitles, which are all treated the same way. Hence, a title with two subtitles would be rendered as follows: Note that a
Subtitles were added after a user requested them.
Done. |
Beta Was this translation helpful? Give feedback.
-
My interpretation is that it's given for granted that there would be contents between the two headings — i.e. not two adjacent headings of the same level. From a pure editorial point of view, this: is viewed as a chapter and a heading, i.e. they define a hierarchical structure. but this: means that Chapter "AAAA" is an empty chapter, followed by Chapter "BBBB". I believe that the example from the specs is correct: <hgroup>
<h1>Dr. Strangelove</h1>
<p>Or: How I Learned to Stop Worrying and Love the Bomb</p>
</hgroup>Even though it's marked as a paragraph, the text "Or: How..." is effectively a subtitle, as the given example clarifies (without margin of doubt, IMO, since that's definitely a subtitle).
A subtitle is not a heading, in fact it shouldn't be shown in the TOC. It's just text that better qualifies the title, like a predicate. This is true for the main title and any other heading in the contents, for when a book is catalogued only the title is indexed, and the TOC is meant to show only title headings, not their subtitles. I'm afraid that this is just one of those aspect of proper editing rules that got corrupted by cheap tools and standards in the course of time, which replaced best practices with cheap solutions, until we reached a point when most self-improvised editors no longer distinguish between the two, and new tools are built according to common practices, instead of good practices. It's not different from the trend to use hyphens as range separators, instead of en-dashes ( Or like the AsciiDoc rule that em-dashes must be surrounded by spaces; where does this rule come from? In some editorial context is a mistake, in other it might depend on the country and its traditions.
But why? There can't be more than one subtitle for any given title, and PMLC should throw an error and abort if it encounters this since it can only be an unintentional mistake.
From the example given at #50, it's clear that what is being referred to as "subtitle 2" is actually a "preamble" (as in AsciiDoc). Different countries and publishing domains have different naming conventions and traditions regarding how Frontispieces are organized and what can go in them: In any case, there's only one subtitle per title, no exceptions to the rule. These technicalities in the implementation — which affect PML compliance to publishing standards — are the reasons why I've been insisting so much on creating official docs that present the PML vision, goals and roadmap in terms of which features and editorial standards PML will ultimately embrace. |
Beta Was this translation helpful? Give feedback.
-
|
Some points to consider:
A possible alternative solution would be this: Note that the
Could you provide an authoritative link to this rule to point users to, if they ask for two (or more) subtitles? Or is this just an unwritten rule?
PMLC doesn't include subtitles in the TOC, as documented in chapter Subtitle: "The subtitle is not displayed in the table of contents." Useful links:
Note 1: Note 2: |
Beta Was this translation helpful? Give feedback.
-
|
Unfortunately I agree with the concerns expressed by J. Knight in So <HGROUP> Is Back In HTML 5 regarding HTML5 being crap — this being one of the reasons I stopped working in website design when it came out. But having said this, HTML based formats remain much desired targets for tools like PML, because of their practical and widespread use for documentation as well as ebook formats like ePub (BTW, things get even uglier with ePub3).
A good baseline reference when it comes to documents styling would be the Chicago Manual of Style (aka CMOS, CMS or TCM). Although it's a reference for American English, and doesn't cover standards of specific domains like medicine, law, etc. (for which there are other standards), it's a good reference for general writing. I'm not quite sure how you'd like me to prove the non-existence of multiple subtitles — i.e. other than the fact that we don't see them used in publications. You might have to do with the fact that when the topic is presented in style guides the singular is employed when mentioning a title and its subtitle. Most likely, no one felt the need to clarify this, since there are no expectations for it. The term sub-title should be indicative of the fact that the element is subordinate to the title, and that any further elements would be subordinate to the subtitle instead (i.e. sub-subtitles), if we look at the hierarchy of these elements. Trying to defend the HTML5 standard and the choices behind its "semantics" is definitely not my battle, I'm more focused on struggling to find ways to produce decent documentation with what the standard has to offer — therefore, my considerations are more practical than technical in nature. I was also clear in my initial comment that I'm sharing impressions about the possible uses of
neither are list entries which don't qualify as full sentences, yet most tools (PML included) default to mark them as Anyhow, according to the So <HGROUP> Is Back In HTML 5 article, it seems that the intended us of It's worth pointing out here what J.Knight wrote in that article:
The implicit understand here is that for publishers the term "paragraph" refers to a full sentence which delivers meaning on its own (which is not true of a list element, for example). The title needs to be self-standing (i.e. to be meaningful even if the subtitle is left out), and the title + subtitle should form a meaningful sentence. But having said that, I see the subtitle as a qualifier of the title, so it doesn't necessary need to be a sentence on its own (although it might, and often does), and while I understand Knight's argument against marking it as a Therefore, I still think that placing the subtitle in a Is it a good solution? Probably not, since it only works as expected through visual styling, and might be confusing on a screen reader for the visually impaired. But then, the reality of alternative HTML representations is already permeated with violations of guidelines and rules, in order to favor usability instead. So, it's a decent workaround IMO. When I look at the HTML source of that example, it's fairly intuitive to me that context of the paragraph being isolated within an HGROUP and immediately following a heading title implies that what I'm seeing is a subtitle (based on my knowledge that there is no The reality PML has to face is that confusion is sovereign when it comes to this topic of proper HTML tag choices for good publications — and the articles you linked confirm this trend. On the one hand, there's the HTML5 standard, which is designed to encompass a very broad spectrum of applications, not just documentation, articles and books — websites, blogs, GUIs, slideshows, CVs, ... you name it — and on the other hand you have publishers, which have their well established standards and traditions. The goals of the HTML standard and publishers don't always overlap, and neither does their terminology, which often differs or carries different meanings. For PML (as any other lightweight markup) the challenge is to find a good compromise that works well for its target audience — which, I'll never be tired to remind that it encompasses multiple standards, depending on the target domain. Which is also why I keep insisting on the need for a PML vision document, which should reassure its potential userbase on this topic. It also seems reasonable to me that the PML standard should adopt an existing style guide as its reference and blueprint, rather than relying on users requests, what you see on the web, or what other tools are doing. We can't solve the confusion that governs HTML5, but we can counterbalance it with a solid publishing standard. This "subtitle" debate strongly exemplifies this dilemma, because even though HTML doesn't have a The HTML is now exactly 30 years old, and my guess is that if its designers haven't felt the need for a dedicated I'm personally not entirely happy about how AsciiDoc and pandoc approach HTML tags, because in daily use I often struggle with their limitations. Interesting to note, Asciidoctor supports subtitles in most output formats except HTML, where it simple concatenates the document title and its subtitle into a single element. I wonder if this choice was ultimately a "non choice" in light of the confusion and many practical problems being discussed here. Even if the HTML5 standard is a pile of crap, we have no other choice than deciding which solution works best. This is nothing new in the programming field, where many (if not most) standards are either outright crap, broken, shallow or inconsistent (starting with Unicode). But if our quest to define good HTML tagging practices is going to be decided solely by confronting personal opinions and needs, or citing examples from third party tools, instead of adopting a well established style standard which is time tested and accepted by the publishing industry ... then the road ahead of us is a very long, tortuous and tiresome one. |
Beta Was this translation helpful? Give feedback.
-
Yes! And make it easy for people to change the PML defaults if needed. |
Beta Was this translation helpful? Give feedback.
-
A few consideration on titles and subtitles.
Doc vs Chapters Subtitles
From the documentation it's not clear whether a PML document supports a subtitle or not, whereas it's clear that chapters do support subtitles.
Most lightweight markup syntaxes only support a subtitle for the document main title, not for chapters/sections. The former is definitely needed, since usually any document has a subtitle, but it's great to see that PML also supports chapter/section subtitles because although they are not used as often they are good practice in certain types of documents (a title and subtitle can be seen as a subject and predicate, describing the section contents).
Doc Subtitles
In any case, it's currently possible to use a
[subtitlenode with the document title:[doc [title DOC TITLE] [subtitle DOC SUBTITLE]which will produce the following HTML:
The problem here is double H1 headers, one after the other.
According to §4.3.11:
I'm not sure this disqualifies having two consecutive H1 headings as being invalid, but the point here is that semantically a subtitle should be of an inferior order to the title. Also, from a mere HTML tag point of view, it doesn't make much sense to have two separate H1 tags here, a simple
<br>separator would have been just as fine.But my impression, from reading the HTML5 specs, is that subtitles (in general) should be handled via the
hgroupelement instead:From §4.3.11 (bold added):
Other markup tools don't seem to adopt this approach though.
Pandoc, when publishing books as chuncked HTML resorts to classes to handle subtitles:
I'm not sure why this is so, but probably it was in order to preserve functionality of the custom CSS created by the community. In any case, pandoc allows customizing HTML5 templates, so the above could be overridden.
Asciidoctor simply joins the document subtitle with the title, separating them with a default
:delimiter (which can be customized). Many users complained about this, since in other output formats the document title and subtitle are styled differently (usually the latter is smaller than the former).Either way, it might be worth investigating what the proper semantics are for handling document- and chapter-subtitles, since PML should adopt the best tagging convention in the HTML output. This is something which is best not to postpone, otherwise a later change in the HTML structure would break any existing custom CSS created by the community — something which would backlash on PML, regardless of whether these stylesheets were created for personal use or shared with the FOSS community.
I'm not an expert on HTML5, but I can clearly see that the new HTML incarnation tries to address fine-grain details of documents publishing, especially in view of how HTML/XML today are also used in e-book publishing (e.g. ePub, ePub3, and other HTML based formats). Although some of the new HTML5 tags/semantics are still not widely adopted by many popular tools, there's no reason why PML shouldn't look into them, and adopt them if they are beneficial in terms of rising the quality of the generated documents.
Chapter Subtitles
As for chapter subtitles, the following PML source:
[ch (id=heading2sub) [title Subtitled Heading Level 2] [subtitle I'm The Subtitle]is rendered as:
again, we can see a doubling of the current heading level, just as with the doc title and subtitle. My guess is that the above considerations also apply here.
I'd love to hear from @pml-lang what the original design goals were when subtitles were implemented into PMLC, and also feedback from other users who might shed some light into the best semantics for handling titles and subtitles in various types of documents.
Beta Was this translation helpful? Give feedback.
All reactions