Group: Guix/Video Documentation

GNU Guix Video Documentation

During Outreachy phase 2018/2019 Laura Lazzati is creating video documentations for Guix. This page collects ideas about that project

Timeline

ORW=Outreachy-Week CWeek = Calendar week (in ISO8601)

ORW	CWeek	Monday	Task
1	49	03.12.	Study more deeply Guix and GuixSD to have fresh all the needed concepts for making the videos. Read in detail all the available documentation. Practice commands or some of their options for which or there was not enough time during the application for Outreachy and are important for making the videos, workflows, GuixSD,so on.
2	50	10.12.	Study in detail video editing concepts and stack of tools needed for them. Video creation and editing concepts (maybe a tutorial?) Tools that will be used and needed for creating the videos.
3	51	17.12.	Go on with studying editing tools Create prototype for first video needed: for example: Installation of Guix on top of Another distro. Create ideas to include in the video and narration. Create slideshow Create localized cli Generate narration and subtitles. Take into account 3 minute timing Do more refinement to the English video until it is accepted by the community Push it to the repo for guix members.
4	52	24.12.	Same as Week 3
5	1	31.12.	When video in English with english subtitled is accepted, translate it to Spanish to have a workflow for other languages. Translate slideshow, cli, narration and subtitles. Generate the new video. Document the accepted process forthe first video.
6	2	07.01.	Create the remaining videos about Installation: GuixSD on a VM. GuixSD on bare metal.
7	3	14.01.	Create videos for daily users: Using guix package command for installing, upgrading, and removing packages, and concepts that might arise - ie: transactional. Having guix up to date, concept of garbage collector, posibility of sharing packages with people who do not have guix (yet)
8	4	21.01.	Create videos for contributing Different ways of contributing Troubleshooting and asking for help
9	5	28.01.	Contributing or using guix as a developer: Differences between profiles and environments, working with them. Packaging tutorial
10	6	04.02.	Videos on common configuration tasks/ videos for daily use as a sysadmin Example video: benefits and howto guix works isolating package installation for unprivileged users, garbage collector - already mentioned for daily users, but could also be mentioned for sysadmins, they might not watch the users videos.
11	7	11.02.	Translate videos: Refine the automated process for the slideshow and cli if necessary Create audios and subtitles for the other ones In my case I could try doing so in Spanish, but if any other translator could try it
12	8	18.02.	Hosting videos, update Guix official webpage, get repo.
13	9	25.02.	Extra week : Guix Days and FOSDEM in between

First Idea

A first proposal came from Ricardo:

https://lists.gnu.org/archive/html/guix-devel/2018-11/msg00386.html

I would like to recommend this workflow:

• create an environment:

   guix environment --ad-hoc inkscape gettext itstool ffmpeg

• create slides in Inkscape (look at existing slides from past talks for style inspiration)

Slides can be in root directory

• create the translation subdir:

   mkdir de
 

• extract texts as gettext template

   #1.svg is out first svg file
   
   itstool -o de/1.pot 1.svg

• initialize translation (e.g. for German):

   #We need to add the name of the output file and where it is located because by default msginit creates one with the
   #locale name (de.po)and then it complains that de.po already exists for the next slide
   
   msginit --locale=de --input=de/1.pot -o de/1.po

• translate texts in “de.po”

• compile “de.po” to “de.mo” binary format:

   #Recall filenames 
   cd de
   msgfmt 1.po -o 1.mo

• use itstool to create a translated SVG:

   #Take into account that the .svg we are merging is the first one the translation. Since there was a `cd de` before,    
   #we don't need the -o argument   
   itstool -l de -m 1.mo ../1.svg

This can be automated with a Makefile.

Translations themselves don’t have to be created as part of this project, but the pot files should be uploaded to the translationproject.org, which is what we already do for other Guix translations.

Once we’ve got the SVGs we can render them as PNGs in the desired output format with Inkscape (here as a Makefile rule):

   %.png: %.svg
       inkscape -z --export-dpi=300 --export-png=$@ $<

Then write a simple concat demuxer file for ffmpeg to specify which slide to show for how long, e.g. this ’durations.txt’:

--8<---------------cut here---------------start------------->8--- file 'slide1.png' duration 5 file 'slide2.png' duration 1 file 'slide3.png' duration 3 file 'end.png' duration 2 file 'end.png' --8<---------------cut here---------------end--------------->8---

(According to the ffmpeg docs the last image has to be specified twice, the second time without a duration.)

Then compile this as a video:

   ffmpeg -f concat -i durations.txt -vsync vfr -pix_fmt yuv420p output.mp4

(The above was taken from here: https://trac.ffmpeg.org/wiki/Slideshow)

With a slightly longer invocation we can merge an existing audio file into the output file (no need for a second call to ffmpeg).

I haven’t given much thought to subtitles yet. We could use the very simple “srt” format, which is just plain text, but maybe “usf” is better. It has support for styling and Unicode, and its format is XML, which means that we can use the same tools as above to handle translations.

Discussion about videos, apart from those mentioned in Outreachy site or in more detail

• Focus on more practical howtos aimed at people new to guix.
  • installing guix on a foreign distro
  • installing guixsd
  • using guix: installing, upgrading and removing packages
  • guix pull
  • MAYBE guix gc
• Developers (not guix, but general devs)
  • environments vs profiles
  • developing on guixsd
  • "getting back to work" when something goes wrong
  • roll-back profile, system-profile, guix