Article XML Guide

A specification of the XML used for articles, which parts are required and which are not, and the roles of each element and its attributes.

Basic document skeleton

<?xml version="1.0" encoding="iso-8859-1"?>
<?xml-stylesheet type="text/xsl" href="/devedge-srce/lib/xsl/devedge-1.00/article_en.xsl"?>
<nde:article
   url="[url]"
   xmlns:nde="http://devedge.netscape.com/2002/de"
   xml:lang="[language code]">

 <nde:header> </nde:header>
 <nde:head> </nde:head>
 <nde:content> </nde:content>
 <nde:related> </nde:related>

</nde:article>

This is the basic toplevel skeleton for an article file. The four toplevel elements all have descendent elements. These are explained by the rest of this document.

The bracketed, italicized, light gray text represents stuff that needs to be replaced by the document author with the proper values. For example, for the article "Images, Tables, and Mysterious Gaps," the value of [url] would be /devedge-srce/viewsource/2002/img-table, and [language code] would be en.

<nde:header> </nde:header>

This element contains the header information for the file, such as keywords, the title of the piece, and so on. This can be thought of the metadata related to the article.

<nde:head> </nde:head>

This element contains any material that needs to be inserted into the HEAD element of the HTML document. Examples include article-specific stylesheets, scripts, or META tags.

<nde:content> </nde:content>

This element contains the actual content of the piece, marked up as HTML 4.01. Note that section headings in the content should be in h2 elements, as these are used to generated a table of contents in articles that are long enough to need one.

<nde:related> </nde:related>

This element contains a list of links to resources that are related to the article's content and overall topic. This will often consist of pointers to any specifications that were referenced in the article text. There are actually two nde:related elements possible, one required and the other optional. These are discussed in detail later on.

nde:header — The Document Header

  <nde:header>
    <nde:title>[insert title here]</nde:title>
    <nde:category>[insert category here]</nde:category>
    <nde:pubdate year="[CCYY]" month="[MM]" day="[DD]"/>
    <nde:moddate year="[CCYY]" month="[MM]" day="[DD]"/>

    <nde:summary>[short summary of piece (blurb text)]</nde:summary> 
    <nde:abstract>
      [longer abstract, typically a paragraph in length]
    </nde:abstract>
    <nde:channels>
      <nde:channel id="[channel id]"/>
      <nde:channel id="[channel id]"/>
    </nde:channels>
    <nde:keywords>[comma separated, keywords]</nde:keywords>
    <nde:translations>
      <nde:trans url="[url]">[language]</nde:trans>
    </nde:translations>
    <nde:alternates>
      <nde:alt url="[url]">[format]</nde:alt>
    </nde:alternates>

    <nde:authlist>
      <nde:author>
        <nde:authname>[name]</nde:authname>
        <nde:authtitle>[title]</nde:authtitle>
        <nde:authaffil>[affiliation]</nde:authaffil>
        <nde:authcontact>[e-mail (if desired)]</nde:authcontact>
        <nde:authdesc>[bio statement; two short sentences maximum]</nde:authdesc>
      </nde:author>
    </nde:authlist>

    <nde:copyright>
      <nde:copyhold>[holder of copyright]</nde:copyhold>
      <nde:copyyear>[copyright date]</nde:copyyear>
      <nde:copyaddr>[contact information]</nde:copyaddr>
    </nde:copyright>

  </nde:header>

This is the meat of the file. It contains all of the really important data that isn't the actual content. Most of the elements in the header are optional, but this does not mean you should drop them. It simply means that the article can be published without the optional elements.

<nde:title>[insert title here]</nde:title>

This contains the title of the article, and will be inserted into the TITLE element in the HTML document. It's also placed at the beginning of the article content.

<nde:category>[insert category here]</nde:category>

This element is used to provide the category of article. The element's content can be any one of the following values:

• article
• technote

<nde:pubdate year="[CCYY]" month="[MM]" day="[DD]"/>

This is the publication date of the article. The values are all numbers; use a leading zero for single-digit numbers. Thus, April would be represented as 04.

<nde:moddate year="[CCYY]" month="[MM]" day="[DD]"/>

This is the modification date of the article, if any. The values are as for the nde:pubdate element.

