Help: Worship Repository Maintenance

Intended audience - If you are a worship leader or someone else charged with the task of maintaining, adding to, correcting, and updating the songs in our music repository, this document is for you. If you are a worship team or leadership person who needs to access and use the songs or songbook, this document is for you.

Individual song sheets are available in PDF format over the web. You must have MIT and personal certificates and you must be in the list of allowed people to access it (ACF leadership, ACF worship people, leaders of other UCO groups ...).

Written by dpark Mar-Jun 2003.

Contents

I. Purpose and rationale
II. Description of directories
III. Description of programs

makesong, viewsong and printsong
makebook and printbook
less
man
fs
blanche

IV. Simple Unix commands
V. How do I .... ?

A. How do I modify an existing song?
B. How do I add a new song?
C. How do I update the songbook to reflect latest changes?
D. How do I print the songbook?
E. How do I download PDF songs to my computer?
F. How do I get/give someone Athena-permissions to read/write songs?
G. How do I find the copyright info for a song I want to enter?
H. How do I find out more about copyright issues?

VI. MITACF-specific LaTeX command reference

The purpose of the MITACF song repository is to support musical worship in ACF by storing and managing our worship songs.

Our current approach has been in use by MITACF/MITKCF since 1995. Songs are stored in our athena locker, one song per file, in a customized LaTeX format. Each file can be compiled into songsheets and the entire directory can be compiled into a songbook.

This approach satisfies several requirements at once:

Centralized storage - Storing our files on Athena is key. It allows for centralized storage instead of disparate copies kept on individual worship leaders PCs.

High availability - Not only will Athena fail less often than your PC, the files will be more frequently available to those who need it when they need it (since athena terminals exist all across campus).

Backups - By storing our files on Athena, MIT I/S takes care of our backups on a daily basis. See /mit/mitacf/OldFiles/music for a one day old copy of our locker. Contact MIT I/S for older archives.

Longevity - We want our repository to last for a long time with little effort, even as worship leaders cycle through every four years. Storing our files on Athena allows this with no effort (aside from technical training). Our athena locker will last as long as MITACF exists and is recognized by ASA.

Separation of semantics and appearance - In english, this means that the meaning and content of the files is separated from its formatting and how it looks on the page. This is particularly important for worship song sheets where "chords" are tied to "lyrics" in specific positions (e.g. an E chord above the first syllable of the first line of the chorus). Such chord-lyric relationships should be independent of things like font styles and sizes--if we resize the font, E should still be above the same syllable. This immediately means we cannot use a word processing format where semantics and appearance are intermixed (changing fonts would change the chord-lyric relationship). We must use a typesetting format such as LaTeX. This allows us to print songs in many different formats (songsheets, songbooks, etc) without altering the files.

The main drawback to this approach is that it requires more intentional training, particularly in the area of our LaTeX file format. In addition, with a declining rate of Unix-literacy among undergrads, training must become more comprehensive. In the end, it still seems that the pros will outweigh the cons for the forseeable future.

Note: MITUCF also uses the same LaTeX format for their worship songs. Their songheader (which defines footers, fonts, commands) is slightly different (e.g. the footer says "MITUCF") but very interchangeable. To include a UCF song, copy the .tex file from their directory (after you obtain Athena permissions to do so) and replace the first or second line with "\include{../Songheader/SONGHEADER}".

/mit/mitacf
The MITACF Athena locker.

/mit/mitacf/music
All files related to MITACF worship are under here.

/mit/mitacf/music/songs
LaTeX source files (.tex)

/mit/mitacf/music/songs-ps
Postscript versions of the songs (.ps)

/mit/mitacf/music/songs-pdf
Adobe Acrobat versions of the songs (.pdf)

/mit/mitacf/music/book
Files that support the creation of the songbook

/mit/mitacf/arch/share/bin
Scripts written by ACF to automate various athena operations. Most of these scripts pertain to our worship music repository. Programs in this directory will automatically be added to your PATH when you type "add mitacf" (ie, add mitacf to run any of these).

makesong (formerly texsongs2ps), viewsong and printsong

(add mitacf)

makesong: an ACF-made script that runs a series of programs to compile your tex file(s) of choice into .ps and .pdf files in the songs-ps/ and songs-pdf/ directories.

viewsong: previews the song sheets on your athena workstation (songs must have had "makesong run on them first")

printsong: prints song sheets to the printer of your choice (songs must have had "makesong" run on them first)

Usage:
% add mitacf
% cd /mit/mitacf/music/songs

% makesong song1.tex
compiles song1.tex into song1.ps and song1.pdf

% makesong song1.tex song2.tex
compiles song1 and song2 into their .ps and .pdf files

% makesong there*
compiles all songs where the titles start with "there"

% makesong *
compiles all 400+ songs

