Science @ NASA Article XML Authoring Guide

Authoring a Science @ NASA article in XML is very similar to authoring
one in HTML. However, because XML is stricter than HTML and because the
tags allowed in an XML article are fewer than those allowed in an HTML
article, authoring a valid Science @ NASA article in XML can be a bit
more difficult than authoring one in HTML.

The best way that authors can assure themselves that the Science @ NASA
article they create is valid is to start from either a previous article
that is already valid or from the Science @ NASA article template below.
By beginning with one of these documents, the article author can be
assured that the exterior XML framework is correct, freeing him/her to
focus on making the interior XML content valid to the Science @ NASA
article DTD or schema.

Once an author has completed a Science @ NASA article in XML, she/he
should validate it against the Science @ NASA DTD or schema. To validate
a Science @ NASA article against the Science @ NASA article DTD or
schema, go to the validation service located at
<http://www.stg.brown.edu/service/xmlvalid/> and follow the
instructions.

## **Science @ NASA Article Template**

\<?xml version=\"1.0\"?\>

\<?xml-stylesheet type=\"text/xsl\"
href=\"../common/xsl/OBPRArticles.xsl\"?\>

\<!DOCTYPE Story PUBLIC \"NASA NEWS\"
\"http://dtd.nasa.gov/SCI-Story.dtd\"\>

\<!---Story element is required and MUST contain at least one of each of
the following elements: Date, Title, Synopsis, Teaser and Body. Source,
Author, Editor, Translator, ChangeLog and Extra elements are optional
and may occur zero or more times. lastmodified and mediabase attributes
are required. pulldate attribute is optional. \--\>

\<Story language=\"English\|Spanish\" lastmodified=\"\_\"
mediabase=\"\_\" pulldate=\"optional\"\>

\<!\-- Date element is required \--\>

\<Date\>\</Date\>

\<!\-- Title element is required \--\>

\<Title\>\</Title\>

\<!\-- Synopsis element is required \--\>

\<Synopsis\>\</Synopsis\>

\<!\-- Teaser element is required. file, width, height and alt
attributes are required, leadout is optional \--\>

\<Teaser file=\"\_\" width=\"\_\" height=\"\_\" alt=\"\_\"
leadout=\"optional\"\>\</Teaser\>

\<!\-- Source element is optional. url attribute is optional \--\>

\<Source url=\"optional\"\>Science at NASA\</Source\>

\<!\-- Author element is optional. email attribute is optional \--\>

\<Author email=\"optional\"\>\</Author\>

\<!\-- Editor element is optional. email attribute is optional \--\>

\<Editor email=\"optional\"\>\</Editor\>

\<!\-- Translator element is optional. email attribute is optional \--\>

\<Translator email=\"optional\"\>\</Translator\>

\<!\-- ChangeLog element is optional. If present, ChangeLog element must
contain at least one Change element \--\>

\<ChangeLog\>

\<!\-- Change element is required within ChangeLog element. date
attribute is required \--\>

> \<Change date=\"\_\"\>\</Change\>

\</ChangeLog\>

\<!\-- Body element is required and must contain at least one Section
element \--\>

\<Body\>

\<!\-- Section elements can contain zero or more of the following
elements: Media, MediaCaption, Table, Sidebar, ul, ol, or p elements.
The title attribute is optional. \--\>

\<Section title=\"optional\"\>

\<!\-- Media element is optional. file, type, width, height and alt
attributes are required. use, align and id attributes are optional.
\--\>

\<Media file=\"\_\" type=\"\_\" width=\"\_\" height=\"\_\" alt=\"\_\"
align=\"left\|right\|center\|auto\" id=\"optional\"
use=\"content\|related\|decoration\"\>

\<!\-- Credit element is optional. url attribute is optional. \--\>

\<Credit url=\"optional\"\>\</Credit\>

\<!\-- Caption element is optional. Caption element can contain plain
text and any of the following elements: Link, b, i, sub, sup. \--\>

\<Caption\>\</Caption\>

\<!\-- Link element is optional. Link elements can contain plain text
and any of the following elements: b, i, sub, sup. url and nasa
attributes are required. type, width, height attributes are optional.
\--\>

\<Link url=\"\_\" nasa=\"true\|false\" type=\"document\|image\|movie\"
width=\"optional\" height=\"optional\"\>\</Link\>

\<!\-- Source element is optional. url attribute is optional. \--\>

\<Source url=\"optional\"\>\</Source\>

\</Media\>

\<!\-- MediaCaption elements are optional. forid and relation attributes
are required. \--\>

\<MediaCaption forid=\"\_\" relation=\"\_\"/\>

\<!\-- p elements are optional. p elements can contain plain text and
any of the following elements: b, i, sub, sup, ul, ol, Measure, Link.
\--\>

\<p\>This is a paragraph. It works the same as in HTML. \<Link
url=\"\_\" nasa=\"true\|false\"\>This is a link with \<b\>bold\</b\> and
\<i\>italic\</i\> text inside of it\</Link\>.\</p\>

\<!\-- Measure elements are optional. Measure elements can contain plain
text. system, metric and english attributes are optional. \--\>

> \<p\>This is a paragraph with a \<Measure system=\"metric\|english\"
> metric=\"optional\" english=\"optional\"\>measurement in
> it\</Measurement\>\</p\>

\<!\-- ol (and ul) elements are optional. ol (and ul) elements can
contain only li elements. \--\>

\<ol\>

