Manual Info & Metadata

[tajmone]

This issue tracks (and discusses) the status of metadata and other book info for the Alan Manual document header:

• Book Info:
  • :doctitle: — The ALAN Adventure Language Reference Manual
  • :description:???
  • :keywords:???
• Author(s) Info:
  • :author:???
  • :email:???
• Others?

---

Live Preview links

These links point to the dev-man branch, and will work even after force-pushing to the PR:

• HTML Manual
• PDF Manual

---

NOTE — some of the header entries will also be useful elsewhere, eg, in the [Colophon] or eBook metadata in formats like ePub, Mobi, etc.; therefore it would be a good idea to employ user defined attributes to store some book-related strings and info that could then be referenced in various places.

Metadata is useful in terms of SEO when creating HTML online pages, and with eBooks it improves indexing them in ebook stores, as well as in an eBook Reader device's indexing.

AsciiDoctor Documentation References

• § 14. Header
  • § 14.5. Metadata
  • § 14.6 Header Summary
• § 51. Colophon

[tajmone]

@thoni56

Authorship

Currently the manual doesn't mention any author(s). I think that having a base author established is important, especially for the Copyright statement (which might be required when submitting the eBook to some book portals or services).

Being a collaborative work, it could have "various authors" — in Italian we use "Aa.Vv." (auctores varii) to indicate this, which has its English counterpart in the "Vv.Aa." acronym (rarely used though). But having established the base author(s), we could employ something like "Thomas Nilefalk et al.".

IMO, regardless of the authors displayed in the book's front matter, the Copyright statement needs to be traceable to some individual(s) or organization.

[tajmone]

OK @thoni56, I've fixed all pending tasks and only need to remove the -CR from the document version and we're ready to merge into master. But first I wanted to discuss with you the metadata addition and some other minor details.

Metadata

Here's the current state of the document metadata:

:doctitle:  The ALAN Adventure Language Reference Manual
:version-label: ALAN
:revnumber: Beta7-RC
:revdate:   September 22, 2020
:revremark: New AsciiDoc Reprint
:author:    Thomas Nilefalk
:email:     thomas@alanif.se
[...]
// HTML METADATA
:keywords: alan, if, interactive fiction, game, text adventures, programming
:description: pass:q,r[*The ALAN IF Manual* -- The official reference manual \
    for the ALAN Adventure programming language for creating Interactive \
    Fiction text-adventures.]

Which produces the following Heading and byline:

The ALAN Adventure Language Reference Manual

Thomas Nilefalk — thomas@alanif.se — Alan Beta7-RC, September 22, 2020 | New AsciiDoc Reprint

I thought of using the :revremark: to show the "New AsciiDoc Reprint" comment on the document byline, since it's a "special edition" of the Manual (like we could do for anniversaries, etc.). But of course, we can remove it if you don't like.

HTML Specific Metadata

In the HTML source, you'll see the keywords and description metadata:

<meta name="description" content="<strong>The ALAN IF Manual</strong>&#8201;&#8212;&#8201;The official reference manual for the ALAN Adventure programming language for creating Interactive Fiction text-adventures.">
<meta name="keywords" content="alan, if, interactive fiction, game, text adventures, programming">

For the description, I've used the <bold> style for the first part, to make it stand out in search engine results. Also, I hope the text is fine.

PDF Issues

Please note that in the PDF document the custom definition of :version-label: to ALAN (in order to show ALAN Beta7 as the version number) doesn't work, and it shows instead:

Revision Beta7-RC

There isn't much I can do about it because it's one of those differences between Asciidoctor and DocBook that can't be worked-around. Maybe in the future we might look again into the native Asciidoctor PDF backend, which has been improved since our last tests, and possibly fixed those problems for which we had discarded it at the time.

Preamble

I though of leaving a document Preamble section, although I've cleaned it up in view of the official release. The idea is that the Preamble could contain a summary introduction to each specific edition, highlighting its new features.

In this case, I focused on the fact that it's the first public release of the new "version":

This is the first public release of the new version of the ALAN Manual, ported to AsciiDoc by Tristano Ajmone. The new edition is now availble in HTML and PDF format, featuring contents updates and many improvements, like syntax highlighting of Alan code examples.
This document is subjected to the Artistic License 2.0 terms.

Also, the "Artistic License 2.0" text now links to "Appendix I", which contains the full license text, instead of the license file on the repository.

---

So, let me know if we need to change anything before releasing.

When we're good to go I'll just do one more commit, removing the -RC from the Beta7-RC in :revnumber:, and then merge into master.

Also, another important detail, the merge strategy ...

Should we just merge, or should we squash?

If we merge, we should then keep the dev-man branch alive, to prevent all the temporary dev commits to end up in master — and, from what I understand, there's no reason why dev-man shouldn't be a long-standing branch, that we keep alive for the whole development cycle, merging into master whenever a public release is ready.

On the other hand, if you want complete separation between master and dev-man we should then squash into a single commit, and then squash dev-man on master to keep it in synch — but I'm not sure how good this is going to be in order to keep it rebaseble on master in the course of time.

I'm not sure which strategy is better, so I leave to you the choice — just let me know how to handle it!

[thoni56]

I thought of using the :revremark: to show the "New AsciiDoc Reprint" comment on the document byline, since it's a "special edition" of the Manual (like we could do for anniversaries, etc.). But of course, we can remove it if you don't like.

I like it. It indicates to the observant reader, at least, that there is something new going on.

Should we just merge, or should we squash?

My thinking was along keeping the dev branch alive, with merging for every SDK release and continuous rebase to keep it easily mergeable. But I'm no expert here, and don't know who to ask (except perhaps StackOverflow ;-).

My suggestion is to go with merging/rebasing of the long-lived dev-branch. If we find troubles along the way we'll re-assess, learn and change.

Cominchiamo!