Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Use a consistent naming convention for Docinfo locations #466

Open
ggrossetie opened this issue Mar 7, 2022 · 5 comments
Open

Use a consistent naming convention for Docinfo locations #466

ggrossetie opened this issue Mar 7, 2022 · 5 comments
Labels
🎤 discussion Items that needs to be discussed with the broader Asciidoctor community 🍩 improvement 📝 documentation
Milestone
5.0.0

Comments

@ggrossetie
Copy link
Member

ggrossetie commented Mar 7, 2022 •
edited

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 New docinfo before slides #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 ggrossetie added 🍩 improvement 🎤 discussion Items that needs to be discussed with the broader Asciidoctor community 📝 documentation labels Mar 7, 2022
@ggrossetie ggrossetie added this to the 5.0.0 milestone Mar 7, 2022
@ggrossetie
Copy link
Member Author

@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
Copy link
Member

mojavelinux commented Jun 7, 2022 •
edited

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!

@ggrossetie ggrossetie mentioned this issue Jun 24, 2023
Open
@yann-soubeyrand
Copy link

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
Copy link
Member Author

ggrossetie commented Jul 1, 2023 •
edited

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
Copy link

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
🎤 discussion Items that needs to be discussed with the broader Asciidoctor community 🍩 improvement 📝 documentation
Projects
None yet
Milestone
5.0.0
Development

No branches or pull requests
3 participants
@mojavelinux @ggrossetie @yann-soubeyrand