HTML Guide and Template for the Pico Project

N. B. It is essential that you become familiar with this page and refer to it often.

Index
Required Documents Special Characters
What is HTML Code? Greek and Hebrew
Step-By-Step Instructions Inserting Thumbnails
Phrase Level Markers Section Introductions
Anchors (Footnote Links) Testing Your Documents
Other Tags Prototype and Templates

This document was prepared as a quick reference tool for section editors of the Pico Project and presupposes no previous knowledge of HTML (Hypertext Mark-up Language). A conscientious effort must be made to ensure that everyone's contributions adhere to a certain format in order to maintain consistency of appearance and content; it is imperative that, as you prepare your sections for inclusion in the Web, you follow the basic guidelines below. If you prefer to have a hard copy of this page, select "Print" on your browser.

Required Documents:

As you are all fully aware, each participant will send to Michael Papio (by April 4 and by attachment) a number of documents. We will all make every effort to stick as closely as possible to the guidelines, not in order to quash our budding originality but to make an otherwise difficult procedure feasible, mais ça va sans dire. To make this process as painless as possible, each of these documents is described in the following table:

NAMECONTENTSANCHOR SOURCETARGET
text.htmlThe corrected Latin text of the Oratio.For textual variants: var.html
For linguistic notes: notes.html
bot
var.htmlTextual variants.--
notes.htmlLinguistically oriented notes to the Oratio.--
itesto.htmlItalian translation of the Oratio.inote.htmlinote
inote.htmlNotes to the Italian translation.--
etext.htmlEnglish translation of the Oratio.enotes.htmlenotes
enotes.htmlNotes to the English translation.--
pres.htmlIntroduction in Italian to the sections assigned to you.--
intro.htmlIntroduction in English to the sections assigned to you.--

What is HTML code?

If you have ever accidentally opened a Word document in a simpler program such as Write or Teach Text, you will have noticed that word processors include a large amount of "code" in and around the text itself which normally remains invisible. These symbols and numbers tell the word processing program how the text is to be displayed on the screen and when printed. Word Wide Web documents too contain encoded information which is "read" by Internet browsers (such as Netscape and Internet Explorer) and translated into formatting (italics, images, paragraph returns, links to other documents and so on). Although HTML code is not normally visible when you look at Internet documents, you can indeed see it by selecting VIEW and SOURCE on Netscape browsers. Try this - both out of curiosity and as a reference in case you don't have your notes handy.

Step-By-Step Instructions

What we are attempting to do here is really very simple: we will insert various symbols, or tags, into the texts, translations and notes that we've already prepared in such a way as to make these documents "browser-readable." The single most substantial obstacle to this endeavor is the sometimes unpredictable way that your texts will be translated into an ASCII environment. In other words, your "machine-readable" document can neither contain some characters commonly found in word-processing software nor formatting commands such as "bold" or "centered text." These special attributes must be added by hand - and that is all that this guide is intended to help you do. While there is a very large selection of different formatting "tags" (the specific characters that indicate to the browsers how the document should be displayed) available in the most recent version of HTML, for our purposes you will have at your disposal a limited set (as described below). Given that HTML is rather unforgiving of careless mistakes, be sure to follow precisely the template included here. HTML code is composed by setting a string of elements within angular brackets into your document. These brackets ("<" and ">") contain the instructions the browser uses to insert images, links and text formatting. They become invisible, when done properly, when your work is viewed by someone following regular links.

Let me state again that this procedure is actually quite simple although admittedly somewhat tedious at times due to the fact that great attention to detail is absolutely necessary.

