= Usage

Showoff is meant to be run in a Showoff formatted repository - that means that
it has a <tt>showoff.json</tt> file and a number of sections (subdirectories) with
markdown files for the slides you're presenting.

    $ git clone (showoff-repo)
    $ cd (showoff-repo)
    $ showoff serve

If you run Showoff in the example subdirectory of Showoff itself, it will
show an example presentation, so you can see what it's like.

You can also run <tt>showoff serve</tt> inside a section subdirectory. If there is no
<tt>showoff.json</tt> file then it will make its best guess, creating a presentation
from all `.md` files in alphabetical order in the given (or current)
directory.

== Available URL Paths

Once the showoff server is running, you can connect to it via a standard modern
web browser. The following URL paths are available for use by you and your audience.

[http://localhost:9090]
  This is the standard no-frills presentation. You can present from this if you wish
  and your audience can also browse to this using the IP or DNS name of your system.
  Press <tt>z</tt> to get hotkey help.

[http://localhost:9090/presenter]
  This view is useful for the presenter. It displays a more complete view of your
  presentation, including a full tree view of all slides and presenter notes underneath
  the slide itself. It will attempt to open a display window that you can put on the
  projector. The display window will follow along with the presenter window. If you have a
  popup blocker running, the display window may not open. There is a button in the toolbar
  to manually open a new display window in this case.

  If password protection is enabled, this view is often protected and you will need
  to authenticate to view.

  If this path is opened by a secondary device, such as a mobile browser, then it can also
  control the presentation if enabled with the <tt>Enable Remote</tt>  button. Showoff
  tries to be intelligent about which slide change updates to track.

[http://localhost:9090/print/$notes-type]
  This will generate printable version of your presentation, including any slides that
  were tagged as _printonly_. This view can be printed directly from the browser, or
  processed with any HTML-to-$thing engine. Add the optional <tt>$notes-type</tt> argument
  to select which <tt>SECTION</tt> variant to attach below the slides.

[http://localhost:9090/download]
  Your slides can include files for viewers to download and these files will be listed
  on this page as the presenter pages past the slide containing the download definition.

[http://localhost:9090/stats]
  The showoff server keeps track of which slides your audience is viewing and how much
  time they are spending on them. Time is only accumulated for slides that are not the
  slide currently being displayed. These stats are available for consumption on this
  page. If the presenter views the page, a full listing of which pages and which hosts
  are viewing them is shown. If an audience member views the page, only a summary is listed.

[http://localhost:9090/supplemental/$type-name]
  Showoff has the ability to include supplemental material that are defined by special
  slide types. This URL path will allow you and/or the audience to retrieve the
  supplemental materials. This is most often used to generate printed material ahead
  of time rather than during the presentation itself.

== Presenter View Tools

The presenter view is broken into several areas with tools that are mostly self explanatory. Nevertheless, I'll summarize their usage.

=== Toolbar

This is the black toolbar across the top of the presenter view. It has several important
tools that you should be familiar with.

[Slide Name]
  This is the name of the current slide. The name is derived from the filename that is
  used to generate the slide, so is exponentially more useful than a slide number when
  correlating slide content with the source file used to generate it.

[Edit Slide]
  If the <tt>showoff.json</tt> file contains an <tt>edit</tt> key then this button
  will allow presenters to edit the source of the current slide using an online editor
  at the configured location. This is most useful when your slide source is stored in
  GitHub, or another repository that allows interactive editing. This button only appears
  when showoff is called with the <tt>--review</tt> command line flag.

[Report Issue With Slide]
  If the <tt>showoff.json</tt> file contains an <tt>issues</tt> key then this button
  will allow presenters to report problems with the slide currently being viewed
  using the configured issue tracker.

[Viewing Statistics]
  Drops down a menu of the viewer stats from the <tt>/stats</tt> URL path. Contains a
  link to open the full page in a new window.

[Downloads]
  Drops down a menu of all available downloads. Contains a link to open the full
  page in a new window.

[Display Window]
  Opens the display window or attempts to reconnect to an existing window. This window
  is useful to place on a projector. The presentation can be controlled from either the
  Display Window or the Presenter View.

[Next Window]
  Opens a small preview window for the next upcoming slide.

[Notes Window]
  Opens a separate and resizable instructor notes window.

[Print Slides]
  Prints the slides using the browser's native print functionality. Many browsers allow
  you to print to PDF.

[Switch View]
  Changes to the Display view that your audience normally sees.

=== Presenter Tools

[Countdown Timer]
  This is just a simple countdown timer. Enter the time allotted to your presentation
  and it will begin counting down for you, changing color as it approaches zero.

[Pace Feedback Gauge]
  When the audience provides pace feedback for you, it will appear on this gauge. You should
  aim to keep the gauge near the center. The left side indicates that you are moving too
  slowly and the right side is too fast. The feedback messages decay over time and will
  expire in about five minutes--meaning that the gauge will move back towards the center.

[Slideshow Tree]
  On the left side of the browser window is a tree like view of the presentation. Each subsection is
  displayed at the top level. Click on any of these subsections and it will expand to list all the
  slides in that section, or collapse again. Click on any slide name and the presentation will
  immediately jump to that slide.

=== Presentation Preview

This contains a scaled down version of the current slide. It will attempt to size it to fit your screen
and scale the contents as closely as possible. Several tools are attached to the bottom of this view.

[Update Follower]
  Allow other viewers in Follow Mode to track your progress.

[Enable Remote]
  Allow remote windows, including mobile devices, to control the presentation by
  opening the presenter view. This button will glow yellow when Showoff is listening
  for remote updates. Please see {Follow Mode}[#label-Follow+Mode] and
  {Remote Control}[#label-Remote+Control] below
  for more information.

[Zoom]
  Zoom in and out of the preview.

=== Presenter Information

[Audience Questions]
  When an audience member uses the anonymous <em>Ask Question</em> feature, it will appear in this list.
  The questions are listed in reverse order, with the newest at the top.

[Notes]
  Just displays all presenter nodes, including any markup, syntax highlighting, etc.

== Hotkeys

The following hotkeys are available for usage while viewing the slideshow. The hotkeys
from the _Navigation_ and the _Presenting_ section, as well as the _Reload_ action are
useful in either the Presenter or audience view.

See CONFIGURATION.rdoc for information on remapping these keys.

[z, ?] Toggle help. This shows a reference table on screen.

=== Navigation
[space, →] Advance to the next slide.
[shift-space, ←] Move to previous slide.
[## <return>] Go to slide #. Type a number and press <return> and you will immediately jump to that slide.

=== Presenting
[p] Run preshow. Start the preshow slideshow. This will cycle through images placed in <tt>_preshow</tt> for a specified time. This is useful for taking timed breaks or for keeping the audience attention while waiting for you to begin.
[P] Toggle pause. This will pause the presentation and dim the screen. You can use this to take a brief moment to address tangential audience questions.
[b] Toggle screenblanker. Similar to pause, this will pause the presentation and slide the slide off screen.

=== Audience view
[f] Toggle follow mode. When follow mode is enabled, the presentation will track the page displayed by the presenter. This is often useful when an audience member has poor eyesight and would like to get a better view of your screen. This defaults to _enabled_.
[c, t] Table of contents. A dropdown menu allowing you to choose a section & slide will appear. You may also press the "hamburger" icon in the upper left.
[F] Toggle footer. The footer contains the progress indicator.
[n] Display a tiny notes view. This will place the first line of text from the slide notes in the footer.

=== Development
[d] Toggle debug mode, when the audience footer is visible. This will show information including the keys pressed and the content filename that is used to generate the current slide in the footer area.
[r] Reload slides. This will reload your presentation as you generate or refine content. Useful in either view.

== Follow Mode

The audience can choose to follow along with the presentation automatically, and the
presenter may control the presentation in a few different ways. Showoff implements
several strategies for keeping all views of the presentation in sync.

[Audience Follow Mode]
  When an audience member is in follow mode, then their browser will
  automatically change slides to follow along with the presentation.

[Display Window]
  When the presenter changes slides from either the Presenter View or the Display Window
  then the other view switches to match.

[Remote Control]
  If the presenter opens multiple presenter views, then Showoff tries to heuristically
  guess which view should be the "controller" at any given time. This is most useful
  when the presenter opens the presenter view on a mobile device for a remote control.

  The presenter view will consider itself to be the authoritative source of the current
  slide indicator as long as you are actively using it. When you have not pressed a key
  for 30 seconds, it will also switch into Follow Mode and will track slide
  updates from remotes. The on screen indicator below the slide preview will glow yellow
  when it has switched into Follow Mode.

== Remote Control

Open the presenter view on a mobile device for a simplified remote control view of your
presentation. You will get a slide preview, plus presentation notes. If you scroll down,
you will also see the presentation tree and can navigate to any slide. If the main
presenter is in Follow Mode, then it will track slide updates.

To save battery, the Remote Control does not listen for slide updates. Instead, there
is a manual <tt>Update</tt> button, which will request the current slide from the
Showoff server and change to it.

[Advance slide forward]
  Tap on the slide, or swipe from right to left.

[Return to a previous slide]
  Swipe from left to right.

[Update]
  Press this button to quickly change to the current slide being displayed by the
  Presenter view.

[Update Follower]
  Enable this toggle to act as a Remote Control. Disable it to navigate through the
  slide deck without updating the slide being projected.

<em>Warning, using the Remote Control will chew the hell out of your phone battery.</em>

== Command Line Interface

See the commandline[rdoc-ref:COMMANDLINE] section for interesting Showoff commands.

== Editor Support

See the {editor support}[rdoc-ref:AUTHORING@Editor+Support] section for editor integrations.
