Hymnal installation

The hymnal installation process consists of importing the data from a hymnal into the Hymnary. Uploading a hymnal from scratch is usually accomplished by entering the data into a spreadsheet, saving the spreadsheet as XML, and uploading the spreadsheet into a hymnal. The data may also be entered directly into Hymnary by adding new text of new tune through the Editor Tools. The direct method is easier if the hymnal has many new-to-Hymnary hymns or hymn tunes without regular hymn tune names. If there are not regular hymn tune names, the first line of the hymn is bracketed; the bracketing can be done automatically if adding the tune directly. The drect method also allows instances to get connected to authorities as the data is added.

Remember: entering information from a hymnal is creating a hymn instance. An instance should detail exactly what is on the printed page, even if it is incorrect. That is, if the hymn lists "Dr. Watts" as the text author, you should enter "Dr. Watts" even though you know the author's real name is Isaac Watts. (The instance information will be connected to verified information on an authority page after the hymnal has been installed.)

Hymnal Set Up

To add a new hymnal, go to Editor Tools in the left side bar (if you are an editor, and logged in), then, Add new...Hymnal. Fill out the form.

• The hymnal ID should consist of the main initials in the hymnal title and the date of the hymnal. For example the hymnal "Worship and Rejoice" published in 2003 should have an id something like "WAR2003"
• Use the title that is on the title page of the hymnal, include the sub-title, if there is one. Separate the title and sub-title with a colon. Put edition statements behind the title in parentheses.
• If you can find a cover image, copy the image to a file, then under Editor Tools--Add new--Media, upload the image to Hymnary; right click on the resulting URL and select "copy"; then paste the URL into the Cover Image URL field.
• Add the denomination if there is one. Use the denomination that the hymnal states it was produced by or for.
• If the denomination name does not appear in the drop down menu, then add it from the "Add New" menu on the left side bar. Use the name on the hymnal. Use the Library of Congress Name Authority files (http://authorities.loc.gov) or ARDA (http://www.thearda.com/Denoms/Families/trees.asp) to find the Parent name (such as Baptist, Lutheran, etc.)
• Skim through the preface
• Check the indexes in the back. Is there a scripture index for the hymns? If so, use the scripture spreadsheet. Is there a topic index? If so, do the topics in the index cover the content headings in the hymnal? If they do, use the topic spreadsheet. Include the content headings on the spreadsheet, or enter them as you edit the hymnal.

Web Interface

It is best to use the web interface if the hymnal you are adding mostly has hymn texts or hymn tunes that are new to the Hymnary database

Individual hymns may be added through the web interface via "add hymn text instance" and " add hymn tune instance" pages under "Editor Tools," in the left side bar. However, the hymnal must exist before adding any hymn instances. A new hymnal can be added through the web interface on the Hymnal page; see further instructions in the above section.

Enter the information found on the page of the hymnal. See the guidelines under Page Spreadsheet section below. Scriptures and topics may be entered directly, but check to see if the scripture or topic is included in an index in the back. If there is a scripture or topic index in the hymnal it is much easier to upload this information from a spreadsheet. Do not use the scripture passages that might be found under the title of the hymn in the hymnal, but only the passages the lyrics come from or that the index in the back indicates are related.

Once the text instance is added, the tune instance may be added from the instance. This will allow the first line of the hymn to be auto-generated in brackets if the hymnal does not have a regular tune name. 

When you use the web interface you will be connecting the people, text and tune authorities as you go. See "Connecting Authorities" below.

When a new authority is added, the information in that authority record comes directly from the instance. If there is a mistake in the instance information or if the instance information is incomplete when the new authority is added, the mistake will show up in the authority and the authority information will be incomplete. Please correct the newly created authorities as well as the instances. There may be information in the instance that is appropriate for the instance but not needed or different than what is wanted in the authority. For instance, a full text does not need to be in the authority, as the text that is seen there comes from an instance; and the copyright information in the authority should be the current copyright and people's names in the authority should be the authority name.

Spreadsheets

A hymnal may be indexed by entering its information into the following spreadsheets:

• Page Spreadsheet
• Scripture Spreadsheet
• Topic Spreadsheet
• Text Spreadsheet

Each of these spreadsheets can be made in Excel and must follow the format specified. This includes the presence of a header row which will be ignored when the data is imported into the Hymnary. Follow the spreadsheet links above for required, recommended and optional columns.

There also are spreadsheets for Media and (Page) Images.

Note that if you already have this information in a database, it may be fairly easy to export it into CSV files matching our needs. Ask your database expert.

Uploading Spreadsheets

• Save the spreadsheets as XML spreadsheets
• After the hymnal has been added, click on "Editor Tools" in the hymnal, and find "Upload xml...spreadsheet"
• Click on "Editor Tools" in the hymnal to find "Resolve...authorities." Resolve the people authorities first, then the text authorities, then the tune authorities.

Connecting Authorities

Include all the information. New authorities are created from the information in the instances. If all the information is not included, or there is a mistake, add the information in the authority, or correct the information in the authority.

For people:

• If you are using the web interface, begin typing the last name of the person, followed by the first name (with a comma after the last name) to find the person authority id; or alternatively; type lastname_firsname
• If you see "See..." after the person's name it means that the person is known by another name or spelling of the name. The name after "See..." is the name that should be used for the authority id
• If you see "See also..." after a person's name, it indicates the person used a pseudonym. Use the authority id for the pseudonym in the instance; but in the authority use the name and id for the person's authority name (the name after "See also..." This is so people can find hymns writtenunder a person's pseudonym and also all hymns written by the person.
• If you have uploaded a spreadsheet and are using the Resolve Person authorities page, select the person from the list of possibilities. There may be reasons a person does not appear on the list of possibilities, so try typing the last name of the person, followed by the first name (with a comma after the last name) to find the person authority id; or alternatively; type lastname_firsname.
• If a new person authority needs to be created:

• Search the Name Authority Headings in the Library of Congress (authorities.loc.gov)
• If the person is found, use the name as it is in LOC. If the person is not found, use the name as it is in the hymnal
• Enter an authority id - LastName_FirstName
• In the Short Name field enter FirstName (or initial LastName
• In the Full Name field, enter exactly what is in the LOC Heading field, including the dates behind the name, if included (even if incomplete) or if not in LOC, LastName, FirstName
• Enter birth and death years if known. If only one is known, estimate the unknown date by adding or subtracting 100 years. Indicate if the birth or death years are estimates. If this information is not in LOC, research may be done, but this is optional.
• Indicate gender, if known
• Copy the LOC control number (no spaces) and paste it under Links. You may also add the Wikipedia link

For texts:

• If you have uploaded a spreadsheet and are using the Resolve Text authority page, select the appropriate text from the list of possibilities, or:
• Begin entering the words of the first line (all small letters) separated by “_” into the authority identifier, select the appropriate authority id from the drop down menu.
• American spellings are used in the authority ids; for example, "Savior," instead of "Saviour"
• "O" and "Oh" are often used interchangeably in hymn texts. In the authority id "o" is used
• If the instance has the text in more than one language, connect the text to the original language authority (or create a new text authority for the original language text). Add the translations and translators in the Note field of the text authority. It it is hard to determine the original language, for example, Taizé hymns which are written in multiple languages, locate the Taizé hymn by searching the English or Latin text, and connect the instance to the existing authority (authority id will be in the URL)
• If an authority cannot be found:
  • Consider the age of the hymn and whether it would be likely that the text would not already be in the Hymnary database
  • Are there words that may have been modernized (ye or thee vs. you) or singular words that could be plural and plural words that could be singular (our/my, we/I"?
  • If it seems like the text should be in the Hymnary database, search the first line you have (in Advanced Search) to see if you can find it.
  • If it seems likely that the text is new to Hymnary, create a new authority id using the words from the first line (separated by underscores). Add a qualifier if needed to make the authority unique. The first choice of a qualifier would be the first couple words from the second line of the hymn. If that's not possible, use the author's last name as a qualifier
• Qualifiers for texts are not needed if there is only one hymn text with that first line. However, it is possible that different texts with the same first line are located under the same authority; or, the hymn text you have in front of you has the same first line as another hymn. Therefore, check the authority to make sure that the author matches or the hymn text matches the other instances in the authority.

For tunes:

• If you have uploaded a spreadsheet and are using the Resolve Tune authority page, select the appropriate tune from the list of possibilities, or:
• Begin entering the words of the tune (all small letters) separated by “_” into the authority identifier, select the appropriate authority id from the drop down menu.
• If an authority cannot be found:
  • Consider the age of the hymn and whether it would be likely that the tune would not already be in the Hymnary database
  • If it seems like the tune should be in the Hymnary database, search the tune by the first 6-10 notes of the incipit (do (or the first note of the scale)=1, re-2, etc.); or find the text authority and see if there is a tune by composer connected with the text, or search the tune name to see if the tune is better known by another name
  • Tunes should have a qualifier behind their names, usually the last name of the composer
  • If it seems likely that the tune is new to Hymnary, create a new authority id using the tune name or words from the first line (separated by underscores). Always add a qualifier to a tune. The first choice of a qualifier would be the composer's last name. If there is not a composer, use the source (such as "french" if it is a traditional tune, or, use the first 5 numbers in the incipit

Page Scans

• Make sure the images are in a zipped file.
• Use the upload page images link under Editor tools for the hymnal
• Count how many pages are before page 1, and use the menu to select that number. If images are coming from Internet Archive, also count the cover as a page,as the scanner bed is usually the first image.
• Use the Attach Page Images link on the hymnal page.
• Copyrighted material may not be displayed, except Hope Publishing allows their copyrighted material to be displayed with a license agreement.
• Use Display Permission: Nobody for copyrighted material and Display Permission: Everybody for Public Domain material.
• Avoid leaving parts of hymns visible, for example, if a copyrighted hymn carries over onto another page, set both page permissions to Nobody; or, if a public domain hymn carries over onto a page with a copyrighted hymn, set both pages permissions to Nobody. People get confused when only part of a hymn is visible.
• We know that if the first copyright date is before 1926 that the hymn is in the public domain.

See Also

• Post-installation procedures
• Proofing and Editing Process

External Links

• Example spreadsheets and blank spreadsheets (zip file)

ThML

ThML is the XML dialect used at www.ccel.org. Hymnals encoded in XML can be installed as books at www.ccel.org, and they can also be imported directly into Hymnary.org. This route may be appropriate for XML experts who want hymnals to appear at CCEL.org as well. There is an introduction to Creating Hymnals in ThML; contact us at ccel@calvin.edu for more information.