Cleaning up title-page templates

Writing documentation for all the title-page options made clear that right now the default template and other templates diverge a lot and each needs custom documentation if one wants to explain how and what values are configurable.

I propose the following variables to be used in all title-pages with resource packs only adding features as to keep documentation minimal:

---
title: 'Slide or page Title'
subtitle: 'Slide or page Subtitle'
author: 'Singular Author of the slides, presented centered'
affilitation: 'Affiliation / Institute of the singular author'
copyright: 'Copyright for the slide or page'
author-link: 'Link to the singular author\'s website'
affiliation-link: 'Link to the singular author\'s affiliation\'s website'
copyright-link: 'Link to the documentation of the used copyright (e.g. creative commons)'

authors:
    - name: 'Name of one of multiple authors'
      affiliation: 'Affiliation of one of multiple authors'
      name-link: 'Link to one of multiple authors\' website'
      affiliation-link: 'Link to one of multiple authors\' affiliation\'s website.'
    - name: 'Name of one of multiple authors'
      affiliation: 'Affiliation of one of multiple authors'
      name-link: 'Link to one of multiple authors\' website'
      affiliation-link: 'Link to one of multiple authors\' affiliation\'s website.'

date: 'Date of release'

teaser: 'Path to an image presented as a teaser image for the whole presentation'

logos:
    - 'Path to an image to be used as a logo'
    - 'Path to a different image file'
---

These include only variables related to the title-page.

Additional issues will be created for other template variables.

Examples for how these turn out can be found in the template-improvements branch.

Additional input is appreciated.

We had a longer discussion about similar topics in the past. It's always not easy where to draw the demarcation line imho. Anyways, I agree, more potential information for the title page would/could be nice. I see this more as meta data of the presentation which might also end up on the title page or even on other slides.

In general, we should cluster the information as soon as it has >1 associated entries. E.g., I would cluster the logos with the affiliation(s) etc. Next questions arises if one want also the group/department etc. However, some meta is inherited by reveal/pandoc and it is always a question how to handle this (e.g., keeping backwards compatibility or not). Some more thought:

