Instructions to WASA Authors

Introduction

Each member project in WASA can establish a "mini-site" where they can publish online documents related to their particular project.

In order to facilitate the quick publishing of documents online, WASA has developed the following instructions or protocol for how documents should be submitted by projects.

Documents

At present, there are five main categories of general content (i.e., not data) that can be added to the Web site. These are:

Breaking News. This is an important news item which is placed on the Home Page. A project should coordinate this through the WASA regional coordinators. If approved, the text and required links can be submitted in an email and WASA Web site personnel will add the content to the HTML pages manually.

News Item. A regular posting of news. This consists of a simple block of text and an optional image. An item gets plonked at the top of a page of items. It is planned that news items can be submitted via a Web form which automates the publishing process.

General page The core pages which act largely as navigational or promotional pages. An example is the Research projects page where the member projects are listed and hot-linked. When a project joins, it provides a project description page. These pages have a fairly set structure and content and a template file will be supplied to the project.

Article Each project can add documents in the form of articles to the site. These are generally single pages, which can nevertheless be long, and may comprise text and photos. These page documents must be submitted as XML documents (details below).

Online book. If the content is extensive and can be logically arranged into "chapters", one page per chapter, then it can be published as an online book with navigation functionality added to move between chapters, such as a Table of Contents, and forward and back buttons. The expedition reports from ISBP seem to be a logical "book" where each day's activities is a chapter. The document is submitted as a series of XML files together with images (details below).

Field Guide

In addition to the types of documents that a project can add to the site, members can add content to the existing online field guide. The guide is organized as an online book, one chapter per species. Each species account consists of text organized into sections, and one or more images with captions. Each species account is atributed to one or more authors who "adopt" the species and are responsible for maintaining and revising the account. A member is free to add a new shorebird species account to the guide, or work with the author of an existing account.

Content for the guide must be submitted in XML format. See details of XMl tags below.

Background

A Web site is largely a collection of HTML pages which comprise text content and style (layout) information. So when we talk about adding a document to the Web site we usually talk about adding HTML pages. The problem is that this means the creator (often a biologist) has to provide both text content (the important part) and style!

Rather than store content and style in one document and expect users to be knowlegable about both, we separate the style from the content and manage them separately. We use Extensible Markup Language (XML) to store the text content, and we use XSLT files to store the page layout instructions. Then when it comes time to create an HTML page with both parts, we do this automatically using special software.

So, the users are asked to submit their text content in XML format. The documentation here will help the user to prepare such documents. By preparing XML files, the process of publishing the content on the site is speeded up tremendously, which means that there can be very fast turn-around times on new documents.

Document Preparation

The basic steps are:

Decide what type of document it is: an article or a new online "book" (i.e., a series of logically related pages or chapters). News items are dealt with separately. This protocol refers mainly to page and book documents.
Compile text and images.
Organize text into XML structure. Integrate image files as links, making sure that filenames and links agree. See tips on naming conventions.
Once ready, package up xml files and image files into one zip file and send to WASA Web site.

When a user is starting to create a new document for the Web site they should think carefully about what type of document is best. The expedition reports from ISBP seem to be a logical "book" where each day's activities is a chapter.

XML structure for documents

An XML file is simply the text content wrapped by XML elements or tags. In this way it is similar to HTML, except that the tags are structural not stylistic, and they (the tags) can be customized. We have developed a WASA set of XML elements which authors must use if they want us to create HTML documents for the site..

There are two basic kinds of elements: block elements start a new line when formatted (e.g., section). Block elements can contain inline elements which do not force a line break but modify text (e.g., emphasis).

The following table lists block and inline elements for a WASA XML file.

