Use semantic constructs for the author(s) and revision

[ggrossetie]

This issue will be addressed as part of: #242

Author(s)

When there are a more than one author, we should probably use an unordered list:

<ul class="byline">
  <li><!-- author 1 --></li>
  <li><!-- author 2 --></li>
</ul>

When there's only a single author, we could probably use a <p> element:

<p class="byline">
  <!-- author -->
</p>

If we want to use same structure regardless of the number of authors, then we could use a generic container like <div class="byline">?

In the above examples, I'm using the class byline because it seems to be a well-established term: https://en.wikipedia.org/wiki/Byline
For reference, the Asciidoctor EPUB3 is using it: https://github.com/asciidoctor/asciidoctor-epub3/blob/3bfee503ee959119c1fe0097b1346fe49ff7fdea/lib/asciidoctor-epub3/converter.rb#L356

An author consists of a name and an optional email.
Using a <span> element for the author's name and a <a> element for the author's email seem sufficient:

<span class="author">John Doe</span> <a rel="author" href="mailto:john@writer.org">john@writer.org</a>

Here are complete examples:

<ul class="byline">
  <li><span class="author">Kismet Lee</span></li>
  <li><span class="author">John Doe</span> <a rel="author" href="mailto:john@writer.org">john@writer.org</a></li>
</ul>

<p class="byline">
  <span class="author">John Doe</span> <a rel="author" href="mailto:john@writer.org">john@writer.org</a>
</p>

Email rel="author"

MDN suggests that we should add the link type "author" (rel="author") on the author's email:

<a rel="author" href="mailto:john@writer.org">john@writer.org</a>

https://developer.mozilla.org/en-US/docs/Web/HTML/Link_types

In addition, some resources claim that contact information should be enclosed in a <address> element:

<address>
  <span class="author">John Doe</span><a rel="author" href="mailto:john@writer.org">john@writer.org</a>
</address>

https://developer.mozilla.org/en-US/docs/Web/HTML/Element/address

Since the email address is optional, I'm not convinded that this is actually a good idea to enclose the author in an <address> element when the email address is present.

Author format

I think, it might be a good idea to have a dedicated method to format an author.
My understanding is that there are cultural differences and we certainly don't use the same format to display someone's name.
Furthermore, some journals might have strict styles regarding author's names, for instance:

Author last name middle name, first name

Author last name, first name initial.

This method would return HTML (as a string), so it would be possible to merge the email address with the author name:

<a rel="author" href="mailto:john@writer.org">John D.</a>

Revision

Revision information includes a revision number, date, and remark.

Description list

Using a description list is one way to structure the information:

<dl class="revision">
  <dt class="revnumber">Version</dt>
  <dd>1.2.3</dd>
  <dt class="revdate">Date</dt>
  <dd><time datetime="2021-10-31">October 31, 2021</time></dd>
  <dt class="revremark">Remark</dt>
  <dd>Fall incarnation</dd>
</dl>

Note: revnumber, revdate and revremark are defined on the dt to make it easier to style.
For instance, if I want to apply a custom style on the revision date:

dt.revdate + dd {
  /* ... */
}

For reference, here's how we can create an inline layout:

dl.revision > dt.revdate, dt.revremark {
  display: none;
}
dl.revision > dd {
  margin: 0;
}
dl.revision > dt.revnumber + dd::after {
  content: ','
}
dl.revision > dt.revdate + dd::after {
  content: ' |'
}
dl.revision > dd, dt {
  display: inline;
}

A nice benefit is that the revision information are "naturally" enclosed inside a container.

Table

Using a table is also a very good way to structure revision information.
It's also "future proof", if we decide to support a list of revisions.

<table class="revision">
  <thead>
  <tr>
    <th>Version</th>
    <th>Date</th>
    <th>Remark</th>
  </tr>
  </thead>
  <tbody>
  <tr>
    <td>1.2.3</td>
    <td>
      <time datetime="2021-10-31">October 31, 2021</time>
    </td>
    <td>Fall incarnation</td>
  </tr>
  </tbody>
</table>

As you can see the information is nicely displayed without any custom style.

Just like a description list, a <table> element provides a "natural" container.

For reference, here's how we can create an inline layout:

table.revision > thead {
  display: none;
}
table.revision tr > td:first-child::before {
  content: 'Version '
}
table.revision tr > td:first-child::after {
  content: ','
}
table.revision tr > td:nth-child(2)::after {
  content: ' |'
}

Please note that the value "Version" could be retrieve from an attribute using attr() CSS function:

table.revision tr > td:first-child::before {
  content: attr(data-title) ' '
}

<tr>
  <td data-title="Version">1.2.3</td>
  <td data-title="Date">
    <time datetime="2021-10-31">October 31, 2021</time>
  </td>
  <td data-title="Remark">Fall incarnation</td>
</tr>

Alternatives

span elements

I feel like <span> elements are a poor way to structure revision information.
One issue is that we cannot associate a label with a value.

label elements

In theory a <label> can describe an element but in practice they are always use in assocation with an <input> element.
In my opinion, using a <label> element to describe an inline element (such as <span>) won't be a legitimate use.

https://developer.mozilla.org/en-US/docs/Web/HTML/Element/label

Revision date

<time datetime="2021-10-31">October 31, 2021</time>

datetime attribute

The format is loose (unspecified?) but according to the specification the datetime attribute is not mandatory:

The datetime attribute may be present. If present, its value must be a representation of the element's contents in a machine-readable format.

https://www.w3.org/TR/html51/textlevel-semantics.html#the-time-element

I guess we could try to parse the date using Date._parse and if the date is "valid" then we could set the datetime attribute using ISO 8601 format (YYYY-MM-DD as in 2021-03-14).

Note: Date._parse can return invalid dates:

p Date._parse('October 31, 2021') # {:year=>2021, :mon=>31, :mday=>10}
p Date._parse('2021-10-31') # {:year=>2021, :mon=>10, :mday=>31}
p Date._parse('2021-31-10') # {:year=>2021, :mon=>31, :mday=>10}

In the last example, the month is 31!

Embedded / Standalone

I think that the author(s) and revision should be included in both the embedded and the standalone HTML using the same structure.
We can then apply styles to control how we want to display these information. Initial discussion: #2408

[mojavelinux]

This is a very well-written proposal. Nice work @Mogztter!

[mojavelinux]

To accommodate multiple revisions, as an alternative to the table, we could consider enclosing each dl structure as an item in an unordered list. The dl structure represents one revision, whereas the list encapsulates all the revision entries. Another possibility is to wrap each revision entry in a div inside the dl, though I'm not sure that's in the spirit of what the WhatWG is intending.