<nde:summary>[short summary of piece (blurb text)]</nde:summary>

This contains a one or two sentence summary of the file. This content is used for the "blurb text" on Centrals and in search results, so it should be direct and clear about what the article will offer the reader.

<nde:abstract> [longer abstract, typically a paragraph in length] </nde:abstract>

The content of this element is text, optionally marked up using HTML, that provides a deatiled abstract of the article's contents. This can be the lead-in text for a long article, or an abstract of the type seen on academic papers. It is inserted before the article content in the HTML document.

<nde:channels> <nde:channel id="[channel id]"/> </nde:channels>

This provides the "channels" in which the article should appear. The nde:channels element can contain one or more nde:channel elements.

<nde:channel id="[channel id]"/>

Channel IDs are defined along two axes: the toplevel area to which the article belongs, and the centrals to which it is closely related. For example, a Viewsource article concentrating on the DOM would have the following nde:channels element:

<nde:channels>
  <nde:channel id="viewsource"/>
  <nde:channel id="dom"/>
</nde:channels>

The channel ID values are used to determine which pages on DevEdge will show the article. Thus, the above example would cause the article to show up as a new entry in Viewsource and the DOM Central. It would also appear in the RSS feeds for those two resources.

<nde:translations> <nde:trans url="[url]" title="[title]">[language]</nde:trans> </nde:translations>

This element contains pointers to tranlsations of the article into other languages. These translations can be on DevEdge itself or hosted by other parties. The links will appear in the right rail of the article. The nde:translations element can contain one or more nde:trans elements.

<nde:trans url="[url]" title="[title]">[language]</nde:trans>

For each nde:trans element, the url attribute is required, and there must be some content to the element. The content is used as the text of the link in the HTML document. The title attribute is technically optional but strongly encouraged for accessibility reasons.

<nde:alternates> <nde:alt url="[url]" title="[title]">[format]</nde:alt> </nde:alternates>

This element contains pointers to copies of the article available in alternate formats, such as PDF, raw XML, or anything else. These copies can be on DevEdge itself or hosted by other parties. The links will appear in the right rail of the article. The nde:alternates element can contain one or more nde:alt elements.

<nde:alt url="[url]" title="[title]">[format]</nde:alt>

For each nde:alt element, the url attribute is required, and there must be some content to the element. The content is used as the text of the link in the HTML document. The title attribute is technically optional but strongly encouraged for accessibility reasons.

<nde:authlist> <nde:author> </nde:author> </nde:authlist>

This element contains a list of authors for the article. While it is not required, it should only be omitted in those cases where the resource has no author. For each author, use a separate nde:author element. nde:author has a number of subelements, all but one of which are optional.

<nde:authname>[name]</nde:authname>

This element contains the name of an author. nde:authname is required for each nde:author element.

<nde:authtitle>[title]</nde:authtitle>

This element contains the author's title (e.g., "CEO" or "Standards Evangelist").

<nde:authaffil>[affiliation]</nde:authaffil>

This element contains the author's affiliation (e.g., "Netscape Communications").

<nde:authcontact>[info]</nde:authcontact>

This element contains the author's contact information. This can be an e-mail address or a URL to a personal Web site. If it is omitted, the XSLT will automatically add a link to the DevEdge feedback page to the author information in the article.

<nde:authdesc>[bio statement]</nde:authdesc>

This element contains a brief biographical description of the author, no more than two or three short sentences in length.

<nde:copyright> </nde:copyright>

This element contains information relevant to the copyright on the article. This is most often used for articles which are written by outside parties who have retained copyright for their work. It can also be used to indicate Netscape copyright, but this is not necessary. nde:copyright has three subelements, all of which are strongly recommended.

<nde:copyhold>[holder of copyright]</nde:copyhold>

The names of the copyright holder. This can be an individual, corporation, or any other entity.

<nde:copyyear>[CCYY]</nde:copyyear>

The copyright date, expressed as a four-digit year.

<nde:copyaddr>[contact information]</nde:copyaddr>

Contact information for the copyright holder. This can be an e-mail address, URL, physical-mail address, or any other method of contact.

nde:head — Content For the Document Head

<nde:head>
 [for document-specific styles, links, scripts, etc.]
