feat(cover-page): add support for subtitle and revision infos

[Nexyll]

A first step to implement #84.

The idea beind this MR is to bring the default generation of asciidoctor-pdf-web closer to what is already done by asciidoctor-pdf.

For other properties (author, revisions, ...) they can be added in divs with specific ids for styling, according to what is already done in this MR.

The drawback of the changes is that existing documents may have based their stylesheet on the fact that the author was in an h2 tag on the cover page. This MR introduce breacking changes for those documents.

[ggrossetie]

To avoid duplicating the outer HTML <div>, you can do:

const titlePageContent = /* ... */
// ...
return `<div id="cover" class="title-page front-matter">${titlePageContent}</div>`

[ggrossetie]

I think the HTML structure should be:

<div class="details">
<span class="author">${node.getDocument().getAuthor()}</span>
<span class="revnumber"><!-- ... --></span>
<span class="revremark"><!-- ... --></span>
</div>

For the revision date, we could use <time> with datetime (if the date is valid).
Also keep in mind that an AsciiDoc document can have more than on author.
We should probably use getAuthors and display author's email if available.

For inspiration, you can take a look at:

• https://github.com/jirutka/asciidoctor-html5s/blob/5c53fd2749ad980b9015f0502a822f86f01a4f8b/data/templates/_header.html.slim#L5-L25
• https://github.com/asciidoctor/asciidoctor/blob/e0c8cc5c4398d37d2558063d25f6c8f100cf50b5/lib/asciidoctor/converter/html5.rb#L190-L213

[ggrossetie]

This code should not be duplicated, you can construct partial HTML blocks:

const title = docTitle.hasSubtitle() ? `<h1>...</h1><h2>...</h2>` : `<h1>...</h1>`
const detail = `<div class="details">...</div>`

return `<div id="cover" class="title-page front-matter">
${title}
${detail}
</div>`

[ggrossetie]

Hey @Nexyll

Thanks for this pull request.
I left a few comments/suggestions.

The idea beind this MR is to bring the default generation of asciidoctor-pdf-web closer to what is already done by asciidoctor-pdf.

That's a good idea 👍

For other properties (author, revisions, ...) they can be added in divs with specific ids for styling, according to what is already done in this MR.

I don't think we should use ids for styling but classes (see comments).

The drawback of the changes is that existing documents may have based their stylesheet on the fact that the author was in an h2 tag on the cover page. This MR introduce breacking changes for those documents.

That's true but this project is still in alpha stage so we can break things (especially when it's for the better!).
I will note down this breaking change in the next release note.

[Nexyll]

Hey,

Thanks for your comments. I've just pushed a new version with your suggestions 😉

[ggrossetie]

It actually brings quite a few questions.

Let's take an example:

= Document Title: Subtitle
Guillaume Grossetie <[email protected]>; Kismet Lee 
2.9, October 31, 2021: Fall incarnation

And here's the result using Asciidoctor PDF 1.5.4:

asciidoctor-pdf doc.adoc

asciidoctor-pdf -a title-page doc.adoc

And here's the result using Asciidoctor 2.0.12

asciidoctor doc.adoc

I think it would make sense to produce the same HTML whether title page is enabled or not.
Using the same logic, I think we should always output all the information and use CSS to decide if they should be displayed or not.

In order to support subtitle, I think we should use the following HTML structure:

<header>
  <h1>Document Title</h1>
  <p class="subtitle">Subtitle</p>
</header>

Also, when there's more than one author, we could use an unordered list:

<ul class="authors">
  <li><span class="author">Guillaume Grossetie</span><a class="email" href="mailto:[email protected]">[email protected]</a></li>
  <li><span class="author">Kismet Lee</span></li>
</ul>

[ggrossetie]

Since I'm not 100% sure what we should do, I need to give it more thoughts and experiment a bit.

I checked out your branch, I will try my suggestion to find its limits.

[ggrossetie]

@Nexyll Just to keep you informed, I'm now leading the effort to create a modern HTML converter upstream: https://github.com/asciidoctor/asciidoctor/projects/1

Following our discussion, I wrote a complete proposal on which semantic constructs we should use for the author(s) and revision: asciidoctor/asciidoctor#3967

[Nexyll]

Thanks!

If I understand correctly, rather than generating something on the asciidoctor-web-pdf side, the goal is to achieve the front page generation cleanly in the new html rendering system of asciidoctor ?

If this is the case, I don't know how I can help, but if you have an idea don't hesitate to ask me.

[ggrossetie]

Thanks!
If I understand correctly, rather than generating something on the asciidoctor-web-pdf side, the goal is to achieve the front page generation cleanly in the new html rendering system of asciidoctor ?

Yes, that's correct.
The goal is to create a modern HTML converter in Asciidoctor (upstream) and then use it in this project (downstream).

If this is the case, I don't know how I can help, but if you have an idea don't hesitate to ask me.

You can review pull requests and comment on issues related to this project: https://github.com/asciidoctor/asciidoctor/projects/1

Currently, I'm working on the revision: asciidoctor/asciidoctor#4022

And here's the new converter: https://github.com/asciidoctor/asciidoctor/blob/feature/html-converter-next/lib/asciidoctor/converter/semantic-html5.rb
Please keep in mind that this is a work in progress.

You can also take a look at: https://github.com/asciidoctor/asciidoctor/tree/feature/html-converter-next/test/fixtures/semantic-html5-scenarios
It will give you a good idea of what the converter will produce for a given AsciiDoc file.
For instance:

author-with-email.adoc

= Document Title
Stuart Rackham <founder@asciidoc.org>

will produce:

author-with-email.html

<header>
<p class="byline">
<span class="author">Stuart Rackham <a href="mailto:[email protected]" rel="author">[email protected]</a></span>
</p>
</header>