element	purpose	example
Table 1: WASA block and inline XML elements
document	page document	`<page id="into" lang="en">...</page>` The root element for a page document. The attribute "id" is optional. The "lang" attribute specifies the language template which should be applied. In this example the document is in English. Other values are: es (Spanish), pt (Portugese), fr (French).
article	chapter	`<article id="ch01">...</page>` The root element for a book chapter. The attribute "id" is optional.
title	Title	`<page> <title>The structure of XML</title>... </page>` This is the page title and it is centred in orange at top of page.
sect1	Section	`<sect1 id="elements"> <title>Block Elements</title>... </sect1>` This is the top-level section. The attribute "id" is optional. A title within sect1 is bolded and left aligned.
para	paragraph	`<sect1 id="elements"> <title>Block Elements</title> <para>The block element is ...</para> </sect1>` This creates a block of text
itemizedlist	List of items where order doesn't matter.	`<itemizedlist> <listitem>A list of two items</listitem> <listitem>another item</listitem> </itemizedlist>`
orderedlist	List of items where order does matter.	`<orderedlist> <listitem>Step One: prepare</listitem> <listitem>Step 2: Go</listitem> </orderedlist>`
sidebar	sidebar	`<sidebar> <para>text put in a shaded box</para> </sidebar>` Sidebars are shaded boxes containing paragraph text and lists. They can have titles.
note	note	`<note href="http://www.noaa.gov" img="../images/logos/noaa_logo.gif" <title>Inline elements</title> <para>The inline element is...</para> </note>` Use a note when you want to put content in a one-row table. In this example the "href" attribute is used to hot-link the note title (it is an inline HTML tag). The "img" attribute (inline HTML tag) will put an image in the first cell of the note.
note-list	note-list	`<note-list> <note><para>The tag we use...</para></note> <note><para>The next tag we can use...</para></note> </note-list>` Use a note-list when you want one table with several rows (one per note) formatted with images in each row.
mediaobject	media object	`<mediaobject align="right"> <objectinfo> <title>Red Knot</title> </objectinfo> <imageobject id="ibp01"> <imagedata fileref="images/rekn-hand0.jpg" width="270" align="right" srccredit="M. Dennison"/> </imageobject> <caption> <para> Red Knot in Delaware Bay </para> </caption> </mediaobject>` This element wraps an image, or a videoclip, or sound file. Use the "align" attribute to specify where on the page to place.
object-info	object information	See example for mediaobject (above). Text here is used for the "alt" tag.
image-object	image object	See example for mediaobject (above). This element wraps the image file details.
imagedata	image data	See example for mediaobject (above). This element includes attributes which specifies file path and who created it.
caption	caption	See example for mediaobject (above). This text will be centred under the image.

Tips on text prepartion

A few tips when you create the XML document.

The software that parses the XML file and applies the stylesheet to it and then creates an HTML file is fussy about the XML tags. Please ensure that tags are clean.
For a "book", there should be one XML file per chapter. Eventually, there is also a "main" file which contains a list of the chapters in the book, but this is created by us at WASA.
Name the xml files carefully. Keep names short. e.g., rigr-2000.xml In the case of book "chapter" files, use a clear, logical convention, such as rigr-ch01.xml, rigr-ch02.xml, etc. for the first two chapters of the book. Please note that case is relevant; preferably use lower-case characters.
Within a document there may be image links. Ensure that the filenames in the document match with the image filenames. As described in the File structure section, images files go into an "images" subdirectory on the server. So the path for the image should be: images/filename-01.jpg
In most cases WASSA can supply the prospective author with an XML file or template which they then simply have to modify by cutting and pasting their content into. Thus avoiding having to do actual XML markup.

Tips on image preparation

The following tips can help when you prepare images to accompany a document.

For photos use JPEG format.
We recommend that images not be wider than 300 pixels to accomodate smaller screens. Keep file sizes small (hence faster for users to download) by using 72dpi images for the Web and medium compression.
Name files carefully. For images within a simple document, assign an acronym and then a sequential numbering system. e.g., rigr-01.jpg, rigr-02.jpg, etc. Keep acronyms short. For images within a book, it is useful to identify the book and chapter for each image file. e.g., rigrch01-01.jpg , rigrch01-02.jpg, rigrch02-01.jpg, etc for the first two images for chapter 1 of the rigr book, and the first image file of chapter 2 of the book.

Submitting your document

Once the document files and images are ready, they can be compiled into a single package such as a zip file and then sent to WASA Web site. Put the images files into a sub-directory called images.

[ Home page ]

[ Maps ]

[ Data entry ]

[ Education ]

[ Contact Us ]