</nde:head>

This element is used to insert any document-specific material into the HEAD element of the HTML document. This could be used to insert a complete stylesheet needed to display certain examples in the article, links to scripts that the article discusses in order to make examples work, and so on. This will only rarely be needed.

nde:content — The Article Itself

<nde:content>
 [content of article]
</nde:content>

This element contains the actual content of the article. The article content should be authored according to the DevEdge editorial guidelines. Note that H2 elements should be used for section titles within the article, as these are used to generate a table of contents in the right rail.

nde:related — Related Resources

<nde:related area="nde">
  <nde:item url="[url]" title="[title]">[link text]</nde:item>
</nde:related>
<nde:related area="ext">
  <nde:item url="[url]" title="[title]">[link text]</nde:item>
</nde:related>

The nde:related element is used to provide a list of related articles, areas of DevEdge, and external resources. For any article, there must be an nde:related element with a value of nde for the area attribute. This is the list of links to resources on DevEdge that are related to the article. This is required because, at a minimum, it will list related Centrals. Any links to resources outside of DevEdge are listed in an optional nde:related element whose area attribute has been set to ext. Each nde:related element can contain one or more nde:item elements.

<nde:item url="[url]" title="[title]">[link text]</nde:item>

For each nde:item element, the url attribute is required, and there must be some content to the element. The content is used as the text of the link in the HTML document. The title attribute is technically optional but strongly encouraged for accessibility reasons.

Full Document Skeleton

<?xml version="1.0" encoding="iso-8859-1"?>
<?xml-stylesheet type="text/xsl" href="/devedge-srce/lib/xsl/devedge-1.00/article_en.xsl"?>
<nde:article
   url="[/devedge-srce/viewsource/2003/example-article/]"
   xmlns:nde="http://devedge.netscape.com/2002/de"
   xml:lang="[language code]">

  <nde:header>
    <nde:title>
       [insert title here]
    </nde:title>

    <nde:category>
      [insert category here]
    </nde:category>

    <nde:pubdate year="[CCYY]" month="[MM]" day="[DD]"/>
    <nde:moddate year="[CCYY]" month="[MM]" day="[DD]"/>

    <nde:summary>
      [short summary of piece (blurb text)]
    </nde:summary>
    <nde:abstract>
      [longer abstract, typically a paragraph in length]
    </nde:abstract>
    <nde:channels>
      <nde:channel id="[channel id]"/>
      <nde:channel id="[channel id]"/>
    </nde:channels>
    <nde:keywords>
      [comma separated, keywords]
    </nde:keywords>
    <nde:translations>
      <nde:trans url="[url]" title="[title]">[language]</nde:trans>
    </nde:translations>

    <nde:alternates>
      <nde:alt url="[url]" title="[title]">[format]</nde:alt>
    </nde:alternates>

    <nde:authlist>
      <nde:author>
        <nde:authname>[name]</nde:authname>
        <nde:authtitle>[title]</nde:authtitle>
        <nde:authaffil>[affiliation]</nde:authaffil>
        <nde:authcontact>[info]</nde:authcontact>
        <nde:authdesc>[bio statement]</nde:authdesc>
      </nde:author>
    </nde:authlist>

    <nde:copyright>
      <nde:copyhold>[holder of copyright]</nde:copyhold>
      <nde:copyyear>[CCYY]</nde:copyyear>
      <nde:copyaddr>[contact information]</nde:copyaddr>
    </nde:copyright>

  </nde:header>

  <nde:head>
   [for document-specific styles, links, scripts, etc.]
  </nde:head>

  <nde:content>

[
    <h2 id="toc1">toc1</h2>

    <p>content of piece 1</p>

    <h2 id="toc2">toc2</h2>

    <p>content of piece 2</p>

    <h2>toc3</h2>

    <p>content of piece 3</p>

    <h2>toc4</h4>

    <p>content of piece 4</p>
]
  </nde:content>

  <nde:related area="nde">
    <nde:item url="[url]" title="[title]">[link text]</nde:item>
  </nde:related>
  <nde:related area="ext">
    <nde:item url="[url]" title="[title]">[link text]</nde:item>
  </nde:related>
</nde:article>