Add documentation and examples for scaling to larger screens.

Document all attributes to root element (#impress) in DOCUMENTATION.md.

For the main demo (/index.html) add width, height, max-scale, min-scale
attributes to the main demo. These just use the defaults, except
data-max-scale="3" which allows to scale to larger screens (HD, 4K).

For examples/classic-slides, add attributes to root element and set it
to target Full HD 1920 x 1080 resolution. Adjust CSS to match.

Add notification everywhere that defaults will change in 2021.

DOCUMENTATION.md

@@ -6,10 +6,55 @@
 
 impress.js requires a Root Element. All the content of the presentation will be created inside that element. It is not recommended to manipulate any of the styles, attributes or classes that are created by impress.js inside the Root Element after initialization.
 
+To change the duration of the transition between slides use `data-transition-duration="2000"` giving it
+a number of ms. It defaults to 1000 (1s).
+
+When authoring impress.js presentations, you should target some screen size, which you can define here.
+The default is 1024 x 768. You should write your CSS as if this is the screen size used for the
+presentation. When you present your presentation on a screen (or browser window) of different size,
+impress.js will automatically scale the presentation to fit the screen. The minimum and maximum limits
+to this scaling can also be defined here.
+
+All impress.js steps are wrapped inside a div element of 0 size! This means that in your CSS you
+can't use relative values for width and height (example: `width: 100%`) to define the size of step elements.
+You need to use pixel values. The pixel values used here correspond to the `data-width` and `data-height`
+given to the `#impress` root element. When the presentation is viewed on a larger or smaller screen, impress.js
+will automatically scale the steps to fit the screen.
+
+**NOTE:** I intend to change the defaults to target HD screens in 2021. So you may want to make a habit
+of explicitly defining these attributes for now, to avoid any disruption when the defaults change.
+
+You can also control the perspective with `data-perspective="500"` giving it a number of pixels.
+It defaults to 1000. You can set it to 0 if you don't want any 3D effects.
+If you are willing to change this value make sure you understand how CSS perspective works:
+https://developer.mozilla.org/en/CSS/perspective
+
+See also [the plugin README](src/plugins/README.md) for documentation on `data-autoplay`.
+
+**Attributes**
+
+Attribute                | Default   | Explanation
+-------------------------|-----------|------------
+data-transition-duration | 1000 (ms) | Speed of transition between steps.
+data-width               | 1024 (px) | Width of target screen size. When presentation is viewed on a larger or smaller screen, impress.js will scale all content automatically.
+data-height              | 768 (px)  | Height of target screen size.
+data-max-scale           | 1         | Maximum scale factor. (Note that the default 1 will not increase content size on larger screens!)
+data-min-scale           | 0         | Minimum scale factor.
+data-perspective         | 1000      | Perspective for 3D rendering. See https://developer.mozilla.org/en/CSS/perspective
+
 **Example:**
 
 ```html
-<div id="impress"></div>
+<div id="impress"
+    data-transition-duration="1000"
+
+    data-width="1024"
+    data-height="768"
+    data-max-scale="3"
+    data-min-scale="0"
+    data-perspective="1000"
+
+    data-autoplay="7">
 ```
 
 ### Step Element
@@ -31,6 +76,13 @@ In the Step Element, you can define a specific set of default attributes and pos
 
 Define the pixel based position in which the **center** of the [Step Element](#step-element) will be positioned inside the infinite canvas.
 
+**Attributes**
+
+Attribute                | Default   | Explanation
+-------------------------|-----------|------------
+data-x                   | 0         | X coordinate for step position
+data-y                   | 0         | Y coordinate for step position
+
 **Example:**
 
 ```html
@@ -273,7 +325,7 @@ api.init();
 api.next();
 ```
 
-#### impress().prev()
+#### .prev()
 
 Navigates to the previous step of the presentation using the [`goto()` function](#impressgotostepindexstepelementidstepelement-duration).
 
@@ -285,7 +337,7 @@ api.init();
 api.prev();
 ```
 
-#### impress().goto( stepIndex | stepElementId | stepElement, [ duration ] )
+#### .goto( stepIndex | stepElementId | stepElement, [ duration ] )
 
 Accepts a [`Number`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) that represents the step index.
 

css/impress-demo.css

@@ -205,6 +205,12 @@ a:focus {
     ;)
 
     They cover everything what you see on first three steps of the demo.
+
+    All impress.js steps are wrapped inside a div element of 0 size! This means that relative
+    values for width and height (example: `width: 100%`) will not work. You need to use pixel
+    values. The pixel values used here correspond to the data-width and data-height given to the
+    #impress root element. When the presentation is viewed on a larger or smaller screen, impress.js
+    will automatically scale the steps to fit the screen.
 */
 .slide {
     display: block;

examples/classic-slides/css/classic-slides.css

@@ -7,7 +7,7 @@
   http://www.webupd8.org/2011/01/automatically-install-all-google-web.html
 */
 
-/* @import url(http://fonts.googleapis.com/css?family=Open+Sans:regular,semibold,italic,italicsemibold|PT+Sans:400,700,400italic,700italic|PT+Serif:400,700,400italic,700italic|Cutive+Mono); */
+/* @import url(https://fonts.googleapis.com/css?family=Open+Sans:regular,semibold,italic,italicsemibold|PT+Sans:400,700,400italic,700italic|PT+Serif:400,700,400italic,700italic|Cutive+Mono); */
 @import url(fonts.css);
 
 
@@ -62,14 +62,14 @@ body {
 
 .step {
     position: relative;
-    width: 900px;
+    width: 1800px;
-    padding: 40px;
+    padding: 60px;
-    margin: 20px auto;
+    margin: 60px auto;
 
     box-sizing:         border-box;
 
     font-family: 'PT Serif', georgia, serif;
-    font-size: 48px;
+    font-size: 60px;
     line-height: 1.5;
 }
 /*
@@ -105,21 +105,21 @@ body {
 .slide {
     display: block;
 
-    width: 900px;
+    width: 1850px;
-    height: 700px;
+    height: 1000px;
     padding: 40px 60px;
 
     background-image: url(../images/background.png);
     background-color: white;
-    border: 1px solid rgba(0, 0, 0, .3);
+    border: 2px solid rgba(0, 0, 0, .3);
-    border-radius: 10px;
+    border-radius: 30px;
-    box-shadow: 0 2px 6px rgba(0, 0, 0, .1);
+    box-shadow: 0 4px 8px rgba(0, 0, 0, .1);
 
-    text-shadow: 0 2px 2px rgba(0, 0, 0, .1);
+    text-shadow: 0 3px 3px rgba(0, 0, 0, .2);
 
     font-family: 'Open Sans', Arial, sans-serif;
-    font-size: 30px;
+    font-size: 45px;
-    letter-spacing: -1px;
+    letter-spacing: -2px;
 }
 
 
@@ -137,15 +137,22 @@ body {
 }
 
 .slide li {
-    margin: 0.2em;    
+    margin-top: 0.2em;
+    margin-bottom: 0.2em;
+    margin-left: 3em;
+    margin-right: 3em;
 }
 
 /* Highlight.js used for coloring pre > code blocks. */
 .slide pre > code {
-    font-size: 14px;
+    font-size: 30px;
     text-shadow: 0 0 0 rgba(0, 0, 0, 0);
 }
 
+.slide input {
+    font-size: 1em;
+}
+
 /* Inline code, no Highlight.js */
 code {
     font-family: "Cutive mono","Courier New", monospace;
@@ -157,17 +164,17 @@ a {
     text-decoration: none;
     padding: 0 0.1em;
     background: rgba(200,200,200,0.2);
-    text-shadow: -1px 1px 2px rgba(100,100,100,0.9);
+    text-shadow: -2px 2px 4px rgba(100,100,100,0.9);
     border-radius: 0.2em;
-    border-bottom: 1px solid rgba(100,100,100,0.2);
+    border-bottom: 3px solid rgba(100,100,100,0.2);
-    border-left:   1px solid rgba(100,100,100,0.2);
+    border-left:   3px solid rgba(100,100,100,0.2);
 
     transition:         0.5s;
 }
 a:hover,
 a:focus {
     background: rgba(200,200,200,1);
-    text-shadow: -1px 1px 2px rgba(100,100,100,0.5);
+    text-shadow: -2px 2px 3px rgba(100,100,100,0.5);
 }
 
 blockquote {
@@ -177,18 +184,18 @@ blockquote {
 }
 
 em {
-    text-shadow: 0 2px 2px rgba(0, 0, 0, .3);    
+    text-shadow: 0 6px 6px rgba(0, 0, 0, .3);
 }
 
 strong {
-    text-shadow: -1px 1px 2px rgba(100,100,100,0.5);
+    text-shadow: -3px 3px 6px rgba(100,100,100,0.5);
 }
 
 q {
     font-family: 'PT Serif';
     font-style: italic;
     font-weight: 400;    
-    text-shadow: 0 2px 2px rgba(0, 0, 0, .3);
+    text-shadow: 0 6px 6px rgba(0, 0, 0, .3);
 }
 
 strike {
@@ -200,34 +207,38 @@ small {
 }
 
 img {
-    width: 300px
+    width: 600px
+}
+
+td {
+    padding: 0.2em;
 }
 
 .slide .right {
     float: right;
-    margin-left:   40px;
+    margin-left:  60px;
     margin-right:   0px;
-    margin-top:    20px;
+    margin-top:    40px;
-    margin-bottom: 20px;
+    margin-bottom: 40px;
 }
 .slide .left {
     float: left;
-    margin-right:  40px;
+    margin-right: 60px;
     margin-left:    0px;
-    margin-top:    20px;
+    margin-top:    40px;
-    margin-bottom: 20px;
+    margin-bottom: 40px;
 }
 .slide .top {
     position: absolute;
-    top: 20px;
+    top: 40px;
-    margin-bottom:  20px;
+    margin-bottom:  40px;
     margin-top:      0px;    
 }
 .slide .bottom {
     position: absolute;
-    bottom: 20px;
+    bottom: 40px;
     margin-bottom:   0px;
-    margin-top:     20px;    
+    margin-top:     40px;    
 }
 
 /* 
@@ -242,13 +253,13 @@ img {
 .title h2,
 .title h3 {
     position: absolute;
-    left: 45px; /* slide width is 900px, so this is like a 5% margin on both sides */
+    left: 90px; /* slide width is 1800px, so this is like a 5% margin on both sides */
     width: 90%;
     text-align: center;
 }
 .title h1 { top: 50px; }
-.title h2 { top: 400px; }
+.title h2 { top: 600px; }
-.title h3 { top: 500px; }
+.title h3 { top: 800px; }
 
 
 
@@ -258,7 +269,7 @@ img {
  fly-in class starts from a position outside the slide, then flies into it's correct position.
 */
 .future .fly-in {
-    transform: translateY(-700px);
+    transform: translateY(-2100px);
     opacity: 0.0; /* Make it invisible, just so it doesn't clutter some other slide that might be in the position where we moved it */
 }
 .present .fly-in {
@@ -267,7 +278,7 @@ img {
     transition:         2s;
 }
 .past .fly-out {
-    transform:         translateY(700px);
+    transform:         translateY(2100px);
     opacity: 0.0;
     transition:         2s;
 }
@@ -400,10 +411,10 @@ body.impress-mouse-timeout {
 #acme-graph-bottom {
     position: absolute;
     bottom: 100px;
-    left: 440px;
+    right: 200px;
     background-color: black;
-    width: 410px;
+    width: 900px;
-    height: 2px;
+    height: 3px;
 }
 
 /* height: is set from javascript */
@@ -412,30 +423,30 @@ body.impress-mouse-timeout {
 #acme-graph-q3,
 #acme-graph-q4 {
     border: solid 1px black;
-    width: 70px;
+    width: 140px;
-    margin-left: 10px;
+    margin-left: 30px;
     position: absolute;
     bottom: 100px;
 }
 
 #acme-graph-q1 {
     background-color: red;
-    left: 450px;
+    right: 900px;
 }
 
 #acme-graph-q2 {
     background-color: blue;
-    left: 550px;
+    right: 700px;
 }
 
 #acme-graph-q3 {
     background-color: green;
-    left: 650px;
+    right: 500px;
 }
 
 #acme-graph-q4 {
     background-color: purple;
-    left: 750px;
+    right: 300px;
 }
 
 /*

examples/classic-slides/index.html

@@ -73,11 +73,24 @@
     data-transition-duration sets the time in microseconds that is used for the
     animation when transtitioning between slides.
     
+    The width, height, scale and perspective options define a target screen size that you should
+    design your CSS against. impress.js will automatically scale all content to different screen
+    sizes. See DOCUMENTATION.md for details. Below, I have targeted full HD screen resolution.
+    
     data-autoplay can be used to set the time in seconds, after which presentation
     automatically moves to next slide. It can also be set individually for each
     slide, but here we just set a common duration for all slides.
 -->
-<div id="impress" data-transition-duration="1000" data-autoplay="10">
+<div id="impress"
+    data-transition-duration="1000"
+
+    data-width="1920"
+    data-height="1080"
+    data-max-scale="3"
+    data-min-scale="0"
+    data-perspective="1000"
+
+    data-autoplay="10">
 
     <!--
         Each step of the presentation should be an element inside the `#impress` with a class name
@@ -101,7 +114,7 @@
         powerpoint slide show. The "slide" class is entirely optional and indeed you wouldn't use it for
         your cooler impress.js presentations.
     -->
-    <div class="step slide title" data-x="-1000" data-y="-1500">
+    <div class="step slide title" data-x="-2200" data-y="-3000">
         <h1>Example Presentation: <br />
             Classic Slides</h1>
         <h2>Henrik Ingo</h2>
@@ -114,7 +127,7 @@
         </div>
     </div>
 
-    <div id="toc" class="step slide" data-rel-x="1000" data-rel-y="0">
+    <div id="toc" class="step slide" data-rel-x="2200" data-rel-y="0">
         <h1>Table of Contents</h1>
         <ul>
             <li><a href="#step-1">A title slide</a></li>
@@ -134,7 +147,7 @@
            <p>Note that instead of absolute positioning we use relative positioning,
            with the data-rel-x and data-rel-y attributes. This means the step is
            positioned relative to the foregoing step. In other words, this is 
-           equivalent to data-x="0" data-y="-1500".</p>
+           equivalent to data-x="0" data-y="-3000".</p>
         </div>
     </div>
 
@@ -174,7 +187,7 @@
         Notation shouldn't be a surprise. We use `data-rotate="30"` attribute, meaning that this
         element should be rotated by 30 degrees clockwise.        
     -->
-    <div class="step slide" data-rel-x="1100" data-rel-y="300" data-rotate="30">
+    <div class="step slide" data-rel-x="2200" data-rel-y="600" data-rotate="30">
         <h1>A blockquote &amp; image</h1>
         <img src="images/3476636111_c551295ca4_b.jpg" 
              alt="Mother Teresa holding a newborn baby" 
@@ -189,7 +202,7 @@
         </div>
     </div>
 
-    <div class="step slide" data-rel-x="800" data-rel-y="800" data-rotate="60">
+    <div class="step slide" data-rel-x="1600" data-rel-y="1600" data-rotate="60">
         <h1>More text styles</h1>
         <p>As usual, use <em>em</em> to emphasize, <br />
            <strong>strong</strong> for strong, <u>u</u> for underline,<br />
@@ -202,7 +215,7 @@
         </div>
     </div>
 
-    <div class="step slide" data-rel-x="300" data-rel-y="1100" data-rotate="90">
+    <div class="step slide" data-rel-x="600" data-rel-y="2200" data-rotate="90">
         <h1>Motion effects 101</h1>
         <p>Items on the slide can</p>
         <p class="fly-in fly-out">Fly in</p>
@@ -232,7 +245,7 @@
         </div>
     </div>
 
-    <div id="addons" class="step slide title" data-rel-x="-300" data-rel-y="1100" data-rotate="120">
+    <div id="addons" class="step slide title" data-rel-x="-600" data-rel-y="2200" data-rotate="120">
         <h2>Add-ons</h2>
         <div class="notes">
         <p>This version of impress.js includes several add-ons, striving to make this a
@@ -240,7 +253,7 @@
         </div>
     </div>
 
-    <div class="step slide" data-rel-x="-800" data-rel-y="800" data-rotate="150" data-autoplay="3">
+    <div class="step slide" data-rel-x="-1600" data-rel-y="1600" data-rotate="150" data-autoplay="3">
         <h1>Impress.js plugins</h1>
         <ul>
         <li>A new <a href="https://github.com/impress/impress.js/blob/master/src/plugins/README.md">plugin framework</a> allows for rich extensibility,
@@ -263,7 +276,7 @@
         </div>
     </div>
 
-    <div class="step slide" data-rel-x="-1100" data-rel-y="300" data-rotate="180">
+    <div class="step slide" data-rel-x="-2200" data-rel-y="600" data-rotate="180">
         <h1>Highlight.js</h1>
         <pre><code>
         // `init` API function that initializes (and runs) the presentation.
@@ -289,7 +302,7 @@
         </div>
     </div>
 
-    <div class="step slide" data-rel-x="-1100" data-rel-y="-300" data-rotate="210">
+    <div class="step slide" data-rel-x="-2200" data-rel-y="-600" data-rotate="210">
         <h1>Mermaid.js</h1>
         <div class="mermaid">
         %% This is a comment in mermaid markup
@@ -316,7 +329,7 @@
         </div>
     </div>
 
-    <div id="markdown" class="step slide markdown" data-rel-x="-800" data-rel-y="-800" data-rotate="240">
+    <div id="markdown" class="step slide markdown" data-rel-x="-1600" data-rel-y="-1600" data-rotate="240">
 # Markdown.js
         
 * [Markdown.js](https://github.com/evilstreak/markdown-js) integration: for authors in a hurry!
@@ -330,7 +343,7 @@
 * [A more advanced Markdown presentation is here.](../markdown/)
     </div>
 
-    <div id="acme" class="step slide" data-rel-x="-300" data-rel-y="-1100" data-rotate="270">
+    <div id="acme" class="step slide" data-rel-x="-600" data-rel-y="-2200" data-rotate="270">
         <ul>
         <li>Remember, in <em>impress.js</em> the full power of HTML5, CSS3 &amp; JavaScript is always at your fingertips!</li>
         <li>For example, you can use tables, forms, or dynamic charts as you would on any web page:</li>
@@ -384,7 +397,7 @@
             
             // Draw the bar graph
             for ( var q in profits ) {
-                var h = 200 * profits[q] / max;
+                var h = 300 * profits[q] / max;
                 var div = document.getElementById('acme-graph-'+q);
                 div.style = 'height: ' + h + 'px';
             }
@@ -398,7 +411,7 @@
         in the root div#impress element, but it is also allowed to set it for each step. Since transitioning
         to this step will rotate twice around it's axis, we give the transition a bit more time here.
     -->
-    <div id="moreinfo" class="step slide" data-x="2020" data-y="700" data-rotate="720" data-transition-duration="2000">
+    <div id="moreinfo" class="step slide" data-x="4400" data-y="1200" data-rotate="720" data-transition-duration="2000">
         <h1>More info</h1>
         <ul>
         <li><a href="https://github.com/impress/impress.js/blob/master/DOCUMENTATION.md">DOCUMENTATION.md</a> is the API reference.
@@ -428,7 +441,7 @@
          It's a common way of zooming out at the end, to show the whole presentation.
          In CSS, we set pointer-events:none to make this slide non-clickable. 
          It makes a difference at least for SVG content, such as the mermaid diagram. -->
-    <div id="overview" class="step" data-x="3000" data-y="1500" data-scale="10" style="pointer-events: none;">
+    <div id="overview" class="step" data-x="4500" data-y="1500" data-scale="10" style="pointer-events: none;">
     </div>
 </div>
 

index.html

@@ -130,25 +130,40 @@
     That's the wrapper for your presentation steps. In this element all the impress.js magic happens.
     It doesn't have to be a `<div>`. Only `id` is important here as that's how the script find it.
     
-    You probably won't need it now, but there are some configuration options that can be set on this element.
+    Often you don't need to use any attributes here, but for educational purposes I have used all of them below.
 
     To change the duration of the transition between slides use `data-transition-duration="2000"` giving it
     a number of ms. It defaults to 1000 (1s).
     
+    When authoring impress.js presentations, you should target some screen size, which you can define here.
+    The default is 1024 x 768. You should write your CSS as if this is the screen size used for the
+    presentation. When you present your presentation on a screen (or browser window) of different size,
+    impress.js will automatically scale the presentation to fit the screen. The minimum and maximum limits
+    to this scaling can also be defined here.
+    
+    NOTE: I intend to change the defaults to target HD screens in 2021. So you may want to make a habit
+    of explicitly defining these attributes for now, to avoid any disruption when the defaults change.
+    
     You can also control the perspective with `data-perspective="500"` giving it a number of pixels.
     It defaults to 1000. You can set it to 0 if you don't want any 3D effects.
     If you are willing to change this value make sure you understand how CSS perspective works:
     https://developer.mozilla.org/en/CSS/perspective
     
-    But as I said, you won't need it for now, so don't worry - there are some simple but interesting things
+    Plugins:
-    right around the corner of this tag ;)
     
-    ----------
+    We set the default time for autoplay plugin to 7 seconds. Autoplay will automatically advance
-    Plugins: We set the default time for autoplay plugin to 6 seconds. Autoplay will automatically advance
     to next slide after a timeout expires.
-    
 -->
-<div id="impress" data-autoplay="7">
+<div id="impress"
+    data-transition-duration="1000"
+    
+    data-width="1024"
+    data-height="768"
+    data-max-scale="3"
+    data-min-scale="0"
+    data-perspective="1000"
+    
+    data-autoplay="7">
 
     <!--