Use a consistent naming convention for Docinfo locations

ggrossetie commented 2 years ago

Currently, we support 4 locations:

Location	Description	Docinfo suffix
`header`	At the beginning of the presentation (i.e. before all slides)	`header-revealjs.html`
`footer`	At the end of the presentation (i.e. after all the slides)	`footer-revealjs.html`
`head`	Just before `</head>`	`head-revealjs.html`
`footer`	Just before `</html>` (after `reveal.js` script)	`footer.html`

In the future, we might want to inject Docinfo files at the beginning of every slide (i.e., slide header) and at the end of every slide (i.e., slide footer). Though, we might want to inject Docinfo files at the beginning of every top-level slide rather than on every slide... or maybe only on vertical (i.e. secondary/vertical navigation) slides.

Proposal

header: Just before and outside of <div class="slides"> (to accomodate https://github.com/asciidoctor/asciidoctor-reveal.js/issues/376)
first: At the beginning of the presentation (i.e. before all slides)
last: At the end of the presentation (i.e. after all the slides)
head: Just before </head>
footer: Just before </html>

//cc @mojavelinux

ggrossetie commented 2 years ago

@mojavelinux I would greatly appreciate your input on this proposal since this is the last standing issue before the 5.0.0 release and I'm a bit unsure about the terminology...

I'm also questioning if we should have Docinfo with and without suffix? For instance, head and footer location are not tied to reveal.js since we insert content respectively just before </head> and just before </html>. But at the same time, it might be useful to dissociate docinfo files that are specific to a reveal.js presentation...

mojavelinux commented 2 years ago

I would prefer "front" and "back" instead of "first" and "last". That's consistent with terminology used elsewhere in the Asciidoctor ecosystem (such as front cover and back cover for a PDF or EPUB 3).

I'm totally find with requiring the location in the filename. The only reason it's optional in the core converters (HTML and DocBook) is for backwards compatibility when there was only a single insertion slot. Now that we have specific insertion slots, it's more intelligible to have the location in the filename.

Beyond that, go for it!

yann-soubeyrand commented 1 year ago

Hello,

I’m not an expert of docinfo, but I was surprised that, what seemed to be standard docinfo to me (docinfo-head.html and docinfo-header.html), didn’t work with asciidoctor-revealjs. By the way, unless I’m wrong, docinfo-footer.html content is added just before </body>, not </html>. However, if these docinfo happen to not really be a standard, I’m fine with renaming them, especially if header-revealjs and footer-revealjs are renamed first and last or front and back.

I also like the idea of having something like a slide-header and slide-footer, and to a lesser extent horizontal-slide-header, horizontal-slide-footer, vertical-slide-header and vertical-slide-footer, though it may reveal (pun not intended) useful.

If the “slides” docinfo are added, may I suggest to rename header-revealjs and footer-revealjs to presentation-header and presentation-footer respectively (maybe changing the suffixes header and footer for better names, like front and back, or prologue and epilogue, etc)?

ggrossetie commented 1 year ago

Thanks for your input!

I’m not an expert of docinfo, but I was surprised that, what seemed to be standard docinfo to me (docinfo-head.html and docinfo-header.html), didn’t work with asciidoctor-revealjs

It does work but the suffix is -revealjs.html not .html. The main challenge is that we need to define/decide what "header" and "footer" means when producing an HTML presentation.

It could mean:

the header and footer of the HTML document
the header and footer of the presentation (first slide, last slide)
the header and footer of slides

For reference, here's the markup of a reveal.js presentation:

<html>
  <head>
    <link rel="stylesheet" href="dist/reveal.css">
    <link rel="stylesheet" href="dist/theme/white.css">
  </head>
  <body>
    <div class="reveal">
      <div class="slides">
        <section>Slide 1</section>
        <section>Slide 2</section>
        <section>
          <section>Slide 2.1 (vertical)</section>
          <section>Slide 2.2 (vertical)</section>
        </section>
      </div>
    </div>
    <script src="dist/reveal.js"></script>
    <script>
      Reveal.initialize();
    </script>
  </body>
</html>

Here's a revised proposal where all possible "header locations" are named:

<html>
  <head>
    <link rel="stylesheet" href="dist/reveal.css">
    <link rel="stylesheet" href="dist/theme/white.css">
  </head>
  <body>
    <!-- header (most likely used to configure plugins since the content won't be visible here) -->
    <div class="reveal">
      <!-- before (most likely used to configure plugins since the content won't be visible here) -->
      <div class="slides">
        <!-- front (first slide) -->
        <section>
           <!-- heading / top? (slide header) -->
           Slide 1
         </section>
         <!-- ... ->

I'm trying to stick to a single word but it might be better to use slideheader instead of heading or top.

By the way, unless I’m wrong, docinfo-footer.html content is added just before , not

You are correct, I will fix it.

If the “slides” docinfo are added, may I suggest to rename header-revealjs and footer-revealjs to presentation-header and presentation-footer respectively

The suffix "revealjs" was added to disambiguate a docinfo used by the built-in HTML5 converter from a docinfo used by the reveal.js converter (HTML5 presentation). The naming is [docname]-docinfo-<location>-<suffix>.

I also like the idea of having something like a slide-header and slide-footer, and to a lesser extent horizontal-slide-header, horizontal-slide-footer, vertical-slide-header and vertical-slide-footer, though it may reveal (pun not intended) useful.

I would prefer to defer until someone makes a strong case for it.

yann-soubeyrand commented 5 months ago

Hello,

I also like the idea of having something like a slide-header and slide-footer, and to a lesser extent horizontal-slide-header, horizontal-slide-footer, vertical-slide-header and vertical-slide-footer, though it may reveal (pun not intended) useful.

I would prefer to defer until someone makes a strong case for it.

I think I’ve a use case for it (unless it’s already possible another way?): I’d like to put an URL and license information in a footer on every slides.

asciidoctor / asciidoctor-reveal.js

Use a consistent naming convention for Docinfo locations #466

Proposal