\<!\-- li elements are required inside of ol and ul. li elements can
contain plain text and any of the following elements: b, i, sub, sup,
Link. \--\>

\<li\>this is a list item\</li\>

\<li\>this is \<b\>bold\</b\> list item\</li\>

\<li\>this list item has a \<Link url=\"\_\" nasa=\"true\|false\"\>link
in it\</Link\>.\</li\>

\<li\>this is a list item that uses \<sub\>sub text\</sub\> and
\<sup\>sup text\</sup\>\</li\>

\</ol\>

\<!\-- Sidebar elements are optional. Sidebar elements can contain any
of the following elements: Media, MediaCaption, Table, ul, ol, p. title,
align and use attributes are optional. \--\>

\<Sidebar title=\"optional\" align=\"left\|right\|center\|auto\"
use=\"content\|related\"\>\</Sidebar\>

\<!\-- Table elements are optional. Table elements must contain at least
one tr element. align and style attributes are optional. \--\>

\<Table align=\"left\|right\|center\|auto\"
style=\"plain\|row_highlight\|column_highlight\|layout\|layout_highlight1\|layout_hightlight2\"\>

\<!\-- tr elements are required in a Table element. Height attribute is
optional \--\>

\<tr height=\"optional\"\>

\<!\-- td or th elements are required in a tr element. Colspan, width
and rowspan attributes are optional \--\>

\<th colspan=\"optional\" rowspan=\"optional\"
width=\"optional\"\>\</th\>

\</tr\>

\</Table\>

\</Section\>

\</Body\>

\<!\-- Extra elements are optional. Extra elements can contain any of
the following elements: Audio, Editorial, WebLinks, Index, Glossary,
Pronunciations, Translation. \--\>

\<Extra\>

\<!\-- Audio elements are optional. Audio elements are always empty.
file attribute is required \--\>

\<Audio file=\"\_\" /\>

\<!\-- Editorial elements are optional. Editorial elements can contain
plain text and any of the following elements: Media, MediaCaption,
Sidebar, p, b, i, sub, sup \--\>

\<Editorial\>\</Editorial\>

\<!\-- Index elements are optional. Index elements can contain plain
text. keywords attribute is required \--\>

\<Index keywords=\"\_\"\>\</Index\>

\<!\-- Glossary elements are optional. Glossary elements must contain at
least one Term element. \--\>

\<Glossary\>

> \<!\-- Term elements are required inside of a Glossary element. Term
> elements can contain plain text. name attribute is required \--\>
>
> \<Term name=\"\_\"\>\</Term\>
>
> \</Glossary\>

\<!\-- Pronunciations elements are optional. Pronunciations elements
must contain at least one Term element. \--\>

> \<Pronunciations\>

\<!\-- Term elements are required inside of a Pronunciation element.
Term elements can contain plain text. name attribute is required \--\>

> \<Term name=\"\_\"\>\</Term\>
>
> \</Pronunciations\>

\<!\-- Translation elements are optional. Translation elements are
always empty. url and kind attributes are required. \--\>

> \<Translation url=\"optional\" kind=\"optional\" /\>

\<!\-- WebLinks elements are optional. WebLinks elements can contain
plain text and any of the following elements: WebLink, Media,
MediaCaption, Link, Measure, p, b, i, sub, sup. \--\>

\<WebLinks\>

\<!\-- WebLink elements are optional. WebLink elements can contain plain
text and any of the following elements: Media, MediaCaption, Link,
Measure, p, b, i, sub, sup. nasa, url, and title attributes are
required. source attribute is optional. \--\>

\<WebLink url=\"\_\" title=\"\_\" nasa=\"\_\" source=\"optional\"\>
\</WebLink\>

\</WebLinks\>

\</Extra\>

\</Story\>

# Common Mistakes Made When Authoring a Science @ NASA Article in XML

Because the Science @ NASA article DTD/schema is stricter than the
regular HTML DTD/schema, but uses some of the same tags, there are
several common mistakes most Science @ NASA article authors tend to make
when authoring an article in XML. If an author begins with a valid
article or the Science @ NASA article template and pays special
attention to not making the common mistakes listed below, his/her
chances of producing a valid Science @ NASA article in XML are very
good.

1)  No use of the required "alt" attribute in the "Teaser" elements or
    "Media" elements. In accordance with Section 508, all media items
    must have alternate textual content describing themselves for
    disabled users who are unable to see or hear the media item.

2)  No use of the "nasa" attribute on Link and WebLink elements. The
    "nasa" attribute determines whether the link will open in the same
    browser window. Internal NASA links, nasa="true" open in the same
    window vs. external NASA links, nasa="false" open a new browser
    window.

3)  Link elements, or other block level elements such as "p," wrapped
    inside of "b," "i," "u" or other in-line formatting elements.
    In-line formatting elements, such as "b," "i," and "u" are not
    allowed to contain block level elements such as "Link" or "p."

4)  Use of underscores or some other placeholder character within the
    "width" and "height" attributes on the "Teaser" element or on
    "Media" elements. To properly display a media item in the browser,
    it is important that the size of the media item be indicated within
    the "width" and "height" attributes.

5)  Use of ASCII character entities, such as "&nbsp;", "&amp;", or
    "&quot;" instead of their equal numerical entities "&#160;",
    "&#38;", or "&#34;". To see all of the character entities and their
    numerical counter-parts, view the ASCII character DTD at:
    <http://dtd.nasa.gov/isolat.dtd>