Pyntor user documentation
-------------------------

This documentation is work in progress. Whenever there are some questions,
the answers will be added here. Real documentation is better than a FAQ :-)

*** Documentation index

The following topics are documented already:

1) Creating presentations
2) Running pyntor
3) Exporting presentations
4) Component sharing

***
*** (1) Creating presentations
***

Pyntor presentations must be written by hand. There is no WYSIWYG tool and
no graphical editor. It's like a mixture of of LaTeX document editing and
programming, since custom Pyntor components can be added.

Some of the components of Pyntor can be used without any others to create
some slides. Those are 'slides', 'tpp' and 'pod'. In case a pure slide
creation is wanted, simply call: pyntor -d "pod my.pl" or similar!

For larger presentations, some more efforts are needed.
It is recommended to start with an empty directory. A 'script' file should
be added there to orchestrate the overall presentation. For custom components,
a 'components' directory must be added, although for many cases Pyntor already
ships with sufficient components. All other file positions can be
chosen feely by the user.

The 'script' file contains sequential calls to components. For example, an
intro module could be called first, and afterwards the 'slides' module, which
takes as option the slides text file.
Read 'components.txt' to learn about how to use the already present
components. Otherwise, have a look at the included demo presentation.

To finish, consider this example:
 $ find
 ./mypresentation
 ./mypresentation/script
 ./mypresentation/components
 ./mypresentation/other-files
 $ pyntor-selfrun -a mypresentation/
 $ pyntor mypresentation.pyntor

The presentation archive 'mypresentation.pyntor' can then be distributed
to other people.

The script 'pyntor-selfrun' can also aid in converting 'mypresentation.pyntor'
into a self-extracting python script, if desired. This is useful for people
who have python and pygame installed, but not pyntor. It also protects
against API changes in the pyntor components.

***
*** (2) Running pyntor
***

There are 3 different ways of running pyntor, depending on the presentation
format:
- in-dir files: If the presentation files have been added to a pyntor
  source tree, just run 'pyntor', it will read 'script' and proceed
  accordingly.
- presentation archive: If all presentation files have been added to an
  archive ('foo.pyntor'), which is really a .tar.gz file, just run
  'pyntor foo.pyntor'. Also, clicking on the 'foo.pyntor' file with a
  graphical file manager should execute pyntor, if the MIME info is
  registered correctly. Note that foo.pyntor must contain a
  directory with the files, not just a collection of files.
  The tool pyntor-selfrun should be used with the -a option to create the
  presentation archive.
- self-extracting archives: In order to not require a pyntor installation,
  it might be packed together with the presentation files. In this case,
  just run './foo.pyntor.selfrun.py'.
  This will create 2 temporary directories: one for extracting pyntor,
  and one for extracting the presentation.

Important keys:
  t - display time
  p - page selection
  s - full text search in slides
  enter/backspace - navigation in 'slides' component

Components might support other key combinations. Again, read 'components.txt'
to learn about them.

***
*** (3) Exporting presentations
***

It is always a good idea to export presentation slides into a static format
so in case trouble strikes, another computer can be used easily. It is also
suitable for putting presentations onto webpages.

Pyntor exports presentations when run with the -x option, which needs an
argument either designating a filename or a directory name.

Two ways of exporting slides exist:
- PDF export
  If -x foo.pdf is used, PNG images will be created first and then be
  assembled to a PDF file. Note that this will *not* result in nice scalable
  PDF, since the screen resolution is fixed. There are two advantages however,
  copying the export around will only take one file, and looking at the PDF
  at another resolution will still be possible on any computer, even if it
  does look a bit blurred.
- HTML + PNG export
  If -x foodir is used, PNG images will be created (by way of BMP images
  and converting them with 'convert', just like with the first step for PDF),
  but then no further editing is done, instead all of those files will stay
  in foodir.
  There is now a helper script to create thumbnail images and an index.html
  file for the PNG images:

  $ zcat /usr/local/share/doc/pyntor/pyntor-minigal.sh.gz | sh

  This script is a very basic one. In most cases, one might want to install
  a dedicated gallery script or tool. One tool for each job, they say... :-)

***
*** (4) Component sharing
***

In order to let Pyntor dominate the world, people should write new components
which can then be used by others. With a bit of luck, these might even end
up in the next Pyntor release!

Pyntor also has a component repository. If components are sent to the author
of Pyntor, they will be made available there.
Use the tool 'pyntor-components' to browse them, or alternatively access
the web pages at http://pyntor.coolprojects.org/repository/.

Using pyntor-components makes it easy to use new components, it installs
them into the user's home directory (~/.pyntor) and Pyntor will find them
automatically!

Documentation about new components can also be read using pyntor-components,
via the --doc option.