Often one also wants to add the venue (think keynotes, conference talks, etc.).
Also, a closing page with the same layout and (maybe floating blocks in the foreground with "thank you for listening" and/or "questions? makes sense.
Instead of link we should name meta more precisely, i.e., url
How about banners often used .

Could look like this:

---
title: 'Slide or page Title'
subtitle: 'Slide or page Subtitle'
author: 'Singular Author of the slides, presented centered'
author-url: 'URL to the singular author\'s website'

affiliation: 
   institution: 'Affiliation / Institute of the singular author'
   logo: 'Path to an image to be used as a logo'
   url: 'URL to the singular author\'s affiliation\'s website'

copyright: 
   type: 'Copyright for the slide or page'
   url: 'Link to the documentation of the used copyright (e.g. creative commons)'

authors:
   author: 
      name: 'Name of one of multiple authors'
      url: 'URL to this author\'s affiliation\'s website'
      affiliation: 
         institution: 'Affiliation / Institute of this author'
         logo: 'Path to an image to be used as a logo'
         url: 'URL to this author\'s affiliation\'s website'
   author: 
      name: 'Name of one of multiple authors'
      url: 'URL to this author\'s affiliation\'s website'
      affiliation: 
         institution: 'Affiliation / Institute of this author'
         logo: 'Path to an image to be used as a logo'
         url: 'URL to this author\'s affiliation\'s website'

date: 'Date of release'

teaser: 'Path to an image presented as a teaser image for the whole presentation'
banner: 'Path to an image presented as a banner image for the title/closing page  presentation' 

---

rfc

I agree with the change from "link" to "url".

While in concept I like the clustering of the affiliation data this use-case is primarily for conference presentations, not lessons. In our case the lessons of our project need three logos: the university's logo, the project's logo and the logo of the foundation giving money. These are not three authors nor three affiliations but one affiliation that simply requires three logos.

In my design of the title-page the logos of those involved would simply be aligned at the bottom of the title page in the order they are specified from left to right, spaced evenly.

Maybe we can agree upon having both: General logos that apply to the presentation and additional logos for each author if multiple authors are supplied that are displayed beneath the authors on the title-page. That way one can supply the necessary logos for a conference's required design and logos for each author if they are required to display each's organisation's logo too.

The other issue I see with this is that affiliation now has to have nested data. The four basic values (title, subtitle, author, affiliation) should be easily specifiable by a new user.

I would like to check if we can handle both kinds of supplying information within one template though: Nested and direct data.

Also I think the authors syntax used does not allow for $for(authors)$ looping last time I tried but I will check that again too.

So writing a template that can evaluate both nested and direct values actually works so I put an example of it inside the template-improvement branch. I have not touched any css for it yet but I hope that the example in the title-header-deck.md in the tests shows how, if every single of the configurable values are used, the title page gets pretty overcrowded.

Let us write down how the overcrowded dom looks like:

<title>
<subtitle>
<authors>
<author>
<affiliation>
<date>
<teaser>
<logos>

So we are having at least 8 "lines" of content that need to fit. I do not yet know how I would distribute the space in order to make it look nice with both a minimal and a maximized configuration.

Also I do not get what the difference between the teaser and banner should be. Or did you just mean to rename "logos" to "banners"?

@monofon Is there a way to clearly declare a path "relative to the project root directory" without using the "$projectPath$" inside the template? This issue crops up when specifying image locations and then putting a deck inside a subdirectory. Using "/path" works only on localhost, as soon as you put it into any complex location on your webserver this beaks if the "/path" does not get expanded into a relative path.

I agree with the change from "link" to "url".

While in concept I like the clustering of the affiliation data this use-case is primarily for conference presentations, not lessons. In our case the lessons of our project need three logos: the university's logo, the project's logo and the logo of the foundation giving money. These are not three authors nor three affiliations but one affiliation that simply requires three logos.

You are arguing with a specific use-case, which does not cover everything in general. This discussion should be more about (potential) extensions for the meta data, we can interpret with different templates.

In my design of the title-page the logos of those involved would simply be aligned at the bottom of the title page in the order they are specified from left to right, spaced evenly.

As you wrote, in your design ;)

Maybe we can agree upon having both: General logos that apply to the presentation and additional logos for each author if multiple authors are supplied that are displayed beneath the authors on the title-page. That way one can supply the necessary logos for a conference's required design and logos for each author if they are required to display each's organisation's logo too.

No, we can and should agree on the meta data. How that is used in the templates is up to the different use-cases (lectures, talks in public, internal talks, ...)

The other issue I see with this is that affiliation now has to have nested data. The four basic values (title, subtitle, author, affiliation) should be easily specifiable by a new user.

I would like to check if we can handle both kinds of supplying information within one template though: Nested and direct data.

Also I think the authors syntax used does not allow for $for(authors)$ looping last time I tried but I will check that again too.

I now understand your viewpoint about our meta-data variables.

The issue I see it with viewing it that way is for the intent of writing a user guide. The information "You can supply a meta-data variable that then gets interpreted by some resource-pack suppliers to be used in a way that is completely up to them." is useless to a a user who wants know "If you want to have X on your title-page, supply this data in your config."

If we leave it open where and when meta-data is interpreted every resource pack needs its own user-guide that explains how the meta-data is used to create the slides.

My whole reason for creating this issue was so we can find a unified way of how we interpret the meta-data so each resource pack does not need to explain itself and instead we can clearly say "Title Pages in general have these parts and if you want to change them: This is how." - where exactly on the page things appear are up to each resource pack but if one resource pack decides "I will not do anything with this data" or "I will put that data on a final 'goodbye' slide" then it will make explaining it to an end-user all the more difficult or redundant.

