* INTRODUCTION

################ THIS IS A WIP README, will be improved in the
following iterations.########################
---------------------------------------------------------------------------

NOTE: to build the videos run: build-video.sh.

This script has two modes, if a video directory is supplied as an
argument, then that video will be built. If no argument is supplied,
it will attempt to build all videos. If additional top level
directories are created in the repository, which are not video
directories, then this script needs to be adjusted.

NOTE: to work on the videos run the following scripts, in this order:
1) environment.sh
2) install-fonts.sh.
This sets up a development environment.

To build a video in the development environment run the buildall.sh in
the video directory.

In the latter case, the script will take some time to execute, so
please, don't cancel it unless you want to stop the video creation.
Bellow you will find the explanation for each step inside these
scripts.

NOTE2: After creating the videos with this script, you can delete them
by running make VIDEO=<video-name> clean, and have your directory
clean like if you have just cloned it.
----------------------------------------------------------------------------

The idea is to help you in the video creation steps. Each video will
be composed of slide videos showing concepts - a.k.a noCli - and might
have videos with command line prompts in between - a.k.a cli.  All of
these videos will then be glued together into the final video for a
certain topic. We are including here an example video, so that you can
see everything in action, as well as help us testing if you find a
bug.

In addition, videos will be able to be translated to other languges,
so we are taking this into account.  We are adding sections of how the
tree structure of the project might look like, how to create the
nonClis, Clis and the final video, how to clean everything to go on
trying, and an example of how to run several makes to have a final
working example video.

If you want to see how to create a nonCli video: please go to RUNNING
MAKE FOR CREATING A VIDEO THAT SHOWS SLIDES.  If you want to create a
cli video: RUNNING MAKE FOR CREATING A VIDEO THAT SHOWS CLI. If you
want to create the final video: RUNNING MAKE FOR CREATING FINAL VIDEO
And if you want to know how to work with the translation process:
RUNNING MAKE FOR TRANSLATIONS.

