Browse Source

update README

automate 2.0-rc
mxmehl 7 months ago
parent
commit
873dba1fae
Signed by: mxmehl GPG Key ID: 2704E4AB371E2E92
  1. 83
      README.md

83
README.md

@ -1,47 +1,72 @@
# Das Songbook
# The Songbook
Dies ist das Repository des Songbooks, das von einigen Pfadfindern stetig erweitert wird. Hier finden sich alle Songs und die Vorlagen für Erweiterungen.
This is the repository of the songbook that is continuously extended by some
scouts. Here are all songs, the accompanying documents and the templates for
extensions.
## Technische Infos
## Technical details
Seit 2017 besteht das Songbook aus einem LibreOffice-Masterdokument, welches zahlreiche Einzeldokumente inkludiert: Das Cover und Intro, alle Songs sowie die Akkorde im Anhang. Das macht Updatepakete und Änderungen an einzelnen Liedern viel einfacher.
Since 2021, the songbook cosists of a number of single ODT files, each per song
plus the cover/intro and chords. This way, incremental updates are much easier
to make.
Das Masterdokument besteht aus nicht mehr als den inkudierten Dateien sowie einem semi-automatisch generierten Inhaltsverzeichnis.
Via `Makefile`, all `.odt` files are being compiled to individual PDF files, an
index is automatically generated, and then all files are being bundled together
in one PDF document in `build/`.
Die PDF-Datei wird einfach aus LibreOffice exportiert.
## Adding new songs
## Hinzufügen neuer Songs
### 1. Fill in song template
### 1. Seitenvorlage befüllen
Open the template `src/Songtemplate.ott` and fill in all fields. Check list:
Man öffne einfach die Vorlage `Einzelseite.ott` und befülle die Felder. Checkliste:
* Ideally, the song fits on one page to keep the songbook compact.
* The font size and family should not be altered.
* The chords should be written as `Am` (minor) or `A` (major). Do not use `a`
for minor chords.
* The chords should be placed with using spaces directly above the syllable
where the chord change takes place.
* In long and complex songs, the verses should also be marked with chords.
Often, there will not be enough space to add them above the text, but you can
also write them after the text line in square brackets, e.g.
`...needed proof [G Em7]` in `src/Songs/D29_Hallelujah.odt`.
* Verse numbers and headlines like `Refrain` should be bold.
* The box at the bottom can be used for further info about the song, e.g. for an
interpretation or explanation of the song's history. If the box is not being
used, please remove the top border of the box.
- Idealerweise passt der Song auf eine Seite, dann bleibt das Songbook schön kompakt
- Die Schriftart und -größe sollte nicht geändert werden
- Die Akkorde sollten als `Am` (Moll) und `E` (Dur) geschrieben werden, nicht als `a` für Moll-Akkorde
- Die Akkorde sollten mit Leerzeichen direkt über der Silbe platziert werden, bei der der Wechsel stattfindet.
- Bei langen und/oder komplizierten Songs sollten auch die anderen Stophen mit Akkorden ausgestattet sein. Oft reicht der Platz nicht dafür, diese über dem Text zu schreiben, aber man kann sie auch hinter einer Zeile in eckigen Klammern schreiben. Siehe `D29 Hallelujah` als Beispiel.
- Strophennummern und Überschriften wie "Refrain" sollten fett markiert sein
- Das unterste Kästchen ist für weitere Infos zu dem Song gedacht, also etwa für eine Interpretation oder wenn die Geschichte zu dem Lied besonders ist. Wenn die Box nicht genutzt werden soll, sollte die Umrandungslinie zwischen den zwei Zeilen entfernt werden.
- Die Tabelle sollte bis fast an den unteren Rand der Seite gezogen werden (aber nicht bündig). Das vermeidet eine kaputte Formatierung im zusammengefügten Masterdokument.
When you're done, save the file in `/src/Songs` with the scheme `X99_Song_name.odt`.
Wenn man fertig ist, speichert man das Dokument im Songs-Unterordner mit dem Schema `X99 Songname.odt`.
### 2. Compile the songbook
### 2. Einfügen im Masterdokument
#### With make
Danach öffnet man das Masterdokument `Songbook_A-Z.odm`. Dort führt man folgende Schritte aus:
With the `Makefile`, all necessary steps are taken to generate the full or
censored version of the songbook, including an index. Run `make` to get a list
of possible commands.
- Im Navigator drückt man auf das "Hinzufügen"-Symbol und wählt die Datei aus. Man kann auch mehrere Dateien auf einmal einfügen.
- Danach muss geschaut werden, ob die Formatierung passt. Es sollten keine leeren Seiten entstanden sein, und die einzelnen Songs müssen klar seitenweise getrennt sein.
- Die Seite muss richtig im Masterdokument platziert sein
- Dann wird das Inhaltsverzeichnis ("Songbook-Index") aktualisiert. Einfach rechtsklicken und "Verzeichnis aktualisieren" auswählen. Dabei geht allerdings die Formatierung verloren, die muss manuell wieder angepasst werden.
It is intended to be run on a Linux-based system.
### 3. PDF generieren
1. Install all dependencies: libreoffice, make, poppler-utils (pdfunite),
python3 (with pip and venv) and the `Courier New` font.
2. Run `python3 -m venv venv` and `. venv/bin/activate` to activate the virtual
environment
3. Run `pip3 install -r requirements.txt` to install the Python modules in your
venv
4. Run `make build`
Zum Schluss wird aus dem Masterdokument über den PDF-Button ein gleichnamiges PDF-Dokument exportiert.
#### With Docker
## Versionierung
The `Dockerfile` should install all required dependencies. All you need is
`docker` to be installed.
Wenn große Änderungen am Songbook stattgefunden haben, also etwa neue Songs hinzugefügt wurden, sollte die Versionsnummer (im Dokument `Cover+Intro`) angehoben werden. Das sollte aber idealerweise erst passieren, wenn mehrere Songs neu sind, etwa vor einem Lager.
1. Run `docker run --rm -v "$pwd":/data mxmehl/songbook`. This will pull the
precompiled image, mount your current directory in `/data` of the container,
and build the songbook. You can append `make build-ay` to only create the
censored version.
Wir sollten damit auch in der Lage sein, Updatepakete zu erstellen, die nur die geänderten Seiten und das angepasste Cover und Inhaltsverzeichnis umfassen.
## Versioning
If there have been major changes, mostly by adding new songs, increment the
version number in `/src/Extra/Cover+Intro.odt`. This then allows to create
update packages.

Loading…
Cancel
Save