Though the underlying concepts of html are explained below more clearly, it is worthwhile to present now an ordered list that delineates the steps followed in the translation of a sample document into html. Please read all the steps before jumping in or you may be sorry later.

  1. Make sure that you have both a back-up copy and a printed copy of all of your documents before you begin. Keep these in a safe place because once you lose your formatting, it's gone forever.
  2. In your favorite word processing program, open the document you've chosen to begin with - the Latin text and the English translation are the simplest - and then save it as "text only." This is done by selecting FILE then SAVE AS and, in the little box that inquires about the type, choose TEXT ONLY. (If your program does not present English commands, try to approximate.) The new name you give the text will depend upon which document it is and the name associated to that type in the table above. Note that all of your footnotes will be deleted when you carry out this step, so have another copy somewhere else so that you'll be able to reconstruct the page of notes. Now, close the file and when your program asks you if it's okay to lose the formatting, say yes (you may have to confirm your decision to change the type to "text only").
  3. Now re-open the file you just created in an html-friendly program. (Note: if you are a Mac user, open your file using Teach Text or Simple Text. DO NOT under ANY circumstances use Word and you SHOULD NOT use an html editor unless you know what you are doing. Should you be a PC user, on the other hand, you can continue to use Word provided that each time you save you continue to respond affirmatively if asked whether you want to maintain the file's "text only" status.) At this point you might be surprised to see that you have done away with much of your information. This is an uncomfortable though normal stage of angst. Your task now is to put back (through html) what you lost in your word processor. If you are using a Mac, your job will be a bit harder because apostrophes and quotation marks are often changed into unwanted symbols in this procedure. Put them back in now.
  4. Now you can use phrase level markers to restore such things as bold or italicized print. Naturally, this is more important for the notes than for the text and translation.
  5. At this point, you insert the footnote references by writing the anchor code.
  6. Now you should put in a few special tags. Insert the text that belongs at the beginning and end of your document and separate your paragraphs with the <p> tag.
  7. Once you've gotten this far, you probably have a feel for what you're doing. And believe it or not, you're almost finished. Now you should put in the special characters and symbols and update your list of words that must be written in non-Roman alphabets.
  8. Insert the thumbnail code where necessary.

Phrase Level Markers:

These tags are placed around text to produce bold (<b>) or italicized (<i>) characters and to set text into centered (<center>) or double-indent format (<blockquote>). Note that there are no spaces between the tags and the formatted text and that the end tag is identical to the beginning tag with a single exception: it is preceded by a front-slash ("/"). Participants in the Pico Project are to use bold for emphasis and italics for foreign words and titles of books. Use double indentation only for citing more than five contiguous lines of text. Though you may use the tags together, you must nest them (e.g. it is okay to write <center><i>Oratio</i></center> but not <center><i>Oratio</center></i>).

<b>Sample Text</b> produces: Sample Text
<i>Sample Text</i> produces: Sample Text
<blockquote>Text</blockquote> creates double indentation.
<center>Text</center> centers the text.

Anchors (Footnote Links):

The greatest advantage of hypertext "webs" is their ability to allow users to control their own sequence of readings - choosing one section of the Oratio then another, not necessarily in linear order. This possibility is achieved through links "anchored" into a text which, when activated, carry the reader to another document (whether in the main window or in a smaller window). A single word, phrase or note reference may be turned into an active link by setting "anchor" tags around it just as we set phrase level tags around words in the examples above. The beginning tag, however, contains the Internet address (URL) which belongs to the destination document. All anchors have two parts, just like phrase level markers: one that opens the link and another that closes it. The first contains the real information (between angled brackets) and the second is always an "indeclinable" </a>.

For the time being, we will only make links which are activated by the users' click upon a footnote reference. In three of your documents (text.html, itesto.html and etext.html) you must manually recreate your footnote references by inserting a string of code at the point where you would like them to appear. Note that there are two different types of notes for the Latin text, variants and linguistic glosses. In a post-Mirandolan meeting, it was decided to distinguish these two types, one from the other, and so their note references are made differently.

Variants:

The reference to textual variants is made using letters of the alphabet from a onwards. After the twenty-sixth letter (we may as well use the English system) comes aa, then ab and so on. The string of code used to make a superscript note "a" is:

<sup><a href="var.html#a" target="bot">a</a></sup>

<sup> turns on the superscripting. In quotation marks after a href= is the name of the document which contains the proper footnote. This is the "anchor source" that is mentioned in the table above. Note that immediately after the name of the anchor source is the number sign (#) followed by the number (or in this case letter) of the note. Within the quotation marks that follow target= you'll insert the target that corresponds to the document upon which you're working. This information too is provided in the table above. After that is the number or letter of the note again and the entire anchor is then closed off by </a>, followed in turn by </sup> which turns off the superscripting.

Linguistic Notes:

Just about everything that you just read pertains to these notes as well with the exception of the anchor source (now notes.html). You'll spot too the change from alphabetical numbering to Arabic numerals; these are put in twice, once after the # and once between the points of the angled brackets. E.g.:

<sup><a href="notes.html#01" target="bot">1</a></sup>

One last thing to keep in mind is that the numbering system here in place after the # runs from "01" upwards; once you want to move beyond "09," you'll arrive at "10." This is not true, however, for the numbering between the points of the angled brackets. There you may simply do away altogether with the "0" in the ten's column. An example: the code that represents the reference of footnote number 10 is:

<sup><a href="notes.html#10" target="bot">10</a></sup>

The process is much the same for the contextual footnotes in your translations except for the fact that your anchor source and target are determined by the language of your text. (The anchor source to be put into Italian translation, for example, is inote.html and the target is inote.) Consult the table above if you're unsure of what name to use. All footnote references in the translations will be made with Arabic numerals.

Just as you insert the clickable footnote references into your transcriptions and translations, you must insert special anchors into those documents of yours that actually contain the notes that will appear in the lower windows of the four-part frame. These documents are: var.html, notes.html, inote.html and enotes.html. These are called "name anchors" and will not be visible to the user - if you do them properly! In short, when you click upon a footnote reference in one of the upper windows you will be calling up a specific footnote reference in one of the lower windows. Of course, for the browser to be able to scroll to the appropriate place it must know where the note in question resides. We provide this information with "name anchors." The sample name anchor for footnote number one is:

<a name="01"></a><sup>1</sup>

That for footnote letter a is:

<a name="a"></a><sup>a</sup>

This may be somewhat confusing at first, but a quick glance at the source code of the templates should clear up your uncertainties. Remember that anchors that have the word "name" in them are meant for the documents that appear in the bottom windows; those that have the phrase "href" are for the upper windows. In case you're interested to know what's going on, suffice it to say that when you click on a link in the upper window, you're telling the browser to look first for the document specified in the anchor source and then to scroll downward to the name anchor - which, if you'll notice, is what comes after the number sign (#) that we discussed above.

Other Tags:

There are some tags that you don't have to understand in order to use them properly. At the very beginning of each document, for example, you must insert the following block of text:

<html>
<head><title>Oratio</title></head>
<body bgcolor="#ffffff" link="#990000" vlink="#CC6633">

There is one additional line that immediately follows this last one in four of your documents (notes.html, var.html, inote.html and enotes.html). It is:

<font size="-1">

Likewise, at the very end of all documents, you will have another block of text:

<p>
</body></html>

If you like, you may copy the text directly from the screen of your browser and paste it in at the appropriate location. Just be careful to delete any unwanted spaces that may creep in when pasting. In addition to the tags discussed above, you will also want to be familiar with the Paragraph Break (<p>, which is used between paragraphs and adds an empty line). It is a "stand-alone" tag: it has no corresponding "end tag." You will use the <p> tag between the numbered paragraphs in your sections and to produce a carriage return in your notes if so desired.

Special Characters:

Inevitably, you will have to use uncommon and accented characters when encoding your documents. "Text only" documents, however, do not allow you to use accents properly and are unable to render symbols. You have to use a sequence of letters or numbers between an ampersand and a semicolon to solve this problem. Some of the most common of these are listed below:

The section symbol (§):&#167;
The paragraph symbol (¶):&para;
The open double bracket («):&#171;
The closed double bracket (»):&#187;

Accentuation is a good deal less arbitrary in nature. The regular pattern is easily memorizable. After the ampersand, there follows the case-sensitive letter which carries the accent and then one of the all lower case key phrases (grave, acute, circ, uml and cedil) before coming to a close with the semicolon.

Grave accents:&agrave; produces à
&Agrave; produces À
Acute accents:&aacute; produces á
&Aacute; produces Á
Circumflex accents:&acirc; produces â
&Acirc; produces Â
The Dieresis:&auml; produces ä
&Auml; produces Ä
The Cedilla:&ccedil; produces ç
&Ccedil; produces Ç
The Tilde:&ntilde; produces ñ
&Ntilde; produces Ñ

N.B. Although you may still see accented characters after saving your document as "text only," you STILL must use these codes above. Be aware that not all users can see what you see. If you need other characters not described here, you may look them up in the character set. Remember that for the Pico Project we will use only the ISO 8859-1 set.

Greek, Hebrew and Other Non-Roman Alphabets:

Words in languages that do not use the Roman alphabet will be rendered by using small images (just as we have done in the Oratio's transcription). You are not expected to know how to do this. For the moment, the best way to vault this hurdle is to make a list of all these words (ordering them by document name and paragraph or note number) and keep them in a secure place until you receive further instructions.

Inserting Thumbnails:

N.B. This section has been revised in accordance with the meeting of Sept. 25, 1999.

Because users may want to refer to the incunabulum while reading the annotated transcription of the text, we will be inserting an image into our pieces wherever there is a page break that, when clicked, will load the corresponding image from the Bolognese version of the text. In order to facilitate this process, we will be using one standard image rather than the thumbnail as previously planned. The string of code is really very easy though at first glance it may seem complicated:

<a href="http://www.brown.edu/Departments/Italian_Studies/pico/incunab/testo/bo01.html" target="_top"><img align="right" src="http://www.brown.edu/Departments/Italian_Studies/pico/incunab/text-icon.gif" height="48" width="85" hspace="4" vspace="4" border="0" alt="text"></a>

Everything you see above with the exception of the part in bold will be exactly the same in everyone's documents. The code in bold (bo01) comes from the list below and will vary depending on the section of the incunabulum in question. In order to determine where exactly to put these strings of code into your document, simply examine the online version of the incunabulum and identify where the page breaks occur. E.g. the first page of the incunabulum, bo01.html, contains all of sections 1 and 2 as well as part of section 3 so it should be placed at the very beginning of Pier Cesare's section. The reference to bo02.html will be inserted in that part of section 3 where the text moves on to the top of the following page. Note that each of the URLs listed here is identical except for the number that follows bo.

1-3
http://www.brown.edu/Departments/Italian_Studies/pico/incunab/testo/bo01.html

3-8
http://www.brown.edu/Departments/Italian_Studies/pico/incunab/testo/bo02.html

8-12
http://www.brown.edu/Departments/Italian_Studies/pico/incunab/testo/bo03.html

12-17
http://www.brown.edu/Departments/Italian_Studies/pico/incunab/testo/bo04.html

17-20
http://www.brown.edu/Departments/Italian_Studies/pico/incunab/testo/bo05.html

20-22
http://www.brown.edu/Departments/Italian_Studies/pico/incunab/testo/bo06.html

22-24
http://www.brown.edu/Departments/Italian_Studies/pico/incunab/testo/bo07.html

24-27
http://www.brown.edu/Departments/Italian_Studies/pico/incunab/testo/bo08.html

27-30
http://www.brown.edu/Departments/Italian_Studies/pico/incunab/testo/bo09.html

30-34
http://www.brown.edu/Departments/Italian_Studies/pico/incunab/testo/bo10.html

34-37
http://www.brown.edu/Departments/Italian_Studies/pico/incunab/testo/bo11.html

37-39
http://www.brown.edu/Departments/Italian_Studies/pico/incunab/testo/bo12.html

39-42
http://www.brown.edu/Departments/Italian_Studies/pico/incunab/testo/bo13.html

42-46
http://www.brown.edu/Departments/Italian_Studies/pico/incunab/testo/bo14.html

46-47
http://www.brown.edu/Departments/Italian_Studies/pico/incunab/testo/bo15.html

Section Introductions:

The HTML translation of the section introductions is simple inasmuch as there are no links and no images to worry about. Otherwise, follow all of the steps listed above. Note that you will still have to use the special tags at the beginning and end of each introduction.

Testing Your Documents:

Obviously, there are so many little bothersome details that it is quite unlikely that you will do everything properly on your first try. The best way to find your errors is by testing your documents in a web browser and comparing what you see with what these documents look like when printed. There are two basic ways to test your documents: outside the four-part window and inside.

Testing outside the four-part window:

In your browser, select FILE and then OPEN FILE IN BROWSER (or whatever seems closest to you in whichever browser you use). Choose the name of the document you want to check and press OPEN or OK. You should see the formatted document filling the entire window. Note that this is the only method by which you can check your section introductions.

Testing inside the four-part window:

The window is composed of a series of frames. Let us imagine the Latin text side-by-side with the English translation (precisely what you find in the prototype):

 
Latin text
 
English translation
variants or linguistic notescontextual notes

Each panel of the frame set contains one or more documents. The names that correspond to each of these documents are listed in the table above. There are, however, other files necessary to the proper functioning of this arrangement which you do not see. To test this all together, you will have to download these other files. All files (those you compose as well as the others) must be placed into the same folder. Be aware that you may only test the frame set-up on a Mac or on a PC running Windows 95/98.

Downloading the Frame Files:

There are five files in all that you must download. Each file's name ends in .html, but cannot be downloaded as such. The names therefore have been changed to .zip. The proper procedure for obtaining your own copy of each is as follows:

  1. Click on one of the file names in the second column below.
  2. When asked, save the file into the folder that contains your other html documents.
  3. Change the end of the name of the downloaded file from .zip to .html.

REAL NAMEDOWNLOAD
frame.htmlframe.zip
frame2.htmlframe2.zip
latin.htmllatin.zip
italian.htmlitalian.zip
english.htmlenglish.zip

Once you have all of them, you may test your documents within the frames. To open the Latin on the left and the Italian on the right, open the document entitled frame2.html in your browser (just as explained in Testing outside the four-part window above). To open the Latin on the left and the English on the right, open frame.html.

Prototype and Templates:

In order to assist you in the completion of your html translations, we have provided a working model of the Latin-English frame set-up for §11 of the Oratio, all of whose component parts may be seen together or separately. It will at times be helpful to you to be able to see what the completed versions look like. To see the source of any window, select VIEW and SOURCE of the desired document after you've opened it in your browser. You can use the source of these individual documents as templates for your own documents.

You may consult:

the entire prototype,
the Latin half only,
the English half only,
the Latin text only,
the variants only,
the linguistic notes only,
the English translation only,
or the English notes only.

Keep in mind, however, that when examining the Latin text and the English translation in windows of their own, clicking on links will cause new browser windows to appear. If this is not what you want to do, simply close the undesired browser window and refrain from clicking upon them again.

The elaboration of this guide has been carried out with no small amount of effort. If you cannot understand something after a fair bit of trying, post a message to the newsgroup as such a problem will no doubt be of interest to all of the project participants.

Project Homepage