NOTE FOR TRANSLATIONS:
1) Recall copying the .pot files under example/es_AR/pots that
simulate the ones already translated from /example/en_US/pots/.
2) As regards screen script, run it and copy/paste the output video
from en_US locale, since translation of these is under discussion.
3) Copy paste session files from <video>/en_US/sessions/* to the
locale's same directory ie <video>/es_AR/sessions/. Then run:
createVideoCli.sh.

NOTE FOR SUBTITLES:
At the moment, the subtitle files worked for the first iteration of
the project,when one video was made, so avoid using them.

* TREE

The TREE up to now looks like this: audio, svgs, subtitles, pots (for
other locales rather than en_US) *MUST BE MANUALLY POPULATED*.

/
|-README
|-Makefile
|-screen
|-createVideoCli
|-<videoName>
  |-slidesList.mk
  |-en_US
  | |-audios/
  | |-svgs/
  | |-slides/
  | |-subtitles/
  | |-pots/ #not translated
  | |-translationsFiles/ #.mo and .po  *ONLY* for this locale
  | |-out/
  | |-videos/
  |
  |-<locale>:ie: es_AR
    |-audios/
    |-svgs
    |-pots/ #translated
    |-slides/
    |-subtitles/
    |-out/
    |-videos/


* RUNNING MAKE FOR CREATING A VIDEO THAT SHOWS CLI

We have created a shell script that automates this process. It calls
the guile script as well as the a make command, to avoid running them
separately.  To create these videos you should run under the root
directory:

** ./creacteVideoCli.sh  <videoName> <locale> <sessionFilename>
<numberOfCLIVideo>

where:
VIDEO=name of the final video ie example,
LOCALE_LANG=locale for which the video is being created. Default is
en_US,
NUMBER=number that indicates the order in which the video will be
shown ie if NUMBER=2 it is the second CLI video that will be included
in VIDEO.

NOTE: all the arguments ARE MANDATORY for now.

Example: ./createCliVideo.sh example en_US firstCli 1

* RUNNING MAKE FOR CREATING A VIDEO THAT SHOWS SLIDES

** make videoNoCli VIDEO=<videoName> LOCALE_LANG=<locale>
 NUMBER=<numberOfNoCLIVideo>

Example: make videoNoCli VIDEO=example LOCALE_LANG=en_US NUMBER=1

Creates a piece of video that shows slides. If omitted, the default
video is used and the locale is considered en_US.

IMPORTANT: THE NAME OF THE AUDIO FILE THAT MATCHES EACH SLIDE
***MUST*** BE THE SAME. For instance, if our cond slide video is
composed by 4.svg, 5.svg and 6.svg, we will need 4.mp3 5.mp3 6.mp3
files even if our NUMBER argument is 2, since that means the number of
noCLIVideo we are creating, NOT its files.


* RUNNING MAKE FOR CREATING FINAL VIDEO

There are two ways of creating a final video:

** make finalvideo VIDEO=<video> LOCALE_LANG=<locale>

Creates the final video with its own audio.

** make finalvideoNoSound VIDEO=<video> LOCALE_LANG=<locale>

Creates the same final video similar to the one above but without
sound, for our in progress state.


* RUNNING MAKE FOR TRANSLATIONS

** make pots_for_video NUMBER=<numberOfNoCliVideo>

Creates the .pots only under en_US locale subdir for the number of
noCli video specified subdir to send them to translators.

Example: make pots_for_video NUMBER=2
(creates .pot files for nonCli video number 2)

* CREATE SVGS FOR BEING ABLE TO RUN LATER MAKE FOR CREATING VIDEOS FOR
OTHER LOCALE RATHER THAN en_US

** make slides VIDEO=<videoName> LOCALE_LANG=<locale>

Creates the translated slides, once the .pot files return from
translators, so that they can be used for locales other than en_US.
The locale subdir, at least <locale>/slides must be created
beforehand.  LOCALE_LANG is MANDATORY


* RUNNING MAKE CLEAN

** make clean VIDEO=<video> LOCALE_LANG=<locale>

Cleans all the files related to video creation and translation.  It
calls all the other clean_* options.  If VIDEO is not provided, it
cleans the DEFAULT.  If LOCALE_LANG is not provided it cleans en_US.

Example: make clean VIDEO=example LOCALE_LANG=en_US

** make clean_noCli VIDEO=<video> LOCALE_LANG=<locale>

Cleans all the intermediate videos that do not show CLI commands.  If
VIDEO is not provided it cleans the ones that belong to the default
video.  If LOCALE_LANG is not provided it cleans en_US ones.

Example: make clean_noCli VIDEO=example LOCALE_LANG=en_US

** make clean_cli VIDEO=<video> LOCALE_LANG=<locale>

Cleans all the intermediate videos that do show CLI commands.  If
VIDEO is not provided it cleans the ones that belong to the default
video.  If LOCALE_LANG is not provided it cleans en_US ones.

Example: make clean_cli VIDEO=example LOCALE_LANG=en_US.

** make clean_intermediate_videos VIDEO=<video> LOCALE_LANG=<locale>

Cleans all the intermediate videos, both slides and cli sessions.  If
VIDEO is not provided it cleans the ones that belong to the default
video.  If LOCALE_LANG is not provided it cleans en_US ones.

Example: make clean_intermediate_videos VIDEO=example LOCALE_LANG=en_US.

** make clean_finalVideo VIDEO=<video> LOCALE_LANG=<locale>

Cleans the final video, that glues all the intermediate videos, but
NOT the INTERMEDIATE ones.  If VIDEO is not provided, it cleans the
one that belong to the default video.  If LOCALE_LANG is not provided
it cleans en_US ones.

** make clean_pots VIDEO=<video>

Cleans the .pot files to send to translators for the given video.
If VIDEO is not provided it uses the default one.

Example: make clean_pots VIDEO=example

** make clean_locale_slides VIDEO=<video> LOCALE_LANG=<LOCALE>

Cleans the translation files - *.po and *.mo inside the en_US subdir
for the video.  If VIDEO is not provided it uses the default one BUT
LOCALE_LANG is *MANDATORY*.  If it is not given make aborts.


* EXAMPLE

For the example video we have five pieces of video: three nonCli with
two cli sessions in between. We have to create them first, to then be
able to glue them. Run the commands as shown here:

#First nonCli video:
make videoNoCli VIDEO=example LOCALE_LANG=en_US NUMBER=1

#First cli video, with audio:
./createCliVideo.sh  example en_US firstCli 1

#Second nonCLI video:
make videoNoCli VIDEO=example LOCALE_LANG=en_US NUMBER=2

#Second cli video:
./createCliVideo.sh  example en_US firstCli 1

#Second nonCli video:
make videoNoCli VIDEO=example LOCALE_LANG=en_US NUMBER=3

#Finally we end up with the final video:
make finalVideo --> output example.webm under /videos subdir.