I now understand your viewpoint about our meta-data variables.

The issue I see it with viewing it that way is for the intent of writing a user guide. The information "You can supply a meta-data variable that then gets interpreted by some resource-pack suppliers to be used in a way that is completely up to them." is useless to a a user who wants know "If you want to have X on your title-page, supply this data in your config."

Yes of course. So the solution to this is to define the necessary meta data first and then to document it.

If we leave it open where and when meta-data is interpreted every resource pack needs its own user-guide that explains how the meta-data is used to create the slides.

I did not imply this. Just the opposite. Sorry, you are a bit lost here maybe because you came in late but this is a discussion with a quite longer history. Yes, if we want to further paramterize templates then of course the required parameters (including meta data for specific contents) have to be properly documented. That should be a no-brainer.

My whole reason for creating this issue was so we can find a unified way of how we interpret the meta-data so each resource pack does not need to explain itself and instead we can clearly say "Title Pages in general have these parts and if you want to change them: This is how." - where exactly on the page things appear are up to each resource pack but if one resource pack decides "I will not do anything with this data" or "I will put that data on a final 'goodbye' slide" then it will make explaining it to an end-user all the more difficult or redundant.

Your ‚unified Way‘ can not exist for all use-cases since there will be meta data important for almost all templates (think ‚author’ etc. or the ones already supported by reveal) but specific general templates will require specific ones where between the templates some will also be shared. However, when it comes to meta data which describes the overall authoring process there will be a lot of meta which is universally applicable to almost all content. The question of which meta data you want to see on your slides, i.e., how specific templates use this data, is not fixed and can‘t because it also depends on the presentation context etc. Hence there is no clean way or „one size fits all“ approach as you can see also with the myriad LaTeX templates for different uses cases, i.e., conferences. They all use some of the meta data but not all and there is no way around proper documentation of the meta-data and of a specific tamplate‘s usage of the latter.

A general one-size-fits-all template where users can arbitrarily chose and activate certain meta data to appear or not to appear is almost impossible due to the constraints between amount of information and available space given the fact one also want a certain appeal in the layout and design. Again, not new and very much comparable to other authoring and layout tools. We can try to approach the ‚more paramterization‘ goal but it would need a different intermediate layout scheme. Here we thought about this but always postponed it since it would lead to a larger change in the overall decker layout approach we are using at the moment.

Yes I understand and I am sorry I didn't clarify what I meant with "unifying" the data. What I meant was basically checking what values our 3 - 4 title-page templates are currently using and taking the intersection of that - adjusting a few words for terminology and adding a few requested options we can maybe all agree upon making use of on the title-page - and calling these our "default values" that we document in a common location.

With the adjustments to the nesting you suggested it would have broken up this intersection unless it was possible to also keep the unnested configuration, therefore I was a bit worried that this discussion would lead to the opposite of what I was actually trying to accomplish: Keeping things simple, tidy and explainable.

With the adjustments to the nesting you suggested it would have broken up this intersection unless it was possible to also keep the unnested configuration, therefore I was a bit worried that this discussion would lead to the opposite of what I was actually trying to accomplish: Keeping things simple, tidy and explainable.

There cannot be a conflict-free unique intersection since reveal's out-of-box meta-data does not express everything some of us want, i.e., multiple authors. Backwards compatibility would then mean we have to support two ways to express the same thing which is not a good approach imho because then we end up with a semantic nightmare to decide what to do if the same is defined twice. This is, b.t.w., different from our alternative ways to specify blocks etc. Though I also am not a big fan of these alternatives (it makes it much harder for newbies to understand what is going on), at least these alternative syntaxes are not potentially conflicting.

However, two alternatives to specify the same meta data is different. So either we decide to clean this up in a sensefull manner, risking to loose backwards compatibility (and update our materials to be compatible with newer decker versions) or we are stuck here.

decker-edu / decker

Cleaning up title-page templates #42