Writing sdoc

sdoc is the current umbrella name for both the markup language and the parser we use to generate documentation for the SEUL Project. The format is based on HTML, and consists of extra tags to provide a faster way to build pages, concentrating on content rather than presentation. The parser is a basic SGML core, with hooks to allow the contents of any tag to be passed into a handler script for processing.

What?

sdoc is primarily intended as a way to build an entire web site in a single style, while offloading the work of building that style to one entity in charge of the site. Maintaining a single look throughout the website with dozens of authors in many countries/timezones would be impossible if all the pages were editted in raw HTML. As such, all tags that exist to date are designed for the SEUL website.

Web pages

Much of the functionality comes from slightly modifying or augmenting existing HTML tags:

  • <TITLE>title</TITLE>

    This tag passes through unchanged, but the contents are stored for future reference.

  • <META name="type" content="data">

    This tag also passes through unchanged, but the type listed will cause one of many things to happen:

    • doctype

      The document type, usually "webpage", tells the parser what tag handlers should be loaded. The webpage type loads handlers appropriate for the generation of external site documents.

    • author

      This simply stores away the information for later use.

  • <BODY> </BODY>

    This tag is modified to include the standard elements (color, background image, etc.), and in the case of a webpage, it adds a <TABLE> </TABLE> to allow the <SECTION> tags to work properly.

Changes

There are a few new tags that are specific to the webpage doctype for now, but may appear (likely with different output) in other doctypes in the future:

  • <SEUL>

    This tag allows any instance of "SEUL" to be converted to a link to the official website with the addition of < >. This tag should be followed by the word <Project> wherever possible, to allow for browsers that eat the resulting "SEUL" alive.

  • <SECTION title="section title">

    Sections can be created with this tag, and they may be nested to provide numbering. Numbering is most useful for some of the derivatives of the webpage doctype, but sections are still required for web pages. They are what provide the headings to the right of the document.

New tags

A basic document is quite simple to create. By far the simplest method would be to copy the following example and fill in the appropriate information. The HTML output is also available.

<HTML>
<HEAD>
<TITLE>Placeholder</TITLE>
<META name="doctype" content="webpage">
<META name="author" content="Erik Walthinsen (omega)">
<META name="description" content="Basic placeholder file, an example">
<META name="keywords" content="placeholder, sdoc, example">
</HEAD>

<BODY>

<section title="Placeholder">
<p>Pathetic placeholder file</p>
</section>

</BODY>

<ADDRESS>
<I>
$Id: writing.html,v 1.1.1.1 2001/02/08 20:09:05 arma Exp $
</I>
</ADDRESS>
</HTML>

Example

$Id: writing.html,v 1.1.1.1 2001/02/08 20:09:05 arma Exp $