% viewsong song1.tex song2.tex
previews song1 and song2 on the screen (must be on an athena workstation or have X-windows on your local terminal)

% printsong printername song1 song2 song3....
prints song1, song2, song3 to printername

The astute of you may notice that, in terms of typing the song names after make/view/printsong, it doesn't matter what file extension (.tex .ps .blahblah) you put at the end of the song name, if at all, because these scripts ignore them and put the proper ones in. It also ignores any leading directories (/mit/mitacf/music/songs/ ../ /booga/booga/) and assumes you are working with ACF's standard repository directories.

makebook and printbook

(add mitacf)

makebook: An ACF-made script that runs a series of programs to compile all the tex files into a compressed songbook (multiple songs per page) located at /mit/mitacf/music/book/book.ps

printbook: Print that songbook to a specified printer.

Usage:
% add mitacf
% makebook
% printbook myathenaprintername

less

(add sipb)

A standard Unix command to view the contents of a text file (e.g. a .tex LaTeX file) without editing it. Very similar to "more", except that it also allos you to scroll up and pgup-pgdown (so "less" is better than "more", believe it or not, that's how the program got its name). Usage:
% add sipb

% less /mit/mitacf/music/songs/songname.tex
Read a file

% ls | less
Give a directory listing, but it's really long so pipe it through less.

% add games; jive /mit/mitacf/music/songs/songname.tex | less
Read a song through an ebonics translator (and pipe it through less so you can read it slowly).

man

(add the locker of the program that your man-ing)

A standard Unix command that tells you how to use other commands ("man" = "manual", typical english usage: "read the man page"). Usage:

% man lpr
Tell me how to use "lpr"

% man man
Tell me how to use "man"

% add sipb
% man less
Tell me how to use "less"

% add fooslocker
% man foo
Tell me how to use "foo"

Note: mitacf-made scripts don't have man pages, but everything else here does.

fs

(local to athena machines)

A standard athena command that shows or sets the access control list for a directory in an athena locker. Usage:

% fs la .
Tell me who has what kind of rights to this directory

% fs quota .
Tell me how much of this locker's quota is used up

% fs sa . <otherstuff>
Set the permissions to this directory. See the fs man page for more details if you have to do this.

blanche

(local to athena machines)

A standard athena command that shows or sets membership in an athena list. Athena lists can do things like be email lists (e.g. mitacf, mitacf-request, etc) or have access control on athena directories. E.g, we've set up mitacf-music-read-acl as a list that can read everything under /mit/mitacf/music and mitacf-music-write-acl as a list of people who can write everything under there. So one can simply grant or revoke permissions to a user by using blanche (or moira/mailmaint or the new web thingy) just once. Usage:

% blanche mitacf -d myusername
Remove yourself from the mitacf list (just a mailing list)

% blanche mitacf-leadership -a someonesusername
Add someone to the mitacf-leadership list (note, only mitacf-admin has the permission to do this).

% blanche mitacf-music-read-acl -a xprod-request
Add the Cross Products leadership to the list of people who can read our music repository.

% blanche mitacf-music-read-acl
List the current members of this list

% blanche mitacf | less
List the members of mitacf, but pipe it through the program "less" since it's a really long list.

In the shell:

~ means "home directory".
If your username is joe, "~" means "/mit/joe" and "~/www" means "/mit/joe/www"

.. means "sub directory".
If your current directory is "/mit/mitacf/music/songs" ".." means "/mit/mitacf/music" and "../print" means "/mit/mitacf/music/print".

tab means "guess the rest of this word"
If you are in /mit/mitacf/music/songs and you type "ls jesus-c" and then hit tab, the shell fills in everything else for you: "ls jesus-christ-is-the-lord-of-all.tex" because there is only one file in the current directory that starts with "jesus-c". If you only had typed "ls jes" followed by a tab, it would fill in up to "ls jesus-" since there are many files that start with "jesus-" but every file that starts with "jes" has a "us-" after it. Hitting tab a second time will list which files meet that criteria. Likewise the shell can guess program names. If you type "makeso" tab, it will fill in "makesong " but if you only type "make" tab, it won't fill it in because about two dozen programs start with those four letters.

| ("pipe") means funnel the output of one program to the input of another.
"ls | more" means "run the program ls and take its output and use it as input to the program called more".

ls [dir]
list the files in a directory.

A. How do I modify an existing song?

1. Go to the songs directory
   % add mitacf
   % cd /mit/mitacf/music/songs

2. Edit the file, e.g.:
   % emacs the-song-file-name.tex &
   if you are sitting at an Athena workstation or
   % emacs the-song-file-name.tex
   if you are logged in from a text dialup.

3. Save the file
   (in emacs this is ctl-X ctl-S)

4. Compile the file to a postscript song sheet
   % makesong the-song-file-name.tex

   Errors:

   • if an error appears along the lines of "can't write to SONGHEADER.aux" and it prompts for a new file name, just hit enter. This is the only error you want to ignore.

   • for all other compiler errors, hit ctl-C to quit compiling. Try to find some clues from the messages what it might be complaining about. You can usually decipher which line it failed on by the lyrics (usually garbled with added hyphenation) or a printed line number (line number 68 would show up as "l.68" near the beginning of the line of some error output). Note that the line LaTeX failed on might be *after* your actual typo. For example, if you used an open brace "{" and forgot to close it with "}" (or typed "]" by accident) the error may appear many lines later. If you had any compiler errors, repeat steps 2-4.

5. Examine the content/appearance of your postscript by either viewing it on screen, via a browser, or printing it.

   Viewing on web:
   https://web.mit.edu/mitacf/www/music-pdf/ (MIT and personal certs required)

   Viewing on screen:
   % viewsong the-song-file-name.tex

   Viewing on paper:
   % printsong printername the-song-file-name.tex

   Does it look right? If not, repeat steps 2-5. Some common things:

   • If you need space between lines (for example, to separate verses), use the sequence "\ \\" on a line to add the space.

   • If you need horizontal space between words, use "\ " (backslash follwed by a space) to force a space. You can put many of these "\ \ \ " to make more space.

   • If chords are bunched up on top of each other, try to add horizontal space, or if the chords don't need to be positioned on specific syllables (e.g. a chord progression at the end of a line), you can just put them all in a single \C{} command and they won't overlap (e.g. "\C{G Am G/B G7/B}").

   • If the song is spanning multiple pages, try to eliminate unnecessary extra spaces, or merge many short lines into fewer longer lines. We generally try to keep all songs to one page, but if it must spill over to a second page, use the command "\twopagesongbreak{titlename}" to *specify* exactly where the break should be (so it can be independent of formatting). Read a file such as all-the-earth.tex for an example. It's often useful to put another copy of the chorus on the second page if one isn't already there (assuming it has a chorus).

6. **Update the overhead box**
   The overhead box must always correspond exactly to the contents of /mit/mitacf/music so that worship leaders know *exactly* what is in the box simply by viewing the directory. Never skip this step:

   • print the song to a printer (printsong)

   • at copytech, photo copy to a single sheet of canary (yellow) pastel colored paper and a single overhead. Keep receipt and get reimbursed by the current MITACF treasurer (even if it's only a dollar or two).

   • add to the overhead box. Note that the folders are separated alphabetically, but there are two folders for "I". One folder contains songs that start with the word "I". The other contains songs that start with the letter "I", but not the word "I" (such as "in" or "I'm").

B. How do I add a new song?

1. Go to the songs directory
   % add mitacf
   % cd /mit/mitacf/music/songs

2. Make sure that your song doesn't already exist, possibly under a different name (think of alternative names).

3. Pick a filename. ACF convention is to spell out the song title with dashes "-" in place of spaces and punctuation. Apostrophes are somewhat inconsistent. Some songs put dashes in place of them (e.g. "you-re-the-source.tex") and some skip them (e.g. "hes-changing-me.tex"). Make sure that some other song doesn't exist at the same file name. If it does, the ACF convention is to append the last name of the song author (e.g. "here-am-i-doerkson.tex", "here-am-i-kilpatrick.tex", "here-am-i-redman.tex"). If the song title starts with "the", move it to the end of the title (e.g. "lord-reigns-the-founds.tex", "lord-reigns-the-stradwick.tex"). If you proceed to step 4 without checking whether your file name exists already, you may erase a pre-existing song!

4. Copy the template to a new file.
   % cp ../SAMPLESONG.tex new-song-file-name.tex

5. Edit the file, compile it, verify its correctness. See instructions for "how do I modify an existing song?" above.

C. How do I update the songbook to reflect latest changes?

% add mitacf
% makebook

This will pretty much work as long as all your songs have been compiling to overheads/songsheets correctly.

D. How do I print the songbook?

% add mitacf
% printbook ajax
(replace "ajax" with the name of your nearest printer)

Note this will print around 120 double-sided sheets of paper and can take anywhere from 10 to 30 minutes depending on the printer. Don't be a printer hog! Try to use a less popular printer and definetly don't do this in a cluster that only has one printer. Be ready to yank your print job if your neighbors get angry. Always make sure your printer is printing cleanly (enough toner, etc) before starting the job and feed it a ream or two of paper if it's running low.

Take to copytech to get it GBC spiral bound (building 11 will do it for you, W20 is self service, but they'll teach you) for about $2.

E. How do I download PDF songs to my computer?

This can all be done from a text terminal login to Athena through a windows program like securecrt or the java applet on http://athena.dialup.mit.edu/

1. Zip up the PDF directory and place it in your web directory.
   % cd /mit/mitacf/music
   % zip -cvpf ~/www/songs-pdf.zip pdf/

2. Grab the zip with a web browser
   http://web.mit.edu/yourusername/www/songs-pdf.zip
   Save it, open it, unpack it to wherever you'd like.

3. Delete the zip from your web directory.
   % rm ~/www/songs-pdf.zip

F. How do I get/give someone Athena-permissions to read/write songs?

Most Athena users do not have permission to write or even read these song files. The Athena File System (AFS) uses "access control lists" on each directory to determine the question of "authorization" (which users should have what kinds of access). The question of "authentication" (are you really the person you say you are) is handled by Kerberos (in other words, don't worry about authentication, only authorization).

We've simplified the AFS permissions in /mit/mitacf/music to boil down to the following:

1. mitacf-music-read-acl (read-only)
   If you are a member of the list "mitacf-music-acl", you can read any file under /mit/mitacf/music. You cannot add new songs, edit old ones, or compile anything. But you can view/print the .ps/.pdf files and copy them. This doesn't mean you *should* copy them (legally speaking), it just means Athena lets you.

2. mitacf-music-write-acl (read/write)
   If you are a member of the list "mitacf-music-write-acl" you can write to anything under /mit/mitacf/music. You can add new songs, edit/remove old ones, compile things.. you can even wipe out the whole thing and switch to an entirely different way of doing things. You have power.

3. mitacf-admin (access control)
   If you are a member of mitacf-admin, you have total control over everything under /mit/mitacf. Not only can you read and write things under the music and other directories, but you can change memberships of any list by the name of "mitacf-...". You can access control lists of directories--who is allowed to do what. You can change who has the ability to change lists. You could even singlehandedly perform a hostile takeover of all ACF athena resources (both the locker and the mailing lists). You have scary power. You're also the one people will go to whenever anyone wants people added/removed from lists.

   You can use blanche or moira to see who is on any of these lists. For example, mitacf-music-read-acl currently looks like:

   fslee
   janetlai
   LIST:mitacf-leadership
   LIST:mitacf-music-write-acl
   LIST:mitacf-request
   LIST:mitacf-worship
   LIST:mitacf-worship-leaders
   LIST:mitcbf-request
   LIST:mitccc-officers
   LIST:mitucf-request
   LIST:mitucf-worship
   LIST:xprod-request
   

   This comes down to: people in leaderships of ACF and other partnering ministries, people involved in ACF worship, and a few rare individuals who needed access once or twice before. Note that most entries in this list are lists. You can keep blanching all the sub lists to see every last user who can read ACF worship files.

   Tell me what to do!

   If a new ACF'er is becoming involved in worship ministry and you want him/her to read the files (or be on the email list), add him/her to "mitacf-worship" and they'll automatically be able to read the files.

   If an ACF'er is a worship leader, stick them in "mitacf-worship-leaders" and they'll get the emails and be able to edit the song repository.

   If an ACF'er is helping out with songs but not leading worship, put him/her in "mitacf-music-write-acl" so they can get access, but not the emails.

   If a non-ACF'er (or ACF'er not involved in worship ministry) needs access for some legitimate reason, add him/her to "mitacf-music-read-acl". This should not be necessary if he/she is already in one of the above leadership lists.

G. How do I find the copyright info for a song I want to enter?

• www.ccli.com

H. How do I find out more about copyright issues?

• www.ccli.com
• /mit/mitacf/documents/ccli-email
• cover page of printed songbooks

\songtitle{...}
Set the song title (mandatory).

\songscripturesource{...}
Set the related scripture ref for the song (optional).

\songauthor{...}
Set the song author (mandatory).

\songcopyright{...}
Set the song copyright info (either this or songpublic is mandatory).

\songpublic
Flag song as Public Domain (either this or songcopyright is mandatory). Most hymns fall under this category.

\C{...}
Chord: position ... above the line at this point. A LaTeX thing to watch out for: # is a special character in LaTeX and needs to be backslashed (e.g. \#). Since # is the symbol used for sharps, make sure your backslash all your sharps. The ACF convention is to use b for flats.




\begin{songlyrics} ... \end{songlyrics}
All song lyrics and chords go here.

\begin{chorus} ... \end{chorus}
Chorus goes here. The only thing this does currently is indent the content.




\twopagesongbreak{...}
"..." should be the song title in caps. For long two-page songs, mark this point as the break point. On overheads, this will cause a nice page break with a "page 1 of 2" footer and a "page 2 of 2" header. In the songbook it will just allow LaTeX to break the two halves across a column or page break.

\songcomment{...}
Put some text in the "song comment" font.

\songitalic{...}
Put some text in italics (e.g. many songs have a line echoed).