Getting Started

Before you even attempt to mark up the content of an ejournal, you should be have at least read the following sections of the handbook:

1. Skills : HTML
2. Skills : Server Side Includes
3. Skills : File and Directory Management

The sections above cover basic journal markup. To deal with more complex journals, you may also want to read the following sections:

1. Skills : Images
2. Skills : Styles
3. Tasks : Converting Word Graphics

Your best guide for the specifics of marking up a given journal is a previous issue of the journal (assuming that issue has been marked up according to these rules). Previous issues should give you an idea of the way a journal issue should look and an idea of the file and directory naming conventions. That being said, here are some guidelines that will help you mark up a new issue of a journal, whether or not previous issues of that journal have been marked up properly.

Overall Layout

Think of a good page as a sandwich with the following structure:

Site Header

Journal Header

Issue Header

Content of Article

Issue Footer

Journal Footer

Site Footer

The headers should include a logo for the site/journal. The headers let the user know where they are, they provide a context for the content.

The footers provide navigational links and contact information for each of the contexts (site, journal, issue) to which an article is related.

If you've read other parts of this site, you can probably see that this type of site design is easy to accomplish with Server Side Includes. Didn't read the section? Forgot what it said? Read about Server Side Includes now.

The best way to implement the nested structure suggested above is to create a header and footer for each issue of a journal. The header for the issue should include the header for the journal. The header for the journal should include the header for the whole site. For examples of this, look at the most recent issues of the JITE and ALAN Review. Remember that you can't just view the source of the document, as the server side includes will already have been replaced by actual code. You'll have to use BBedit or Fetch to bypass the web server, so that you can see the server side includes. Doing this is a simple matter of opening the include file in Bbedit, it should be located in the include folder in the directory.

Marking Up the Content

Most content you'll be asked to mark up will be delivered as a word processed file. Although modern versions of Word and other word processors offer the ability to save as HTML, it is not recommended that you do so. Word processors often generate invalid HTML and attempt to preserve fonts, margins, and even page breaks that are inappropriate for inclusion in a journal article.

Instead of exporting from a word processor, we copy and paste the entire text of an article into the body of a blank web page in BBedit (hint: hit the "New Document" button on the HTML tool bar to generate a blank web page). The copied text will be unformatted, you'll need to use a paper or PDF version of the article as a basic reference. Here is a good basic sequence for adding presentation to an unformatted article:

1. Add paragraphs
   Go through the text and make sure there are two and only two carriage returns between each paragraph. Now select the text you'd like to add paragraphs to, then click the "Paragraph" button on the HTML Tools Palette.
2. Add headings and blockquotes
   Markup any section headings with the appropriate heading tag (<h3> is usually best). Enclose the text between headings in <blockquote> tags.
3. Add text formatting
   Text that appears as bold within the article should be bold. Text that appears as italic, etc.. This is a general rule; remember that you're first trying to preserve the content of the article, and secondly the presentation. If the author uses underlining to indicate the title of a book, then you need to make sure the title of the book is underlined. If the entire article has a one inch margin, you don't need to reproduce this exactly in the HTML version. However, if a section of the text is indented to indicate that it's a long quote from another source, you need to enclose the quote in <blockquote> tags.
4. Add tables
   With practice, you should be able to reproduce most any table included in an article in HTML format. Take the time to learn how to create a table that makes appropriate use of background colors, colspans, rowspans, and alignment, and you shouldn't need to rely on any of these dirty tricks:
   • enclosing a text-only table in <pre> tags
   • using non breaking spaces (&  elements) to make cells line up with each other.
   • including a picture of a text-only table
   • using transparent gifs to add horizontal space to a column or vertical space to a row
   If you really don't think you can reproduce a text-only table in HTML format, ask for help before relying on any of the messy, messy tricks listed above.
5. Add figures
   There are a number of strategies for creating web images from a word processed file. Two of these are discussed in the section of the handbook entitled "Tasks : Converting Word Graphics." Keep in mind that the figure needs to be legible, but if at all possible should not be more than 575 pixels wide.
6. Check for word processing characters
   You were going to check the syntax of your document anyway, right? Good. Unlike iCab, BBedit will check for word processing characters that don't belong in an HTML file. BBedit will point all of the illegal characters out to you, you'll need to replace them with the appropriate HTML entities. For a list of HTML entities, refer to the book HTML: The Definitive Guide, which should be available in the office. For a very dry reference (but one that is not likely to go away), visit the W3C page on entities that are supported in HTML 4.0.

Now you should be ready to mark up the references in the article.

Marking Up the References

At the end of any article that includes references to or quotes from another work, there should be a bibliography or references section. Our job is to add a link between all cited references to a work and its entry in the bibliography or reference section.

This is accomplished in two stages:

1. Add a placeholder anchor of the type <a name="{last_nameYEAR}"></a> in front of each entry in the bibliography or reference section, where last_name is the last name of the first author, and YEAR is the year the work was published. If there is more than one work with the same primary author in a given year, use something like smith1999-1, smith1999-2, etc.
2. Wherever there is a citation in the text (usually in parentheses), add an internal link (<a href="#last_nameYEAR">) to the appropriate placeholder. For example, a citation like (Jones, 1998) would be linked to the appropriate entry in the bibliography using the following code: (<a href="#jones1998">Jones, 1998</a>)

Be sure to double check your work. Make sure all the internal links match the placeholder anchors you've created. The "Check Links" button (on the HTML Tools Palette) in BBedit may be of use.