title: stx2any -- definitions for DocBook XML
doc_id: impl.docbook-xml

This file is copyright (c) 2004,2005,2006 by Panu Kalliokoski
and released under the license in ../LICENSE

w_use(examples/reflection-disclaimer)

Definitions for DocBook XML.

XML requires well-formed paragraphs, so we have our own paragraph system
here.  We put a paragraph inside most everything "just to be sure".
Here are the macros to keep the result well-formed.
{{{
define(`w_paragraph', `w_close<Para>define(`@w_para_open',t)')
define(`w_open', `w_paragraph`'undefine(`@w_para_flag')')
define(`w_close',
`ifelse(defn(`@w_para_open'),t,</Para>)'dnl
`define(`@w_para_open',)')
}}}
`w_close' must be called before emitting any block-level tag.  `w_open'
will open a paragraph, no matter what.  `w_softopen' marks that if there
is text forthcoming, it must be in its own paragraph.

DocBook has its own sectioning system -- very structured but poorly
corresponding to traditional typography.  (In some ways, a section is a
unit, in others, it is not.  For example, a document usually makes
sensible reading if you take away headings, but not always when you
remove some section.)

The macros here are linked to headings: headings produce sections.  But
we need to hook closing of sections somewhere.  This is done at the
template.
{{{
define(`@w_sectlev', 0)
define(`w_set_sect_level',
`ifelse(eval(`$1>'defn(`@w_sectlev')),1,
  `define(`@w_sectlev',incr(defn(`@w_sectlev')))'dnl
`w_close<Sect`'defn(`@w_sectlev')>w_set_sect_level(`$1')',
  eval(`$1<'defn(`@w_sectlev')),1,
  `w_close</Sect`'defn(`@w_sectlev')>w_softopen`'define(`@w_sectlev',
    decr(defn(`@w_sectlev')))w_set_sect_level(`$1')')')
define(`w_headline',
`w_set_sect_level(decr(`$1'))'dnl
`w_set_sect_level(`$1')<Title>$2</Title>w_softopen')
}}}

Block system environments.

{{{
w_define_env(-,`w_close<ItemizedList>',`w_close</ItemizedList>w_softopen')
w_define_env(#,`w_close<OrderedList>',`w_close</OrderedList>w_softopen')
w_define_env(i,`w_close<ListItem>w_open',`w_close</ListItem>')
w_define_env(q,`w_close<BlockQuote>w_open',`w_close</BlockQuote>w_softopen')
w_define_env(:,
`w_close<VariableList>pushdef(`@w_varitem_open',)',
`w_close`'w_close_varitem</VariableList>popdef(`@w_varitem_open')w_softopen')
define(`w_defnterm', `w_open_varitem<Term>$1</Term>')
w_define_env(t,
`define(`w_pending_block_hook', `w_close<ListItem>w_open')',
`ifelse(defn(`w_pending_block_hook'),,
   `w_close</ListItem>w_close_varitem',
   `define(`w_pending_block_hook',)')')
define(`w_open_varitem',
`ifelse(defn(`@w_varitem_open'),,`w_close<VarListEntry>')'dnl
`define(`@w_varitem_open',t)')
define(`w_close_varitem',
`ifelse(defn(`@w_varitem_open'),t,`w_close</VarListEntry>w_softopen`'')'dnl
`define(`@w_varitem_open',)')
}}}

Other environments.

{{{
w_define_env(litblock,`w_close<Screen>',`w_close</Screen>w_softopen')
w_define_env(footnote,`<Footnote><Para>',`</Para></Footnote>')
w_define_env(compactlist,
`w_close<LiteralLayout>w_open',
`w_close</LiteralLayout>w_softopen')
w_define_env(center,
`w_close<InformalTable><TGroup><ColSpec align="center"/><TBody><Row><Entry>w_open',
`w_close</Entry></Row></TBody></TGroup></InformalTable>w_softopen')
w_define_env(abstract,
`w_close`'w_begdiv(ingr)<Abstract>w_open',
`w_close</Abstract>w_enddiv(ingr)w_softopen')
w_define_env(comment, `<!-- ', ` -->')
w_define_env(citation,
`w_close<BlockQuote><Attribution>$*</Attribution>w_open',
`w_close</BlockQuote>w_softopen')
w_define_env(`w_float_n',
`w_close<Figure>w_softopen',
`w_caption(`$1') w_close</Figure>w_softopen')
}}}

There is no real way to put line breaks into documents in DocBook.  We
should wrap the whole paragraph in literal layout, but we can't do that
at this stage, and there might be non-hard line breaks in the same
paragraph.  Let's just settle for this ugly hack:
{{{
define(`w_linebr', <LiteralLayout>w_nl</LiteralLayout>)
}}}

Emphasis.

{{{
define(`w_literal', `<Literal>$1</Literal>')
define(`w_emph', `<Emphasis>$1</Emphasis>')
define(`w_techemph', `<Replaceable>$1</Replaceable>')
define(`w_strong', `<Emphasis Role="strong">$1</Emphasis>')
define(`w_quotation', `<Quote>$1</Quote>')
}}}

Other inlines.

{{{
define(`w_link', `<ULink url="$1">$2</ULink>')
define(`w_url', `<URI>$1</URI>')
define(`w_img',
`<InlineMediaObject>'
`<ImageObject><ImageData fileref="w_file(`$1.'w_picture_suffix)"/></ImageObject>'
`<TextObject>$2</TextObject>'
`</InlineMediaObject>')
define(`w_label', `<Anchor id="$1"/>'dnl
`ifdef(`w_symmetric_crossrefs',`<Link linkend="$1.rev">$2</Link>',`$2')')
define(`w_refer',
`ifdef(`w_symmetric_crossrefs',`<Anchor id="$1.rev"/>')'dnl
`<Link linkend="$1">$2</Link>')
}}}

Tables.

{{{
define(`w_make_tablespec',
`ifelse(`$*',,,`<ColSpec align="'dnl
`ifelse(`$1',p,justify,`$1',l,left,`$1',r,right,`$1',c,center)"/>'dnl
`w_make_tablespec(shift($@))')')
w_define_env(w_table,
`pushdef(`w_caption', `<Caption>$1</Caption>')'dnl
`w_close<InformalTable><TGroup cols="$#">w_make_tablespec($@)w_nl<TBody>',
`w_close</TBody></TGroup>popdef(`w_caption')</InformalTable>w_softopen`'')
w_define_env(w_row, `w_close<Row>', `w_close</Row>')
w_define_env(w_cell, `w_close<Entry>', `w_close</Entry>')
define(`w_table_rule',) dnl TODO?
}}}

Admonitions.

{{{
w_define_env(`admonition',
`w_close`'ifelse(w_standard_admonition(`$1'),t,`<`$1'>',`<Note>`$1':')w_open',
`w_close`'ifelse(w_standard_admonition(`$1'),t,`</`$1'>',`</Note>')w_softopen')
define(`w_standard_admonition',
`ifelse(index(`Note,Tip,Caution,Warning,Important',`$1'),-1,,t)')
}}}

Special and quoted characters.

{{{
define(`w_lt', `&lt;')
define(`w_gt', `&gt;')
define(`w_amp', `&amp;')
define(`w_emdash', `&mdash;')
define(`w_endash', `&ndash;')
define(`w_ellipsis', `&hellip;')
define(`w_copyrightsign', `&copy;')
define(`w_trademarksign', `&trade;')
define(`w_larrow', `&larr;')
define(`w_rarrow', `&rarr;')
}}}