Keywords: conference , documentation , DocBook , authoring , schema
Vancouver British Columbia Canada http://www.laurenwood.org/
Biography
Lauren Wood chairs the XML 2005 conference. She is also a Senior Technical Program Manager at Sun Microsystems Inc. Her resume is at Textuality and her blog is named Anyway.
Note that the
honorific
element is not needed, but you can use it if you wish. There is also alineage
element for name suffixes (Jr., etc.) that is used after the surname. Theotheraddr
element is used for web addresses, such as for your company or your blog.
This is the documentation to accompany the DocBook subset used for the proceedings for the XML 2005 Conference. It includes some examples of use, and in fact the entire document is written as a sample proceedings paper.
1. Introduction
2. Character Encodings
3. Types of Elements
3.1 Overall Structure
3.2 Block Elements
3.2.1 Code Example
3.2.2 Blockquote Example
3.2.3 Note Example
3.3 Inline Elements
3.4 Keywords
3.5 Lists
3.5.1 List examples
3.6 Tables
3.6.1 Table Example
3.7 Figures and Examples
3.7.1 Figure Examples
3.7.1.1 Simple figure, no title or caption
3.7.1.2 Formal figure with title and caption
3.7.1.3 Example of a Formal Example
3.8 Links and References
3.9 Bibliographical Entries
3.10 Miscellaneous
3.10.1 Acronyms
3.10.2 Footnotes
4. Generated Text
Acknowledgements
Bibliography
Footnotes
The conference proceedings schema is a subset of DocBook. This subset has been cut down substantially from the full DocBook schema; for example CALS tables are not allowed. This makes authoring and processing the papers easier than if we were to allow all DocBook elements to be used. Papers must validate according to this subset in order to be accepted by the conference submission system and processed into the proceedings. The final proceedings may not look precisely like the preview version on the conference web site, but will be fairly close. Papers should be at least 2000 words long. Longer papers are welcome; generally at least 2500 words are needed to adequately cover the subject matter.
The following documentation includes notes on some of the elements used in the conference subset. You may also wish to refer to the DocBook web site, where there is much more documentation.
If you're reading the HTML version of this document, you should also look at the XML version (schema_documentation.xml) for some of the examples.
All proceedings documents should use Unicode, either UTF-8 or UTF-16. Other character encodings are not supported. Numeric character entities may be used; named character entities are not supported in this subset of DocBook.
Each proceedings paper is one article
element. This
contains one articleinfo
element (with author information,
the abstract, and keywords) and one or more paragraphs or sections. The paper can finish with
appendices, acknowledgements, and a bibliography.
The basic paragraph element is para
. Paragraphs may
be contained within sections (section
) and
in various other locations. Sections embedded in other sections automatically
become subsections.
The other types of paragraphs you may wish to use are
blockquote
, which is used for block quotations,
or note
, which is typically preceded by the word
"Note:". Block quotations and notes contain para
elements.
Long code examples should be put within a programlisting
element, which also ensures the linebreaks are preserved. Please make sure the
contents of these code examples will fit easily on one printed line (for the
PDF version); we recommend using no more than 70 characters per line. Also,
don't use tabs in these code examples, as they will be converted to spaces and
the conversion process may destroy the code layout. If your software tool does
pretty-printing of the XML, you will probably need to turn this off for the
code examples. If you wish to make a formal example with a title, use the
example
element (see
Section 3.7
).
Programlisting keeps the line breaks and formats the text using a suitable font... for code. |
Blockquotes don't keep the line breaks you give them, but you can put in paragraphs. To keep the linebreaks without changing the font, use the
literallayout
element.
If you use literallayout, It will allow you with might To write poetry throughout Even if it isn't very bright.
NOTE: Notes usually have the word "Note" before them. |
This is a Note Title: “Note” is just the default title, you can have your own title. |
The inline presentation elements such as big
or
i
have been replaced with the emphasis
element. The various types of emphasis are given by the role
attribute, which can have values of italic, bold, big, small
,
with italic
being the default.
There are other inline text elements that you may find useful. The definitions were taken from the online DocBook documentation - see [DocBook] for more details.
Keywords (using the keyword
element) should be put
in a keywordset
element within the
articleinfo
element.
They fit between the author
information and the
abstract
. The content of the keyword element does not
appear in the final rendered output, but is used as an index. Please use keywords from the list
available on the conference
website, and put each keyword in a separate
element. Feel free to use your own keywords as well; if you think other people
may want to use the same keywords, please email
Lauren Wood (lauren@textuality.com) or David Kunkel
dkunkel@idealliance.org) to add these to the standard list.
There are three main different types of lists: numbered, bulleted, and
definition lists. The numbered and bulleted lists can have various types of
numbering schemes or bullets associated with them for styling. Since styling in
HTML is done using
CSS
(Cascading Style Sheets), this subset of DocBook
uses the CSS list-style-type
values to define the
types of bullets available for unordered lists.
Use the itemizedlist
element for bulleted lists. There is
an attribute on that element called mark
with
values disc
(closed bullet), circle
(open circle), and square
(solid square) that define the types of
bullets available.
The orderedlist
element for numbered lists uses the attribute
numeration
to change the numbering style.
It has the values arabic
, upperalpha
,
upperroman
, loweralpha
,
lowerroman
(with the results: arabic 1, 2, 3, 4,...;
upperalpha A, B, C, D,... ; upperroman
I, II, III, IV,... ; loweralpha a, b, c, d,..; lowerroman i, ii, iii, iv,...). Both of
these types of lists use the same listitem
element, so it's
easy to change from one type into another.
Definition lists are used for definitions and have varlistentry
elements which contain terms (term
) and
definitions (listitem
).
Every list type can have a title.
The numbered, bulleted, and simple lists are shown here; for examples of what the definition or variable entry lists look like, see Section 3.3 .
DocBook uses a similar table module to HTML 4.01.
Nested tables are not allowed in table cells. CALS tables are not permitted in this subset
of DocBook. There are two types of tables, the informaltable
element
and the table
element. Both types of tables can have
thead
, tbody
,
col
, and colgroup
, and also
contain tr/td/th
elements. table
elements have generated titles of the form "Table 1: " and a mandatory caption while
informaltable
elements have no titles or captions.
Beverage | mg of Caffeine per 7oz serving |
---|---|
Drip | 115-175 |
Espresso 1 serving (1.5-2oz) | 100 |
Brewed | 80-135 |
Instant | 65-100 |
Decaf, brewed | 3-4 |
Decaf, instant | 2-3 |
Table 1
A simple (informal) table |
has no title |
or caption |
There are a number of ways to put figures into your paper. You can have simple figures, with no title or caption, or figures that have titles. You can also have formal examples with titles. Images for inclusion in the proceedings paper must be in one of the formats JPG, GIF, PNG, SVG, or SVGZ. The rendered size of the images must be smaller than 7" (17.5cm) wide by 9" (23cm) high, or 600 pixels wide by 800 pixels high, to fit on the PDF version of the proceedings. The imagedata element allows three ways to size your images; please see the DocBook documentation at imagedata for details. Images that are larger than allowed may be sent back to the author for resizing, automatically scaled down in size, or clipped.
All figures use the mediaobject
element;
formal figures are wrapped with a figure
element
and have a title
element. The "Figure x." is generated
automatically for formal figures but not for simple figures.
If you wish to link to simple figures, use the link
element and provide your own text.
I'm linking to the first figure.
A caption explaining the figure; if you're going to have a caption you must use a title as well.
Figure 1: The XML Conference Logo
this isn't really code but should show the point |
Example 1: this example has a title
The ulink
element is used to reference an external
web-based document. The URI value in the url
attribute will be
treated as a link in the HTML version, and printed in the PDF version of
the proceedings.
Example start…
Please see <ulink url="http://www.xmlconference.org">the conference
web site</ulink>.
…end example.
To generate a cross reference within your paper, use the
xref
element. Set the value of the
linkend
attribute
to match the value of the target element's id
attribute. The
appropriate text and/or links (depending on output medium) will be generated at
the location of the xref
element.
All elements that have an id
attribute
may be cross referenced using the xref
element.
Bibliography entries ( Section 3.9 ), footnotes ( Section 3.10.2 )and acronyms ( Section 3.10.1 ) (all of which use some type of referencing) are documented later.
The bibliography is a list of the bibliographical references you
have used in the paper (including web sites). The list with the full details
for each item you refer to (full URI, publisher, author, etc) is in the rear
matter part of the paper, in the bibliography
element. Each separate
item is in its own bibliomixed
element, with an
id
attribute whose value is used for the references.
The bibliomixed
element contains an abbrev
element, where you put the item label you
want to show up in the paper, as well as other content which
contains the information about title, author, publisher, web site, etc. Although full DocBook does allow the
xreflabel
attribute to be used for item labels, this usage is
deprecated for this conference subset as attributes can't be properly internationalized,
whereas elements can.
You put references in the body of the paper to those items using
the xref
element. The linkend
attribute value must match the id
attribute of the
bibliomixed
element you're referencing.
The content of the referenced abbrev
element will be put in the
processed paper in place of the xref
element. The square
brackets will be automatically generated.
Since the content model
of bibliomixed
is mixed content, you have to be careful
with white space. The processing may turn newlines into spaces, or join two spaces together.
You must add any punctuation such as commas yourself; the system does not add this information.
If the bibliography preview doesn't look right, try adding the punctuation.
Note that we recommend a relatively light style - you don't need to mark up author information
with elements, for example. There are also different ways of putting links in the entries - either
in the bibliomisc
element (which is a slightly better solution),
or directly in the citetitle
element. Please author titles using initial capital
letters only. Do not use all capital letters except for acronyms. If you are
referencing books or other printed material, please include the full title,
authors, publisher, and year of publication, and, if appropriate, volume number and/or page.
The bibliography examples are placed at the end of this document so you can
also see how they are processed.
<bibliography> <bibliomixed id="DocBook"><abbrev>DocBook</abbrev><citetitle> <ulink url="http://www.docbook.org">DocBook documentation</ulink>.</citetitle> </bibliomixed> <bibliomixed id="COMP97"> <abbrev>COMP97</abbrev> <citetitle>Computer Graphics,</citetitle> J. D. Foley et al., <publishername>Addison-Wesley</publishername>, <pubdate>1997</pubdate>. </bibliomixed> <bibliomixed id="COMP90"> <abbrev>COMP90</abbrev> <citetitle>Computer Graphics Principles and Practice,</citetitle> J. D. Foley et al., <publishername>Addison-Wesley</publishername>, <pubdate>1990</pubdate>. </bibliomixed> <bibliomixed id="ECMA"> <abbrev>ECMA</abbrev> <citetitle>ECMAScript Language Specification,</citetitle> <publishername>ECMA General Assembly</publishername>, <pubdate>June 1997</pubdate>. Available at <bibliomisc><ulink url="http://www.el-mundo.es/internet/ecmascript.html"/></bibliomisc>. </bibliomixed> <bibliomixed id="GraphicOM"> <abbrev>GraphicOM</abbrev> <citetitle>Common graphical object models and how to translate them to SVG</citetitle>, P. A. Mansfield, SVG Open 2002 Conference Paper, <pubdate>16 July 2002</pubdate>. Available at <bibliomisc><ulink url="http://www.svgopen.org/papers/2002/mansfield__graphical_object_models/"/></bibliomisc>. </bibliomixed> <bibliomixed id="GS"> <abbrev>GS</abbrev> <citetitle>Graphical Stylesheets: Using XSLT to Generate SVG</citetitle>, P. A. Mansfield, D. W. Fuller, XML 2001 Conference Paper, <pubdate>13 December 2001</pubdate>. Available at <bibliomisc><ulink url="http://www.idealliance.org/papers/xml2001/papers/html/05-05-02.html"/></bibliomisc>. </bibliomixed> <bibliomixed id="PtPoly"> <abbrev>PtPoly</abbrev> <citetitle>Fastest Point in Polygon Test,</citetitle> MacMartin, Stuart et al, Ray Tracing News <issuenum>5</issuenum> <pagenums>(3)</pagenums>, <pubdate>1992</pubdate>. </bibliomixed> <bibliomixed id="SVG"> <abbrev>SVG</abbrev> <citetitle>Scalable Vector Graphics (SVG) 1.0 Specification,</citetitle> J. Ferraiolo, editor, W3C Recommendation, <pubdate>4 September 2001</pubdate>. Available at <bibliomisc><ulink url="http://www.w3.org/TR/SVG"/></bibliomisc>. </bibliomixed> <bibliomixed id="VRML"> <abbrev>VRML</abbrev> <citetitle>Virtual Reality Modeling Language (VRML),</citetitle> International Standard ISO/IEC 14772-1:1997, <publishername>VRML Consortium Incorporated</publishername>, <pubdate>1997</pubdate>. Available at <bibliomisc><ulink url="http://www.web3d.org/technicalinfo/specifications/vrml97/index.htm"/></bibliomisc>. </bibliomixed> <bibliomixed id="X3D"> <abbrev>X3D</abbrev> <citetitle>Extensible 3D Graphics (X3D)</citetitle>. Available at <bibliomisc><ulink url="http://www.web3d.org/x3d.html"/></bibliomisc>. </bibliomixed> </bibliography> |
Example start…
IDEAlliance (formerly the <acronym>GCA</acronym> Graphic Communications Association) is a non-profit industry association.
The XML standard was first announced at a <acronym >GCA</acronym> conference in 1996.
processes as:
IDEAlliance (formerly the GCA Graphic Communications Association) is a non-profit industry association. The XML standard was first announced at a GCA conference in 1996.
…end example.
You don't need to define well-known acronyms such as XML, but defining more rather than fewer is beneficial.
When text requires a footnote, use the footnote
element at the point where the footnote should occur. The footnote marks will
be automatically generated, so don't put these in. If you think you might want
to reuse the content of the footnote, put a value in the
id
attribute on the footnote
element.
Then you can use the
footnoteref
element's
linkend
attribute to reference that
footnote.
Example start…
He was not himself that day<footnote id="fn01"><para>01 January 2001</para></footnote>.
On that fateful day<footnoteref linkend="fn01"/>, he woke up late.
processes as:
He was not himself that day [1] . On that fateful day [1] , he woke up late.
…end example.
When processed into HTML or PDF, the elements listed here automatically generate the required text. Therefore, please do not insert the following text items in your paper within these elements.
itemizedlist
) - arabic, lower alpha, upper alpha, lower
roman or upper roman counter
orderedlist
) - bullet or dash
XHTML rendition made possible by SchemaSoft's Document Interpreter™ technology.