diff options
Diffstat (limited to 'doc/mallard/C')
75 files changed, 0 insertions, 9151 deletions
diff --git a/doc/mallard/C/Makefile.am b/doc/mallard/C/Makefile.am deleted file mode 100644 index d238901..0000000 --- a/doc/mallard/C/Makefile.am +++ /dev/null @@ -1,72 +0,0 @@ -SUBDIRS = figures - -EXTRA_DIST = \ - details.page \ - explore.page \ - i18n.page \ - index.page \ - its.page \ - l10n.page \ - legal.xml \ - links.page \ - mal_attr_link.page \ - mal_block_cite.page \ - mal_block_code.page \ - mal_block_comment.page \ - mal_block_desc.page \ - mal_block_example.page \ - mal_block_figure.page \ - mal_block_listing.page \ - mal_block_list.page \ - mal_block_media.page \ - mal_block_note.page \ - mal_block.page \ - mal_block_p.page \ - mal_block_quote.page \ - mal_block_screen.page \ - mal_block_steps.page \ - mal_block_subtitle.page \ - mal_block_synopsis.page \ - mal_block_terms.page \ - mal_block_title.page \ - mal_block_tree.page \ - mal_external.page \ - mal_info_copyright.page \ - mal_info_credit.page \ - mal_info_desc.page \ - mal_info_license.page \ - mal_info_link.page \ - mal_info.page \ - mal_info_revision.page \ - mal_info_title.page \ - mal_inline_app.page \ - mal_inline_cmd.page \ - mal_inline_code.page \ - mal_inline_em.page \ - mal_inline_file.page \ - mal_inline_gui.page \ - mal_inline_guiseq.page \ - mal_inline_input.page \ - mal_inline_key.page \ - mal_inline_keyseq.page \ - mal_inline_link.page \ - mal_inline_media.page \ - mal_inline_output.page \ - mal_inline.page \ - mal_inline_span.page \ - mal_inline_sys.page \ - mal_inline_var.page \ - mal_page.page \ - mal_section.page \ - mal_table_col.page \ - mal_table.page \ - mal_table_td.page \ - mal_table_tr.page \ - mal_TODO.page \ - principle-guide.page \ - principle-justenough.page \ - principle-redundancy.page \ - principles.page \ - spec.page \ - tenminutes.page -
\ No newline at end of file diff --git a/doc/mallard/C/TODO b/doc/mallard/C/TODO deleted file mode 100644 index 49458f7..0000000 --- a/doc/mallard/C/TODO +++ /dev/null @@ -1,21 +0,0 @@ -intro text: -- what it is -- what it isn't -- in what elements it's used -- what content is valid, if simple - -sections: -- content: Content -- attributes: Attributes -- examples: Examples -- best: Best Practices -- design: Design Notes -- processing: Processing Expectations -- html: Comparison to HTML -- docbook: Comparison to DocBook - -display environments: -- rich display -- terminal -- print -- aural diff --git a/doc/mallard/C/details.page b/doc/mallard/C/details.page deleted file mode 100644 index f332193..0000000 --- a/doc/mallard/C/details.page +++ /dev/null @@ -1,34 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="guide" - id="details"> - -<info> - <revision version="0.1" date="2007-02-21" status="stub"/> - - <credit type="author"> - <name>Shaun McCance</name> - <email>shaunm@gnome.org</email> - <years>2008</years> - </credit> - - <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" /> - - <desc>How to process and work with Mallard documents.</desc> -</info> - -<title>Processing Details</title> - -<comment> - <cite date="2009-05-28">shaunm</cite> - <p>Add content</p> -</comment> - -<section id="i18n"> - <title>Internationalization and Localization</title> -</section> - -<section id="misc"> - <title>Additional Reference Material</title> -</section> - -</page> diff --git a/doc/mallard/C/docbook.page b/doc/mallard/C/docbook.page deleted file mode 100644 index 0f25b32..0000000 --- a/doc/mallard/C/docbook.page +++ /dev/null @@ -1,1291 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="docbook"> - -<info> - <link type="guide" xref="details#misc"/> -</info> - -<title>DocBook Element Reference</title> - -<p>The following table lists all of the elements in DocBook and provides -recommendations for equivalent or similar functionality in Mallard, when -available.</p> - -<table rules="rowgroups cols" frame="all"> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/abbrev.html">abbrev</code></p></td> - <td><p>No equivalent in Mallard. Use plain text instead.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/abstract.html">abstract</code></p></td> - <td><p>No equivalent in Mallard. The <code xref="mal_block_synopsis">synopsis</code> element - may be appropriate in some cases.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/accel.html">accel</code></p></td> - <td><p>No equivalent in Mallard, as marking the accelerator in the help text - is not considered important.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/ackno.html">ackno</code></p></td> - <td><p>No equivalent in Mallard. Simply put acknowledgements in a regular - <link xref="mal_block_p">paragraph</link>.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/acronym.html">acronym</code></p></td> - <td><p>No equivalent in Mallard. Use plain text instead.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/action.html">action</code></p></td> - <td><p>No equivalent in Mallard. Use plain text instead.</p></td> - </tr></tbody> - <tbody> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/address.html">address</code></p></td> - <td rowspan="2"><p>No equivalent in Mallard. <link xref="mal_external">External - namespace elements</link> may provide this information for - <link xref="mal_info_credit">credits</link></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/affiliation.html">affiliation</code></p></td> - </tr> - </tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/alt.html">alt</code></p></td> - <td><p>No equivalent in Mallard, as Mallard does not currently support equations.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/anchor.html">anchor</code></p></td> - <td><p>Currently no equivalent in Mallard. Future versions may address this.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/answer.html">answer</code></p></td> - <td><p>Mallard does not currently have a structured environment for question - and answer sessions.</p></td> - </tr></tbody> - <tbody> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/appendix.html">appendix</code></p></td> - <td rowspan="2"><p>No direct equivalent in Mallard. Use the <code xref="mal_page">page</code> - and <code xref="mal_info">info</code> elements instead.</p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/appendixinfo.html">appendixinfo</code></p></td> - </tr> - </tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/application.html">application</code></p></td> - <td><p>Similar to the <code xref="mal_inline_app">app</code> element.</p></td> - </tr></tbody> - <tbody> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/area.html">area</code></p></td> - <td rowspan="3"><p>Mallard does not support callouts.</p></td> - </tr> - <tr><td><p><code href="http://www.docbook.org/tdg/en/html/areaset.html">areaset</code></p></td></tr> - <tr><td><p><code href="http://www.docbook.org/tdg/en/html/areaspec.html">areaspec</code></p></td></tr> - </tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/arg.html">arg</code></p></td> - <td><p>Mallard does not have a structured environment for command synopses.</p></td> - </tr></tbody> - <tbody> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/article.html">article</code></p></td> - <td rowspan="2"><p>No direct equivalent in Mallard. Use the <code xref="mal_page">page</code> - and <code xref="mal_info">info</code> elements instead.</p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/articleinfo.html">articleinfo</code></p></td> - </tr> - </tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/artpagenums.html">artpagenums</code></p></td> - <td><p>No equivalent in Mallard. <link xref="mal_external">External - namespace elements</link> may provide this information in - <code xref="mal_info">info</code> elements.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/attribution.html">attribution</code></p></td> - <td><p>Similar to the <code xref="mal_block_cite">cite</code> element.</p></td> - </tr></tbody> - <tbody> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/audiodata.html">audiodata</code></p></td> - <td rowspan="2"><p>See the <code xref="mal_block_media">media</code> element for details.</p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/audioobject.html">audioobject</code></p></td> - </tr> - </tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/author.html">author</code></p></td> - <td><p>Use the common <code xref="mal_info_credit">credit</code> element.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/authorblurb.html">authorblurb</code></p></td> - <td><p>No equivalent in Mallard. <link xref="mal_external">External - namespace elements</link> may provide this information for - <link xref="mal_info_credit">credits</link>.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/authorgroup.html">authorgroup</code></p></td> - <td><p>No equivalent in Mallard.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/authorinitials.html">authorinitials</code></p></td> - <td><p>No equivalent in Mallard. <link xref="mal_external">External - namespace elements</link> may provide this information for - <link xref="mal_info_credit">credits</link>.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/beginpage.html">beginpage</code></p></td> - <td><p>No equivalent in Mallard.</p></td> - </tr></tbody> - <tbody> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/bibliocoverage.html">bibliocoverage</code></p></td> - <td rowspan="14"><p>Mallard does not currently have a structured environment for bibliographies.</p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/bibliodiv.html">bibliodiv</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/biblioentry.html">biblioentry</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/bibliography.html">bibliography</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/bibliographyinfo.html">bibliographyinfo</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/biblioid.html">biblioid</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/bibliolist.html">bibliolist</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/bibliomisc.html">bibliomisc</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/bibliomixed.html">bibliomixed</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/bibliomset.html">bibliomset</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/biblioref.html">biblioref</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/bibliorelation.html">bibliorelation</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/biblioset.html">biblioset</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/bibliosource.html">bibliosource</code></p></td> - </tr> - </tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/blockinfo.html">blockinfo</code></p></td> - <td><p>No equivalent in Mallard. Future versions may add metadata holders for block elements - to record credits and licensing information for external resources.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/blockquote.html">blockquote</code></p></td> - <td><p>Similar to the block <code xref="mal_block_quote">quote</code> element.</p></td> - </tr></tbody> - <tbody> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/book.html">book</code></p></td> - <td rowspan="2"><p>No direct equivalent in Mallard. Use the <code xref="mal_page">page</code> - and <code xref="mal_info">info</code> elements instead.</p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/bookinfo.html">bookinfo</code></p></td> - </tr> - </tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/bridgehead.html">bridgehead</code></p></td> - <td><p>No equivalent in Mallard.</p></td> - </tr></tbody> - <tbody> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/callout.html">callout</code></p></td> - <td rowspan="2"><p>Mallard does not support callouts.</p></td> - </tr> - <tr><td><p><code href="http://www.docbook.org/tdg/en/html/calloutlist.html">calloutlist</code></p></td></tr> - </tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/caption.html">caption</code></p></td> - <td><p>No direct equivalent in Mallard. Use the <code xref="mal_block_desc">desc</code> - element in a <code xref="mal_block_figure">figure</code> element for a similar effect.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/caution.html">caution</code></p></td> - <td><p>Use the common <code xref="mal_block_note">note</code> element.</p></td> - </tr></tbody> - <tbody> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/chapter.html">chapter</code></p></td> - <td rowspan="2"><p>No direct equivalent in Mallard. Use the <code xref="mal_page">page</code> - and <code xref="mal_info">info</code> elements instead.</p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/chapterinfo.html">chapterinfo</code></p></td> - </tr> - </tbody> - <tbody> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/citation.html">citation</code></p></td> - <td rowspan="2"><p>Mallard does not currently have a structured environment for bibliographies.</p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/citebiblioid.html">citebiblioid</code></p></td> - </tr> - </tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/citerefentry.html">citerefentry</code></p></td> - <td><p>Mallard does not currently have a structured environment for reference pages.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/citetitle.html">citetitle</code></p></td> - <td><p>No equivalent in Mallard.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/city.html">city</code></p></td> - <td><p>No equivalent in Mallard. <link xref="mal_external">External - namespace elements</link> may provide this information for - <link xref="mal_info_credit">credits</link>.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/classname.html">classname</code></p></td> - <td><p>No specific element in Mallard. Use the inline <code xref="mal_inline_code">code</code> - element instead.</p></td> - </tr></tbody> - <tbody> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/classsynopsis.html">classsynopsis</code></p></td> - <td rowspan="3"><p>No direct equivalent in Mallard. Use the block <code xref="mal_block_code">code</code> - element instead, possibly inside a <code xref="mal_block_synopsis">synopsis</code> element.</p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/classsynopsisinfo.html">classsynopsisinfo</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/cmdsynopsis.html">cmdsynopsis</code></p></td> - </tr> - </tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/co.html">co</code></p></td> - <td><p>Mallard does not support callouts.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/code.html">code</code></p></td> - <td><p>Similar to the <code xref="mal_inline_code">code</code> element.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/col.html">col</code></p></td> - <td><p>Similar to the <code xref="mal_table_col">col</code> element.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/colgroup.html">colgroup</code></p></td> - <td><p>Similar to the <code xref="mal_table_col">colgroup</code> element.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/collab.html">collab</code></p></td> - <td><p>Use the common <code xref="mal_info_credit">credit</code> element.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/collab.html">collabname</code></p></td> - <td><p>Varies with use. The <code xref="mal_info_credit">name</code> element in - a <code xref="mal_info_credit">credit</code> element may be appropriate.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/colophon.html">colophon</code></p></td> - <td><p>No equivalent in Mallard.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/colophon.html">colspec</code></p></td> - <td><p>Mallard does not use the CALS table model.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/command.html">command</code></p></td> - <td><p>Similar to the <code xref="mal_inline_cmd">cmd</code> element.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/computeroutput.html">computeroutput</code></p></td> - <td><p>Similar to the <code xref="mal_inline_output">output</code> element.</p></td> - </tr></tbody> - <tbody> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/confdates.html">confdates</code></p></td> - <td rowspan="5"><p>No equivalent in Mallard. <link xref="mal_external">External - namespace elements</link> may provide this information in - <code xref="mal_info">info</code> elements.</p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/confgroup.html">confgroup</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/confnum.html">confnum</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/confsponsor.html">confsponsor</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/conftitle.html">conftitle</code></p></td> - </tr> - </tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/constant.html">constant</code></p></td> - <td><p>No specific element in Mallard. Use an inline <code xref="mal_inline_code">code</code> - or <code xref="mal_inline_sys">sys</code> element instead.</p></td> - </tr></tbody> - <tbody> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/constraint.html">constraint</code></p></td> - <td rowspan="2"><p>Mallard does not have structured EBNF productions.</p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/constraintdef.html">constraintdef</code></p></td> - </tr> - </tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/constructorsynopsis.html">constructorsynopsis</code></p></td> - <td><p>No specific element in Mallard. Use the block <code xref="mal_block_code">code</code> - element instead, possibly inside a <code xref="mal_block_synopsis">synopsis</code> element.</p></td> - </tr></tbody> - <tbody> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/contractnum.html">contractnum</code></p></td> - <td rowspan="2"><p>No equivalent in Mallard. <link xref="mal_external">External - namespace elements</link> may provide this information in - <code xref="mal_info">info</code> elements.</p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/contractsponsor.html">contractsponsor</code></p></td> - </tr> - </tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/contrib.html">contrib</code></p></td> - <td><p>No equivalent in Mallard. <link xref="mal_external">External namespace elements</link> - may provide this information in <code xref="mal_info">info</code> elements or for - <link xref="mal_info_credit">credits</link>.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/copyright.html">copyright</code></p></td> - <td rowspan="2"><p>Use the <code xref="mal_info_credit">credit</code> element to - record copyright information.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/coref.html">coref</code></p></td> - <td><p>Mallard does not support callouts.</p></td> - </tr></tbody> - <tbody> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/corpauthor.html">corpauthor</code></p></td> - <td rowspan="2"><p>Use the common <code xref="mal_info_credit">credit</code> element.</p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/corpcredit.html">corpcredit</code></p></td> - </tr> - </tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/corpname.html">corpname</code></p></td> - <td><p>Varies with use. The <code xref="mal_info_credit">name</code> element in - a <code xref="mal_info_credit">credit</code> element may be appropriate.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/country.html">country</code></p></td> - <td><p>No equivalent in Mallard. <link xref="mal_external">External - namespace elements</link> may provide this information for - <link xref="mal_info_credit">credits</link>.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/database.html">database</code></p></td> - <td><p>No specific element in Mallard. Use the inline <code xref="mal_inline_sys">sys</code> - element instead.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/date.html">date</code></p></td> - <td><p>Varies with use. For <link xref="mal_info_revision">revisions</link>, use the - <code>date</code> attribute. <link xref="mal_external">External namespace elements</link> - may provide this information in <code xref="mal_info">info</code> elements.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/dedication.html">dedication</code></p></td> - <td><p>No equivalent in Mallard.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/destructorsynopsis.html">destructorsynopsis</code></p></td> - <td><p>No specific element in Mallard. Use the block <code xref="mal_block_code">code</code> - element instead, possibly inside a <code xref="mal_block_synopsis">synopsis</code> element.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/edition.html">edition</code></p></td> - <td><p>No equivalent in Mallard. <link xref="mal_external">External namespace elements</link> - may provide this information in <code xref="mal_info">info</code> elements.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/editor.html">editor</code></p></td> - <td><p>Use the common <code xref="mal_info_credit">credit</code> element.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/email.html">email</code></p></td> - <td><p>Varies with use. Use the <code xref="mal_info_credit">name</code> element in - a <code xref="mal_info_credit">credit</code> element in an informational context. - Inline, use <code xref="mal_inline_sys">sys</code>.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/emphasis.html">emphasis</code></p></td> - <td><p>Similar to the <code xref="mal_inline_em">em</code> element.</p></td> - </tr></tbody> - <tbody> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/entry.html">entry</code></p></td> - <td rowspan="2"><p>Mallard does not use the CALS table model.</p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/entrytbl.html">entrytbl</code></p></td> - </tr> - </tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/envar.html">envar</code></p></td> - <td><p>No specific element in Mallard. Use the inline <code xref="mal_inline_sys">sys</code> - element instead.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/epigraph.html">epigrah</code></p></td> - <td><p>No direct equivalent in Mallard. Some processing tools may support the - <code>epigraph</code> style hint on the block <code xref="mal_block_quote">quote</code> - element.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/equation.html">equation</code></p></td> - <td><p>Currently no equivalent in Mallard. Future versions may address this.</p></td> - </tr></tbody> - <tbody> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/errorcode.html">errorcode</code></p></td> - <td rowspan="4"><p>No specific elements in Mallard. Use the inline - <code xref="mal_inline_sys">sys</code> element. For error text, the - <code xref="mal_inline_output">output</code> may be appropriate.</p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/errorname.html">errorname</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/errortext.html">errortext</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/errortype.html">errortype</code></p></td> - </tr> - </tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/example.html">example</code></p></td> - <td><p>Similar to the <code xref="mal_block_example">example</code> element, except - that examples in Mallard are not formal elements.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/exceptionname.html">exceptionname</code></p></td> - <td><p>No specific element in Mallard. Use the inline <code xref="mal_inline_code">code</code> - element instead.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/fax.html">fax</code></p></td> - <td><p>No equivalent in Mallard. <link xref="mal_external">External - namespace elements</link> may provide this information for - <link xref="mal_info_credit">credits</link>.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/fieldsynopsis.html">fieldsynopsis</code></p></td> - <td><p>No specific element in Mallard. Use the block <code xref="mal_block_code">code</code> - element instead, possibly inside a <code xref="mal_block_synopsis">synopsis</code> element.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/figure.html">figure</code></p></td> - <td><p>Similar to the <code xref="mal_block_figure">figure</code> element.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/filename.html">filename</code></p></td> - <td><p>Similar to the <code xref="mal_inline_file">file</code> element.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/firstname.html">firstname</code></p></td> - <td><p>No equivalent in Mallard. <link xref="mal_external">External - namespace elements</link> may provide this information for - <link xref="mal_info_credit">credits</link>.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/firstterm.html">firstterm</code></p></td> - <td><p>No specific element in Mallard. Use the <code xref="mal_inline_em">em</code> - element to emphasize the first usage of a term.</p></td> - </tr></tbody> - <tbody> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/footnote.html">footnote</code></p></td> - <td rowspan="2"><p>Mallard does not currently have support for footnotes. Future - versions may add annotations.</p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/footnoteref.html">footnoteref</code></p></td> - </tr> - </tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/foreignphrase.html">foreignphrase</code></p></td> - <td><p>No specific element in Mallard. If necessary, use the - <code xref="mal_inline_em">em</code> element to emphasize a foreign phrase.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/formalpara.html">formalpara</code></p></td> - <td><p>No equivalent in Mallard.</p></td> - </tr></tbody> - <tbody> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/funcdef.html">funcdef</code></p></td> - <td rowspan="5"><p>No direct equivalent in Mallard. Use the block <code xref="mal_block_code">code</code> - element instead, possibly inside a <code xref="mal_block_synopsis">synopsis</code> element.</p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/funcparams.html">funcparams</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/funcprototype.html">funcprototype</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/funcsynopsis.html">funcsynopsis</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/funcsynopsisinfo.html">funcsynopsisinfo</code></p></td> - </tr> - </tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/function.html">function</code></p></td> - <td><p>No specific element in Mallard. Use the inline <code xref="mal_inline_code">code</code> - element instead.</p></td> - </tr></tbody> - <tbody> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/glossary.html">glossary</code></p></td> - <td rowspan="2"><p>No direct equivalent in Mallard. Use the <code xref="mal_page">page</code> - and <code xref="mal_info">info</code> elements instead. Future versions may address - glossaries directly.</p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/glossaryinfo.html">glossaryinfo</code></p></td> - </tr> - </tbody> - <tbody> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/glossdef.html">glossdef</code></p></td> - <td rowspan="7"><p>Mallard does not currently have a structured environment for glossaries. - Use the <code xref="mal_block_terms">terms</code> element instead. Future versions may - address glossaries directly.</p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/glossdiv.html">glossdiv</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/glossentry.html">glossentry</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/glosslist.html">glosslist</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/glosssee.html">glosssee</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/glossseealso.html">glossseealso</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/glossterm.html">glossterm</code></p></td> - </tr> - </tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/graphic.html">graphic</code></p></td> - <td><p>See the <code xref="mal_block_media">media</code> element for details.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/graphicco.html">graphicco</code></p></td> - <td><p>Mallard does not support callouts.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/group.html">group</code></p></td> - <td><p>Mallard does not have a structured environment for command synopses.</p></td> - </tr></tbody> - <tbody> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/guibutton.html">guibutton</code></p></td> - <td rowspan="6"><p>Use the common <code xref="mal_inline_gui">gui</code> element.</p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/guiicon.html">guiicon</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/guilabel.html">guilabel</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/guimenu.html">guimenu</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/guimenuitem.html">guimenuitem</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/guisubmenu.html">guisubmenu</code></p></td> - </tr> - </tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/hardware.html">hardware</code></p></td> - <td><p>No specific element in Mallard. Use the inline <code xref="mal_inline_sys">sys</code> - element instead.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/highlights.html">highlights</code></p></td> - <td><p>Currently no equivalent in Mallard. Future versions may support marking the - introductory text of a topic.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/holder.html">holder</code></p></td> - <td><p>Use the <code xref="mal_info_name">name</code> element in a - <code xref="mal_info_credit">credit</code> element. Mallard records - copyright information in <code>credit</code> elements.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/honorific.html">honorific</code></p></td> - <td><p>No equivalent in Mallard. <link xref="mal_external">External - namespace elements</link> may provide this information for - <link xref="mal_info_credit">credits</link>.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/html-form.html">html:form</code></p></td> - <td><p>Mallard does not support forms.</p></td> - </tr></tbody> - <tbody> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/imagedata.html">imagedata</code></p></td> - <td rowspan="2"><p>See the <code xref="mal_block_media">media</code> element for details.</p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/imageobject.html">imageobject</code></p></td> - </tr> - </tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/imageobjectco.html">imageobjectco</code></p></td> - <td><p>Mallard does not support callouts.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/important.html">important</code></p></td> - <td><p>Use the common <code xref="mal_block_note">note</code> element.</p></td> - </tr></tbody> - <tbody> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/index.html">index</code></p></td> - <td rowspan="5"><p>Mallard does not currently have a structured environment for indexes.</p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/indexdiv.html">indexdiv</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/indexentry.html">indexentry</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/indexinfo.html">indexinfo</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/indexterm.html">indexterm</code></p></td> - </tr> - </tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/informalequation.html">informalequation</code></p></td> - <td><p>Currently no equivalent in Mallard. Future versions may address this.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/informalexample.html">informalexample</code></p></td> - <td><p>Similar to the <code xref="mal_block_example">example</code> element.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/informalfigure.html">informalfigure</code></p></td> - <td><p>Similar to the <code xref="mal_block_figure">figure</code> element.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/informaltable.html">informaltable</code></p></td> - <td><p>Similar to the <code xref="mal_table">table</code> element. Mallard - does not use the CALS table model.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/initializer.html">initializer</code></p></td> - <td><p>Mallard does not have a structured environment for field synopses.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/inlineequation.html">inlineequation</code></p></td> - <td><p>Currently no equivalent in Mallard. Future versions may address this.</p></td> - </tr></tbody> - <tbody> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/inlinegraphic.html">inlinegraphic</code></p></td> - <td rowspan="2"><p>See the inline <code xref="mal_inline_media">media</code> element for details.</p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/inlinemediaobject.html">inlinemediaobject</code></p></td> - </tr> - </tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/interface.html">interface</code></p></td> - <td><p>Use the common <code xref="mal_inline_gui">gui</code> element.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/interfacename.html">interfacename</code></p></td> - <td><p>No specific element in Mallard. Use the inline <code xref="mal_inline_code">code</code> - element instead.</p></td> - </tr></tbody> - <tbody> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/invpartnumber.html">invpartnumber</code></p></td> - <td rowspan="4"><p>No equivalent in Mallard. <link xref="mal_external">External namespace - elements</link> may provide this information in <code xref="mal_info">info</code> - elements.</p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/isbn.html">isbn</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/issn.html">issn</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/issuenum.html">issuenum</code></p></td> - </tr> - </tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/itemizedlist.html">itemizedlist</code></p></td> - <td><p>See the <code xref="mal_block_list">list</code> element for details.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/itermset.html">itermset</code></p></td> - <td><p>No equivalent in Mallard. <link xref="mal_external">External namespace - elements</link> may provide this information in <code xref="mal_info">info</code> - elements.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/jobtitle.html">jobtitle</code></p></td> - <td><p>No equivalent in Mallard. <link xref="mal_external">External - namespace elements</link> may provide this information for - <link xref="mal_info_credit">credits</link>.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/keycap.html">keycap</code></p></td> - <td><p>Similar to the <code xref="mal_inline_key">key</code> element.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/keycode.html">keycode</code></p></td> - <td><p>No specific element in Mallard. Use the inline <code xref="mal_inline_sys">sys</code> - element instead.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/keycombo.html">keycombo</code></p></td> - <td><p>Similar to the <code xref="mal_inline_keyseq">keyseq</code> element.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/keysym.html">keysym</code></p></td> - <td><p>No specific element in Mallard. Use the inline <code xref="mal_inline_sys">sys</code> - element instead.</p></td> - </tr></tbody> - <tbody> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/keyword.html">keyword</code></p></td> - <td rowspan="2"><p>No equivalent in Mallard. <link xref="mal_external">External namespace - elements</link> may provide this information in <code xref="mal_info">info</code> - elements.</p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/keywordset.html">keywordset</code></p></td> - </tr> - </tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/label.html">label</code></p></td> - <td><p>Mallard does not currently have a structured environment for question - and answer sessions.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/legalnotice.html">legalnotice</code></p></td> - <td><p>No general-purpose legal notice in Mallard. <link xref="mal_external">External - namespace elements</link> may provide this information in <code xref="mal_info">info</code> - elements. For license information, use the <code xref="mal_info_license">license</code> - element.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/lhs.html">lhs</code></p></td> - <td><p>Mallard does not have structured EBNF productions.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/lineage.html">lineage</code></p></td> - <td><p>No equivalent in Mallard. <link xref="mal_external">External - namespace elements</link> may provide this information for - <link xref="mal_info_credit">credits</link>.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/lineannotation.html">lineannotation</code></p></td> - <td><p>Currently no equivalent in Mallard. You may use <link xref="mal_inline_em">inline - emphasis</link> for a similar effect.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/link.html">link</code></p></td> - <td><p>See the <code xref="mal_inline_link">link</code> element for details.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/listitem.html">listitem</code></p></td> - <td><p>See the <code>item</code> element for each <link xref="mal_block#list">list - element</link> for details.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/literal.html">literal</code></p></td> - <td><p>No specific element in Mallard. Use an inline <code xref="mal_inline_code">code</code> - or <code xref="mal_inline_sys">sys</code> element instead.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/literallayout.html">literallayout</code></p></td> - <td><p>Currently no general-purpose literal layout in Mallard. Future versions may address this.</p></td> - </tr></tbody> - <tbody> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/lot.html">lot</code></p></td> - <td rowspan="2"><p>No equivalent in Mallard.</p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/lotentry.html">lotentry</code></p></td> - </tr> - </tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/manvolnum.html">manvolnum</code></p></td> - <td><p>Mallard does not currently have a structured environment for reference pages.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/markup.html">markup</code></p></td> - <td><p>No specific element in Mallard. Use the inline <code xref="mal_inline_code">code</code> - element instead.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/markup.html">mathprase</code></p></td> - <td><p>Currently no equivalent in Mallard. Future versions may address this.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/medialabel.html">medialabel</code></p></td> - <td><p>No equivalent in Mallard. Use plain text instead.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/mediaobject.html">mediaobject</code></p></td> - <td><p>See the <code xref="mal_block_media">media</code> element for details.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/mediaobjectco.html">mediaobjectco</code></p></td> - <td><p>Mallard does not support callouts.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/member.html">member</code></p></td> - <td><p>No equivalent in Mallard to DocBook's - <code href="http://www.docbook.org/tdg/en/html/simplelist.html">simplelist</code> - element.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/menuchoice.html">menuchoice</code></p></td> - <td><p>Similar to the <code xref="mal_inline_guiseq">guiseq</code> element.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/methodname.html">methodname</code></p></td> - <td><p>No specific element in Mallard. Use the inline <code xref="mal_inline_code">code</code> - element instead.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/methodparam.html">methodparam</code></p></td> - <td><p>Mallard does not have a structured environment for method synopses.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/methodsynopsis.html">methodsynopsis</code></p></td> - <td><p>No specific element in Mallard. Use the block <code xref="mal_block_code">code</code> - element instead, possibly inside a <code xref="mal_block_synopsis">synopsis</code> element.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/mml-math.html">mml:math</code></p></td> - <td><p>Currently no equivalent in Mallard. Future versions may address this.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/modespec.html">modespec</code></p></td> - <td><p>No equivalent in Mallard.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/modifier.html">modifier</code></p></td> - <td><p>Mallard does not have a structured environment for code synopses.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/mousebutton.html">mousebutton</code></p></td> - <td><p>No equivalent in Mallard. Use plain text instead.</p></td> - </tr></tbody> - <tbody> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/msg.html">msg</code></p></td> - <td rowspan="12"><p>Mallard does not have a structured environment for messages.</p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/msgaud.html">msgaud</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/msgentry.html">msgentry</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/msgexplan.html">msgexplan</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/msginfo.html">msginfo</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/msglevel.html">msglevel</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/msgmain.html">msgmain</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/msgorig.html">msgorig</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/msgrel.html">msgrel</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/msgset.html">msgset</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/msgsub.html">msgsub</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/msgtext.html">msgtext</code></p></td> - </tr> - </tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/nonterminal.html">nonterminal</code></p></td> - <td><p>Mallard does not have structured EBNF productions.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/note.html">note</code></p></td> - <td><p>Use the common <code xref="mal_block_note">note</code> element.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/objectinfo.html">objectinfo</code></p></td> - <td><p>No equivalent in Mallard. Future versions may add metadata holders for block elements - to record credits and licensing information for external resources.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/olink.html">olink</code></p></td> - <td><p>See the <code xref="mal_inline_link">link</code> element for details.</p></td> - </tr></tbody> - <tbody> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/ooclass.html">ooclass</code></p></td> - <td rowspan="3"><p>Mallard does not have a structured environment for code synopses.</p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/ooexception.html">ooexception</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/oointerface.html">oointerface</code></p></td> - </tr> - </tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/option.html">option</code></p></td> - <td><p>No specific element in Mallard. Use the <code xref="mal_inline_cmd">cmd</code> - element instead.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/optional.html">optional</code></p></td> - <td><p>No equivalent in Mallard.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/orderedlist.html">orderedlist</code></p></td> - <td><p>See the <code xref="mal_block_list">list</code> element for details. See - also the <code xref="mal_block_steps">steps</code> element.</p></td> - </tr></tbody> - <tbody> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/orgdiv.html">orgdiv</code></p></td> - <td rowspan="3"><p>No equivalent in Mallard. <link xref="mal_external">External - namespace elements</link> may provide this information for - <link xref="mal_info_credit">credits</link>.</p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/orgname.html">orgname</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/otheraddr.html">otheraddr</code></p></td> - </tr> - </tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/othercredit.html">othercredit</code></p></td> - <td><p>Use the common <code xref="mal_info_credit">credit</code> element.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/othername.html">othername</code></p></td> - <td><p>No equivalent in Mallard. <link xref="mal_external">External - namespace elements</link> may provide this information for - <link xref="mal_info_credit">credits</link>.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/package.html">package</code></p></td> - <td><p>No specific element in Mallard. Use the inline <code xref="mal_inline_sys">sys</code> - element instead.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/pagenums.html">pagenums</code></p></td> - <td><p>Mallard does not currently have a structured environment for bibliographies.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/para.html">para</code></p></td> - <td><p>Similar to the <code xref="mal_block_p">p</code> element.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/paramdef.html">paramdef</code></p></td> - <td><p>Mallard does not have a structured environment for function prototypes.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/parameter.html">parameter</code></p></td> - <td><p>No specific element in Mallard. Use the inline <code xref="mal_inline_code">code</code> - element instead.</p></td> - </tr></tbody> - <tbody> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/part.html">part</code></p></td> - <td rowspan="2"><p>No direct equivalent in Mallard. Use the <code xref="mal_page">page</code> - and <code xref="mal_info">info</code> elements instead.</p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/partinfo.html">partinfo</code></p></td> - </tr> - </tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/partintro.html">partintro</code></p></td> - <td><p>No direct equivalent in Mallard. The <code xref="mal_page">page</code> or - <code xref="mal_section">section</code> element may be appropriate.</p></td> - </tr></tbody> - <tbody> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/personblurb.html">personblurb</code></p></td> - <td rowspan="3"><p>No equivalent in Mallard. <link xref="mal_external">External - namespace elements</link> may provide this information for - <link xref="mal_info_credit">credits</link>.</p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/personname.html">personname</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/phone.html">phone</code></p></td> - </tr> - </tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/partintro.html">partintro</code></p></td> - <td><p>Similar to the <code xref="mal_inline_span">span</code> element.</p></td> - </tr></tbody> - <tbody> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/pob.html">pob</code></p></td> - <td rowspan="2"><p>No equivalent in Mallard. <link xref="mal_external">External - namespace elements</link> may provide this information for - <link xref="mal_info_credit">credits</link>.</p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/postcode.html">postcode</code></p></td> - </tr> - </tbody> - <tbody> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/preface.html">preface</code></p></td> - <td rowspan="2"><p>No direct equivalent in Mallard. Use the <code xref="mal_page">page</code> - and <code xref="mal_info">info</code> elements instead.</p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/prefaceinfo.html">prefaceinfo</code></p></td> - </tr> - </tbody> - <tbody> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/primary.html">primary</code></p></td> - <td rowspan="2"><p>Mallard does not currently have a structured environment for indexes.</p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/primaryie.html">primaryie</code></p></td> - </tr> - </tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/printhistory.html">printhistory</code></p></td> - <td><p>No equivalent in Mallard. <link xref="mal_external">External - namespace elements</link> may provide this information in - <code xref="mal_info">info</code> elements.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/procedure.html">procedure</code></p></td> - <td><p>See the <code xref="mal_block_steps">steps</code> element for details.</p></td> - </tr></tbody> - <tbody> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/production.html">production</code></p></td> - <td rowspan="3"><p>Mallard does not have structured EBNF productions.</p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/productionrecap.html">productionrecap</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/productionset.html">productionset</code></p></td> - </tr> - </tbody> - <tbody> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/productname.html">productname</code></p></td> - <td rowspan="2"><p>No equivalent in Mallard. Inline, use plain text. - <link xref="mal_external">External namespace elements</link> may provide this information - in <code xref="mal_info">info</code> elements.</p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/productnumber.html">productnumber</code></p></td> - </tr> - </tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/programlisting.html">programlisting</code></p></td> - <td><p>Similar to the block <code xref="mal_block_code">code</code> element.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/programlistingco.html">programlistingco</code></p></td> - <td><p>Mallard does not support callouts.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/prompt.html">prompt</code></p></td> - <td><p>No specific element in Mallard. Use the inline <code xref="mal_inline_output">outut</code> - element instead.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/property.html">property</code></p></td> - <td><p>No specific element in Mallard. Use the inline <code xref="mal_inline_sys">sys</code> - element instead.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/pubdate.html">pubdate</code></p></td> - <td><p>No equivalent in Mallard. <link xref="mal_external">External - namespace elements</link> may provide this information in - <code xref="mal_info">info</code> elements.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/publisher.html">publisher</code></p></td> - <td><p>Use the common <code xref="mal_info_credit">credit</code> element.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/publishername.html">publishername</code></p></td> - <td><p>No equivalent in Mallard. <link xref="mal_external">External - namespace elements</link> may provide this information for - <link xref="mal_info_credit">credits</link>.</p></td> - </tr></tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/pubsnumber.html">pubsnumber</code></p></td> - <td><p>No equivalent in Mallard. <link xref="mal_external">External - namespace elements</link> may provide this information in - <code xref="mal_info">info</code> elements.</p></td> - </tr></tbody> - <tbody> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/qandadiv.html">qandadiv</code></p></td> - <td rowspan="4"><p>Mallard does not currently have a structured environment for question - and answer sessions.</p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/qandaentry.html">qandaentry</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/qandaset.html">qandaset</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/question.html">question</code></p></td> - </tr> - </tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/pubsnumber.html">pubsnumber</code></p></td> - <td><p>No equivalent in Mallard.</p></td> - </tr></tbody> - <tbody> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/refclass.html">refclass</code></p></td> - <td rowspan="22"><p>Mallard does not currently have a structured environment for reference pages.</p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/refdescriptor.html">refdescriptor</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/refentry.html">refentry</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/refentryinfo.html">refentryinfo</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/refentrytitle.html">refentrytitle</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/reference.html">reference</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/referenceinfo.html">referenceinfo</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/refmeta.html">refmeta</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/refmiscinfo.html">refmiscinfo</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/refname.html">refname</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/refnamediv.html">refnamediv</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/refpurpose.html">refpurpose</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/refsect1.html">refsect1</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/refsect1info.html">refsect1info</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/refsect2.html">refsect2</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/refsect2info.html">refsect2info</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/refsect3.html">refsect3</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/refsect3info.html">refsect3info</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/refsection.html">refsection</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/refsectioninfo.html">refsectioninfo</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/refsynopsisdiv.html">refsynopsisdiv</code></p></td> - </tr> - <tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/refsynopsisdivinfo.html">refsynopsisdivinfo</code></p></td> - </tr> - </tbody> - <tbody><tr> - <td><p><code href="http://www.docbook.org/tdg/en/html/releaseinfo.html">releaseinfo</code></p></td> - <td><p>No equivalent in Mallard. <link xref="mal_external">External - namespace elements</link> may provide this information in - <code xref="mal_info">info</code> elements.</p></td> - </tr></tbody> -</table> - -<comment> - <cite date="2009-06-17">shaunm</cite> - <p>This is a long list. Bear with me as I complete it.</p> -</comment> - -</page> diff --git a/doc/mallard/C/explore.page b/doc/mallard/C/explore.page deleted file mode 100644 index 2f2d5af..0000000 --- a/doc/mallard/C/explore.page +++ /dev/null @@ -1,27 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="guide" - id="explore"> - -<info> - <revision version="0.1" date="2007-02-21" status="stub"/> - - <credit type="author"> - <name>Shaun McCance</name> - <email>shaunm@gnome.org</email> - <years>2008-2009</years> - </credit> - - <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" /> - - <desc>Explore more of what Mallard has to offer.</desc> -</info> - -<title>Explore Mallard</title> - -<comment> - <cite date="2007-02-22">Shaun McCance</cite> - <p>Add content</p> -</comment> - - -</page> diff --git a/doc/mallard/C/figures/Makefile.am b/doc/mallard/C/figures/Makefile.am deleted file mode 100644 index aa2c155..0000000 --- a/doc/mallard/C/figures/Makefile.am +++ /dev/null @@ -1 +0,0 @@ -EXTRA_DIST = mallard.png diff --git a/doc/mallard/C/figures/mallard.png b/doc/mallard/C/figures/mallard.png Binary files differdeleted file mode 100644 index 0ed0645..0000000 --- a/doc/mallard/C/figures/mallard.png +++ /dev/null diff --git a/doc/mallard/C/i18n.page b/doc/mallard/C/i18n.page deleted file mode 100644 index 7e4bb54..0000000 --- a/doc/mallard/C/i18n.page +++ /dev/null @@ -1,19 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="i18n"> - -<info> - <link type="guide" xref="details#i18n"/> - - <revision version="0.1" date="2009-05-26" status="stub"/> - - <credit type="author"> - <name>Shaun McCance</name> - <email>shaunm@gnome.org</email> - <years>2009</years> - </credit> -</info> - -<title>Internationalization Notes</title> - -</page> diff --git a/doc/mallard/C/index.page b/doc/mallard/C/index.page deleted file mode 100644 index 12f0c13..0000000 --- a/doc/mallard/C/index.page +++ /dev/null @@ -1,30 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="guide" - id="index"> - -<info> - <link type="topic" xref="tenminutes"/> - <link type="topic" xref="explore"/> - <link type="topic" xref="details"/> - <link type="topic" xref="principles"/> - <link type="topic" xref="spec"/> - - <revision version="0.1" date="2007-02-22" status="stub"/> - - <credit type="author"> - <name>Shaun McCance</name> - <email>shaunm@gnome.org</email> - <years>2007</years> - </credit> - - <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" /> -</info> - -<title>Mallard</title> - -<comment> - <cite date="2007-02-20">Shaun McCance</cite> - <p>Add some intro text</p> -</comment> - -</page> diff --git a/doc/mallard/C/its.page b/doc/mallard/C/its.page deleted file mode 100644 index cb2d7b6..0000000 --- a/doc/mallard/C/its.page +++ /dev/null @@ -1,356 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="its"> - -<info> - <link type="guide" xref="details#i18n"/> - - <revision version="0.1" date="2009-05-27" status="review"/> - - <credit type="author"> - <name>Shaun McCance</name> - <email>shaunm@gnome.org</email> - <years>2009</years> - </credit> - - <desc>Conformance to the W3C Internationalization and Localization - Markup Requirements.</desc> -</info> - -<title>ITS Conformance</title> - -<p>This page discusses Mallard's conformance to the requirements in the -<link href="http://www.w3.org/TR/itsreq/">W3C Internationalization and -Localization Markup Requirements</link>, as well as its usage of attributes -and elements from the <link href="http://www.w3.org/TR/its/">W3C -Internationalization Tag Set</link>.</p> - -<note><p>As of the time of this writing, there are 26 requirements, though not -all of them are complete. This page discusses a selection of the requirements. -Future versions may discuss more requirements.</p></note> - -<section id="R002"> - <title>R002: Span-Like Element</title> - - <quote> - <cite href="http://www.w3.org/TR/itsreq/#span">W3C - Internationalization and Localization Markup Requirements</cite> - <p>[R002] span-like element is required to allow authors to mark sections - text that may have special properties, from a localization and - internationalization point of view.</p> - </quote> - - <p>Mallard provides the <code xref="mal_inline_span">span</code> element, - a general-purpose span-like element. The <code>span</code> element accepts - attributes from external namespaces, allowing attributes such as - <code>xml:lang</code> and - <code href="http://www.w3.org/TR/its/#trans-datacat">its:translate</code> - to be used in Mallard documents.</p> -</section> - -<section id="R004"> - <title>R004: Unique Identifier</title> - - <quote> - <cite href="http://www.w3.org/TR/itsreq/#uid">W3C - Internationalization and Localization Markup Requirements</cite> - <p>[R004] It should be possible to attach a unique identifier to any - localizable item. This identifier should be unique within a document set, - but should be identical across all translations of the same item.</p> - </quote> - - <p>While the <code>id</code> attribute is only allowed on - <code xref="mal_page">page</code> and <code xref="mal_section">section</code> - elements, Mallard does allow attributes from external namespaces to be used - on all elements. If necessary for translation purposes, any attribute from - an external namespace may be used as a unique identifier. In particular, - Mallard does not use the common <code>xml:id</code> for page and section - IDs, but it may be used on any element to provide a unique identifier for - translation or any other purposes.</p> -</section> - -<section id="R006"> - <title>R006: Identifying Language/Locale</title> - - <quote> - <cite href="http://www.w3.org/TR/itsreq/#langlocale">W3C - Internationalization and Localization Markup Requirements</cite> - <p>[R006] Any document at its beginning should declare a language/locale - that is applied to both main content and external content stored separately. - While the language/locale may be declared for the whole document, when an - element or a text span is in a different language/locale from the - document-level language, it should be labeled appropriately. Therefore, - DTD/Schema should allow any elements to have a language/locale specifying - attribute. The language/locale declaration should use industry standard - approaches.</p> - </quote> - - <p>Mallard allows the standard <code>xml:lang</code> attribute to be used - on all elements.</p> - - <p>Note that there are two different methods of identifying language and locale - information that are likely to be encountered by those working with Mallard. - Since Mallard is an XML format, language identifiers are expected to conform - to <link href="http://tools.ietf.org/html/rfc3066">IETF RFC 3066</link>. - Since Mallard is designed to be used in a desktop help system, - <link href="http://en.wikipedia.org/wiki/Locale">POSIX locale identifiers</link> - are more convenient. This is a potentially serious interchange issue, and this - document currently offers no solutions to this problem.</p> -</section> - -<section id="R007"> - <title>R007: Identifying Terms</title> - - <quote> - <cite href="http://www.w3.org/TR/itsreq/#termid">W3C - Internationalization and Localization Markup Requirements</cite> - <p>[R007] It should be possible to identify terms inside an element or a - span and to provide data for terminology management and index generation. - Terms should be either associated with attributes for related term - information or linked to external terminology data.</p> - </quote> - - <p>Mallard does not currently provide a means of marking up terms and - definitions. When necessary for translation purposes, the - <link href="http://www.w3.org/TR/its/#terminology"><code>its:term</code> - and <code>its:termInfoRef</code></link> attributes may be used on any - elements to indicate such a relationship.</p> -</section> - -<section id="R008"> - <title>R008: Purpose Specification/Mapping</title> - - <quote> - <cite href="http://www.w3.org/TR/itsreq/#mapping">W3C - Internationalization and Localization Markup Requirements</cite> - <p>[R008] Currently, it does not appear to be realistic that all XML - vocabularies tag localization-relevant information identical (e.g. all - use the "term" tag for terms). One way to take care of diverse - localization-relevant markup in localization environments is a mapping - mechanism which maps localization-relevant markup onto a canonical - representation (such as the Internationalization Tag Set).</p> - </quote> - - <p>Any purpose mapping that can be encoded using the - <code href="http://www.w3.org/TR/its/#basic-concepts-selection-global">its:rules</code> - element can be included in a Mallard document. The <code>its:rules</code> element - may be used in any <code xref="mal_info">info</code> element. See also - <link href="http://www.w3.org/TR/its/#associating-its-with-existing-markup">Associating - ITS Data Categories with Existing Markup</link>.</p> -</section> - -<section id="R011"> - <title>R011: Bidirectional Text Support</title> - - <quote> - <cite href="http://www.w3.org/TR/itsreq/#bidi">W3C - Internationalization and Localization Markup Requirements</cite> - <p>[R011] Markup should be available to support the needs of bidirectional - scripts.</p> - </quote> - - <p>Mallard allows attributes from external namespaces to be used on all - elements. Consequently, the - <code href="http://www.w3.org/TR/its/#directionality">its:dir</code> - attribute may be used to specify text directionality.</p> -</section> - -<section id="R012"> - <title>R012: Indicator of Translatability</title> - - <quote> - <cite href="http://www.w3.org/TR/itsreq/#transinfo">W3C - Internationalization and Localization Markup Requirements</cite> - <p>[R012] Methods must exist to allow to specify the parts of a document - that are to be translated or not.</p> - </quote> - - <p>Mallard allows attributes from external namespaces to be used on all - elements. Consequently, the - <code href="http://www.w3.org/TR/its/#trans-datacat">its:translate</code> - attribute may be used to specify whether parts of a document are to be - translated.</p> - - <p>Additionally, the - <code href="http://www.w3.org/TR/its/#basic-concepts-selection-global">its:rules</code> - element may be used in any <code xref="mal_info">info</code> element to - provide translatability rules for a page or section.</p> -</section> - -<section id="R014"> - <title>R014: Limited Impact</title> - - <quote> - <cite href="http://www.w3.org/TR/itsreq/#impact">W3C - Internationalization and Localization Markup Requirements</cite> - <p>[R014] All solutions proposed should be designed to have as less impact - as possible on the tree structure of the original document and on the - content models in the original schema.</p> - </quote> - - <p>Mallard allows tool-specific extensibility using attributes and elements - from external namespaces. Mallard has - <link xref="mal_external">clearly defined rules</link> for how attributes - and elements from external namespaces are to be processed in various contexts. - Tools writers are expected to be aware of these issues. Whenever possible, - this document issues that can arise from extensions, including those for - translation purposes.</p> - - <p>While it is impossible to predict all issues one might encounter, Mallard - was developed after years of developing translation tools for other formats. - Internationalization and localization were primary concerns in the design - of Mallard.</p> -</section> - -<section id="R015"> - <title>R015: Attributes and Translatable Text</title> - - <quote> - <cite href="http://www.w3.org/TR/itsreq/#transattr">W3C - Internationalization and Localization Markup Requirements</cite> - <p>[R015] Provisions must be taken to ensure that attributes with - translatable values do not impair the localization process.</p> - </quote> - - <p>Mallard never places translatable text in attribute values.</p> -</section> - -<section id="R017"> - <title>R017: Localization Notes</title> - - <quote> - <cite href="http://www.w3.org/TR/itsreq/#locnotes">W3C - Internationalization and Localization Markup Requirements</cite> - <p>[R017] A method must exist for authors to communicate information to - localizers about a particular item of content.</p> - </quote> - - <p>Mallard allows attributes from external namespaces to be used on all - elements. Consequently, the - <code href="http://www.w3.org/TR/its/#trans-datacat">its:locNote</code> and - <code href="http://www.w3.org/TR/its/#trans-datacat">its:locNoteRule</code> - attributes may be used to provide localization notes.</p> - - <p>If more extensive localization notes are needed, the - <code xref="mal_block_comment">comment</code> element may be used. Using a - <code href="http://www.w3.org/TR/its/#basic-concepts-selection-global">its:rules</code> - element in an <code xref="mal_info">info</code> element, one can clearly - specify which editorial comments are localization notes.</p> -</section> - -<section id="R020"> - <title>R020: Annotation Markup</title> - - <quote> - <cite href="http://www.w3.org/TR/itsreq/#annomark">W3C - Internationalization and Localization Markup Requirements</cite> - <p>[R020] There must be a way to support markup up of text annotations of - the 'ruby' type.</p> - </quote> - - <p>All translatable content in Mallard is placed in element content, which - allows annotation markup to be used. Mallard never places translatable - content in attribute values. Note, however, that Mallard documents will - often be displayed by converting them to a format such as HTML. If the - display format places textual content in attribute values (such as the - <code>alt</code> attribute of the <code>img</code> tag in HTML), then - annotations could be lost in rendering.</p> - - <p>Elements from external namespaces may be used in all - <link xref="mal_inline">inline contexts</link>. While this allows Ruby - annotations to be embedded within a Mallard document, the - <link xref="mal_inline#processing">fallback processing expectations</link> - are unlikely to produce satisfactory results for tools that do not support - Ruby. Future versions of this document should address this issue.</p> -</section> - -<section id="R022"> - <title>R022: Nested Elements</title> - - <quote> - <cite href="http://www.w3.org/TR/itsreq/#nestedelems">W3C - Internationalization and Localization Markup Requirements</cite> - <p>[R022] Great care must be taken when defining or using nested - translatable elements.</p> - </quote> - - <p>Mallard explicitly disallows mixing block and inline content, - except in well-defined cases which can easily be detected and - handled. In Mallard, any block element which can contain text - directly is considered to be a translation unit. Since these - elements do not allow general block content to be mixed into - the inline content, translation units can always be presented - to translators without the need for placeholders.</p> - - <p>Note that this may not be the case if a translation tool chooses - to treat certain container elements as translation units. For example, - under some circumstances a translation tool might choose to present - <link xref="mal_table">tables</link> or - <link xref="mal_block_list">lists</link> as translatable to allow - translators to reorder the rows or items. In these cases, the block - content inside the entries or items would still constitute discrete - units of translations, making placeholders necessary.</p> -</section> - -<section id="R025"> - <title>R025: Elements and Segmentation</title> - - <quote> - <cite href="http://www.w3.org/TR/itsreq/#elemseg">W3C - Internationalization and Localization Markup Requirements</cite> - <p>[R025] Methods, independent of the semantic, of the elements must - exist to provide hints on how to break down document content into - meaningful runs of text.</p> - </quote> - - <p>Making meaningful distinctions is ultimately the job of a processing - tool, although the design of an XML vocabulary can have a significant - impact on implementation difficulty. The following notes will be relevant - to most tool implementors.</p> - - <list> - <item> - <p>In Mallard, the content of any element, taken in context, is unambiguously - <link xref="mal_inline">general inline content</link>, - <link xref="mal_block">general block content</link>, or some particular - type of structured content. It is never the case that processing tools - must probe the contents to determine the content model.</p> - <p>Note that, since some element names are used in both block and inline - contexts, such ambiguous content models would be particularly problematic - for Mallard. Ambiguous content models could lead to situations where it - is not possible to determine the function of an element such as - <code>code</code>. Thus, ambiguous content models are explicitly avoided. - This makes most processing tasks simpler.</p> - </item> - - <item> - <p>In Mallard, elements generally contain either block content or - inline content. Thus, for example, you cannot place a paragraph - inside a paragraph. This is simpler for translators, as well as - for translation tool implementors, because it reduces the need - to use placeholders for separate translation units.</p> - </item> - - <item> - <p>One notable exception to the above is the <code>item</code> - element in <link xref="mal_block_tree">tree lists</link>. To - simplify writing, tree list items simply take inline content - followed by any number of nested tree list items. Since the - block-like items are not interspersed with the inline content, - however, translation tools should be able to handle this case - without placeholders.</p> - </item> - - <item> - <p>It is noteworthy that Mallard reuses some element names in both block - and inline contexts. The <code xref="mal_block_code">code</code> and - <code xref="mal_block_media">media</code> elements are two examples of - this. Since Mallard never allows general block content to be mixed with - general inline content, the purpose of these elements is unambiguous when - processed in context. Thus, it is important that tools always process - elements in context to handle them correctly.</p> - </item> - </list> -</section> - -</page> diff --git a/doc/mallard/C/l10n.page b/doc/mallard/C/l10n.page deleted file mode 100644 index 3d5150a..0000000 --- a/doc/mallard/C/l10n.page +++ /dev/null @@ -1,19 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="l10n"> - -<info> - <link type="guide" xref="details#i18n"/> - - <revision version="0.1" date="2009-05-26" status="stub"/> - - <credit type="author"> - <name>Shaun McCance</name> - <email>shaunm@gnome.org</email> - <years>2009</years> - </credit> -</info> - -<title>Translation Notes</title> - -</page> diff --git a/doc/mallard/C/legal.xml b/doc/mallard/C/legal.xml deleted file mode 100644 index 6f643be..0000000 --- a/doc/mallard/C/legal.xml +++ /dev/null @@ -1,9 +0,0 @@ -<license xmlns="http://projectmallard.org/1.0/" - href="http://creativecommons.org/licenses/by-sa/3.0/us/"> -<p>This work is licensed under a -<link href="http://creativecommons.org/licenses/by-sa/3.0/us/">Creative Commons -Attribution-Share Alike 3.0 United States License</link>.</p> -<p>As a special exception, the copyright holders give you permission to copy, -modify, and distribute the example code contained in this document under the -terms of your choosing, without restriction.</p> -</license> diff --git a/doc/mallard/C/links.page b/doc/mallard/C/links.page deleted file mode 100644 index 44716dd..0000000 --- a/doc/mallard/C/links.page +++ /dev/null @@ -1,40 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="links"> - -<info> - <link type="guide" xref="details"/> - <link type="seealso" xref="mal_page"/> - <link type="seealso" xref="mal_section"/> - - <revision version="0.1" date="2008-02-21" status="stub"/> - - <credit type="author"> - <name>Shaun McCance</name> - <email>shaunm@gnome.org</email> - <years>2009</years> - </credit> -</info> - -<title>Automatic Links</title> - - -<!-- BEGIN topic --> -<section id="topic"> - <title>Topic Links</title> -</section> -<!-- END topic --> - -<!-- BEGIN guide --> -<section id="guide"> - <title>Guide Links</title> -</section> -<!-- END guide --> - -<!-- BEGIN seealso --> -<section id="seealso"> - <title>See Also Links</title> -</section> -<!-- END seealso --> - -</page> diff --git a/doc/mallard/C/mal_TODO.page b/doc/mallard/C/mal_TODO.page deleted file mode 100644 index a90f023..0000000 --- a/doc/mallard/C/mal_TODO.page +++ /dev/null @@ -1,13 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="mal_TODO"> - -<info> -</info> - -<title>TODO</title> - -<synopsis><code mime="application/relax-ng-compact-syntax"> -</code></synopsis> - -</page> diff --git a/doc/mallard/C/mal_attr_link.page b/doc/mallard/C/mal_attr_link.page deleted file mode 100644 index 1c03d50..0000000 --- a/doc/mallard/C/mal_attr_link.page +++ /dev/null @@ -1,36 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="mal_attr_link"> - -<info> - <link type="seealso" xref="mal_inline"/> - - <credit type="author"> - <name>Shaun McCance</name> - <email>shaunm@gnome.org</email> - <years>2008</years> - </credit> - - <revision version="0.1" date="2008-02-19" status="incomplete"/> - - <desc>Link to other pages or documents directly from most inline elements.</desc> -</info> - -<title>Ubiquitous Linking</title> - -<synopsis><code mime="application/relax-ng-compact-syntax"> -mal_attr_link = - ( attribute xref { text } ? - | { attribute dref { text } ?, attribute href { text } ? } - ) -</code></synopsis> - -<comment> - <cite date="2006-11-16">Shaun McCance</cite> - <p>The content model is perhaps not as clearly expressed as it could be. - The <code>ref</code> attribute may need to be renamed. The idea is that - we can have a reference to a document within a help system, with a defined - fallback to something on the web with <code>href</code>.</p> -</comment> - -</page> diff --git a/doc/mallard/C/mal_block.page b/doc/mallard/C/mal_block.page deleted file mode 100644 index bc97c83..0000000 --- a/doc/mallard/C/mal_block.page +++ /dev/null @@ -1,182 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="guide" - id="mal_block"> - -<info> - <link type="guide" xref="spec"/> - - <revision version="0.1" date="2009-05-28" status="review"/> - - <credit type="author"> - <name>Shaun McCance</name> - <email>shaunm@gnome.org</email> - <years>2008-2009</years> - </credit> - - <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" /> - - <desc>Paragraphs, lists, tables, and various semantic elements for - building simple yet stunning pages.</desc> -</info> - -<title>Block Elements</title> - -<synopsis><code mime="application/relax-ng-compact-syntax"> -mal_block = ( - <link xref="#basic">mal_block_basic</link> | - <link xref="#formal">mal_block_formal</link> | - <link xref="#lists">mal_block_lists</link> | - <link xref="mal_table">mal_table</link> -) -</code></synopsis> - -<p>Block elements are the building blocks of pages. Mallard provides block -elements for most common needs in software documentation, from simple paragraphs -to example blocks to powerful tables. Pages and sections in Mallard are built -up of block elements, which in turn contain either further block elements or -inline content.</p> - -<p>Authors, editors, or other content producers sometimes need to supply -richer information in their documents. While this information may not -be conveyed by display tools, it may be used for various internal tracking -purposes. Mallard allows elements to be extended with attributes from -external namespaces. See <link xref="mal_external"/> for more -information.</p> - - -<!-- BEGIN basic --> -<section id="basic" style="2column"> - <info> - <title type="link">Basic Block Elements</title> - <link type="topic" xref="mal_block_code"/> - <link type="topic" xref="mal_block_example"/> - <link type="topic" xref="mal_block_media"/> - <link type="topic" xref="mal_block_p"/> - <link type="topic" xref="mal_block_screen"/> - </info> - <title>Basic Elements</title> - <synopsis><code mime="application/relax-ng-compact-syntax"> -mal_block_basic = ( - <link xref="mal_block_code">mal_block_code</link> | - <link xref="mal_block_example">mal_block_example</link> | - <link xref="mal_block_media">mal_block_media</link> | - <link xref="mal_block_p">mal_block_p</link> | - <link xref="mal_block_screen">mal_block_screen</link> -)</code></synopsis> - - <p>Basic block elements are elements that do not contain a title and which - have either general block content or <link xref="mal_inline">inline - content</link>. Using basic block elements, you can build up simple pages - which convey information clearly.</p> -</section> -<!-- END basic --> - - -<!-- BEGIN formal --> -<section id="formal" style="2column"> - <info> - <title type="link">Formal Block Elements</title> - <link type="topic" xref="mal_block_comment"/> - <link type="topic" xref="mal_block_figure"/> - <link type="topic" xref="mal_block_listing"/> - <link type="topic" xref="mal_block_note"/> - <link type="topic" xref="mal_block_quote"/> - <link type="topic" xref="mal_block_synopsis"/> - </info> - <title>Formal Elements</title> - <synopsis><code mime="application/relax-ng-compact-syntax"> -mal_block_formal = ( - <link xref="mal_block_comment">mal_block_comment</link> | - <link xref="mal_block_figure">mal_block_figure</link> | - <link xref="mal_block_listing">mal_block_listing</link> | - <link xref="mal_block_note">mal_block_note</link> | - <link xref="mal_block_quote">mal_block_quote</link> | - <link xref="mal_block_synopsis">mal_block_synopsis</link> -)</code></synopsis> - - <p>Formal block elements contain a <link xref="mal_block_title">title</link> - and general block content. Formal block elements allow you to provide - richer information in your pages.</p> -</section> -<!-- END formal --> - - -<!-- BEGIN lists --> -<section id="lists"> - <info> - <link type="topic" xref="mal_block_list"/> - <link type="topic" xref="mal_block_steps"/> - <link type="topic" xref="mal_block_terms"/> - <link type="topic" xref="mal_block_tree"/> - </info> - <title>List Elements</title> - <synopsis><code mime="application/relax-ng-compact-syntax"> -mal_block_lists = ( - <link xref="mal_block_list">mal_block_list</link> | - <link xref="mal_block_steps">mal_block_steps</link> | - <link xref="mal_block_terms">mal_block_terms</link> | - <link xref="mal_block_tree">mal_block_tree</link> -)</code></synopsis> - - <p>Mallard provides list elements for most common needs, including the common - definition, ordered, and unordered lists. Mallard also provides simple trees, - which are useful for representing heirarchies such as class inheritance or - directory layouts. Each of the list elements uses the <code>item</code> - element, though the content model for <code>item</code> varies. See the - list element pages for details.</p> -</section> -<!-- END lists --> - - -<!-- BEGIN tables --> -<section id="tables"> - <info> - <link type="topic" xref="mal_table"/> - </info> - <title>Tables</title> - - <p>Mallard provides a simple table model based on HTML tables. While not - allowing the level of styling flexibility as HTML and CSS, Mallard tables - provides simple solutions to common styling needs, such as alternate-row - shading.</p> -</section> -<!-- END tables --> - - -<!-- BEGIN other --> -<section id="other"> - <info> - <link type="topic" xref="mal_block_title"/> - <link type="topic" xref="mal_block_subtitle"/> - <link type="topic" xref="mal_block_desc"/> - <link type="topic" xref="mal_block_cite"/> - </info> - <title>Other Block-like Elements</title> - - <p>Mallard contains various block-like elements which are only used in - specific contexts, and are not allowed in general block content. These - elements allow for richer content models for the elements they appear - in.</p> -</section> -<!-- END other --> - - -<!-- BEGIN processing --> -<section id="processing"> - <title>Processing Expectations</title> - - <p>Block elements all begin on a new line in rendered output. Pages can - be visualized as a sequence of vertically-stacked block elements. Some - block elements contain other block elements. In these cases, the - containing element may introduce certain styling effects, and each of - the child elements is rendered as normal.</p> - - <p>Each block element should be clearly distinguishable from its surrounding - block elements. Typically, vertical padding is placed between block elements - to set them apart. Certain block elements, especially those that have block - content, may use a border, background color, or other styling effects. See - each block element's specification for more details.</p> -</section> -<!-- END processing --> - -</page> diff --git a/doc/mallard/C/mal_block_cite.page b/doc/mallard/C/mal_block_cite.page deleted file mode 100644 index 321e10a..0000000 --- a/doc/mallard/C/mal_block_cite.page +++ /dev/null @@ -1,66 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="mal_block_cite"> - -<info> - <link type="seealso" xref="mal_block_comment"/> - <link type="seealso" xref="mal_block_quote"/> - - <credit type="author"> - <name>Shaun McCance</name> - <email>shaunm@gnome.org</email> - <years>2008</years> - </credit> - - <revision version="0.1" date="2007-02-08" status="draft"/> - <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" /> -</info> - -<title>Citations</title> - -<synopsis><code mime="application/relax-ng-compact-syntax"> -mal_block_cite = element cite { - attribute style { xsd:NMTOKENS } ?, - attribute * - (mal:* | local:*) { text } *, - attribute date { text } ?, - attribute href { text } ?, - - <link xref="mal_inline">mal_inline</link> -} -</code></synopsis> - -<comment> - <cite date="2007-02-08">Shaun McCance</cite> - <p>Possibly add source for block quote citations.</p> -</comment> - -<p>The <code>cite</code> element provides information about the source of a -<code xref="mal_quote">quote</code> or a <code xref="mal_block_comment">comment</code> -element.</p> - -<comment> - <cite date="2007-02-08">Shaun McCance</cite> - <p>Add examples, processing expectations.</p> -</comment> - -<!-- BEGIN notes --> -<section id="notes"> - <title>Notes</title> - <list> - <item><p>The <code>style</code> attribute takes a space-separated list of - style hints. Processing tools should adjust their behavior according to - those style hints they understand.</p></item> - - <item><p>The <code>cite</code> element can have attributes from external - namespaces. See <link xref="mal_external"/> for more information - on external-namespace attributes.</p></item> - - <item><p>The <code>href</code> attribute provides a URL to identify the - entity being cited. It will frequently be a <sys>mailto:</sys> URL with - a person's email address.</p></item> - </list> -</section> -<!-- END notes --> - - -</page> diff --git a/doc/mallard/C/mal_block_code.page b/doc/mallard/C/mal_block_code.page deleted file mode 100644 index ff0b04e..0000000 --- a/doc/mallard/C/mal_block_code.page +++ /dev/null @@ -1,139 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="mal_block_code"> - -<info> - <link type="seealso" xref="mal_inline_code"/> - - <revision version="0.1" date="2009-04-19" status="review"/> - - <credit type="author"> - <name>Shaun McCance</name> - <email>shaunm@gnome.org</email> - <years>2008-2009</years> - </credit> - - <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" /> - - <desc>Mark up a block of code or the contents of a file.</desc> -</info> - -<title>Code Blocks</title> - -<synopsis><code mime="application/relax-ng-compact-syntax"> -mal_block_code = element code { - attribute style { xsd:NMTOKENS } ?, - attribute mime { text } ?, - attribute * - (mal:* | local:*) { text } *, - - <link xref="mal_inline">mal_inline</link> -} -</code></synopsis> - -<p>Use the <code>code</code> element to mark up a block of text from -a computer language. This will typically be used for programming -languages, markup languages, and configuration files; however, you -may use <code>code</code> for the contents of any text file.</p> - -<p>Use the <code xref="mal_inline_var">var</code> element inside a -<code>code</code> element to indicate text that should be replaced -by the user.</p> - - -<!-- BEGIN notes --> -<section id="notes"> - <title>Notes</title> - <list> - <item><p>The <code>code</code> element can contain a mixture of text and - any <link xref="mal_inline">general inline elements</link>. Whitespace - is interpreted literally.</p></item> - - <item><p>The <code>code</code> element can occur in any - general block context, including inside - <link xref="mal_page">pages</link>, <link xref="mal_section">sections</link>, - and certain <link xref="mal_block">block elements</link>.</p></item> - - <item><p>The <code>style</code> attribute takes a space-separated list of - style hints. Processing tools should adjust their behavior according to - those style hints they understand.</p></item> - - <item><p>The <code>mime</code> attribute takes a valid MIME type. Processing - tools may adjust their behavior for particular MIME types.</p></item> - - <item><p>The <code>code</code> element can have attributes from external - namespaces. See <link xref="mal_external"/> for more information - on external-namespace attributes.</p></item> - - <item><p>The <code>code</code> element may also be used in an inline context. - See <link xref="mal_inline_code"/> for more information.</p></item> - - <item><p>Use the <code>code</code> element inside a - <code xref="mal_block_listing">listing</code> element to provide a title - and description for the code block. This is frequently used to provide - the name of the file whose contents are being shown.</p></item> - </list> -</section> -<!-- END notes --> - - -<!-- BEGIN examples --> -<section id="examples"> - <title>Examples</title> - - <p>Use <code>code</code> to mark up a class definition:</p> - - <example> - <code><![CDATA[<code mime="text/x-c++src"> -class BeanStalk { -public: - void add_bean(Bean bean); - int count_beans(); -}</code>]]></code> - <code mime="text/x-c++src"> -class BeanStalk { -public: - void add_bean(Bean bean); - int count_beans(); -}</code> - </example> -</section> -<!-- END examples --> - - -<!-- BEGIN processing --> -<section id="processing"> - <title>Processing Expectations</title> - - <p>Code blocks should be displayed verbatim, with all whitespace and line - breaks reproduced in the rendered output. The only exception is a single - leading line break, which should be stripped by display tools if present. - Display tools should only strip a leading line break in an initial text - node. They are not expected to strip line breaks from child elements.</p> - - <p>Code blocks should be displayed in a fixed-width font. Inline markup may - cause style variations, but they should not cause a change to a variable-width - font.</p> -</section> -<!-- END processing --> - - -<!-- BEGIN comparison --> -<section id="comparison"> - <title>Comparison to Other Formats</title> - <p>The <code>code</code> element is similar to the - <code href="http://www.docbook.org/tdg/en/html/programlisting.html">programlisting</code> - element in DocBook. DocBook also contains numerous elements for modeling - code in procedural and object-oriented programming languages. Many of - these elements can be seen by browsing the content models for the - <code href="http://www.docbook.org/tdg/en/html/classsynopsis.html">classsynopsis</code> - and - <code href="http://www.docbook.org/tdg/en/html/funcsynopsis.html">funcsynopsis</code> - elements. Mallard does not attempt to model any programming languages.</p> - - <p>The <code>code</code> element is similar to the - <code href="http://docs.oasis-open.org/dita/v1.1/CS01/langspec/langref/codeblock.html">codeblock</code> - element in DITA.</p> -</section> -<!-- END comparison --> - -</page> diff --git a/doc/mallard/C/mal_block_comment.page b/doc/mallard/C/mal_block_comment.page deleted file mode 100644 index 35bf956..0000000 --- a/doc/mallard/C/mal_block_comment.page +++ /dev/null @@ -1,176 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="mal_block_comment"> - -<info> - <revision version="0.1" date="2009-05-07" status="review"/> - - <credit type="author"> - <name>Shaun McCance</name> - <email>shaunm@gnome.org</email> - <years>2007-2009</years> - </credit> - - <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" /> - - <desc>Include an editorial comment that's hidden from normal readers.</desc> -</info> - -<title>Editorial Comments</title> - -<synopsis><code mime="application/relax-ng-compact-syntax"> -mal_block_comment = element comment { - attribute style { xsd:NMTOKENS } ?, - attribute * - (mal:* | local:*) { text } *, - - <link xref="mal_block_title">mal_block_title</link> ?, - <link xref="mal_block_cite">mal_block_cite</link>, - <link xref="mal_block">mal_block</link> + -} -</code></synopsis> - -<p>The <code>comment</code> element allows you to insert editorial comments -into your document. These comments are intended to be displayed only when -editing or reviewing the document, and not when the document is viewed by the -end reader. A <code>comment</code> element can contain other <code>comment</code> -elements, allowing you to have a threaded discussion inside editorial comments.</p> - -<p>A <code>comment</code> element may optionally contain a -<code xref="mal_block_title">title</code> element to provide a brief description -of the subject of the comment. Titles are encouraged in top-level comments, -although they are usually unnecessary in replies.</p> - -<p>The <code xref="mal_block_cite">cite</code> element is a required element -that specifies the person making the comment. Writers are highly encouraged -to provide a <code>date</code> attribute.</p> - - -<!-- BEGIN notes --> -<section id="notes"> - <title>Notes</title> - <list> - <item><p>The <code>comment</code> element contains an optional - <link xref="mal_block_title">title</link> element, a - <link xref="mal_block_cite">cite</link> element, and any - <link xref="mal_block">general block content</link>.</p></item> - - <item><p>The <code>comment</code> element can occur in any - general block context, including inside - <link xref="mal_page">pages</link>, <link xref="mal_section">sections</link>, - and certain <link xref="mal_block">block elements</link>.</p></item> - - <item><p>The <code>style</code> attribute takes a space-separated list of - style hints. Processing tools should adjust their behavior according to - those style hints they understand.</p></item> - - <item><p>The <code>comment</code> element can have attributes from external - namespaces. See <link xref="mal_external"/> for more information - on external-namespace attributes.</p></item> - </list> -</section> -<!-- END notes --> - - -<!-- BEGIN examples --> -<section id="examples"> - <title>Examples</title> - - <p>Provide a comment:</p> - - <example> - <code><![CDATA[ -<comment> - <title>Mallards Are Dabbling Ducks</title> - <cite date="2009-05-07" href="mailto:drake@example.com">Drake</cite> - <p>The information in this section is wrong. Mallards are dabbling - ducks, not diving ducks.</p> -</comment>]]></code> - <comment> - <?mal2html.show_comment?> - <title>Mallards Are Dabbling Ducks</title> - <cite date="2009-05-07" href="mailto:drake@example.com">Drake</cite> - <p>The information in this section is wrong. Mallards are dabbling - ducks, not diving ducks.</p> - </comment> - </example> - - <p>Use <code>comment</code> to carry out a threaded discussion:</p> - - <example> - <code><![CDATA[ -<comment> - <title>Mallards Are Dabbling Ducks</title> - <cite date="2009-05-07" href="mailto:drake@example.com">Drake</cite> - <p>The information in this section is wrong. Mallards are dabbling - ducks, not diving ducks.</p> - <comment> - <cite date="2009-05-08" href="mailto:rupert@example.com">Rupert</cite> - <p>But I saw a mallard dive just the other day.</p> - <comment> - <cite date="2009-05-09" href="mailto:drake@example.com">Drake</cite> - <p>Rupert, please see the - <link href="http://en.wikipedia.org/wiki/Mallard">Wikipedia - entry</link>.</p> - </comment> - </comment> -</comment>]]></code> - <comment> - <?mal2html.show_comment?> - <title>Mallards Are Dabbling Ducks</title> - <cite date="2009-05-07" href="mailto:drake@example.com">Drake</cite> - <p>The information in this section is wrong. Mallards are dabbling - ducks, not diving ducks.</p> - <comment> - <?mal2html.show_comment?> - <cite date="2009-05-08" href="mailto:rupert@example.com">Rupert</cite> - <p>But I saw a mallard dive just the other day.</p> - <comment> - <?mal2html.show_comment?> - <cite date="2009-05-09" href="mailto:drake@example.com">Drake</cite> - <p>Rupert, please see the - <link href="http://en.wikipedia.org/wiki/Mallard">Wikipedia - entry</link>.</p> - </comment> - </comment> - </comment> - </example> -</section> -<!-- END examples --> - - -<!-- BEGIN processing --> -<section id="processing"> - <title>Processing Expectations</title> - - <p>In normal processing, <code>comment</code> elements are not displayed. - It may be displayed under various circumstances, such as for writing and - editing purposes.</p> - - <p>When shown, a <code>comment</code> element is rendered as a displayed - block, with each of its child elements interpreted as block elements. - A border, background color, or other stylistic effect should be used to - clearly set distinguish comments from the surrounding content.</p> - - <p>If a <code>title</code> element is present, it is displayed at the top - of the comment. The <code>cite</code> my require special processing to - dispaly both its inline content and its <code>date</code> attribute. - Automatic text may be used for this.</p> -</section> -<!-- END processing --> - - -<!-- BEGIN comparison --> -<section id="comparison"> - <title>Comparison to Other Formats</title> - - <p>The <code>comment</code> element is similar to the - <code href="http://www.docbook.org/tdg/en/html/remark.html">remark</code> - element in DocBook. The DocBook <code>remark</code> element may be used - in either a block or an inline context, whereas the <code>comment</code> - element may only be used as a block element. The DocBook <code>remark</code> - element does not provide a way to supply a title or the name of the person - making the remark.</p> -</section> -<!-- END comparison --> - -</page> diff --git a/doc/mallard/C/mal_block_desc.page b/doc/mallard/C/mal_block_desc.page deleted file mode 100644 index aae6d6c..0000000 --- a/doc/mallard/C/mal_block_desc.page +++ /dev/null @@ -1,132 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="mal_block_desc"> - -<info> - <link type="seealso" xref="mal_block_figure"/> - <link type="seealso" xref="mal_block_listing"/> - <link type="seealso" xref="mal_block_synopsis"/> - - <revision version="0.1" date="2009-05-19" status="review"/> - - <credit type="author"> - <name>Shaun McCance</name> - <email>shaunm@gnome.org</email> - <years>2007-2009</years> - </credit> - - <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" /> - - <desc>Provide a caption for a formal block element.</desc> -</info> - -<title>Block Descriptions</title> - -<synopsis><code mime="application/relax-ng-compact-syntax"> -mal_block_desc = element desc { - attribute style { xsd:NMTOKENS } ?, - attribute * - (mal:* | local:*) { text } *, - - <link xref="mal_inline">mal_inline</link> -} -</code></synopsis> - -<p>The <code>desc</code> element marks a short text description for -formal block elements like <link xref="mal_block_figure">figure</link>. -The description provided by <code>desc</code> is formatted as a caption -for the formal element.</p> - - -<!-- BEGIN notes --> -<section id="notes"> - <title>Notes</title> - <list> - <item><p>The <code>desc</code> element can contain a mixture of text and - any <link xref="mal_inline">general inline elements</link>.</p></item> - - <item><p>The <code>desc</code> element can occur in the formal block elements - <code xref="mal_block_figure">figure</code>, - <code xref="mal_block_listing">listing</code>, and - <code xref="mal_block_synopsis">synopsis</code>.</p></item> - - <item><p>The <code>style</code> attribute takes a space-separated list of - style hints. Processing tools should adjust their behavior according to - those style hints they understand.</p></item> - - <item><p>The <code>desc</code> element can have attributes from external - namespaces. See <link xref="mal_external"/> for more information - on external-namespace attributes.</p></item> - - <item><p>The <code>desc</code> element can also be used in an informational - context. See <link xref="mal_info_desc"/> for more information.</p></item> - </list> -</section> -<!-- END notes --> - - -<!-- BEGIN examples --> -<section id="examples"> - <title>Examples</title> - - <p>Use <code>desc</code> to provide a caption for a - <link xref="mal_block_figure">figure</link>:</p> - - <example> - <code><![CDATA[ -<figure> - <desc>Drake, the Mallard mascot</desc> - <media type="image" mime="image/png" src="figures/mallard.png"/> -</figure> -]]></code> - <figure> - <desc>Drake, the Mallard mascot</desc> - <media type="image" mime="image/png" src="figures/mallard.png"/> - </figure> - </example> - - <p>Use <code>desc</code> to provide a caption for a - <link xref="mal_block_figure">listing</link>:</p> - - <example> - <code><![CDATA[ -<listing> - <desc>A first Mallard page</desc> - <code><![CDATA[ -<page xmlns="http://projectmallard.org/1.0/" - type="guide" - id="index"> - <!-- Content goes here --> -</page>]]]>]><![CDATA[</code> -</listing>]]></code> - <listing> - <desc>A first Mallard page</desc> - <code><![CDATA[ -<page xmlns="http://projectmallard.org/1.0/" - type="guide" - id="index"> - <!-- Content goes here --> -</page>]]></code> - </listing> - </example> - - <p>More exaples can be found on the pages <link xref="mal_block_figure"/>, - <link xref="mal_block_listing"/>, and <link xref="mal_block_synopsis"/>.</p> -</section> -<!-- END examples --> - - -<!-- BEGIN processing --> -<section id="processing"> - <title>Processing Expectations</title> - - <p>The exact display of a description will depend on how the enclosing formal - element is displayed. A description is a block of text that is displayed - directly above or below the normal contents of the enclosing element.</p> - - <p>A description should be displayed in a way that makes its role clearn and - which clearly distinguishes it from the normal block content of the enclosing - element.</p> -</section> -<!-- END processing --> - -</page> diff --git a/doc/mallard/C/mal_block_example.page b/doc/mallard/C/mal_block_example.page deleted file mode 100644 index f56763c..0000000 --- a/doc/mallard/C/mal_block_example.page +++ /dev/null @@ -1,131 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="mal_block_example"> - -<info> - <revision version="0.1" date="2009-05-06" status="review"/> - - <credit type="author"> - <name>Shaun McCance</name> - <email>shaunm@gnome.org</email> - <years>2008-2009</years> - </credit> - - <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" /> - - <desc>Mark a group of block elements as being part of a single example.</desc> -</info> - -<title>Examples</title> - -<synopsis><code mime="application/relax-ng-compact-syntax"> -mal_block_example = element example { - attribute style { xsd:NMTOKENS } ?, - attribute * - (mal:* | local:*) { text } *, - - <link xref="mal_block">mal_block</link> + -} -</code></synopsis> - -<p>Use the <code>example</code> element to place block elements into a -logical group, indicating that they are part of a single example. This -may be used to group example input with its result, to show different -steps with different types of block elements, or simply to group some -paragraphs together.</p> - - -<!-- BEGIN notes --> -<section id="notes"> - <title>Notes</title> - <list> - <item><p>The <code>example</code> element can contain any - <link xref="mal_block">general block content</link>.</p></item> - - <item><p>The <code>example</code> element can occur in any - general block context, including inside - <link xref="mal_page">pages</link>, <link xref="mal_section">sections</link>, - and certain <link xref="mal_block">block elements</link>.</p></item> - - <item><p>The <code>style</code> attribute takes a space-separated list of - style hints. Processing tools should adjust their behavior according to - those style hints they understand.</p></item> - - <item><p>The <code>example</code> element can have attributes from external - namespaces. See <link xref="mal_external"/> for more information - on external-namespace attributes.</p></item> - </list> -</section> -<!-- END notes --> - - -<!-- BEGIN examples --> -<section id="examples"> - <title>Examples</title> - - <p>Use <code>example</code> to show how to use the <code>screen</code> - element, grouping the input and formatted result:</p> - - <example> - <code><![CDATA[ -<example> -<code><![CDATA[ -<screen> -xsltproc -o mal_block_screen.html \ - --stringparam mal.cache.file `pwd`/mallard.cache \ - `pkg-config --variable mal2html gnome-doc-utils` \ - mal_block_screen.html -</screen> -]]>]<![CDATA[]></code> -<screen> -xsltproc -o mal_block_screen.html \ - --stringparam mal.cache.file `pwd`/mallard.cache \ - `pkg-config --variable mal2html gnome-doc-utils` \ - mal_block_screen.html -</screen> -</example> -]]></code> - <example> - <code><![CDATA[ -<screen> -xsltproc -o mal_block_screen.html \ - --stringparam mal.cache.file `pwd`/mallard.cache \ - `pkg-config --variable mal2html gnome-doc-utils` \ - mal_block_screen.html -</screen> -]]></code> - <screen> -xsltproc -o mal_block_screen.html \ - --stringparam mal.cache.file `pwd`/mallard.cache \ - `pkg-config --variable mal2html gnome-doc-utils` \ - mal_block_screen.html -</screen></example> - </example> -</section> -<!-- END examples --> - - -<!-- BEGIN processing --> -<section id="processing"> - <title>Processing Expectations</title> - - <p>The contents of an <code>example</code> element should each be rendered - as block elements as normal. Example should use margins, borders, or other - stylistic effects to provide a clear visual indication of the grouping.</p> -</section> -<!-- END processing --> - - -<!-- BEGIN comparison --> -<section id="comparison"> - <title>Comparison to Other Formats</title> - - <p>The <code>example</code> element is similar to the - <code href="http://www.docbook.org/tdg/en/html/example.html">example</code> - element in DocBook. In DocBook, the <code>example</code> element is a - formal element. In Mallard, <code>example</code> is a simple container - element, and does not allow a <code xref="mal_block_title">title</code> - element.</p> -</section> -<!-- END comparison --> - -</page> diff --git a/doc/mallard/C/mal_block_figure.page b/doc/mallard/C/mal_block_figure.page deleted file mode 100644 index 21106d4..0000000 --- a/doc/mallard/C/mal_block_figure.page +++ /dev/null @@ -1,112 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="mal_block_figure"> - -<info> - <link type="seealso" xref="mal_block_media"/> - <link type="seealso" xref="mal_block_listing"/> - - <revision version="0.1" date="2009-05-19" status="review"/> - - <credit type="author"> - <name>Shaun McCance</name> - <email>shaunm@gnome.org</email> - <years>2008-2009</years> - </credit> - - <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" /> - - <desc>Provide a title or caption for a multimedia object.</desc> -</info> - -<title>Figures</title> - -<synopsis><code mime="application/relax-ng-compact-syntax"> -mal_block_figure = element figure { - attribute style { xsd:NMTOKENS } ?, - attribute * - (mal:* | local:*) { text } *, - - <link xref="mal_block_title">mal_block_title</link> ?, - <link xref="mal_block_desc">mal_block_desc</link> ?, - <link xref="mal_block">mal_block</link> + -} -</code></synopsis> - -<p>Use the <code>figure</code> element to provide a title or caption for a -<link xref="mal_block_media">multimedia object</link> or other block object. -To provide a title for the contents of a file, such as a -<link xref="mal_block_code">code block</link>, use the -<code xref="mal_block_listing">listing</code> element instead.</p> - -<!-- BEGIN notes --> -<section id="notes"> - <title>Notes</title> - <list> - <item><p>The <code>figure</code> element contains an optional - <link xref="mal_block_title">title</link> element, an optional - <link xref="mal_block_desc">desc</link> element, and any - <link xref="mal_block">general block content</link>.</p></item> - - <item><p>The <code>figure</code> element can occur in any - general block context, including inside - <link xref="mal_page">pages</link>, <link xref="mal_section">sections</link>, - and certain <link xref="mal_block">block elements</link>.</p></item> - - <item><p>The <code>style</code> attribute takes a space-separated list of - style hints. Processing tools should adjust their behavior according to - those style hints they understand.</p></item> - - <item><p>The <code>figure</code> element can have attributes from external - namespaces. See <link xref="mal_external"/> for more information - on external-namespace attributes.</p></item> - </list> -</section> -<!-- END notes --> - -<!-- BEGIN examples --> -<section id="examples"> - <title>Examples</title> - - <p>Use <code>figure</code> to provide a title and caption for an image:</p> - - <example> - <code><![CDATA[ -<figure> - <title>Drake</title> - <desc>Drake is the Mallard mascot.</desc> - <media type="image" mime="image/png" src="figures/mallard.png"/> -</figure> -]]></code> - <figure> - <title>Drake</title> - <desc>Drake is the Mallard mascot.</desc> - <media type="image" mime="image/png" src="figures/mallard.png"/> - </figure> - </example> -</section> -<!-- END examples --> - - -<!-- BEGIN processing --> -<section id="processing"> - <title>Processing Expectations</title> - - <p>Figures are displayed as block elements, with each of their child elements - being interpreted as block elements. When present, the title and description - should be displayed in a way that makes their respective roles clear.</p> -</section> -<!-- END processing --> - - -<!-- BEGIN comparison --> -<section id="comparison"> - <title>Comparison to Other Formats</title> - - <p>The <code>figure</code> is similar to the - <code href="http://www.docbook.org/tdg/en/html/figure.html">figure</code> - element in DocBook. DocBook only provides a title for figures, whereas - Mallard distinguishes between a title and a caption.</p> -</section> -<!-- END comparison --> - -</page> diff --git a/doc/mallard/C/mal_block_list.page b/doc/mallard/C/mal_block_list.page deleted file mode 100644 index 8dea44d..0000000 --- a/doc/mallard/C/mal_block_list.page +++ /dev/null @@ -1,205 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="mal_block_list"> - -<info> - <revision version="0.1" date="2009-05-22" status="review"/> - - <credit type="author"> - <name>Shaun McCance</name> - <email>shaunm@gnome.org</email> - <years>2008-2009</years> - </credit> - - <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" /> - - <desc>Create a basic bulleted or numbered list.</desc> -</info> - -<title>Basic Lists</title> - -<synopsis><code mime="application/relax-ng-compact-syntax"> -mal_block_list = element list { - attribute type { xsd:NMTOKEN } ?, - attribute style { xsd:NMTOKENS } ?, - attribute * - (mal:* | local:*) { text } *, - - <link xref="mal_block_title">mal_block_title</link> ?, - - element item { - attribute style { xsd:NMTOKENS } ?, - attribute * - (mal:* | local:*) { text } *, - - <link xref="mal_block">mal_block</link> + - } + -} -</code></synopsis> - -<p>Use the <code>list</code> element to create a basic bulleted or numbered -list. By default, lists are unordered, and list items are marked with a -bullet or other glyph. You can select various numbering systems using the -<code>type</code> attribute. If you need a numbered list to enumerate steps -the reader should perform, use the <code xref="mal_block_steps">steps</code> -element.</p> - - -<!-- BEGIN notes --> -<section id="notes"> - <title>Notes</title> - <list> - <item><p>The <code>list</code> element can contain an optional - <code xref="mal_block_title">title</code> element followed by one or more - <code>item</code> elements. Each child <code>item</code> element can - contain a mixture of text and any - <link xref="mal_inline">general inline elements</link>.</p></item> - - <item><p>The <code>list</code> element can occur in any - general block context, including inside - <link xref="mal_page">pages</link>, <link xref="mal_section">sections</link>, - and certain <link xref="mal_block">block elements</link>.</p></item> - - <item><p>The <code>type</code> attribute allows you to select the list type, - which affects the markers used for each list item. Allowed values are those - from the <link href="http://www.w3.org/TR/css3-lists/">CSS - <code>list-style-type</code> property</link>. Additionally, the value of - <code>"numbered"</code> can be used to select a numbered list type appropriate - for the page's language.</p></item> - - <item><p>If no <code>type</code> attribute is present, it is assumed to be a - <link href="http://www.w3.org/TR/css3-lists/#glyphs">glyph type</link> such - as <code>"disc"</code> or <code>"circle"</code>. That is, lists default to - bulleted lists.</p></item> - - <item><p>The <code>style</code> attribute takes a space-separated list of - style hints. Processing tools should adjust their behavior according to - those style hints they understand.</p></item> - - <item><p>The <code>list</code> element can have attributes from external - namespaces. See <link xref="mal_external"/> for more information - on external-namespace attributes.</p></item> - </list> -</section> -<!-- END notes --> - - -<!-- BEGIN examples --> -<section id="examples"> - <title>Examples</title> - - <p>Create a basic unordered list:</p> - - <example> - <code><![CDATA[ -<list> - <item><p><code>GTK_MESSAGE_INFO</code></p></item> - <item><p><code>GTK_MESSAGE_WARNING</code></p></item> - <item><p><code>GTK_MESSAGE_QUESTION</code></p></item> - <item><p><code>GTK_MESSAGE_ERROR</code></p></item> - <item><p><code>GTK_MESSAGE_OTHER</code></p></item> -</list> -]]></code> - <list> - <item><p><code>GTK_MESSAGE_INFO</code></p></item> - <item><p><code>GTK_MESSAGE_WARNING</code></p></item> - <item><p><code>GTK_MESSAGE_QUESTION</code></p></item> - <item><p><code>GTK_MESSAGE_ERROR</code></p></item> - <item><p><code>GTK_MESSAGE_OTHER</code></p></item> - </list> - </example> - - <p>Create an unordered list with a title:</p> - - <example> - <code><![CDATA[ -<list> - <title>Message Types</title> - <item><p><code>GTK_MESSAGE_INFO</code></p></item> - <item><p><code>GTK_MESSAGE_WARNING</code></p></item> - <item><p><code>GTK_MESSAGE_QUESTION</code></p></item> - <item><p><code>GTK_MESSAGE_ERROR</code></p></item> - <item><p><code>GTK_MESSAGE_OTHER</code></p></item> -</list> -]]></code> - <list> - <title>Message Types</title> - <item><p><code>GTK_MESSAGE_INFO</code></p></item> - <item><p><code>GTK_MESSAGE_WARNING</code></p></item> - <item><p><code>GTK_MESSAGE_QUESTION</code></p></item> - <item><p><code>GTK_MESSAGE_ERROR</code></p></item> - <item><p><code>GTK_MESSAGE_OTHER</code></p></item> - </list> - </example> - - <p>Create a simple numbered list:</p> - - <example> - <code><![CDATA[ -<list type="numbered"> - <item><p>First</p></item> - <item><p>Second</p></item> - <item><p>Third</p></item> -</list> -]]></code> - <list type="numbered"> - <item><p>First</p></item> - <item><p>Second</p></item> - <item><p>Third</p></item> - </list> - </example> - - <p>Create a numbered list with Roman numerals:</p> - - <example> - <code><![CDATA[ -<list type="upper-roman"> - <item><p>First</p></item> - <item><p>Second</p></item> - <item><p>Third</p></item> -</list> -]]></code> - <list type="upper-roman"> - <item><p>First</p></item> - <item><p>Second</p></item> - <item><p>Third</p></item> - </list> - </example> -</section> -<!-- END examples --> - - -<!-- BEGIN processing --> -<section id="processing"> - <title>Processing Expectations</title> - - <p>Lists are displayed as block elements, with each child <code>item</code> - displayed as a list item. When present, the title should be displayed in a - way that makes it clear that it is the title of the list. List items are - interpreted in the same way as <code>li</code> elements in HTML, except that - the <code>item</code> element only allows block-level child content.</p> - - <p>Item markers are taken from the <code>type</code> attribute, which is - either a valid value of the <link href="http://www.w3.org/TR/css3-lists/">CSS - <code>list-style-type</code> property</link>, or the special value - <code>"numbered"</code>. When the <code>"numbered"</code> type is used, a - numeric marker type is chosen that is appropriate for the language of the - page. The default numeric marker type per language may vary between - implementations.</p> -</section> -<!-- END processing --> - - -<!-- BEGIN comparison --> -<section id="comparison"> - <title>Comparison to Other Formats</title> - - <p>The <code>list</code> element combines the functionality of the - <code href="http://www.docbook.org/tdg/en/html/itemizedlist.html">itemizedlist</code> - and <code href="http://www.docbook.org/tdg/en/html/orderedlist.html">orderedlist</code> - elements in DocBook. DocBook allows leading block-level content in its list - elements. This is not allowed in Mallard, though an optional <code>title</code> - element is allowed. DocBook allows you to override the bullet or numbering - type on each list item. Mallard does not allow this.</p> -</section> -<!-- END comparison --> - -</page> diff --git a/doc/mallard/C/mal_block_listing.page b/doc/mallard/C/mal_block_listing.page deleted file mode 100644 index 70864b9..0000000 --- a/doc/mallard/C/mal_block_listing.page +++ /dev/null @@ -1,124 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="mal_block_listing"> - -<info> - <link type="seealso" xref="mal_block_code"/> - <link type="seealso" xref="mal_block_figure"/> - - <revision version="0.1" date="2009-05-19" status="review"/> - - <credit type="author"> - <name>Shaun McCance</name> - <email>shaunm@gnome.org</email> - <years>2008-2009</years> - </credit> - - <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" /> - - <desc>Provide a name and description for a code block or other content.</desc> -</info> - -<title>Listings</title> - -<synopsis><code mime="application/relax-ng-compact-syntax"> -mal_block_listing = element listing { - attribute style { xsd:NMTOKENS } ?, - attribute * - (mal:* | local:*) { text } *, - - <link xref="mal_block_title">mal_block_title</link> ?, - <link xref="mal_block_desc">mal_block_desc</link> ?, - <link xref="mal_block">mal_block</link> + -} -</code></synopsis> - -<p>Use the <code>listing</code> element to create named listing of file contents -or other content. Listings are usually used with <link xref="mal_block_code">code -blocks</link> to provide a name for the file to enter the content into. They may -also be used to provide a name for an <link xref="mal_block_screen">interactive -shell session</link> or any other type of content. To provide a title for images -or other multimedia objects, use the <link xref="mal_block_figure">figure</link> -element.</p> - -<!-- BEGIN notes --> -<section id="notes"> - <title>Notes</title> - <list> - <item><p>The <code>listing</code> element contains an optional - <link xref="mal_block_title">title</link> element, an optional - <link xref="mal_block_desc">desc</link> element, and any - <link xref="mal_block">general block content</link>.</p></item> - - <item><p>The <code>listing</code> element can occur in any - general block context, including inside - <link xref="mal_page">pages</link>, <link xref="mal_section">sections</link>, - and certain <link xref="mal_block">block elements</link>.</p></item> - - <item><p>The <code>style</code> attribute takes a space-separated list of - style hints. Processing tools should adjust their behavior according to - those style hints they understand.</p></item> - - <item><p>The <code>listing</code> element can have attributes from external - namespaces. See <link xref="mal_external"/> for more information - on external-namespace attributes.</p></item> - </list> -</section> -<!-- END notes --> - - -<!-- BEGIN examples --> -<section id="examples"> - <title>Examples</title> - - <p>Use <code>listing</code> to provide a file name and description for a - code block:</p> - - <example> - <code><![CDATA[ -<listing> - <title><file>index.page</file></title> - <desc>A first Mallard page</desc> - <code><![CDATA[ -<page xmlns="http://projectmallard.org/1.0/" - type="guide" - id="index"> - <!-- Content goes here --> -</page>]]]>]><![CDATA[</code> -</listing>]]></code> - <listing> - <title><file>index.page</file></title> - <desc>A first Mallard page</desc> - <code><![CDATA[ -<page xmlns="http://projectmallard.org/1.0/" - type="guide" - id="index"> - <!-- Content goes here --> -</page>]]></code> - </listing> - </example> -</section> -<!-- END examples --> - - -<!-- BEGIN processing --> -<section id="processing"> - <title>Processing Expectations</title> - - <p>Listings are displayed as block elements, with each of their child elements - being interpreted as block elements. When present, the title and description - should be displayed in a way that makes their respective roles clear.</p> -</section> -<!-- END processing --> - - -<!-- BEGIN comparison --> -<!-- -No direct analog in DocBook. I'm sure people accomplish the same thing somehow, -but my brain isn't working right now. Also check DITA. -<section id="comparison"> - <title>Comparison to Other Formats</title> -</section> ---> -<!-- END comparison --> - -</page> diff --git a/doc/mallard/C/mal_block_media.page b/doc/mallard/C/mal_block_media.page deleted file mode 100644 index 837fa8b..0000000 --- a/doc/mallard/C/mal_block_media.page +++ /dev/null @@ -1,154 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="mal_block_media"> - -<info> - <link type="seealso" xref="mal_inline_media"/> - - <revision version="0.1" date="2009-05-03" status="review"/> - - <credit type="author"> - <name>Shaun McCance</name> - <email>shaunm@gnome.org</email> - <years>2008-2009</years> - </credit> - - <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" /> - - <desc>Insert an image, video, or other multimedia object.</desc> -</info> - -<title>Multimedia Objects</title> - -<synopsis><code mime="application/relax-ng-compact-syntax"> -mal_block_media = element media { - attribute type { "image" | "video" | "audio" | "application" } ?, - attribute mime { text } ?, - attribute src { text }, - attribute height { text } ?, - attribute width { text } ?, - attribute style { xsd:NMTOKENS } ?, - attribute * - (mal:* | local:*) { text } *, - - <link xref="mal_block">mal_block</link> * -} -</code></synopsis> - -<p>Use the <code>media</code> element to insert an image, video, or other -multimedia object into your document. Since not all display tools will be -able to display all types of objects, you can provide fallback elements in -the contents of a <code>media</code> element. See <link xref="#processing"/> -for details on how fallback elements are handled.</p> - - -<!-- BEGIN notes --> -<section id="notes"> - <title>Notes</title> - <list> - <item><p>The <code>media</code> element can contain any - <link xref="mal_block">general block content</link>. The content is only - used as a fallback or alternative.</p></item> - - <item><p>The <code>media</code> element can occur in any - general block context, including inside - <link xref="mal_page">pages</link>, <link xref="mal_section">sections</link>, - and certain <link xref="mal_block">block elements</link>.</p></item> - - <item><p>The <code>style</code> attribute takes a space-separated list of - style hints. Processing tools should adjust their behavior according to - those style hints they understand.</p></item> - - <item><p>The <code>mime</code> attribute takes a valid MIME type for the - object that is being inserted.</p></item> - - <item><p>The <code>media</code> element can have attributes from external - namespaces. See <link xref="mal_external"/> for more information - on external-namespace attributes.</p></item> - - <item><p>The <code>media</code> element may also be used in an inline context. - See <link xref="mal_inline_media"/> for more information.</p></item> - </list> -</section> -<!-- END notes --> - - -<!-- BEGIN examples --> -<section id="examples"> - <title>Examples</title> - - <p>Use <code>media</code> to insert an image into your document:</p> - - <example> - <code><![CDATA[ -<media type="image" mime="image/png" src="figures/mallard.png"> -<p>Drake, the Mallard mascot</p> -</media> -]]></code> - <media type="image" mime="image/png" src="figures/mallard.png"> - <p>Drake, the Mallard mascot</p> - </media> - </example> - -</section> -<!-- END examples --> - - -<!-- BEGIN processing --> -<section id="processing"> - <title>Processing Expectations</title> - - <p>When a <code>media</code> element occurs in a block context, it should be - displayed as a block element. The exact rendering of a <code>media</code> - element will depend on the <code>type</code> and <code>mime</code> attributes. - Display tools may need to add controls for audio and video objects.</p> - - <p>The <code>application</code> type is intended for embedding interactive - applications in documents. There are currently no specific recommendations - for displaying application objects. Behavior may vary according to the - type of application being embedded.</p> - - <p>Some display tools will not be able to display all types of objects. - For example, a printed document will not be able to display video or play - back audio. Even when a display tool can display the type of object, it - may not be able to work with the given MIME type for technical or other - reasons.</p> - - <p>When a display tool cannot display a <code>media</code> element, it - should display the child elements of the element, as if the <code>media</code> - element itself were replaced by its children. The child elements may consist - of simply another <code>media</code> element referencing a different type of - content. When processing any child <code>media</code> elements, display tools - may need to fall back further to their child elements.</p> - - <p>Frequently, the children of a <code>media</code> element will be a single - block element, such as another <code>media</code> element or a <code>p</code> - element. Note, however, that this is not required, and fallback rendering - may involve displaying several block elements.</p> - - <p>In some display media, multimedia objects can have alternate text. This - may be displayed when a user hovers over the object, or it may be provided - to assistive technologies. When displaying in such a medium, display tools - should extract the text value of a <code>media</code> element by processing - its child elements, and recursively processing any child <code>media</code> - elements, as if it can not display any types of <code>media</code> elements.</p> -</section> -<!-- END processing --> - - -<!-- BEGIN comparison --> -<section id="comparison"> - <title>Comparison to Other Formats</title> - - <p>The <code>media</code> element can be used in place of the DocBook elements - <code xref="http://www.docbook.org/tdg/en/html/audiooobject.html">audioobject</code>, - <code xref="http://www.docbook.org/tdg/en/html/imageobject.html">imageobject</code>, and - <code xref="http://www.docbook.org/tdg/en/html/videoobject.html">videoobject</code>. - DocBook uses the - <code xref="http://www.docbook.org/tdg/en/html/mediaobject.html">mediaobject</code> - element to provide alternative objects. In Mallard, alternative objects are - nested, obviating the need for a container element.</p> -</section> -<!-- END comparison --> - - -</page> diff --git a/doc/mallard/C/mal_block_note.page b/doc/mallard/C/mal_block_note.page deleted file mode 100644 index 702fc48..0000000 --- a/doc/mallard/C/mal_block_note.page +++ /dev/null @@ -1,230 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="mal_block_note"> - -<info> - <revision version="0.1" date="2009-05-18" status="review"/> - - <credit type="author"> - <name>Shaun McCance</name> - <email>shaunm@gnome.org</email> - <years>2008-2009</years> - </credit> - - <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" /> - - <desc>Include notes, tips, warnings, and other parenthetical information.</desc> -</info> - -<title>Notes</title> - -<synopsis><code mime="application/relax-ng-compact-syntax"> -mal_block_note = element note { - attribute style { xsd:NMTOKENS } ?, - attribute * - (mal:* | local:*) { text } *, - - <link xref="mal_block_title">mal_block_title</link> ?, - <link xref="mal_block">mal_block</link> + -} -</code></synopsis> - -<p>The <code>note</code> element allows you to insert parenthetical block-level -content into your document. Notes are visually distinct blocks, allowing readers -to skip them or focus on them, depending on their needs. You can use notes to -give tips, warn readers of potentially dangerous operations, point out known bugs, -or otherwise provide additional information without interfering with the main text -of your document.</p> - - -<!-- BEGIN notes --> -<section id="notes"> - <title>Notes</title> - <list> - <item><p>The <code>note</code> element contains an optional - <link xref="mal_block_title">title</link> element and any - <link xref="mal_block">general block content</link>.</p></item> - - <item><p>The <code>note</code> element can occur in any - general block context, including inside - <link xref="mal_page">pages</link>, <link xref="mal_section">sections</link>, - and certain <link xref="mal_block">block elements</link>.</p></item> - - <item><p>The <code>style</code> attribute takes a space-separated list of - style hints. Processing tools should adjust their behavior according to - those style hints they understand.</p></item> - - <item> - <p>The following style hints are recommended:</p> - <table rules="rows"> - <tr> - <td><p><code>advanced</code></p></td> - <td><p>information that advanced users may find useful</p></td> - </tr> - <tr> - <td><p><code>bug</code></p></td> - <td><p>a note about a known bug in the software</p></td> - </tr> - <tr> - <td><p><code>important</code></p></td> - <td><p>important information highlighted in a note</p></td> - </tr> - <tr> - <td><p><code>tip</code></p></td> - <td><p>a general tip that may help the reader perform an operation better</p></td> - </tr> - <tr> - <td><p><code>warning</code></p></td> - <td><p>a warning to the reader about a potentially dangerous operation</p></td> - </tr> - </table> - </item> - - <item><p>The <code>note</code> element can have attributes from external - namespaces. See <link xref="mal_external"/> for more information - on external-namespace attributes.</p></item> - </list> -</section> -<!-- END notes --> - - -<!-- BEGIN examples --> -<section id="examples"> - <title>Examples</title> - - <p>Insert a basic note into your document:</p> - - <example> - <code><![CDATA[ -<note> - <p>Information in this section is non-normative.</p> -</note> -]]></code> - <note> - <p>Information in this section is non-normative.</p> - </note> - </example> - - <p>Include a note with extra information for advanced readers:</p> - - <example> - <code><![CDATA[ -<note style="advanced"> - <p>The Mallard schema is maintained in RELAX-NG Compact Syntax in - code blocks embedded within the specification.</p> -</note> -]]></code> - <note style="advanced"> - <p>The Mallard schema is maintained in RELAX-NG Compact Syntax in - code blocks embedded within the specification.</p> - </note> - </example> - - <p>Mention a known bug the reader is likely to encounter:</p> - - <example> - <code><![CDATA[ -<note style="bug"> - <title>Cannot Save Files</title> - <p>Due to <link href="http://bugs.example.com/1234">bug #1234</link> you - cannot actually save files. If you try to save your files, the application - will crash. We recommend memorizing all your data on a regular basis.</p> -</note> -]]></code> - <note style="bug"> - <title>Cannot Save Files</title> - <p>Due to <link href="http://bugs.example.com/1234">bug #1234</link> you - cannot actually save files. If you try to save your files, the application - will crash. We recommend memorizing all your data on a regular basis.</p> - </note> - </example> - - <p>Highlight a vital piece of information to ensure readers see it even - when skimming a document:</p> - - <example> - <code><![CDATA[ -<note style="important"> - <title>Supply Your Name and Email Address</title> - <p>Before making any commits to a git repository, make sure to - supply your name and email address so that your commits are - correctly attributed.</p> - <code> -git config --global user.name <var>full_name</var> -git config --global user.email <var>email_address</var></code> -</note> -]]></code> - <note style="important"> - <title>Supply Your Name and Email Address</title> - <p>Before making any commits to a git repository, make sure to - supply your name and email address so that your commits are - correctly attributed.</p> - <code> -git config --global user.name <var>full_name</var> -git config --global user.email <var>email_address</var></code> - </note> - </example> - - <p>Provide a helpful but non-essential tip:</p> - - <example> - <code><![CDATA[ -<note style="tip"> - <p>Press <keyseq><key>Ctrl</key><key>J</key></keyseq> to jump to - the currently playing track.</p> -</note> -]]></code> - <note style="tip"> - <p>Press <keyseq><key>Ctrl</key><key>J</key></keyseq> to jump to - the currently playing track.</p> - </note> - </example> - - <p>Warn the reader about dangerous operations:</p> - - <example> - <code><![CDATA[ -<note style="warning"> - <p>There is no way to recover files deleted with the - <cmd>shred</cmd> command.</p> -</note> -]]></code> - <note style="warning"> - <p>There is no way to recover files deleted with the <cmd>shred</cmd> command.</p> - </note> - </example> -</section> -<!-- END examples --> - -<!-- BEGIN processing --> -<section id="processing"> - <title>Processing Expectations</title> - - <p>Notes are displayed as block elements, with each of their child elements - being interpreted as block elements. When present, the title should be - displayed in a way that makes it clear that it is the title of the block. - Notes should have a border, background color, or other styling effect to - distinguish them from the surrounding block content. Notes often use an - icon to identify what type of note is being displayed.</p> -</section> -<!-- END processing --> - -<!-- BEGIN comparison --> -<section id="comparison"> - <title>Comparison to Other Formats</title> - - <p>The <code>note</code> element is similar to the - <code href="http://www.docbook.org/tdg/en/html/caution.html">caution</code>, - <code href="http://www.docbook.org/tdg/en/html/important.html">important</code>, - <code href="http://www.docbook.org/tdg/en/html/note.html">note</code>, - <code href="http://www.docbook.org/tdg/en/html/tip.html">tip</code>, and - <code href="http://www.docbook.org/tdg/en/html/warning.html">warning</code> - elements in DocBook. Rather than use separate elements, Mallard uses single - <code>note</code> element which can be specialized and extended through style - hints. This document recommends the style hints <code>advanced</code> and - <code>bug</code>, which have no counterpart in DocBook. This document does - not recommend separate <code>caution</code> and <code>warning</code> types, - as there is rarely a useful distinction in practice.</p> -</section> -<!-- END comparison --> - -</page> diff --git a/doc/mallard/C/mal_block_p.page b/doc/mallard/C/mal_block_p.page deleted file mode 100644 index 875d8c6..0000000 --- a/doc/mallard/C/mal_block_p.page +++ /dev/null @@ -1,103 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="mal_block_p"> - -<info> - <revision version="0.1" date="2009-05-28" status="review"/> - - <credit type="author"> - <name>Shaun McCance</name> - <email>shaunm@gnome.org</email> - <years>2008-2009</years> - </credit> - - <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" /> - - <desc>Create a simple paragraph of text.</desc> -</info> - -<title>Paragraphs</title> - -<synopsis><code mime="application/relax-ng-compact-syntax"> -mal_block_p = element p { - attribute style { xsd:NMTOKENS } ?, - attribute * - (mal:* | local:*) { text } *, - - <link xref="mal_inline">mal_inline</link> -} -</code></synopsis> - -<p>The most basic block-level element in Mallard is the <code>p</code> -element. The <code>p</code> element creates a paragraph in the formatted -output.</p> - - -<!-- BEGIN notes --> -<section id="notes"> - <title>Notes</title> - <list> - <item><p>The <code>p</code> element can contain a mixture of text and - any <link xref="mal_inline">general inline elements</link>.</p></item> - - <item><p>The <code>p</code> element can occur in any - general block context, including inside - <link xref="mal_page">pages</link>, <link xref="mal_section">sections</link>, - and certain <link xref="mal_block">block elements</link>.</p></item> - - <item><p>The <code>style</code> attribute takes a space-separated list of - style hints. Processing tools should adjust their behavior according to - those style hints they understand.</p></item> - - <item><p>The <code>p</code> element can have attributes from external - namespaces. See <link xref="mal_external"/> for more information - on external-namespace attributes.</p></item> - </list> -</section> -<!-- END notes --> - - -<!-- BEGIN examples --> -<section id="examples"> - <title>Examples</title> - - <p>Create a simple paragraph:</p> - - <example> - <code><![CDATA[ -<p>The most basic block-level element in Mallard is the <code>p</code> -element. The <code>p</code> element creates a paragraph in the formatted -output.</p>]]></code> - <p>The most basic block-level element in Mallard is the <code>p</code> - element. The <code>p</code> element creates a paragraph in the formatted - output.</p> - </example> -</section> -<!-- END examples --> - - -<!-- BEGIN processing --> -<section id="processing"> - <title>Processing Expectations</title> - <p>Paragraphs are displayed as block elements, with their child elements - interpreted as inline elements. In on-screen media, paragraphs generally - have padding above and below them to separate them from the surrounding - block content. In print media, the first line of each paragraph has - traditionally been indented.</p> -</section> -<!-- END processing --> - - -<!-- BEGIN docbook --> -<section id="docbook"> - <title>Comparison to DocBook</title> - <p>The <code>p</code> element in Mallard appears to be equivalent to to the - <code href="http://www.docbook.org/tdg/en/html/para.html">para</code> element - in DocBook. While both elements create a paragraph in the formatted output, - the <code>p</code> element in Mallard is actually much more restrictive, as it - does not permit nested block content. In this regard, it is actaully similar - to the <code href="http://www.docbook.org/tdg/en/html/simpara.html">simpara</code> - element in DocBook.</p> -</section> -<!-- END docbook --> - -</page> diff --git a/doc/mallard/C/mal_block_quote.page b/doc/mallard/C/mal_block_quote.page deleted file mode 100644 index d0abbc5..0000000 --- a/doc/mallard/C/mal_block_quote.page +++ /dev/null @@ -1,153 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="mal_block_quote"> - -<info> - <revision version="0.1" date="2009-05-19" status="review"/> - - <credit type="author"> - <name>Shaun McCance</name> - <email>shaunm@gnome.org</email> - <years>2008-2009</years> - </credit> - - <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" /> - - <desc>Create a block-level quotation with an attribution.</desc> -</info> - -<title>Block Quotes</title> - -<synopsis><code mime="application/relax-ng-compact-syntax"> -mal_block_quote = element quote { - attribute style { xsd:NMTOKENS } ?, - attribute * - (mal:* | local:*) { text } *, - - <link xref="mal_block_title">mal_block_title</link> ?, - <link xref="mal_block_cite">mal_block_cite</link>, - <link xref="mal_block">mal_block</link> + -} -</code></synopsis> - -<p>The <code>quote</code> element allows you to mark a quoted block of text -and include an attribution for the quote. Block quotations are useful for -long passages, or for quotes you want to draw attention to. You can provide -an attribution using the <code xref="mal_block_cite">cite</code> element, -and have it automatically formatted by display tools.</p> - -<!-- BEGIN notes --> -<section id="notes"> - <title>Notes</title> - <list> - <item><p>The <code>quote</code> element contains an optional - <link xref="mal_block_title">title</link> element, a mandatory - <link xref="mal_block_cite">cite</link> element, and any - <link xref="mal_block">general block content</link>.</p></item> - - <item><p>The <code>quote</code> element can occur in any - general block context, including inside - <link xref="mal_page">pages</link>, <link xref="mal_section">sections</link>, - and certain <link xref="mal_block">block elements</link>.</p></item> - - <item><p>The <code>style</code> attribute takes a space-separated list of - style hints. Processing tools should adjust their behavior according to - those style hints they understand.</p></item> - - <item> - <p>The following style hints are recommended:</p> - <table rules="rows"> - <tr> - <td><p><code>epigraph</code></p></td> - <td><p>an introductory or closing quote that is not part of the - running prose, generally formatted flush right</p></td> - </tr> - </table> - </item> - - <item><p>The <code>quote</code> element can have attributes from external - namespaces. See <link xref="mal_external"/> for more information - on external-namespace attributes.</p></item> - </list> -</section> -<!-- END notes --> - - -<!-- BEGIN examples --> -<section id="examples"> - <title>Examples</title> - - <p>Include a simple block quote in your document:</p> - - <example> - <code><![CDATA[ -<quote> - <cite>Henry David Thoreau</cite> - <p>Our life is frittered away by detail.... Simplify, simplify.</p> -</quote> -]]></code> - <quote> - <cite>Henry David Thoreau</cite> - <p>Our life is frittered away by detail.... Simplify, simplify.</p> - </quote> - </example> - - <p>Add a title to the quote:</p> - - <example> - <code><![CDATA[ -<quote> - <title>Simplify</title> - <cite>Henry David Thoreau</cite> - <p>Our life is frittered away by detail.... Simplify, simplify.</p> -</quote> -]]></code> - <quote> - <title>Simplify</title> - <cite>Henry David Thoreau</cite> - <p>Our life is frittered away by detail.... Simplify, simplify.</p> - </quote> - </example> - - <p>Add a date to the attribution:</p> - - <example> - <code><![CDATA[ -<quote> - <cite date="1854">Henry David Thoreau</cite> - <p>Our life is frittered away by detail.... Simplify, simplify.</p> -</quote> -]]></code> - <quote> - <cite date="1854">Henry David Thoreau</cite> - <p>Our life is frittered away by detail.... Simplify, simplify.</p> - </quote> - </example> -</section> -<!-- END examples --> - - -<!-- BEGIN processing --> -<section id="processing"> - <title>Processing Expectations</title> - - <p>Block quotes are displayed as block elements, with each of their child - elements being interpreted as block elements. When present, the title and - attribution should be displayed in a way that makes their respective roles - clear. Block quotes are frequently adorned with a watermark of quotation - marks. Processing tools should ensure any quotation marks used in the - formatting of quotes, including watermark images, are appropriate for the - document's language.</p> -</section> -<!-- END processing --> - - -<!-- BEGIN comparison --> -<section id="comparison"> - <title>Comparison to Other Formats</title> - <p>The <code>quote</code> element is similar to the - <code href="http://www.docbook.org/tdg/en/html/blockquote.html">blockquote</code> - element in DocBook. The <code xref="mal_block_cite">cite</code> element is - mandatory in Mallard, whereas attribution is optional in DocBook.</p> -</section> -<!-- END comparison --> -</page> diff --git a/doc/mallard/C/mal_block_screen.page b/doc/mallard/C/mal_block_screen.page deleted file mode 100644 index 9c0bf8e..0000000 --- a/doc/mallard/C/mal_block_screen.page +++ /dev/null @@ -1,182 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="mal_block_screen"> - -<info> - <link type="seealso" xref="mal_block_code"/> - - <revision version="0.1" date="2009-04-16" status="review"/> - - <credit type="author"> - <name>Shaun McCance</name> - <email>shaunm@gnome.org</email> - <years>2009</years> - </credit> - - <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" /> - - <desc>Mark up a textual user interface or an interactive shell session.</desc> -</info> - -<title>Screens</title> - -<synopsis><code mime="application/relax-ng-compact-syntax"> -mal_block_screen = element screen { - attribute style { xsd:NMTOKENS } ?, - attribute mime { text } ?, - attribute * - (mal:* | local:*) { text } *, - - <link xref="mal_inline">mal_inline</link> -} -</code></synopsis> - -<p>Use the <code>screen</code> element to mark up a textual screen for -a textual user interface or an interactive shell. The contents of a -<code>screen</code> element are displayed verbatim. While all inline -content is allowed, <code xref="mal_inline_input">input</code> and -<code xref="mal_inline_output">output</code> will frequently be used -to provide richer markup when showing a shell session.</p> - -<p>The <code>screen</code> element may also be used to mark up a single -command in a block context.</p> - -<p>Use the <code xref="mal_inline_var">var</code> element inside a -<code>screen</code> element to indicate text that should be replaced -by the user.</p> - - -<!-- BEGIN notes --> -<section id="notes"> - <title>Notes</title> - <list> - <item><p>The <code>screen</code> element can contain a mixture of text and - any <link xref="mal_inline">general inline elements</link>. Whitespace - is interpreted literally.</p></item> - - <item><p>The <code>screen</code> element can occur in any - general block context, including inside - <link xref="mal_page">pages</link>, <link xref="mal_section">sections</link>, - and certain <link xref="mal_block">block elements</link>.</p></item> - - <item><p>The <code>style</code> attribute takes a space-separated list of - style hints. Processing tools should adjust their behavior according to - those style hints they understand.</p></item> - - <item><p>The <code>mime</code> attribute takes a valid MIME type. Processing - tools may adjust their behavior for particular MIME types. A MIME type is - assumed to apply to the user input only; thus, processing tools may ignore - the MIME type if the <code>screen</code> element is not composed of - <code>input</code> and <code>output</code> elements.</p></item> - - <item> - <p>Typical values for the <code>mime</code> attribute include:</p> - <table rules="rows"><tr> - <td><p><code>application/x-sh</code></p></td> - <td><p>Command to execute with the Bourne shell</p></td> - </tr><tr> - <td><p><code>application/x-csh</code></p></td> - <td><p>Command to execute with the C shell</p></td> - </tr></table> - </item> - - <item><p>The <code>screen</code> element can have attributes from external - namespaces. See <link xref="mal_external"/> for more information - on external-namespace attributes on block elements.</p></item> - </list> -</section> -<!-- END notes --> - - -<!-- BEGIN examples --> -<section id="examples"> - <title>Examples</title> - - <p>Use <code>screen</code> to mark up the screen of an interactive - text-based interface:</p> - - <example> - <code><![CDATA[<screen> -+==== Beanstalk =====================================+ -| Type the letter of the command you want: | -| O - Order beans | -| P - Plant beans | -| T - Track bean inventory | -+====================================================+ -</screen>]]></code> - <screen> -+==== Beanstalk =====================================+ -| Type the letter of the command you want: | -| O - Order beans | -| P - Plant beans | -| T - Track bean inventory | -+====================================================+ -</screen> - </example> - - <p>Use <code>screen</code> to mark up a long command:</p> - - <example> - <code><![CDATA[ -<screen> -xsltproc -o mal_block_screen.html \ - --stringparam mal.cache.file `pwd`/mallard.cache \ - `pkg-config --variable mal2html gnome-doc-utils` mal_block_screen.html -</screen> -]]></code> - <screen> -xsltproc -o mal_block_screen.html \ - --stringparam mal.cache.file `pwd`/mallard.cache \ - `pkg-config --variable mal2html gnome-doc-utils` mal_block_screen.html -</screen> - </example> - - <p>Use <code xref="mal_inline_input">input</code> and <code xref="mal_inline_output">output</code> - inside <code>screen</code> for richer text:</p> - - <example> - <code><![CDATA[ -<screen> -<output style="prompt">[rupert@gnome] </output><input>ls foo bar</input> -<output style="error">foo: cannot access file: No such file or directory</output> -<output>bar</output></screen> -]]></code> - <screen> -<output style="prompt">[rupert@gnome] </output><input>ls foo bar</input> -<output style="error">foo: cannot access file: No such file or directory</output> -<output>bar</output></screen> - </example> -</section> -<!-- END examples --> - - -<!-- BEGIN processing --> -<section id="processing"> - <title>Processing Expectations</title> - - <p>Screens should be displayed verbatim, with all whitespace and line breaks - reproduced in the rendered output. The only exception is a single leading - line break, which should be stripped by display tools if present. Display - tools should only strip a leading line break in an initial text node. They - are not expected to strip line breaks from child elements.</p> - - <p>Screens should be displayed in a fixed-width font. Inline markup may cause - style variations, but they should not cause a change to a variable-width font.</p> -</section> -<!-- END processing --> - - -<!-- BEGIN comparison --> -<section id="comparison"> - <title>Comparison to Other Formats</title> - - <p>The <code>screen</code> element is similar to the - <code href="http://www.docbook.org/tdg/en/html/screen.html">screen</code> - element in DocBook.</p> - - <p>The <code>screen</code> element is similar to the - <code href="http://docs.oasis-open.org/dita/v1.1/CS01/langspec/langref/screen.html">screen</code> - element in DITA.</p> -</section> -<!-- END comparison --> - -</page> diff --git a/doc/mallard/C/mal_block_steps.page b/doc/mallard/C/mal_block_steps.page deleted file mode 100644 index 1c8e356..0000000 --- a/doc/mallard/C/mal_block_steps.page +++ /dev/null @@ -1,192 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="mal_block_steps"> - -<info> - <revision version="0.1" date="2009-05-23" status="review"/> - - <credit type="author"> - <name>Shaun McCance</name> - <email>shaunm@gnome.org</email> - <years>2008-2009</years> - </credit> - - <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" /> - - <desc>Create a list of steps the reader should perform to accomplish a task.</desc> -</info> - -<title>Procedures</title> - -<synopsis><code mime="application/relax-ng-compact-syntax"> -mal_block_steps = element steps { - attribute style { xsd:NMTOKENS } ?, - attribute * - (mal:* | local:*) { text } *, - - <link xref="mal_block_title">mal_block_title</link> ?, - - element item { - attribute style { xsd:NMTOKENS } ?, - attribute * - (mal:* | local:*) { text } *, - - <link xref="mal_block">mal_block</link> + - } + -} -</code></synopsis> - -<p>Use the <code>steps</code> element to create a list of steps the reader -should follow. The <code>steps</code> element is structurally similar to -the <code xref="mal_block_list">list</code> element, but marking the list -as being instructions to the reader allows special display rules to be -applied. If you want a numbered list that is not a procedure, use the -<code xref="mal_block_list">list</code> element with the <code>type</code> -attribute to <code>"numbered"</code> instead.</p> - -<!-- BEGIN notes --> -<section id="notes"> - <title>Notes</title> - <list> - <item><p>The <code>steps</code> element can contain an optional - <code xref="mal_block_title">title</code> element followed by one or more - <code>item</code> elements. Each child <code>item</code> element can - contain a mixture of text and any - <link xref="mal_inline">general inline elements</link>.</p></item> - - <item><p>The <code>steps</code> element can occur in any - general block context, including inside - <link xref="mal_page">pages</link>, <link xref="mal_section">sections</link>, - and certain <link xref="mal_block">block elements</link>.</p></item> - - <item><p>The <code>style</code> attribute takes a space-separated list of - style hints. Processing tools should adjust their behavior according to - those style hints they understand.</p></item> - - <item><p>The <code>steps</code> element can have attributes from external - namespaces. See <link xref="mal_external"/> for more information - on external-namespace attributes.</p></item> - </list> -</section> -<!-- END notes --> - - -<!-- BEGIN examples --> -<section id="examples"> - <title>Examples</title> - - <p>Create a simple procedure of steps for the reader to follow:</p> - - <example> - <code><![CDATA[ -<steps> - <title>Planting Magic Beans</title> - <item><p>Dig a hole 10cm deep.</p></item> - <item><p>Place magic beans in the hole.</p></item> - <item><p>Fill hole with fertilized soil.</p></item> - <item><p>Water frequently.</p></item> -</steps> -]]></code> - <steps> - <title>Planting Magic Beans</title> - <item><p>Dig a hole 10cm deep.</p></item> - <item><p>Place magic beans in the hole.</p></item> - <item><p>Fill hole with fertilized soil.</p></item> - <item><p>Water frequently.</p></item> - </steps> - </example> - - <p>Create a procedure with a nested list and a nested procedure:</p> - - <example> - <code><![CDATA[ -<steps> - <title>Planting Magic Beans</title> - <item> - <p>Perform one of the following:</p> - <list> - <item><p>Dig a whole 10cm deep.</p></item> - <item><p>Find a whole 10cm deep.</p></item> - </list> - </item> - <item><p>Place magic beans in the hole.</p></item> - <item><p>Fill hole with fertilized soil.</p></item> - <item> - <p>Water frequently with the following steps:</p> - <steps> - <item><p>Fill watering can with water.</p></item> - <item><p>Pour water onto spot where beans were planted.</p></item> - </steps> - </item> -</steps> -]]></code> - <steps> - <title>Planting Magic Beans</title> - <item> - <p>Perform one of the following:</p> - <list> - <item><p>Dig a whole 10cm deep.</p></item> - <item><p>Find a whole 10cm deep.</p></item> - </list> - </item> - <item><p>Place magic beans in the hole.</p></item> - <item><p>Fill hole with fertilized soil.</p></item> - <item> - <p>Water frequently with the following steps:</p> - <steps> - <item><p>Fill watering can with water.</p></item> - <item><p>Pour water onto spot where beans were planted.</p></item> - </steps> - </item> - </steps> - </example> -</section> -<!-- END examples --> - - -<!-- BEGIN processing --> -<section id="processing"> - <title>Processing Expectations</title> - - <p>Procedures are displayed as block elements, with each child <code>item</code> - displayed as a numbered list item. When present, the <code>title</code> element - should be displayed in a way that makes it clear that it is the title of the list. - List items are interpreted in the same way as <code>li</code> elements in HTML, - except that the <code>item</code> element only allows block-level child content.</p> - - <p>Procedures should have a background color, border, or other styling effect - to clearly differentiate them from basic numbered lists. Special styling allows - readers to skim pages more easily.</p> -</section> -<!-- END processing --> - - -<!-- BEGIN comparison --> -<section id="comparison"> - <title>Comparison to Other Formats</title> - - <p>The <code>steps</code> element is similar to the - <code href="http://www.docbook.org/tdg/en/html/procedure.html">procedure</code> - element in DocBook. Note the following differences:</p> - - <list> - <item><p>Instead of a separate - <code href="http://www.docbook.org/tdg/en/html/step.html">step</code> element, - Mallard simply uses the common <code>item</code> element for each step.</p></item> - - <item><p>DocBook provides an explicit - <code href="http://www.docbook.org/tdg/en/html/substeps.html">substeps</code> - element. Mallard provides no such element; simply nest <code>steps</code> - elements for the same effect.</p></item> - - <item><p>Mallard provides no equivalent to the - <code href="http://www.docbook.org/tdg/en/html/stepalternatives.html">stepalternatives</code> - element. Use a <code xref="mal_block_list">basic bulleted list</code> with - introductory text when this is needed.</p></item> - - <item><p>DocBook allows leading block-level content in the <code>procedure</code> - element. This is not allowed in Mallard, though an optional <code>title</code> - element is allowed.</p></item> - </list> -</section> -<!-- END comparison --> - -</page> diff --git a/doc/mallard/C/mal_block_subtitle.page b/doc/mallard/C/mal_block_subtitle.page deleted file mode 100644 index c414577..0000000 --- a/doc/mallard/C/mal_block_subtitle.page +++ /dev/null @@ -1,17 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="mal_block_subtitle"> - -<info> - <revision version="0.1" date="2007-02-21" status="stub"/> -</info> - -<title>Subtitles</title> - -<synopsis><code mime="application/relax-ng-compact-syntax"> -mal_block_subtitle = element subtitle { - <link xref="mal_inline">mal_inline</link> -} -</code></synopsis> - -</page> diff --git a/doc/mallard/C/mal_block_synopsis.page b/doc/mallard/C/mal_block_synopsis.page deleted file mode 100644 index 7674946..0000000 --- a/doc/mallard/C/mal_block_synopsis.page +++ /dev/null @@ -1,133 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="mal_block_synopsis"> - -<info> - <link type="seealso" xref="mal_block_listing"/> - - <revision version="0.1" date="2009-05-19" status="review"/> - - <credit type="author"> - <name>Shaun McCance</name> - <email>shaunm@gnome.org</email> - <years>2008-2009</years> - </credit> - - <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" /> - - <desc>Create an overview of concepts.</desc> -</info> - -<title>Synopses</title> - -<synopsis><code mime="application/relax-ng-compact-syntax"> -mal_block_synopsis = element synopsis { - attribute style { xsd:NMTOKENS } ?, - attribute * - (mal:* | local:*) { text } *, - - <link xref="mal_block_title">mal_block_title</link> ?, - <link xref="mal_block_desc">mal_block_desc</link> ?, - <link xref="mal_block">mal_block</link> + -} -</code></synopsis> - -<p>The <code>synopsis</code> element allows you to mark up a block as -providing an overview of the material being presented. It is useful -for providing a listing of functions, commands, or options in reference -material, or for enumerating the items in a menu or other graphical -control element.</p> - -<comment> - <cite date="2006-11-16">Shaun McCance</cite> - <p>Add explanation, examples</p> -</comment> - - -<!-- BEGIN notes --> -<section id="notes"> - <title>Notes</title> - <list> - <item><p>The <code>synopsis</code> element contains an optional - <link xref="mal_block_title">title</link> element, an optional - <link xref="mal_block_desc">desc</link> element, and any - <link xref="mal_block">general block content</link>.</p></item> - - <item><p>The <code>synopsis</code> element can occur in any - general block context, including inside - <link xref="mal_page">pages</link>, <link xref="mal_section">sections</link>, - and certain <link xref="mal_block">block elements</link>.</p></item> - - <item><p>The <code>style</code> attribute takes a space-separated list of - style hints. Processing tools should adjust their behavior according to - those style hints they understand.</p></item> - - <item><p>The <code>synopsis</code> element can have attributes from external - namespaces. See <link xref="mal_external"/> for more information - on external-namespace attributes.</p></item> - </list> -</section> -<!-- END notes --> - - -<!-- BEGIN examples --> -<section id="examples"> - <title>Examples</title> - - <p>Use <code>synopsis</code> to create an overview of functions:</p> - - <example> - <code><![CDATA[<synopsis> -<title>Beanstalk Functions</title> -<desc>Use these methods on a <code>Beanstalk</code> object.</desc> -<code> -void add_bean (Bean bean); -int count_beans (); -</code> -</synopsis> -]]></code> - <synopsis> - <title>Beanstalk Functions</title> - <desc>Use these methods on a <code>beanstalk</code> object.</desc> - <code> -void add_bean (Bean bean); -int count_beans (); -</code> - </synopsis> - </example> -</section> -<!-- END examples --> - - -<!-- BEGIN processing --> -<section id="processing"> - <title>Processing Expectations</title> - - <p>A <code>synopsis</code> element is rendered as a displayed block, - with each of its child elements interpreted as block elements. Since - a <code>synopsis</code> element often contains large blocks, and is - generally offset from the running text, display tools may opt to render - it inside a colored box, with a border, or otherwise differently from - the surrounding text.</p> - - <p>When present, the title and description should be displayed in a - way that makes their respective roles clear.</p> -</section> -<!-- END processing --> - - -<!-- BEGIN comparison --> -<section id="comparison"> - <title>Comparison to Other Formats</title> - - <p>The <code>synopsis</code> element is similar to the - <code href="http://www.docbook.org/tdg/en/html/synopsis.html">synopsis</code> - element in DocBook, although the DocBook element is not a formal element. - DocBook also provides the - <code href="http://www.docbook.org/tdg/en/html/cmdsynopsis.html">cmdsynopsis</code> and - <code href="http://www.docbook.org/tdg/en/html/funcsynopsis.html">funcsynopsis</code> - elements, which attempt to model the data for command and function synopses, - respectively. Mallard does not provide modelling elements.</p> -</section> -<!-- END comparison --> - -</page> diff --git a/doc/mallard/C/mal_block_terms.page b/doc/mallard/C/mal_block_terms.page deleted file mode 100644 index 158ea9a..0000000 --- a/doc/mallard/C/mal_block_terms.page +++ /dev/null @@ -1,184 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="mal_block_terms"> - -<info> - <revision version="0.1" date="2009-05-28" status="review"/> - - <credit type="author"> - <name>Shaun McCance</name> - <email>shaunm@gnome.org</email> - <years>2008-2009</years> - </credit> - - <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" /> - - <desc>Create a list of terms and associated descriptions.</desc> -</info> - -<title>Definition Lists</title> - -<synopsis><code mime="application/relax-ng-compact-syntax"> -mal_block_terms = element terms { - attribute style { xsd:NMTOKENS } ?, - attribute * - (mal:* | local:*) { text } *, - - <link xref="mal_block_title">mal_block_title</link> ?, - - element item { - attribute style { xsd:NMTOKENS } ?, - attribute * - (mal:* | local:*) { text } *, - - <link xref="mal_block_title">mal_block_title</link> +, - <link xref="mal_block">mal_block</link> + - } + -} -</code></synopsis> - -<p>The <code>terms</code> element creates a list of terms and associated -definitions or descriptions. This type of list is often called a definition -list or a variable list.</p> - -<!-- BEGIN notes --> -<section id="notes"> - <title>Notes</title> - <list> - <item><p>The <code>terms</code> element can contain an optional - <code xref="mal_block_title">title</code> element followed by one or more - <code>item</code> elements. Each child <code>item</code> element can - contain one or more <code xref="mal_block_title">title</code> elements - followed by a mixture of text and any - <link xref="mal_inline">general inline elements</link>.</p></item> - - <item><p>The <code>terms</code> element can occur in any - general block context, including inside - <link xref="mal_page">pages</link>, <link xref="mal_section">sections</link>, - and certain <link xref="mal_block">block elements</link>.</p></item> - - <item><p>The <code>style</code> attribute takes a space-separated list of - style hints. Processing tools should adjust their behavior according to - those style hints they understand.</p></item> - - <item><p>The <code>terms</code> element can have attributes from external - namespaces. See <link xref="mal_external"/> for more information - on external-namespace attributes.</p></item> - </list> -</section> -<!-- END notes --> - - -<!-- BEGIN examples --> -<section id="examples"> - <title>Examples</title> - - <p>Create a simple definition list with a title:</p> - - <example> - <code><![CDATA[ -<terms> - <title>Selected Basic Block Elements</title> - <item> - <title><code>code</code></title> - <p>Mark up a block of code or the contents of a file.</p> - </item> - <item> - <title><code>example</code></title> - <p>Mark up a group of block elements as being part of a single example.</p> - </item> - <item> - <title><code>screen</code></title> - <p>Mark up a textual user interface or an interactive shell session.</p> - </item> -</terms>]]></code> - <terms> - <title>Selected Basic Block Elements</title> - <item> - <title><code>code</code></title> - <p>Mark up a block of code or the contents of a file.</p> - </item> - <item> - <title><code>example</code></title> - <p>Mark up a group of block elements as being part of a single example.</p> - </item> - <item> - <title><code>screen</code></title> - <p>Mark up a textual user interface or an interactive shell session.</p> - </item> - </terms> - </example> - - <p>Create a definition list with multiple terms per entry:</p> - - <example> - <code><![CDATA[ -<terms> - <item> - <title><code>comment</code></title> - <title><code>quote</code></title> - <p>Formal elements which allow a <code>cite</code> element.</p> - </item> - <item> - <title><code>figure</code></title> - <title><code>listing</code></title> - <title><code>synopsis</code></title> - <p>Formal elements which allow a <code>desc</code> element.</p> - </item> - <item> - <title><code>note</code></title> - <p>Formal elements which only allow a <code>title</code> element.</p> - </item> -</terms>]]></code> - <terms> - <item> - <title><code>comment</code></title> - <title><code>quote</code></title> - <p>Formal elements which allow a <code>cite</code> element.</p> - </item> - <item> - <title><code>figure</code></title> - <title><code>listing</code></title> - <title><code>synopsis</code></title> - <p>Formal elements which allow a <code>desc</code> element.</p> - </item> - <item> - <title><code>note</code></title> - <p>Formal elements which only allow a <code>title</code> element.</p> - </item> - </terms> - </example> -</section> -<!-- END examples --> - - -<!-- BEGIN processing --> -<section id="processing"> - <title>Processing Expectations</title> - - <p>Definition lists are displayed as block elements, with each child - <code>item</code> displayed as some number of list items. When present, the - title should be displayed in a way that makes it clear that it is the title - of the list. Each <code>title</code> element of each list item is treated - as a term, and is displayed as a block element. The remaining block content - is then treated as the description and displayed as normal. The description - blocks should be indented from the terms.</p> -</section> -<!-- END processing --> - - -<!-- BEGIN comparison --> -<section id="comparison"> - <title>Comparison to Other Formats</title> - - <p>The <code>terms</code> element is similar to - <code href="http://www.docbook.org/tdg/en/html/variablelist.html">variablelist</code> - element in DocBook. Like DocBook (and unlike HTML), Mallard groups terms with their - corresponding entries. In DocBook, the entry must be wrapped with a - <code href="http://www.docbook.org/tdg/en/html/listitem.html">listitem</code> - element inside the - <code href="http://www.docbook.org/tdg/en/html/varlistentry.html">varlistentry</code> - element. In Mallard, the entry is simply all of the block content except the - <code xref="mal_block_title">title</code> elements.</p> -</section> -<!-- END comparison --> - -</page> diff --git a/doc/mallard/C/mal_block_title.page b/doc/mallard/C/mal_block_title.page deleted file mode 100644 index c124700..0000000 --- a/doc/mallard/C/mal_block_title.page +++ /dev/null @@ -1,17 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="mal_block_title"> - -<info> - <revision version="0.1" date="2007-02-21" status="stub"/> -</info> - -<title>Titles</title> - -<synopsis><code mime="application/relax-ng-compact-syntax"> -mal_block_title = element title { - <link xref="mal_inline">mal_inline</link> -} -</code></synopsis> - -</page> diff --git a/doc/mallard/C/mal_block_tree.page b/doc/mallard/C/mal_block_tree.page deleted file mode 100644 index 474980b..0000000 --- a/doc/mallard/C/mal_block_tree.page +++ /dev/null @@ -1,187 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="mal_block_tree"> - -<info> - <revision version="0.1" date="2009-05-25" status="review"/> - - <credit type="author"> - <name>Shaun McCance</name> - <email>shaunm@gnome.org</email> - <years>2008-2009</years> - </credit> - - <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" /> - - <desc>Create simple trees to show heirarchical structures.</desc> -</info> - -<title>Tree Lists</title> - -<synopsis><code mime="application/relax-ng-compact-syntax"> -mal_block_tree = element tree { - attribute style { xsd:NMTOKENS } ?, - attribute * - (mal:* | local:*) { text } *, - - <link xref="mal_block_title">mal_block_title</link> ?, - mal_tree_item + -} -mal_tree_item = element item { - attribute style { xsd:NMTOKENS } ?, - attribute * - (mal:* | local:*) { text } *, - - <link xref="mal_inline">mal_inline</link>, - mal_tree_item * -} -</code></synopsis> - -<p>Use the <code>tree</code> element to create a heirarchical tree. While -conceptually similar to nested <code xref="mal_block_list">list</code> -elements, trees offer a simple way to display common heirarchies such as -class inheritance or directory layouts.</p> - - -<!-- BEGIN notes --> -<section id="notes"> - <title>Notes</title> - <list> - <item><p>The <code>tree</code> element can contain an optional - <code xref="mal_block_title">title</code> element followed by one or more - <code>item</code> elements. Each child <code>item</code> element can - contain a mixture of text and any - <link xref="mal_inline">general inline elements</link>, followed by - zero or more nested <code>item</code> elements.</p></item> - - <item><p>The <code>tree</code> element can occur in any - general block context, including inside - <link xref="mal_page">pages</link>, <link xref="mal_section">sections</link>, - and certain <link xref="mal_block">block elements</link>.</p></item> - - <item><p>The <code>style</code> attribute takes a space-separated list of - style hints. Processing tools should adjust their behavior according to - those style hints they understand.</p></item> - - <item> - <p>The following style hints are recommended:</p> - <table rules="rows"> - <tr> - <td><p><code>lines</code></p></td> - <td><p>draw lines to show the hierarchy</p></td> - </tr> - </table> - </item> - - <item><p>The <code>tree</code> element can have attributes from external - namespaces. See <link xref="mal_external"/> for more information - on external-namespace attributes.</p></item> - </list> -</section> -<!-- END notes --> - - -<!-- BEGIN examples --> -<section id="examples"> - <title>Examples</title> - - <p>Use a tree to outline a class heirarchy inside a - <code xref="mal_block_synopsis">>synopsis</code> element:</p> - - <example> - <code><![CDATA[ -<synopsis> - <tree> - <item> - <code>GtkBin</code> - <item> - <code>GtkButton</code> - <item><code>GtkToggleButton</code></item> - <item><code>GtkColorButton</code></item> - <item><code>GtkFontButton</code></item> - <item><code>GtkLinkButton</code></item> - <item><code>GtkOptionMenu</code></item> - <item><code>GtkScaleButton</code></item> - </item> - </item> - </tree> -</synopsis>]]></code> - <synopsis> - <tree> - <item> - <code>GtkBin</code> - <item> - <code>GtkButton</code> - <item><code>GtkToggleButton</code></item> - <item><code>GtkColorButton</code></item> - <item><code>GtkFontButton</code></item> - <item><code>GtkLinkButton</code></item> - <item><code>GtkOptionMenu</code></item> - <item><code>GtkScaleButton</code></item> - </item> - </item> - </tree> - </synopsis> - </example> - - <p>Use the <code>lines</code> style hint to visually show the tree structure:</p> - - <example> - <code><![CDATA[ -<tree style="lines"> - <item> - Anatinae (dabbling ducks) - <item> - Anas - <item>Baikal Teal</item> - <item>Wigeons</item> - <item>Mallard</item> - </item> - <item>Lophonetta</item> - <item>Speculanas</item> - </item> - <item> - Anthyinae (diving ducks) - <item>Aythya</item> - <item>Netta</item> - </item> - <item>Dendrocygninae (whistling ducks)</item> -</tree>]]></code> - <tree style="lines"> - <item> - Anatinae (dabbling ducks) - <item> - Anas - <item>Baikal Teal</item> - <item>Wigeons</item> - <item>Mallard</item> - </item> - <item>Lophonetta</item> - <item>Speculanas</item> - </item> - <item> - Anthyinae (diving ducks) - <item>Aythya</item> - <item>Netta</item> - </item> - <item>Dendrocygninae (whistling ducks)</item> - </tree> - </example> -</section> -<!-- END examples --> - - -<!-- BEGIN processing --> -<section id="processing"> - <title>Processing Expectations</title> - - <p>Tree lists are display as block elements. Each child <code>item</code> - has its leading inline content displayed in a single block and any nested - <code>item</code> elements displayed as blocks in turn. Successive levels - of nesting should yield more indentation, though this may vary based on - style hints or other factors. By default, there should be little vertical - spacing between items; trees are compact. No bullets, icons, or other marks - are expected to precede items, although they may be used for certain style - hints.</p> -</section> -<!-- END processing --> - -</page> diff --git a/doc/mallard/C/mal_external.page b/doc/mallard/C/mal_external.page deleted file mode 100644 index 4dc47e6..0000000 --- a/doc/mallard/C/mal_external.page +++ /dev/null @@ -1,83 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="mal_external"> - -<info> - <link type="seealso" xref="mal_inline"/> - - <credit type="author"> - <name>Shaun McCance</name> - <email>shaunm@gnome.org</email> - <years>2008</years> - </credit> - - <revision version="0.1" date="2008-02-19" status="incomplete"/> - - <desc>Use elements and attributes from other namespaces in Mallard - documents.</desc> -</info> - -<title>External Namespaces</title> - -<comment> - <cite date="2008-12-01">Shaun McCance</cite> - <p>Add content</p> -</comment> - -<synopsis><code mime="application/relax-ng-compact-syntax"> -mal_external = element * - (mal:* | local:*) { - attribute * { text } *, - mal_anything * -} -mal_anything = element * { - attribute * { text } *, - mal_anything * -} -</code></synopsis> - - -<!-- BEGIN attributes --> -<section id="attributes"> - <info> - <title type="link">External Namespace Attributes</title> - </info> - <title>Attributes</title> - - <p>All elements in Mallard can have attributes from external namespaces. - This can be used to clarify the meaning of an element in a particular - context, to provide additional information to processing tools, or to - embed richer semantic data in a document.</p> - - <p>For example, a translation tool might copy - <link xref="mal_block_code">code blocks</link> directly into the translated - document without presenting them to translators. Some code blocks, however, - may contain human-readable comments which should be translated. In order to - force translation tools to present these code blocks for translation, authors - could use the <code>its:translate</code> attribute from the - <link href="http://www.w3.org/TR/its/">Internationalization Tag Set</link>, - as in the following:</p> - - <code><![CDATA[ -<code xmlns:its="http://www.w3.org/2005/11/its" - its:version="1.0" its:translate="yes"> -// This code block should be translated because it contains this comment. -some_code () -</code> -]]></code> - - <p>Processing tools should ignore any attributes from external namespaces - they do not understand.</p> -</section> -<!-- END attributes --> - - -<!-- BEGIN elements --> -<section id="elements"> - <info> - <title type="link">External Namespace Elements</title> - </info> - <title>Elements</title> -</section> -<!-- END elements --> - -</page> diff --git a/doc/mallard/C/mal_info.page b/doc/mallard/C/mal_info.page deleted file mode 100644 index 7d448e4..0000000 --- a/doc/mallard/C/mal_info.page +++ /dev/null @@ -1,58 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="guide" - id="mal_info"> - -<info> - <link type="guide" xref="spec"/> - - <revision version="0.1" date="2008-02-21" status="stub"/> -</info> - -<title>Informational Elements</title> - -<synopsis><code mime="application/relax-ng-compact-syntax"> -mal_info = element info { - attribute * - (mal:* | local:*) { text } *, - - ( - <link xref="mal_info_desc">mal_info_desc</link> ? & - <link xref="mal_info_credit">mal_info_credit</link> * & - <link xref="mal_info_license">mal_info_license</link> * & - <link xref="mal_info_link">mal_info_link</link> * & - <link xref="mal_info_title">mal_info_title</link> * & - <link xref="mal_info_revision">mal_info_revision</link> * & - <link xref="mal_external">mal_external</link> * - ) -} -</code></synopsis> -<!-- -credit (type) -credit/date -credit/email -credit/name - -link (guide/page/seealso) - -? version number date -? license -? notice -? desc -? keyword ---> - -<!-- BEGIN elements --> -<section id="elements"> - <title>Informational Elements</title> -</section> -<!-- END elements --> - -<!-- BEGIN additional --> -<section id="additional"> - <info> - <title type="link">Additional Informational Elements</title> - </info> - <title>Additional Elements</title> -</section> -<!-- END additional --> - -</page> diff --git a/doc/mallard/C/mal_info_credit.page b/doc/mallard/C/mal_info_credit.page deleted file mode 100644 index 4ec8d28..0000000 --- a/doc/mallard/C/mal_info_credit.page +++ /dev/null @@ -1,147 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="mal_info_credit"> - -<info> - <link type="guide" xref="mal_info#elements"/> - - <revision version="0.1" date="2009-09-08" status="review"/> - - <credit type="author"> - <name>Shaun McCance</name> - <email>shaunm@gnome.org</email> - <years>2008</years> - </credit> - - <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" /> - - <desc>Give credit where credit is due.</desc> -</info> - -<title>Credits</title> - -<synopsis><code mime="application/relax-ng-compact-syntax"> -mal_info_credit = element credit { - attribute type { xsd:NMTOKENS } ?, - attribute * - (mal:* | local:*) { text } *, - - ( - <link xref="mal_info_name">mal_info_name</link> & - <link xref="mal_info_email">mal_info_email</link> ? & - <link xref="mal_info_years">mal_info_years</link> ? & - <link xref="mal_external">mal_external</link> * - ) -} -</code></synopsis> - -<p>Use the <code>credit</code> element to record who has contributed to the page -or section. You can optionally use the <code>type</code> attribute to specify -what types of contribution the person has made. The <code>credit</code> element -also specifies copyright holders when used with the -<code xref="mal_info_years">years</code> element.</p> - - -<!-- BEGIN notes --> -<section id="notes"> - <title>Notes</title> - <list> - <item><p>The <code>credit</code> element contains a - <code xref="mal_info_name">name</code> element, - an optional <code xref="mal_info_email">>email</code> element, - and an optional <code xref="mal_info_years">years</code> element. The - <code>credit</code> element can also contain elements from external - namespaces. The order of the child elements does not matter.</p></item> - - <item><p>The <code>credit</code> element can occur in any - <code xref="mal_info">info</code> element.</p></item> - - <item> - <p>The optional <code>type</code> attribute can be used to specify - what type of contribution the person has made. The <code>type</code> - attribute contains a space-separated list of credit types. The following - values are recommended:</p> - - <table rules="rows"> - <tr> - <td><p><code>"author"</code></p></td> - <td><p>somebody responsible for writing content</p></td> - </tr> - <tr> - <td><p><code>"editor"</code></p></td> - <td><p>somebody who has provided reviews or editorial corrections</p></td> - </tr> - <tr> - <td><p><code>"copyright"</code></p></td> - <td><p>a person or entity which holds copyright on the work</p></td> - </tr> - <tr> - <td><p><code>"maintainer"</code></p></td> - <td><p>the person or entity currently responsible for the work</p></td> - </tr> - <tr> - <td><p><code>"collaborator"</code></p></td> - <td><p>somebody who has provided extensive rough information</p></td> - </tr> - <tr> - <td><p><code>"translator"</code></p></td> - <td><p>somebody who has translated the work into another language</p></td> - </tr> - <tr> - <td><p><code>"publisher"</code></p></td> - <td><p>a person or entity who distributes formatted copies</p></td> - </tr> - </table> - </item> - - <item><p>The <code>credit</code> element can have attributes from external - namespaces. See <link xref="mal_external"/> for more information - on external-namespace attributes.</p></item> - </list> -</section> -<!-- END notes --> - - -<!-- BEGIN processing --> -<section id="processing"> - <title>Processing Expectations</title> - - <p>There are no specific processing expectations for the <code>credit</code> - element. As an informational element, it is not necessarily displayed. Some - tools, however, may choose to display credits at the bottom of a page, on a - separate information page, or in a dialog.</p> - - <p>When processing the children of a <code>credit</code> element, tools - should select the child elements they understand and ignore all other child - content.</p> -</section> -<!-- END processing --> - - -<!-- BEGIN comparison --> -<section id="comparison"> - <title>Comparison to Other Formats</title> - - <p>The <code>credit</code> element serves the purpose of the - <code href="http://www.docbook.org/tdg/en/html/author.html">author</code>, - <code href="http://www.docbook.org/tdg/en/html/collab.html">collab</code>, - <code href="http://www.docbook.org/tdg/en/html/corpauthor.html">corpauthor</code>, - <code href="http://www.docbook.org/tdg/en/html/editor.html">editor</code>, - <code href="http://www.docbook.org/tdg/en/html/othercredit.html">othercredit</code>, and - <code href="http://www.docbook.org/tdg/en/html/publisher.html">publisher</code> - elements in DocBook. DocBook does not have specific elements for maintainers - and translators.</p> - - <p>In DocBook, certain credit elements have highly structured content, whereas - others allow simple inline text. In Mallard, all credits use simple structured - content. While Mallard does not provide child elements for everything that can - be recorded in DocBook, elements from external namespaces may be used for any - additional information that is needed.</p> - - <p>The <code>credit</code> element also records copyright information. - In this capacity, it is similar to the - <code href="http://www.docbook.org/tdg/en/html/copyright.html">copyright</code> - element in DocBook.</p> -</section> -<!-- END comparison --> - -</page> diff --git a/doc/mallard/C/mal_info_desc.page b/doc/mallard/C/mal_info_desc.page deleted file mode 100644 index 8ccfbdf..0000000 --- a/doc/mallard/C/mal_info_desc.page +++ /dev/null @@ -1,70 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="mal_info_desc"> - -<info> - <link type="guide" xref="mal_info#elements"/> - - <revision version="0.1" date="2009-05-29" status="review"/> - - <credit type="author"> - <name>Shaun McCance</name> - <email>shaunm@gnome.org</email> - <years>2008-2009</years> - </credit> - - <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" /> - - <desc>Provide a short description of a page or section.</desc> -</info> - -<title>Page Descriptions</title> - -<synopsis><code mime="application/relax-ng-compact-syntax"> -mal_info_desc = element desc { - attribute * - (mal:* | local:*) { text } *, - - <link xref="mal_inline">mal_inline</link> -} -</code></synopsis> - -<p>The <code>desc</code> element can be used to provide a short description -for a page or section. While this description is generally not shown on the -page itself, it is used in automatic links to the page or section. It may -also be used for various other purposes by different tools.</p> - -<!-- BEGIN notes --> -<section id="notes"> - <title>Notes</title> - - <list> - <item><p>The <code>desc</code> element can contain a mixture of text and - any <link xref="mal_inline">general inline elements</link>.</p></item> - - <item><p>The <code>desc</code> element can occur in any - <code xref="mal_info">info</code> element.</p></item> - - <item><p>The <code>desc</code> element can have attributes from external - namespaces. See <link xref="mal_external"/> for more information - on external-namespace attributes.</p></item> - - <item><p>The <code>desc</code> element can also be used in a block context. - See <link xref="mal_block_desc"/> for more information.</p></item> - </list> -</section> -<!-- END notes --> - - -<!-- BEGIN processing --> -<section id="processing"> - <title>Processing Expectations</title> - - <p>The <code>desc</code> is not necessarily displayed on the page in which it - appears. It is, however, used for <link xref="links">automatic links</link>, - which usually display a link block showing the title and description of the - linked-to page or section. When it is displayed, its contents are treated - as inline content.</p> -</section> -<!-- END processing --> - -</page> diff --git a/doc/mallard/C/mal_info_email.page b/doc/mallard/C/mal_info_email.page deleted file mode 100644 index e70a70f..0000000 --- a/doc/mallard/C/mal_info_email.page +++ /dev/null @@ -1,75 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="mal_info_email"> - -<info> - <link type="guide" xref="mal_info#additional"/> - - <revision version="0.1" date="2009-09-08" status="review"/> - - <credit type="author"> - <name>Shaun McCance</name> - <email>shaunm@gnome.org</email> - <years>2009</years> - </credit> - - <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" /> - - <desc>FIXME</desc> -</info> - -<title>Email Addresses</title> - -<synopsis><code mime="application/relax-ng-compact-syntax"> -mal_info_email = element email { - attribute * - (mal:* | local:*) { text } *, - <link xref="mal_inline">mal_inline</link> -} -</code></synopsis> - -<p>Use the <code>email</code> element to mark up the email address for a -person or organization in a <code xref="mal_info_credit">credit</code> element.</p> - - -<!-- BEGIN notes --> -<section id="notes"> - <title>Notes</title> - <list> - <item><p>The <code>email</code> element can contain a mixture of text and - any <link xref="mal_inline">general inline elements</link>.</p></item> - - <item><p>The <code>email</code> element can occur in the - <code xref="mal_info_credit">credit</code> element.</p></item> - - <item><p>The <code>email</code> element can have attributes from external - namespaces. See <link xref="mal_external"/> for more information - on external-namespace attributes.</p></item> - </list> -</section> -<!-- END notes --> - - -<!-- BEGIN processing --> -<section id="processing"> - <title>Processing Expectations</title> - - <p>See the processing expectations for the - <code xref="mal_info_credit">credit</code> element.</p> -</section> -<!-- END processing --> - - -<!-- BEGIN comparison --> -<section id="comparison"> - <title>Comparison to Other Formats</title> - - <p>The <code>email</code> element is similar to the - <code href="http://www.docbook.org/tdg/en/html/email.html">email</code> - element in DocBook when that element is used in an informational context. - The <code>email</code> element in Mallard does not double as an inline - element.</p> -</section> -<!-- END comparison --> - - -</page> diff --git a/doc/mallard/C/mal_info_license.page b/doc/mallard/C/mal_info_license.page deleted file mode 100644 index 87d165f..0000000 --- a/doc/mallard/C/mal_info_license.page +++ /dev/null @@ -1,90 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="mal_info_license"> - -<info> - <link type="guide" xref="mal_info#elements"/> - - <revision version="0.1" date="2009-05-28" status="review"/> - - <credit type="author"> - <name>Shaun McCance</name> - <email>shaunm@gnome.org</email> - <years>2008-2009</years> - </credit> - - <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" /> - - <desc>Provide information about the licensing terms of the material.</desc> -</info> - -<title>License Information</title> - -<synopsis><code mime="application/relax-ng-compact-syntax"> -mal_info_license = element license { - attribute href { text } ?, - attribute * - (mal:* | local:*) { text } *, - - <link xref="mal_block">mal_block</link> + -} -</code></synopsis> - -<p>The <code>license</code> element can be used to provide information about -the licensing terms of the material in a page or section. The <code>href</code> -attribute can be used to uniquely identify certain licenses.</p> - -<!-- BEGIN notes --> -<section id="notes"> - <title>Notes</title> - <list> - <item><p>The <code>license</code> element can contain any - <link xref="mal_block">general block content</link>.</p></item> - - <item><p>The <code>license</code> element can occur in any - <code xref="mal_info">info</code> element.</p></item> - - <item><p>The <code>href</code> attribute can be used to provide a URI which - uniquely identifies the license terms.</p></item> - - <item><p>The <code>license</code> element can have attributes from external - namespaces. See <link xref="mal_external"/> for more information - on external-namespace attributes.</p></item> - </list> -</section> -<!-- END notes --> - -<!-- BEGIN processing --> -<section id="processing"> - <title>Processing Expectations</title> - - <p>The <code>license</code> is not necessarily displayed on the page in - which it appears. Some tools may display license information on a separate - informational page or dialog. When it is displayed, its contents are treated - as block content.</p> - - <p>There is no requirement that the URI <code>href</code> will actually - be displayed, or that the <code>href</code> attribute will cause a link - to be displayed. If authors wish to ensure that an external resource - is linked to, they should add a link into the block content. Processing - tools may recognize certain license URIs for special processing. This - could be used, for instance, to place a license badge at the bottom of - a displayed page for certain common licenses.</p> -</section> -<!-- END processing --> - -<!-- BEGIN comparison --> -<section id="comparison"> - <title>Comparison to Other Formats</title> - - <p>DocBook contains the more general-purpose - <code href="http://www.docbook.org/tdg/en/html/legalnotice.html">legalnotice</code> - element, which is frequently used to include licensing terms. The - <code>license</code> element is intended mostly for redistribution - terms, which are not immediately relevent to most readers. When it - is important that readers see certain legal information, authors - should provide that information in the main content, possibly on a - separate page.</p> -</section> -<!-- END comparison --> - -</page> diff --git a/doc/mallard/C/mal_info_link.page b/doc/mallard/C/mal_info_link.page deleted file mode 100644 index 5431bb2..0000000 --- a/doc/mallard/C/mal_info_link.page +++ /dev/null @@ -1,21 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="mal_info_link"> - -<info> - <link type="guide" xref="mal_info#elements"/> - - <revision version="0.1" date="2007-02-21" status="stub"/> -</info> - -<title>Hyperlinks</title> - -<synopsis><code mime="application/relax-ng-compact-syntax"> -mal_info_link = element link { - attribute type { "guide" | "topic" | "seealso" }, - attribute xref { text }, - attribute weight { text } ? -} -</code></synopsis> - -</page> diff --git a/doc/mallard/C/mal_info_name.page b/doc/mallard/C/mal_info_name.page deleted file mode 100644 index d41dc82..0000000 --- a/doc/mallard/C/mal_info_name.page +++ /dev/null @@ -1,79 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="mal_info_name"> - -<info> - <link type="guide" xref="mal_info#additional"/> - - <revision version="0.1" date="2009-08-01" status="review"/> - - <credit type="author"> - <name>Shaun McCance</name> - <email>shaunm@gnome.org</email> - <years>2009</years> - </credit> - - <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" /> - - <desc>FIXME</desc> -</info> - -<title>Names</title> - -<synopsis><code mime="application/relax-ng-compact-syntax"> -mal_info_name = element name { - attribute * - (mal:* | local:*) { text } *, - <link xref="mal_inline">mal_inline</link> -} -</code></synopsis> - -<p>Use the <code>name</code> element to mark up the name of a person or -organization in a <code xref="mal_info_credit">credit</code> element.</p> - - -<!-- BEGIN notes --> -<section id="notes"> - <title>Notes</title> - <list> - <item><p>The <code>name</code> element can contain a mixture of text and - any <link xref="mal_inline">general inline elements</link>.</p></item> - - <item><p>The <code>name</code> element can occur in the - <code xref="mal_info_credit">credit</code> element.</p></item> - - <item><p>The <code>name</code> element can have attributes from external - namespaces. See <link xref="mal_external"/> for more information - on external-namespace attributes.</p></item> - </list> -</section> -<!-- END notes --> - - -<!-- BEGIN processing --> -<section id="processing"> - <title>Processing Expectations</title> - - <p>See the processing expectations for the - <code xref="mal_info_credit">credit</code> element.</p> -</section> -<!-- END processing --> - - -<!-- BEGIN comparison --> -<section id="comparison"> - <title>Comparison to Other Formats</title> - - <p>The <code>name</code> element fulfills the same role as numerous DocBook - elements, including - <link href="http://www.docbook.org/tdg/en/html/collabname.html">collabname</link>, - <link xref="http://www.docbook.org/tdg/en/html/personname.html">personname</link>, and - <link xref="http://www.docbook.org/tdg/en/html/publishername.html">publishername</link>. - Note that Mallard does not attempt to model the names of people, as the rules for - how to display names from their constituent parts vary considerably. If parts of - a name are needed for a domain-specific purpose, they can be included using elements - from external namespaces on the parent element.</p> -</section> -<!-- END comparison --> - - -</page> diff --git a/doc/mallard/C/mal_info_revision.page b/doc/mallard/C/mal_info_revision.page deleted file mode 100644 index 91c3506..0000000 --- a/doc/mallard/C/mal_info_revision.page +++ /dev/null @@ -1,152 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="mal_info_revision"> - -<info> - <link type="guide" xref="mal_info#elements"/> - - <revision version="0.1" date="2009-05-29" status="review"/> - - <credit type="author"> - <name>Shaun McCance</name> - <email>shaunm@gnome.org</email> - <years>2008-2009</years> - </credit> - - <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" /> - - <desc>Record revision numbers, dates, and statuses.</desc> -</info> - -<title>Version Information</title> - -<synopsis><code mime="application/relax-ng-compact-syntax"> -mal_info_revision = element revision { - attribute version { text } ?, - attribute docversion { text } ?, - attribute pkgversion { text } ?, - attribute date { xsd:date } ?, - attribute status { - "stub" | "incomplete" | "draft" | "outdated" | - "review" | "candidate" | "final" } ?, - attribute * - (mal:* | local:*) { text } *, - - <link xref="mal_block_title">mal_block_title</link> ?, - <link xref="mal_block_desc">mal_block_desc</link> ?, - <link xref="mal_external">mal_external</link> * -} -</code></synopsis> - -<p>Use the <code>revision</code> information to record information about -revisions of a document, page, or section. The <code>revision</code> -element allows you to specify version numbers, the revision date, and -the revision status. Other information can be recorded with attributes -or elements from external namespaces. Multiple <code>revision</code> -elements can be used to record the revision history.</p> - -<p>You can use the <code>title</code> and <code>desc</code> elements -in a <code>revision</code> element to provide a title and description -of that revision. This is not necessarily the same as the title and -description of the page or section as of that revision.</p> - -<!-- BEGIN notes --> -<section id="notes"> - <title>Notes</title> - <list> - <item><p>The <code>revision</code> element contains an optional - <code xref="mal_block_title">title</code> element, an optional - <code xref="mal_block_desc">desc</code> element, and any number - of elements from external namespaces.</p></item> - - <item><p>The <code>revision</code> element can occur in any - <code xref="mal_info">info</code> element.</p></item> - - <item><p>The <code>version</code> attribute records the version number - of the page or section.</p></item> - - <item><p>The <code>docversion</code> attribute can be used to record the - version number of the enclosing document.</p></item> - - <item><p>The <code>pkgversion</code> attribute can be used to record the - version number of the package containing this document.</p></item> - - <item><p>The <code>date</code> attribute records the date this revision - was made.</p></item> - - <item><p>The <code>status</code> attribute records the status of the page - or section as of the given revision. The following values are allowed:</p> - <table rules="rows"> - <tr> - <td><p><code>"stub"</code></p></td> - <td><p>contains little to no real content</p></td> - </tr> - <tr> - <td><p><code>"incomplete"</code></p></td> - <td><p>outline of all information, but lacking content</p></td> - </tr> - <tr> - <td><p><code>"draft"</code></p></td> - <td><p>all content available, but unpolished</p></td> - </tr> - <tr> - <td><p><code>"outdated"</code></p></td> - <td><p>was once complete or nearly complete, but needs to be revised - to reflect changes</p></td> - </tr> - <tr> - <td><p><code>"review"</code></p></td> - <td><p>ready to be reviewed by editors</p></td> - </tr> - <tr> - <td><p><code>"candidate"</code></p></td> - <td><p>reviewed and awaiting a final approval</p></td> - </tr> - <tr> - <td><p><code>"final"</code></p></td> - <td><p>approved and ready for publication or distribution</p></td> - </tr> - </table> - </item> - - <item><p>The <code>revision</code> element can have attributes from external - namespaces. See <link xref="mal_external"/> for more information - on external-namespace attributes.</p></item> - </list> -</section> -<!-- END notes --> - - -<!-- BEGIN processing --> -<section id="processing"> - <title>Processing Expectations</title> - - <p>As an informational element, the <code>revision</code> element is not - necessarily displayed directly on the page or section in which it appears. - Some tools may show revision on a separate informational page or dialog. - Tools designed for editors might show revision information directly.</p> - - <p>When a <code>revision</code> element is displayed or processed, tools - should process only those child elements that they understand, and ignore - everything else.</p> -</section> -<!-- END processing --> - - -<!-- BEGIN comparison --> -<section id="comparison"> - <title>Comparison to Other Formats</title> - - <p>The <code>revision</code> element is similar to the - <code href="http://www.docbook.org/tdg/en/html/revision.html">revision</code> - element in DocBook. In DocBook, <code>revision</code> elements must occur - inside a - <code href="http://www.docbook.org/tdg/en/html/revhistory.html">revhistory</code> - element. In Mallard, they are placed directly in an - <code xref="mal_info">info</code> element. DocBook provides more specific - child elements for structured content, as well as for block content for - detailed remarks. Mallard allows such information to be encoded with - elements from external namespaces when needed.</p> -</section> -<!-- END comparison --> - -</page> diff --git a/doc/mallard/C/mal_info_title.page b/doc/mallard/C/mal_info_title.page deleted file mode 100644 index 3b26f3d..0000000 --- a/doc/mallard/C/mal_info_title.page +++ /dev/null @@ -1,137 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="mal_info_title"> - -<info> - <link type="guide" xref="mal_info#elements"/> - - <revision version="0.1" date="2009-05-29" status="review"/> - - <credit type="author"> - <name>Shaun McCance</name> - <email>shaunm@gnome.org</email> - <years>2008-2009</years> - </credit> - - <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" /> - - <desc>Provide alternate titles for automatic link text and sorting.</desc> -</info> - -<title>Informational Tiltes</title> - -<synopsis><code mime="application/relax-ng-compact-syntax"> -mal_info_title = element title { - attribute type { xsd:NMTOKEN }, - attribute role { xsd:NMTOKEN } ?, - attribute * - (mal:* | local:*) { text } *, - - <link xref="mal_inline">mal_inline</link> -} -</code></synopsis> - -<p>Use the <code>title</code> element inside an <code xref="mal_info">info</code> -to list alternative titles for pages and sections. These titles can be used -as alternative link text, for sorting, or for other application-specific -purposes.</p> - - -<!-- BEGIN notes --> -<section id="notes"> - <title>Notes</title> - <list> - <item><p>The <code>title</code> element can contain a mixture of text and - any <link xref="mal_inline">general inline elements</link>.</p></item> - - <item><p>The <code>title</code> element can occur in any - <code xref="mal_info">info</code> element.</p></item> - - <item><p>The <code>type</code> attribute specifies what purpose this - informational title is serving. The following values are currently - recognized:</p> - <table rules="rows"> - <tr> - <td><p><code>"link"</code></p></td> - <td><p>specifies alternate link text; see <link xref="#link"/></p></td> - </tr> - <tr> - <td><p><code>"sort"</code></p></td> - <td><p>specifies a sort key; see <link xref="#sort"/></p></td> - </tr> - </table></item> - - <item><p>The <code>role</code> attribute can be used for link titles - to specify multiple alternate link texts.</p></item> - - <item><p>The <code>title</code> element can have attributes from external - namespaces. See <link xref="mal_external"/> for more information - on external-namespace attributes.</p></item> - </list> -</section> -<!-- END notes --> - - -<!-- BEGIN primary --> -<section id="primary"> - <title>Primary Titles</title> - - <p>The <em>primary title</em> of a page or section is the one specified in - the block context and used for display purpose. While this title is not - an informational title as specified here, it is used as fallback for all - informational titles.</p> -</section> -<!-- END primary --> - - -<!-- BEGIN link --> -<section id="link"> - <title>Link Titles</title> - - <p>Pages and sections can have multiple link titles. These are used as - alternate content for automatic link text. When automatic text must be - generated for a <code xref="mal_block_link">link</code> element, it is - taken first from the link titles, falling back to the primary title if - no suitable link title is found.</p> - - <p>You can use the <code>role</code> attribute to specify multiple link - titles. These can be selected using the <code>role</code> attribute of - the <code>link</code> element. This can be used for a variety of purposes. - One common purpose is to specify link text for different parts of speech - in languages which have case declensions. Without this feature, it can - be difficult to provide grammatically correct automatic link text in - some languages.</p> -</section> -<!-- END link --> - - -<!-- BEGIN sort --> -<section id="sort"> - <title>Sort Titles</title> - - <p>Sort titles allow you to specify alternate text to be used when sorting - the page or section. Certain automatic link sections will sort the nodes - they link to. When this happens, providing a sort title allows you to - control how the node is collated. This is useful for excluding leading - articles such as “an” and “the”.</p> -</section> -<!-- END sort --> - - -<!-- BEGIN processing --> -<section id="processing"> - <title>Processing Expectations</title> - - <p>Informational titles are not displayed directly, although they will - affect the output of any material which links to the given page or - section.</p> - - <p>The content model of the <code xref="mal_info">info</code> element - allows for any mixture of informational titles. As such, it is entirely - possible for multiple titles to exist for some specified combination of - the <code>type</code> and <code>role</code> attributes. When such an - ambiguity arrises, processing tools should select the first informational - title that matches the desired criteria.</p> -</section> -<!-- END processing --> - -</page> diff --git a/doc/mallard/C/mal_info_years.page b/doc/mallard/C/mal_info_years.page deleted file mode 100644 index 8fef04a..0000000 --- a/doc/mallard/C/mal_info_years.page +++ /dev/null @@ -1,74 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="mal_info_years"> - -<info> - <link type="guide" xref="mal_info#additional"/> - - <revision version="0.1" date="2009-09-08" status="stub"/> - - <credit type="author"> - <name>Shaun McCance</name> - <email>shaunm@gnome.org</email> - <years>2009</years> - </credit> - - <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" /> - - <desc>FIXME</desc> -</info> - -<title>Copyright Years</title> - -<synopsis><code mime="application/relax-ng-compact-syntax"> -mal_info_years = element years { - attribute * - (mal:* | local:*) { text } *, - <link xref="mal_inline">mal_inline</link> -} -</code></synopsis> - -<p>Use the <code>years</code> element to mark up the years for which -a person or organization holds a copyright.</p> - - -<!-- BEGIN notes --> -<section id="notes"> - <title>Notes</title> - <list> - <item><p>The <code>years</code> element can contain a mixture of text and - any <link xref="mal_inline">general inline elements</link>.</p></item> - - <item><p>The <code>years</code> element can occur in the - <code xref="mal_info_credit">credit</code> element.</p></item> - - <item><p>The <code>years</code> element can have attributes from external - namespaces. See <link xref="mal_external"/> for more information - on external-namespace attributes.</p></item> - </list> -</section> -<!-- END notes --> - - -<!-- BEGIN processing --> -<section id="processing"> - <title>Processing Expectations</title> - - <p>See the processing expectations for the - <code xref="mal_info_credit">credit</code> element.</p> -</section> -<!-- END processing --> - - -<!-- BEGIN comparison --> -<section id="comparison"> - <title>Comparison to Other Formats</title> - - <p>The <code>years</code> element is similar to the - <code href="http://www.docbook.org/tdg/en/html/year.html">year</code> element - in DocBook. In DocBook, each year is listed separately, and processing tools - are expected to join them appropriately. In Mallard, all years are listed in - a single <code>years</code> element, formatted as they should be displayed.</p> -</section> -<!-- END comparison --> - -</page> diff --git a/doc/mallard/C/mal_inline.page b/doc/mallard/C/mal_inline.page deleted file mode 100644 index f2cc5cd..0000000 --- a/doc/mallard/C/mal_inline.page +++ /dev/null @@ -1,97 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="guide" - id="mal_inline"> - -<info> - <link type="guide" xref="spec"/> - - <revision version="0.1" date="2009-04-16" status="review"/> - - <credit type="author"> - <name>Shaun McCance</name> - <email>shaunm@gnome.org</email> - <years>2009</years> - </credit> - - <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" /> - - <desc>Rich semantic elements for marking up inline content.</desc> -</info> - -<title>Inline Elements</title> - -<synopsis><code mime="application/relax-ng-compact-syntax"> -mal_inline = { - <link xref="mal_inline_app">mal_inline_app</link> * & - <link xref="mal_inline_cmd">mal_inline_cmd</link> * & - <link xref="mal_inline_code">mal_inline_code</link> * & - <link xref="mal_inline_em">mal_inline_em</link> * & - <link xref="mal_inline_file">mal_inline_file</link> * & - <link xref="mal_inline_gui">mal_inline_gui</link> * & - <link xref="mal_inline_guiseq">mal_inline_guiseq</link> * & - <link xref="mal_inline_input">mal_inline_input</link> * & - <link xref="mal_inline_key">mal_inline_key</link> * & - <link xref="mal_inline_keyseq">mal_inline_keyseq</link> * & - <link xref="mal_inline_link">mal_inline_link</link> * & - <link xref="mal_inline_media">mal_inline_media</link> * & - <link xref="mal_inline_output">mal_inline_output</link> * & - <link xref="mal_inline_span">mal_inline_span</link> * & - <link xref="mal_inline_sys">mal_inline_sys</link> * & - <link xref="mal_inline_var">mal_inline_var</link> * & - element * - (mal:* | local:*) { mal_inline } * & - text ? -} -</code></synopsis> - -<p>Mallard provides a small but rich set of semantic inline elements. -The elements provided are culled from first-hand experience with software -documentation and other document formats. The inline elements defined in -this specification will serve most software documentation writers' needs -well.</p> - -<p>Authors, editors, or other content producers sometimes need to supply -richer information in their documents. While this information may not -be conveyed by display tools, it may be used for various internal tracking -purposes. Mallard allows elements to be extended with attributes from -external namespaces. See <link xref="mal_external"/> for more -information.</p> - -<p>Furthermore, Mallard allows elements from external namespaces to be -used in any inline context. See <link xref="#processing"/> below for -more information.</p> - - -<!-- BEGIN elements --> -<section id="elements" style="2column"> - <info> - <title type="link">Inline Elements</title> - </info> - <title>Elements</title> -</section> -<!-- END elements --> - - -<!-- BEGIN processing --> -<section id="processing"> - <info> - <title type="link">Inline Processing Instructions</title> - </info> - <title>Processing Expectations</title> - - <p>Inline elements occur within block elements or other inline elements. - Mallard never allows block elements within inline elements. Inline elements - should never introduce a line break in the rendered output.</p> - - <p>Different inline elements may introduce different styling effects, such - as font variations, text and background colors, and backgrounds. Generally, - if a styling effect is set for a particular element, it is in effect for all - descendant elements, unless explicitly overridden.</p> - - <p>Mallard allows elements from external namespaces to be used in any inline - context. Processing tools may have special behavior for particular elements - they understand. Otherwise, an unknown inline element should be processed - as if it were replaced by its child content.</p> -</section> -<!-- END processing --> - -</page> diff --git a/doc/mallard/C/mal_inline_app.page b/doc/mallard/C/mal_inline_app.page deleted file mode 100644 index 557c98b..0000000 --- a/doc/mallard/C/mal_inline_app.page +++ /dev/null @@ -1,129 +0,0 @@ -<?xml version="1.0" encoding="utf-8"?> -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="mal_inline_app"> - -<info> - <link type="guide" xref="mal_inline#elements"/> - - <revision version="0.1" date="2008-12-12" status="review"/> - - <credit type="author"> - <name>Shaun McCance</name> - <email>shaunm@gnome.org</email> - <years>2007-2009</years> - </credit> - - <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" /> - - <desc>Mark up the human-readable name of an application or window.</desc> -</info> - -<title>Application Names</title> - -<synopsis><code mime="application/relax-ng-compact-syntax"> -mal_inline_app = element app { - <link xref="mal_attr_link">mal_attr_link</link> ?, - attribute style { xsd:NMTOKENS } ?, - attribute * - (mal:* | local:*) { text } *, - - <link xref="mal_inline">mal_inline</link> -} -</code></synopsis> - -<p>Use the <code>app</code> element to mark up the human-readable name of an -application or the title of a window within an application. Do not use the -<code>app</code> element to mark up the command used to run an application; -use <code xref="mal_inline_cmd">cmd</code> for this purpose instead.</p> - - -<!-- BEGIN notes --> -<section id="notes"> - <title>Notes</title> - <list> - <item><p>The <code>app</code> element can contain a mixture of text and - any <link xref="mal_inline">general inline elements</link>.</p></item> - - <item><p>The <code>app</code> element can occur in any - general inline context, including inside most - <link xref="mal_inline">inline elements</link>, some - <link xref="mal_block#basic">basic block elements</link>, and certain - <link xref="mal_info">informational elements</link>.</p></item> - - <item><p>The <code>app</code> element can link to other pages or documents. - See <link xref="mal_attr_link"/> for more information.</p></item> - - <item><p>The <code>style</code> attribute takes a space-separated list of - style hints. Processing tools should adjust their behavior according to - those style hints they understand.</p></item> - - <item><p>The <code>app</code> element can have attributes from external - namespaces. See <link xref="mal_external"/> for more information - on external-namespace attributes.</p></item> - </list> -</section> -<!-- END notes --> - - -<!-- BEGIN examples --> -<section id="examples"> - <title>Examples</title> - - <p>Use <code>app</code> to mark up the name of an application:</p> - - <example> - <code><![CDATA[ -To start <app>Totem Movie Player</app>, enter <cmd>totem</cmd> at -the command line. -]]></code> - <p>To start <app>Totem Movie Player</app>, enter <cmd>totem</cmd> at the - command line.</p> - </example> - - <p>Use <code>app</code> to refer to a window:</p> - - <example> - <code><![CDATA[ -Use the <app>Theme Preferences</app> window to adjust the look of -your desktop. -]]></code> - <p>Use the <app>Theme Preferences</app> window to adjust the look of your desktop.</p> - </example> -</section> -<!-- END examples --> - - -<!-- BEGIN processing --> -<section id="processing"> - <title>Processing Expectations</title> - - <p>Application names are usually nouns, and are often common words or phrases - that are indicative of their functionality. Frequently, they are simply the - name of what the application is. In English and many other languages, the - use of an application name in a sentence may sound like the author has simply - mistakenly omitted an article, if the application name is not understood to - be a title.</p> - - <p>For example, the calculator application that comes with Gnome is called - <app>Calculator</app>. If an author were to write “To start Calculator…”, - then a reader may confuse this for “To start the calculator…” with an error. - This is even more pronounced in languages such as German where nouns are - always capitalized.</p> - - <p>For this reason, it is recommended that application names marked with the - <code>app</code> element are rendered in italics or using some other font - variation.</p> -</section> -<!-- END processing --> - - -<!-- BEGIN comparison --> -<section id="comparison"> - <title>Comparison to Other Formats</title> - <p>The <code>app</code> element is similar to the - <code href="http://www.docbook.org/tdg/en/html/application.html">application</code> - element in DocBook.</p> -</section> -<!-- END comparison --> - -</page> diff --git a/doc/mallard/C/mal_inline_cmd.page b/doc/mallard/C/mal_inline_cmd.page deleted file mode 100644 index fa38094..0000000 --- a/doc/mallard/C/mal_inline_cmd.page +++ /dev/null @@ -1,176 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="mal_inline_cmd"> - -<info> - <link type="guide" xref="mal_inline#elements"/> - <link type="seealso" xref="mal_block_screen"/> - - <revision version="0.1" date="2008-12-01" status="review"/> - - <credit type="author"> - <name>Shaun McCance</name> - <email>shaunm@gnome.org</email> - <years>2007-2009</years> - </credit> - - <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" /> - - <desc>Mark up a command to be entered at an interactive shell.</desc> -</info> - -<title>Commands</title> - -<synopsis><code mime="application/relax-ng-compact-syntax"> -mal_inline_cmd = element cmd { - <link xref="mal_attr_link">mal_attr_link</link> ?, - attribute style { xsd:NMTOKENS } ?, - attribute mime { text } ?, - attribute * - (mal:* | local:*) { text } *, - - <link xref="mal_inline">mal_inline</link> -} -</code></synopsis> - -<p>Use the <code>cmd</code> element to mark up a command or a portion of a -command to run in an interactive shell. It is frequently used to mark up -the command to run an application. Do not use the <code>cmd</code> element -to mark up the human-readable name of an application; use -<code xref="mal_inline_app">app</code> for this purpose instead.</p> - -<p>You may use the <code>cmd</code> element to mark up the entire command, -including all arguments. Mallard does not contain elements to mark up the -arguments specifically, as there is rarely a need to distinguish them. -You may also use the <code>cmd</code> element to mark up parts of a command, -such as options and arguments, when these need to be referenced alone.</p> - -<p>Use the <code xref="mal_inline_var">var</code> element inside a -<code>cmd</code> element to indicate text that should be replaced -by the user.</p> - - -<!-- BEGIN notes --> -<section id="notes"> - <title>Notes</title> - <list> - <item><p>The <code>cmd</code> element can contain a mixture of text and - any <link xref="mal_inline">general inline elements</link>.</p></item> - - <item><p>The <code>cmd</code> element can occur in any - general inline context, including inside most - <link xref="mal_inline">inline elements</link>, some - <link xref="mal_block#basic">basic block elements</link>, and certain - <link xref="mal_info">informational elements</link>.</p></item> - - <item><p>The <code>cmd</code> element can link to other pages or documents. - See <link xref="mal_attr_link"/> for more information.</p></item> - - <item><p>The <code>style</code> attribute takes a space-separated list of - style hints. Processing tools should adjust their behavior according to - those style hints they understand.</p></item> - - <item><p>The <code>mime</code> attribute takes a valid MIME type. Processing - tools may adjust their behavior for particular MIME types.</p></item> - - <item> - <p>Typical values for the <code>mime</code> attribute include:</p> - <table rules="rows"><tr> - <td><p><code>application/x-sh</code></p></td> - <td><p>Command to execute with the Bourne shell</p></td> - </tr><tr> - <td><p><code>application/x-csh</code></p></td> - <td><p>Command to execute with the C shell</p></td> - </tr></table> - </item> - - <item><p>The <code>cmd</code> element can have attributes from external - namespaces. See <link xref="mal_external"/> for more information - on external-namespace attributes.</p></item> - </list> -</section> -<!-- END notes --> - - -<!-- BEGIN examples --> -<section id="examples"> - <title>Examples</title> - - <p>Use <code>cmd</code> to mark up a simple command to run:</p> - - <example> - <code><![CDATA[ -To start <app>Totem Movie Player</app>, enter <cmd>totem</cmd> at -the command line. -]]></code> - <p>To start <app>Totem Movie Player</app>, enter <cmd>totem</cmd> at the - command line.</p> - </example> - - <p>Use <code>cmd</code> with <code xref="mal_inline_var">var</code> to mark - up a command with a placeholder for an argument the user should supply:</p> - - <example> - <code><![CDATA[ -To view a file in <app>Totem Movie Player</app>, enter <cmd>totem -<var>file</var></cmd> at the command line, replacing <var>file</var> -with the name of the file. -]]></code> - <p>To view a file in <app>Totem Movie Player</app>, enter <cmd>totem <var>file</var></cmd> - at the command line, replacing <var>file</var> with the name of the file.</p> - </example> - - <p>Use <code>cmd</code> to mark up command names and options:</p> - - <example> - <code><![CDATA[ -The <cmd>-mtime</cmd> option for the <cmd>find</cmd> command allows -you to filter files based on their modification times. -]]></code> - <p>The <cmd>-mtime</cmd> option for the <cmd>find</cmd> command allows you to - filter files based on their modification times.</p> - </example> - -</section> -<!-- END examples --> - - -<!-- BEGIN processing --> -<section id="processing"> - <title>Processing Expectations</title> - <p>Commands are displayed in a fixed-width font. This mimics the look - of a typical environment where commands are executed. More importantly, - fixed-width fonts tend to have more distinction between visually similar - characters. This is particularly important in commands, since letters often - appear without the context of a known word that helps make them discernable - in normal prose.</p> - - <p>Commands in documentation are often provided with options to illustrate - how to use them to a particular effect. This can make it difficult to find - the end of the command quickly. Surrounding text content, especially - punctuation, can sometimes be confused for part of the command. For this - reason, it is recommended that commands be displayed with a border or - background color.</p> -</section> -<!-- END processing --> - - -<!-- BEGIN comparison --> -<section id="comparison"> - <title>Comparison to Other Formats</title> - - <p>The <code>cmd</code> element is similar to the - <code href="http://www.docbook.org/tdg/en/html/command.html">command</code> - element in DocBook. In DocBook, writers frequently use the - <code href="http://www.docbook.org/tdg/en/html/option.html">option</code> - element inside <code>command</code>. Mallard does not provide an element - for this purpose.</p> - - <p>In DocBook, the <code>option</code> element is also used outside the - <code>command</code> element. In Mallard, simply use the <code>cmd</code> - element for options outside of an entire command.</p> - - <p>See <link xref="principle-justenough"/> for more background.</p> -</section> -<!-- END comparison --> - -</page> diff --git a/doc/mallard/C/mal_inline_code.page b/doc/mallard/C/mal_inline_code.page deleted file mode 100644 index d75f1a0..0000000 --- a/doc/mallard/C/mal_inline_code.page +++ /dev/null @@ -1,168 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="mal_inline_code"> - -<info> - <link type="guide" xref="mal_inline#elements"/> - - <revision version="0.1" date="2008-12-12" status="review"/> - - <credit type="author"> - <name>Shaun McCance</name> - <email>shaunm@gnome.org</email> - <years>2008-2009</years> - </credit> - - <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" /> - - <desc>Mark up code from a programming, markup, or other machine-readable format.</desc> -</info> - -<title>Code Snippets</title> - -<synopsis><code mime="application/relax-ng-compact-syntax"> -mal_inline_code = element code { - <link xref="mal_attr_link">mal_attr_link</link> ?, - attribute style { xsd:NMTOKENS } ?, - attribute mime { text } ?, - attribute * - (mal:* | local:*) { text } *, - - <link xref="mal_inline">mal_inline</link> -} -</code></synopsis> - -<p>Use the <code>code</code> element to mark up a portion of text from a -computer language. This includes programming languages, markup languages, -and the contents of any type of file with a structured syntax. For commands -which are run in an interactive shell, however, you should use the -<code xref="mal_inline_cmd">cmd</code> element, even though they may -include snippets of shell programming.</p> - -<p>You can use the <code>code</code> element to mark up any portion of -code, including comments or textual content that doesn't strictly follow -any syntax.</p> - -<p>Use the <code xref="mal_inline_var">var</code> element inside a -<code>code</code> element to indicate text that should be replaced -by the user.</p> - - -<!-- BEGIN notes --> -<section id="notes"> - <title>Notes</title> - <list> - <item><p>The <code>code</code> element can contain a mixture of text and - any <link xref="mal_inline">general inline elements</link>.</p></item> - - <item><p>The <code>code</code> element can occur in any - general inline context, including inside most - <link xref="mal_inline">inline elements</link>, some - <link xref="mal_block#basic">basic block elements</link>, and certain - <link xref="mal_info">informational elements</link>.</p></item> - - <item><p>The <code>code</code> element can link to other pages or documents. - See <link xref="mal_attr_link"/> for more information.</p></item> - - <item><p>The <code>style</code> attribute takes a space-separated list of - style hints. Processing tools should adjust their behavior according to - those style hints they understand.</p></item> - - <item><p>The <code>mime</code> attribute takes a valid MIME type. Processing - tools may adjust their behavior for particular MIME types.</p></item> - - <item><p>The <code>code</code> element can have attributes from external - namespaces. See <link xref="mal_external"/> for more information - on external-namespace attributes.</p></item> - - <item><p>The <code>code</code> element may also be used in a block context. - See <link xref="mal_block_code"/> for more information.</p></item> - </list> -</section> -<!-- END notes --> - - -<!-- BEGIN examples --> -<section id="examples"> - <title>Examples</title> - - <p>Use <code>code</code> to mark up the name of a function, struct, or other - constuct in a programming language:</p> - - <example> - <code><![CDATA[ -Use <code>gtk_container_add</code> to add a child widget to a -<code>GtkButton</code>. -]]></code> - <p>Use <code>gtk_container_add</code> to add a child widget to a <code>GtkButton</code>.</p> - </example> - - <p>Use <code>code</code> with <code xref="mal_inline_var">var</code> to mark - up code with a placeholder for an argument the user should supply:</p> - - <example> - <code><![CDATA[ -To create a new button with a label, use -<code>gtk_button_new_with_label(<var>label</var>)</code>, -replacing <var>label</var> with the text of the label. -]]></code> - <p>To create a new button with a label, use - <code>gtk_button_new_with_label(<var>label</var>)</code>, - replacing <var>label</var> with the text of the label.</p> - </example> - - <p>Link to a web page directly with a <code>code</code> element:</p> - - <example> - <code><![CDATA[ -Use <code>code</code> with <code xref="mal_inline_var">var</code> to mark -up code with a placeholder for an argument the user should supply. -]]></code> - <p>Use <code>code</code> with <code xref="mal_inline_var">var</code> to mark - up code with a placeholder for an argument the user should supply.</p> - </example> -</section> -<!-- END examples --> - - -<!-- BEGIN processing --> -<section id="processing"> - <title>Processing Expectations</title> - <p>Code snippets are displayed in a fixed-width font. This mimics - the look of a typical environment where code is typed. More importantly, - fixed-width fonts tend to have more distinction between visually similar - characters. This is particularly important in code, since letters often - appear without the context of a known word that helps make them discernable - in normal prose.</p> - - <p>For particularly long code snippets, display tools may use a background - color or border to make the beginning and end clear, although authors should - prefer <link xref="mal_block_code">code blocks</link> for long code snippets.</p> -</section> -<!-- END processing --> - - -<!-- BEGIN comparison --> -<section id="comparison"> - <title>Comparison to Other Formats</title> - <p>The <code>code</code> element is similar to the - <code href="http://www.docbook.org/tdg/en/html/code.html">code</code> element - in DocBook. Since Mallard does not attempt to model programming languages, - <code>code</code> may be used in place of numerous DocBook elements, including - <code href="http://www.docbook.org/tdg/en/html/classname.html">classname</code>, - <code href="http://www.docbook.org/tdg/en/html/constant.html">constant</code>, - <code href="http://www.docbook.org/tdg/en/html/function.html">function</code>, - <code href="http://www.docbook.org/tdg/en/html/interfacename.html">interfacename</code>, - <code href="http://www.docbook.org/tdg/en/html/methodname.html">methodname</code>, - <code href="http://www.docbook.org/tdg/en/html/parameter.html">parameter</code>, - <code href="http://www.docbook.org/tdg/en/html/structfield.html">structfield</code>, - <code href="http://www.docbook.org/tdg/en/html/structname.html">structname</code>, and - <code href="http://www.docbook.org/tdg/en/html/varname.html">varname</code>. - Additionally, since Mallard does not provide separate elements for marking - portions of markup languages, the <code>code</code> element should be used - in place of the DocBook elements - <code href="http://www.docbook.org/tdg/en/html/markup.html">markup</code> and - <code href="http://www.docbook.org/tdg/en/html/sgmltag.html">sgmltag</code>.</p> -</section> -<!-- END comparison --> - -</page> diff --git a/doc/mallard/C/mal_inline_em.page b/doc/mallard/C/mal_inline_em.page deleted file mode 100644 index 92be5ae..0000000 --- a/doc/mallard/C/mal_inline_em.page +++ /dev/null @@ -1,121 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="mal_inline_em"> - -<info> - <link type="guide" xref="mal_inline#elements"/> - - <revision version="0.1" date="2008-12-16" status="review"/> - - <credit type="author"> - <name>Shaun McCance</name> - <email>shaunm@gnome.org</email> - <years>2008-2009</years> - </credit> - - <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" /> - - <desc>Emphasize important text.</desc> -</info> - -<title>Emphasis</title> - -<synopsis><code mime="application/relax-ng-compact-syntax"> -mal_inline_em = element em { - <link xref="mal_attr_link">mal_attr_link</link> ?, - attribute style { xsd:NMTOKENS } ?, - attribute * - (mal:* | local:*) { text } *, - - <link xref="mal_inline">mal_inline</link> -} -</code></synopsis> - -<p>Use the <code>em</code> element to emphasize text. You may use <code>em</code> -to stress certain words in a sentence. Do not use <code>em</code> to effect a -particular typographic style, since it may be rendered differently by different -display tools.</p> - - -<!-- BEGIN notes --> -<section id="notes"> - <title>Notes</title> - <list> - <item><p>The <code>em</code> element can contain a mixture of text and - any <link xref="mal_inline">general inline elements</link>.</p></item> - - <item><p>The <code>em</code> element can occur in any - general inline context, including inside most - <link xref="mal_inline">inline elements</link>, some - <link xref="mal_block#basic">basic block elements</link>, and certain - <link xref="mal_info">informational elements</link>.</p></item> - - <item><p>The <code>em</code> element can link to other pages or documents. - See <link xref="mal_attr_link"/> for more information.</p></item> - - <item><p>The <code>style</code> attribute takes a space-separated list of - style hints. Processing tools should adjust their behavior according to - those style hints they understand.</p></item> - - <item><p>The <code>em</code> element can have attributes from external - namespaces. See <link xref="mal_external"/> for more information - on external-namespace attributes.</p></item> - </list> -</section> -<!-- END notes --> - - -<!-- BEGIN examples --> -<section id="examples"> - <title>Examples</title> - - <p>Use <code>em</code> to stress a word in a sentence:</p> - - <example> - <code><![CDATA[ -You should <em>never</em> run a graphical application as root. -]]></code> - <p>You should <em>never</em> run a graphical application as root.</p> - </example> - - <p>Use <code>em</code> to mark the first occurance of a term:</p> - - <example> - <code><![CDATA[ -Note that <em>accelerators</em> are different from <em>mnemonics</em>. -]]></code> - <p>Note that <em>accelerators</em> are different from <em>mnemonics</em>.</p> - </example> -</section> -<!-- END examples --> - - -<!-- BEGIN processing --> -<section id="processing"> - <title>Processing Expectations</title> - <p>Emphasized text is traditionally presented in an italic or oblique font. - Italic and oblique fonts stress a portion of text without making it stand - out. By contrast, bold text tends to draw the eye, which can be distracting - when reading long passages of text. In scripts without a distinction between - roman and italic type styles, it may still be possible to use an oblique font - or some other font variation. Bold text may be used if necessary.</p> - <p>Underlining should be avoided completely, since it hurts the legibility - of the text. This problem is especially pronounced in scripts which place - diacritical marks below the text. In these scripts, underlining can render - the text completely illegible.</p> -</section> -<!-- END processing --> - - -<!-- BEGIN comparison --> -<section id="comparison"> - <title>Comparison to Other Formats</title> - <p>The <code>em</code> element is similar to the - <code href="http://www.docbook.org/tdg/en/html/emphasis.html">emphasis</code> - element in DocBook. Athough DocBook does not normatively specify a means of - controlling the presentation, most DocBook display tools allow writers to - set the <code>role</code> attribute to <code>bold</code> or <code>strong</code> - to specify bold text. No such recommendation is made for Mallard.</p> -</section> -<!-- END comparison --> - -</page> diff --git a/doc/mallard/C/mal_inline_file.page b/doc/mallard/C/mal_inline_file.page deleted file mode 100644 index 579ffd0..0000000 --- a/doc/mallard/C/mal_inline_file.page +++ /dev/null @@ -1,86 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="mal_inline_file"> - -<info> - <link type="guide" xref="mal_inline#elements"/> - - <revision version="0.1" date="2008-12-01" status="review"/> - - <credit type="author"> - <name>Shaun McCance</name> - <email>shaunm@gnome.org</email> - <years>2008-2009</years> - </credit> - - <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" /> - - <desc>Mark up the name of a file or directory.</desc> -</info> - -<title>Filenames</title> - -<synopsis><code mime="application/relax-ng-compact-syntax"> -mal_inline_file = element file { - <link xref="mal_attr_link">mal_attr_link</link> ?, - attribute style { xsd:NMTOKENS } ?, - attribute * - (mal:* | local:*) { text } *, - - <link xref="mal_inline">mal_inline</link> -} -</code></synopsis> - -<p>Use the <code>file</code> element to mark up the name of a file or -directory. You may also use it to mark up collections or portions of -filenames, such as search paths and file extensions.</p> - - -<!-- BEGIN notes --> -<section id="notes"> - <title>Notes</title> - <list> - <item><p>The <code>file</code> element can contain a mixture of text and - any <link xref="mal_inline">general inline elements</link>.</p></item> - - <item><p>The <code>file</code> element can occur in any - general inline context, including inside most - <link xref="mal_inline">inline elements</link>, some - <link xref="mal_block#basic">basic block elements</link>, and certain - <link xref="mal_info">informational elements</link>.</p></item> - - <item><p>The <code>file</code> element can link to other pages or documents. - See <link xref="mal_attr_link"/> for more information.</p></item> - - <item><p>The <code>style</code> attribute takes a space-separated list of - style hints. Processing tools should adjust their behavior according to - those style hints they understand.</p></item> - - <item><p>The <code>file</code> element can have attributes from external - namespaces. See <link xref="mal_external"/> for more information - on external-namespace attributes.</p></item> - </list> -</section> -<!-- END notes --> - - -<!-- BEGIN processing --> -<section id="processing"> - <title>Processing Expectations</title> - <p>Filenames should be displayed in a fixed-width or wide font. Fixed-width - fonts tend to have more distinction between visually similar characters. This - is particularly important in filenames, since letters often appear without the - context of a known word that helps make them discernable in normal prose.</p> -</section> -<!-- END processing --> - - -<!-- BEGIN comparison --> -<section id="comparison"> - <title>Comparison to Other Formats</title> - <p>The <code>file</code> element is similar to the - <code href="http://www.docbook.org/tdg/en/html/filename.html">filename</code> - element in DocBook.</p> -</section> -<!-- END comparison --> - -</page> diff --git a/doc/mallard/C/mal_inline_gui.page b/doc/mallard/C/mal_inline_gui.page deleted file mode 100644 index 5ce02bb..0000000 --- a/doc/mallard/C/mal_inline_gui.page +++ /dev/null @@ -1,174 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="mal_inline_gui"> - -<info> - <link type="guide" xref="mal_inline#elements"/> - - <revision version="0.1" date="2008-12-16" status="review"/> - - <credit type="author"> - <name>Shaun McCance</name> - <email>shaunm@gnome.org</email> - <years>2008-2009</years> - </credit> - - <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" /> - - <desc>Mark up control labels from a graphical user interface.</desc> -</info> - -<title>GUI Labels</title> - -<synopsis><code mime="application/relax-ng-compact-syntax"> -mal_inline_gui = element gui { - <link xref="mal_attr_link">mal_attr_link</link> ?, - attribute style { xsd:NMTOKENS } ?, - attribute * - (mal:* | local:*) { text } *, - - <link xref="mal_inline">mal_inline</link> -} -</code></synopsis> - -<p>Use the <code>gui</code> element to mark up the label of a control in -a graphical user interface. You can use <code>gui</code> for all sorts -of controls, including buttons, check boxes, and menu items. If necessary, -you can use the <code>style</code> attribute to indicate what kind of -control is being marked up.</p> - - -<!-- BEGIN notes --> -<section id="notes"> - <title>Notes</title> - <list> - <item><p>The <code>gui</code> element can contain a mixture of text and - any <link xref="mal_inline">general inline elements</link>.</p></item> - - <item><p>The <code>gui</code> element can occur in any - general inline context, including inside most - <link xref="mal_inline">inline elements</link>, some - <link xref="mal_block#basic">basic block elements</link>, and certain - <link xref="mal_info">informational elements</link>.</p></item> - - <item><p>The <code>gui</code> element can also occur inside the - <code xref="mal_inline_guiseq">guiseq</code> element, where it has - special meaning.</p></item> - - <item><p>The <code>gui</code> element can link to other pages or documents. - See <link xref="mal_attr_link"/> for more information.</p></item> - - <item><p>The <code>style</code> attribute takes a space-separated list of - style hints. Processing tools should adjust their behavior according to - those style hints they understand.</p></item> - - <item><p>Typical style hints include:</p> - <table rules="rows"> - <tr> - <td><p><code>button</code></p></td> - <td><p>The text of a button</p></td> - </tr> - <tr> - <td><p><code>checkbox</code></p></td> - <td><p>The label for a check box</p></td> - </tr> - <tr> - <td><p><code>group</code></p></td> - <td><p>The label for a group of controls</p></td> - </tr> - <tr> - <td><p><code>input</code></p></td> - <td><p>The label for any text entry control</p></td> - </tr> - <tr> - <td><p><code>menu</code></p></td> - <td><p>The name of a menu</p></td> - </tr> - <tr> - <td><p><code>menuitem</code></p></td> - <td><p>The name of an item in a menu</p></td> - </tr> - <tr> - <td><p><code>radiobutton</code></p></td> - <td><p>The label for a radio button</p></td> - </tr> - <tr> - <td><p><code>tab</code></p></td> - <td><p>The label on a tab</p></td> - </tr> - </table></item> - - <item><p>The <code>gui</code> element can have attributes from external - namespaces. See <link xref="mal_external"/> for more information - on external-namespace attributes.</p></item> - </list> -</section> -<!-- END notes --> - - -<!-- BEGIN examples --> -<section id="examples"> - <title>Examples</title> - - <p>Use <code>gui</code> to mark up the text of a button:</p> - - <example> - <code><![CDATA[ -Click the <gui>Close</gui> button to close the window. -]]></code> - <p>Click the <gui>Close</gui> button to close the window.</p> - </example> - - <p>Use <code>gui</code> to mark up the label on a tab:</p> - - <example> - <code><![CDATA[ -The <gui>Filters</gui> tab contains options to change the behavior -of your keyboard to meet certain accessibility needs. -]]></code> - <p>The <gui>Filters</gui> tab contains options to change the behavior - of your keyboard to meet certain accessibility needs.</p> - </example> - -</section> -<!-- END examples --> - - -<!-- BEGIN processing --> -<section id="processing"> - <title>Processing Expectations</title> - - <p>No particular special rendering is required for <code>gui</code> elements. - Interface labels may be rendered with lightened text or other sublte styling - effects to distinguish them from the surrounding text.</p> - - <p>In certain environments, interface labels may be decorated with an icon or - other effect based on the <code>style</code> attribute. For example, in a - table of options where the first element of each row is a <code>gui</code> - element, those with the <code>checkbox</code> style hint could be decorated - with a check box icon.</p> -</section> -<!-- END processing --> - - -<!-- BEGIN comparison --> -<section id="comparison"> - <title>Comparison to Other Formats</title> - <p>The <code>gui</code> element is similar to the deprecated - <code href="http://www.docbook.org/tdg/en/html/interface.html">interface</code> - element in DocBook. DocBook 3 introduced more specific elements for marking up - parts of a user interface: - <code href="http://www.docbook.org/tdg/en/html/guibutton.html">guibutton</code>, - <code href="http://www.docbook.org/tdg/en/html/guiicon.html">guiicon</code>, - <code href="http://www.docbook.org/tdg/en/html/guilabel.html">guilabel</code>, - <code href="http://www.docbook.org/tdg/en/html/guimenu.html">guimenu</code>, - <code href="http://www.docbook.org/tdg/en/html/guimenuitem.html">guimenuitem</code>, and - <code href="http://www.docbook.org/tdg/en/html/guisubmenu.html">guisubmenu</code>. - In practice, there is rarely a need to distinguish between types of interface - elements in markup. When such a need arises, it can be handled using attributes - on a single element. Furthermore, DocBook's various elements are nowhere near - exhaustive. Thus, authors must frequently either abuse a specific element or - use the deprecated <code>interface</code> element.</p> -</section> -<!-- END comparison --> - -</page> diff --git a/doc/mallard/C/mal_inline_guiseq.page b/doc/mallard/C/mal_inline_guiseq.page deleted file mode 100644 index d2af913..0000000 --- a/doc/mallard/C/mal_inline_guiseq.page +++ /dev/null @@ -1,114 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="mal_inline_guiseq"> - -<info> - <link type="guide" xref="mal_inline#elements"/> - <link type="seealso" xref="mal_inline_gui"/> - - <revision version="0.1" date="2008-12-16" status="review"/> - - <credit type="author"> - <name>Shaun McCance</name> - <email>shaunm@gnome.org</email> - <years>2008-2009</years> - </credit> - - <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" /> - - <desc>Mark up a sequence of interface controls to navigate.</desc> -</info> - -<title>GUI Sequences</title> - -<synopsis><code mime="application/relax-ng-compact-syntax"> -mal_inline_guiseq = element guiseq { - attribute style { xsd:NMTOKENS } ?, - attribute * - (mal:* | local:*) { text } *, - - mixed { <link xref="mal_inline_gui">mal_inline_gui</link> + } -} -</code></synopsis> - -<p>Use the <code>guiseq</code> element to mark up a sequence of graphical -interface elements. This is typically used to present a sequence of menu -items.</p> - - -<!-- BEGIN notes --> -<section id="notes"> - <title>Notes</title> - <list> - <item><p>The <code>guiseq</code> element can contain a mixture of text and - <code xref="mal_inline_gui">gui</code> elements.</p></item> - - <item><p>The <code>guiseq</code> element can occur in any - general inline context, including inside most - <link xref="mal_inline">inline elements</link>, some - <link xref="mal_block#basic">basic block elements</link>, and certain - <link xref="mal_info">informational elements</link>.</p></item> - - <item><p>The <code>style</code> attribute takes a space-separated list of - style hints. Processing tools should adjust their behavior according to - those style hints they understand.</p></item> - - <item><p>The <code>guiseq</code> element can have attributes from external - namespaces. See <link xref="mal_external"/> for more information - on external-namespace attributes.</p></item> - </list> -</section> -<!-- END notes --> - - -<!-- BEGIN examples --> -<section id="examples"> - <title>Examples</title> - - <p>Use <code>guiseq</code> to mark up a sequence of menu items:</p> - - <example> - <code><![CDATA[ -Select <guiseq><gui>File</gui><gui>New</gui></guiseq> to open -a new document. -]]></code> - <p>Select <guiseq><gui>File</gui><gui>New</gui></guiseq> to open - a new document.</p> - </example> -</section> -<!-- END examples --> - - -<!-- BEGIN processing --> -<section id="processing"> - <title>Processing Expectations</title> - - <p>Each of the child <code>key</code> elements and text nodes, except - whitespace-only text nodes, is displayed as described below, adding a - separator between them. The exact separator may vary according to the - language and style preferences, but it will typically be some sort of - right-pointing arrow or triangle, or left-pointing for right-to-left - languages.</p> - - <p>Child <code>gui</code> elements are shown as normal. Text nodes - have their whitespace normalized to strip leading and trailing spaces. - Text nodes may be rendered using a font variation.</p> -</section> -<!-- END processing --> - - -<!-- BEGIN comparison --> -<section id="comparison"> - <title>Comparison to Other Formats</title> - <p>The <code>guiseq</code> element is similar to the - <code href="http://www.docbook.org/tdg/en/html/menuchoice.html">menuchoice</code> - element in DocBook. Since Mallard does not provide different elements for - different types of interface elements, the contents of <code>guiseq</code> - are all <code>gui</code> elements or text. Currently, Mallard does not - provide a way to encode shortcut keys like the - <code href="http://www.docbook.org/tdg/en/html/shortcut.html">shortcut</code> - element in DocBook. It is recommended that shortcuts, when necessary, be - written into prose separately.</p> -</section> -<!-- END comparison --> - -</page> diff --git a/doc/mallard/C/mal_inline_input.page b/doc/mallard/C/mal_inline_input.page deleted file mode 100644 index ef09cef..0000000 --- a/doc/mallard/C/mal_inline_input.page +++ /dev/null @@ -1,123 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="mal_inline_input"> - -<info> - <link type="guide" xref="mal_inline#elements"/> - <link type="seealso" xref="mal_inline_output"/> - - <revision version="0.1" date="2009-06-13" status="review"/> - - <credit type="author"> - <name>Shaun McCance</name> - <email>shaunm@gnome.org</email> - <years>2008-2009</years> - </credit> - - <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" /> - - <desc>Mark up text the user should input into a computer program.</desc> -</info> - -<title>User Input</title> - -<synopsis><code mime="application/relax-ng-compact-syntax"> -mal_inline_input = element input { - <link xref="mal_attr_link">mal_attr_link</link> ?, - attribute style { xsd:NMTOKENS } ?, - attribute * - (mal:* | local:*) { text } *, - - <link xref="mal_inline">mal_inline</link> -} -</code></synopsis> - -<p>Use the <code>input</code> element to mark up text that is input by -the user. This may be text entered into a command-line environment -or into a text field in a graphical application.</p> - - -<!-- BEGIN notes --> -<section id="notes"> - <title>Notes</title> - <list> - <item><p>The <code>input</code> element can contain a mixture of text and - any <link xref="mal_inline">general inline elements</link>.</p></item> - - <item><p>The <code>input</code> element can occur in any - general inline context, including inside most - <link xref="mal_inline">inline elements</link>, some - <link xref="mal_block#basic">basic block elements</link>, and certain - <link xref="mal_info">informational elements</link>.</p></item> - - <item><p>The <code>input</code> element can link to other pages or documents. - See <link xref="mal_attr_link"/> for more information.</p></item> - - <item><p>The <code>style</code> attribute takes a space-separated list of - style hints. Processing tools should adjust their behavior according to - those style hints they understand.</p></item> - - <item><p>The <code>input</code> element can have attributes from external - namespaces. See <link xref="mal_external"/> for more information - on external-namespace attributes.</p></item> - - <item><p>The <code>input</code> element, together with the - <code xref="mal_inline_output">output</code> element, may be used to mark up - the contents of a <code xref="mal_block_screen">screen</code> element, - allowing processing tools to treat them differently.</p></item> - </list> -</section> -<!-- END notes --> - - -<!-- BEGIN examples --> -<section id="examples"> - <title>Examples</title> - - <p>Use <code>input</code> to mark up a user response to a prompt:</p> - - <example> - <code><![CDATA[Type <input>Y</input> at the prompt to proceed.]]></code> - <p>Type <input>Y</input> at the prompt to proceed.</p> - </example> - - <p>Use <code>input</code> and <code xref="mal_inline_output">output</code> - inside a <code xref="mal_block_screen">screen</code> element:</p> - - <example> - <code><![CDATA[ -<screen> -<output style="prompt">$ </output><input>ls mal_inline_output.xml</input> -<output>mal_inline_output.xml</output> -</screen> -]]></code> -<screen> -<output style="prompt">$ </output><input>ls mal_inline_output.xml</input> -<output>mal_inline_output.xml</output> -</screen> - </example> -</section> -<!-- END examples --> - - -<!-- BEGIN processing --> -<section id="processing"> - <title>Processing Expectations</title> - - <p>User input is displayed in a fixed-width or wide font. Fixed-width - fonts tend to have more distinction between visually similar characters. - A border or background color may be used to make the beginning and end of - the intput clear.</p> -</section> -<!-- END processing --> - - -<!-- BEGIN comparison --> -<section id="comparison"> - <title>Comparison to Other Formats</title> - <p>The <code>input</code> element is similar to the - <code href="http://www.docbook.org/tdg/en/html/userinput.html">userinput</code> - element in DocBook.</p> -</section> -<!-- END comparison --> - -</page> diff --git a/doc/mallard/C/mal_inline_key.page b/doc/mallard/C/mal_inline_key.page deleted file mode 100644 index bd32811..0000000 --- a/doc/mallard/C/mal_inline_key.page +++ /dev/null @@ -1,143 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="mal_inline_key"> - -<info> - <link type="guide" xref="mal_inline#elements"/> - - <revision version="0.1" date="2008-12-16" status="review"/> - - <credit type="author"> - <name>Shaun McCance</name> - <email>shaunm@gnome.org</email> - <years>2007-2009</years> - </credit> - - <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" /> - - <desc>Mark up a key to be pressed on the user's keyboard.</desc> -</info> - -<title>Key Strokes</title> - -<synopsis><code mime="application/relax-ng-compact-syntax"> -mal_inline_key = element key { - <link xref="mal_attr_link">mal_attr_link</link> ?, - attribute style { xsd:NMTOKENS } ?, - attribute * - (mal:* | local:*) { text } *, - - <link xref="mal_inline">mal_inline</link> -} -</code></synopsis> - -<p>Use the <code>key</code> element to mark up a key on the keyboard. -You can use this for letter keys, such as <key>Q</key>, or for keys -with names, such as <key>Ctrl</key>. Generally, the contents of the -<code>key</code> element should be what is printed on the physical -key, although it may be a textual description for keys with symbols -printed on them.</p> - -<p>Do not use <code>key</code> to mark up a class of keys, such as -<em>arrow keys</em>. These do not require markup in running prose. -Inside a <code xref="mal_inline_keyseq">keyseq</code> element, you -are allowed to use text without a <code>key</code> element exactly -for this purpose.</p> - -<p>Do not use <code>key</code> to mark up a symbolic key code or a numeric -key value; if necesarry, use <code xref="mal_inline_sys">sys</code> for -these instead.</p> - - -<!-- BEGIN notes --> -<section id="notes"> - <title>Notes</title> - <list> - <item><p>The <code>key</code> element can contain a mixture of text and - any <link xref="mal_inline">general inline elements</link>.</p></item> - - <item><p>The <code>key</code> element can occur in any - general inline context, including inside most - <link xref="mal_inline">inline elements</link>, some - <link xref="mal_block#basic">basic block elements</link>, and certain - <link xref="mal_info">informational elements</link>.</p></item> - - <item><p>The <code>key</code> element can also occur inside the - <code xref="mal_inline_keyseq">keyseq</code> element, where it has - special meaning.</p></item> - - <item><p>The <code>key</code> element can link to other pages or documents. - See <link xref="mal_attr_link"/> for more information.</p></item> - - <item><p>The <code>style</code> attribute takes a space-separated list of - style hints. Processing tools should adjust their behavior according to - those style hints they understand.</p></item> - - <item><p>The <code>key</code> element can have attributes from external - namespaces. See <link xref="mal_external"/> for more information - on external-namespace attributes.</p></item> - </list> -</section> -<!-- END notes --> - - -<!-- BEGIN examples --> -<section id="examples"> - <title>Examples</title> - - <p>Use <code>key</code> to mark up a letter key:</p> - - <example> - <code><![CDATA[ -Press <key>M</key> to mark the selected message as read. -]]></code> - <p>Press <key>M</key> to mark the selected message as read.</p> - </example> - - <p>Use <code>key</code> to mark up a function key:</p> - - <example> - <code><![CDATA[ -Press <key>F9</key> to check for new messages. -]]></code> - <p>Press <key>F9</key> to check for new messages.</p> - </example> - - <p>Use <code>key</code> to refer to a specific key by a - textual description:</p> - - <example> - <code><![CDATA[ -Press the <key>Down</key> key to select the next item. -]]></code> - <p>Press the <key>Down</key> key to select the next item.</p> - </example> -</section> -<!-- END examples --> - - -<!-- BEGIN processing --> -<section id="processing"> - <title>Processing Expectations</title> - - <p>No particular special rendering is required for <code>key</code> elements. - Keys may be rendered with lightened text or other sublte styling effects to - distinguish them from the surrounding text.</p> -</section> -<!-- END processing --> - - -<!-- BEGIN comparison --> -<section id="comparison"> - <title>Comparison to Other Formats</title> - <p>The <code>key</code> element is similar to the - <code href="http://www.docbook.org/tdg/en/html/keycap.html">keycap</code> - element in DocBook. Mallard does not provide elements analogous to the - DocBook elements - <code href="http://www.docbook.org/tdg/en/html/keysym.html">keysym</code> and - <code href="http://www.docbook.org/tdg/en/html/keycode.html">keycode</code>. - In most cases, these should be marked simply with the - <code xref="mal_inline_sys">sys</code> element.</p> -</section> -<!-- END comparison --> - -</page> diff --git a/doc/mallard/C/mal_inline_keyseq.page b/doc/mallard/C/mal_inline_keyseq.page deleted file mode 100644 index 15b8b18..0000000 --- a/doc/mallard/C/mal_inline_keyseq.page +++ /dev/null @@ -1,169 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="mal_inline_keyseq"> - -<info> - <link type="guide" xref="mal_inline#elements"/> - <link type="seealso" xref="mal_inline_key"/> - - <revision version="0.1" date="2008-12-17" status="review"/> - - <credit type="author"> - <name>Shaun McCance</name> - <email>shaunm@gnome.org</email> - <years>>2008-2009</years> - </credit> - - <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" /> - - <desc>Mark up a key combination or sequence.</desc> -</info> - -<title>Key Sequences</title> - -<synopsis><code mime="application/relax-ng-compact-syntax"> -mal_inline_keyseq = element keyseq { - attribute style { xsd:NMTOKENS } ?, - attribute type { "combo" | "sequence" } ?, - attribute * - (mal:* | local:*) { text } *, - - mixed { - (<link xref="mal_inline_gui">mal_inline_key</link> | mal_inline_keyseq) * - } -} -</code></synopsis> - -<p>Use the <code>keyseq</code> element to mark up a key combination or sequence. -Use the <code xref="mal_inline_key">key</code> element to mark up each individual -key press. You can use text without markup to indicate a class of keys, such as -<em>arrow keys</em>, or to indicate a mouse action.</p> - - -<!-- BEGIN notes --> -<section id="notes"> - <title>Notes</title> - <list> - <item><p>The <code>keyseq</code> element can contain a mixture of text, - <code xref="mal_inline_key">key</code> elements, and other - <code>keyseq</code> elements.</p></item> - - <item><p>The <code>keyseq</code> element can occur in any - general inline context, including inside most - <link xref="mal_inline">inline elements</link>, some - <link xref="mal_block#basic">basic block elements</link>, and certain - <link xref="mal_info">informational elements</link>.</p></item> - - - <item><p>The <code>style</code> attribute takes a space-separated list of - style hints. Processing tools should adjust their behavior according to - those style hints they understand.</p></item> - - <item><p>The <code>type</code> element indicates whether the keys should be - pressed together (<code>"combo"</code>) or in sequence (<code>"sequence"</code>). - The default is <code>"combo"</code>.</p></item> - - <item><p>The <code>keyseq</code> element can have attributes from external - namespaces. See <link xref="mal_external"/> for more information - on external-namespace attributes.</p></item> - </list> -</section> -<!-- END notes --> - - -<!-- BEGIN examples --> -<section id="examples"> - <title>Examples</title> - - <p>Use <code>keyseq</code> to mark up a keyboard shortcut:</p> - - <example> - <code><![CDATA[ -Press <keyseq><key>Ctrl</key><key>Q</key></keyseq> to quit. -]]></code> - <p>Press <keyseq><key>Ctrl</key><key>Q</key></keyseq> to quit.</p> - </example> - - <p>Use <code>keyseq</code> with text for classes of keys:</p> - - <example> - <code><![CDATA[ -Press <keyseq><key>Shift</key>arrow keys</keyseq> to make a continuous -selection as you move the keyboard focus. -]]></code> - <p>Press <keyseq><key>Shift</key>arrow keys</keyseq> to make a continuous - selection as you move the keyboard focus.</p> - </example> - - <p>Use <code>keyseq</code> with text for mouse actions:</p> - - <example> - <code><![CDATA[ -<keyseq><key>Shift</key>click</keyseq> to make a continuous selection. -]]></code> - <p><keyseq><key>Shift</key>click</keyseq> to make a continuous selection.</p> - </example> - - <p>Use nested <code>keyseq</code> elements for complex key commands:</p> - - <example> - <code><![CDATA[ -Press <keyseq type="sequence"><keyseq><key>C</key><key>x</key></keyseq> -<keyseq><key>C</key><key>s</key></keyseq></keyseq> to save a file in -<app>Emacs</app>. -]]></code> - <p>Press <keyseq type="sequence"><keyseq><key>C</key><key>x</key></keyseq> - <keyseq><key>C</key><key>s</key></keyseq></keyseq> to save a file in - <app>Emacs</app>.</p> - </example> - - <p>Since classes of keys and mouse actions are written without surrounding - markup, you can't have two consecutive key classes or mouse actions. You - can overcome this limitation by using nested singleton <code>keyseq</code> - elements:</p> - - <example> - <code><![CDATA[ -There are various ways to modify drag behavior by using -<keyseq><keyseq>modifier</keyseq>drag</keyseq>. -]]></code> - <p>There are various ways to modify drag behavior by using - <keyseq><keyseq>modifier</keyseq>drag</keyseq>.</p> - </example> -</section> -<!-- END examples --> - - -<!-- BEGIN processing --> -<section id="processing"> - <title>Processing Expectations</title> - - <p>Each of the child <code>key</code> elements and text nodes, except - whitespace-only text nodes, is displayed as described below, adding a - separator between them. The exact separator may vary according to - language and style preferences, and according to the <code>type</code> - attribute. For sequences, a space is typically used. For combinations, - the plus sign (+) is most frequently used on modern systems, although the - hyphen (-) is still common in some areas. A style hint may be used to - choose between different separators.</p> - - <p>Child <code>key</code> and <code>keyseq</code> elements are shown as - normal. Text nodes have their whitespace normalized to strip leading and - trailing spaces. Text nodes may be rendered using a font variation.</p> -</section> -<!-- END processing --> - - -<!-- BEGIN comparison --> -<section id="comparison"> - <title>Comparison to Other Formats</title> - <p>The <code>keyseq</code> element is similar to the - <code href="http://www.docbook.org/tdg/en/html/keycombo.html">keycombo</code> - element in DocBook. Like <code>keycombo</code>, <code>keyseq</code> elements - can be nested to indicate sequences of key combinations. Since Mallard does - not provide an element analogous to the DocBook element - <code href="http://www.docbook.org/tdg/en/html/mousebutton.html">mousebutton</code>, - mouse actions in key sequences should be written as text content without markup.</p> -</section> -<!-- END comparison --> - -</page> diff --git a/doc/mallard/C/mal_inline_link.page b/doc/mallard/C/mal_inline_link.page deleted file mode 100644 index 8811b63..0000000 --- a/doc/mallard/C/mal_inline_link.page +++ /dev/null @@ -1,203 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="mal_inline_link"> - -<info> - <link type="guide" xref="mal_inline#elements"/> - - <revision version="0.1" date="2007-05-20" status="review"/> - - <credit type="author"> - <name>Shaun McCance</name> - <email>shaunm@gnome.org</email> - <years>2007-2009</years> - </credit> - - <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" /> - - <desc>Link to other pages, sections, or web pages.</desc> -</info> - -<title>Hyperlinks</title> - -<synopsis><code mime="application/relax-ng-compact-syntax"> -mal_inline_link = element link { - ( attribute xref { text } | - attribute href { text } | - ( attribute xref { text }, attribute href { text } ) - ), - attribute role { text } ?, - attribute style { xsd:NMTOKENS } ?, - attribute * - (mal:* | local:*) { text } *, - - <link xref="mal_inline">mal_inline</link> -} -</code></synopsis> - -<p>Use the <code>link</code> to create a link to another page or section, or to -an external resource such as a web page. Most <link xref="mal_inline">inline -elements</link> can act as links, but the <code>link</code> element allows you -to create a link without any associated semantics. The <code>link</code> element -can also generate link text automatically for links to pages and sections within -the same document.</p> - - -<!-- BEGIN notes --> -<section id="notes"> - <title>Notes</title> - <list> - <item><p>The <code>link</code> element can contain a mixture of text and - any <link xref="mal_inline">general inline elements</link>.</p></item> - - <item><p>For links within the same document, content can be automatically - generated.</p></item> - - <item><p>The <code>link</code> element can occur in any - general inline context, including inside most - <link xref="mal_inline">inline elements</link>, some - <link xref="mal_block#basic">basic block elements</link>, and certain - <link xref="mal_info">informational elements</link>.</p></item> - - <item><p>The <code>xref</code> attribute creates a link to another page - or section within the same document, or to an external resource in some - document management system.</p></item> - - <item><p>The <code>href</code> attribute creates a link to a web page - or other network-accessible resource.</p></item> - - <item><p>The <code>role</code> attribute can be used to select alternative - titles of the target page or section to be used as automatic content.</p></item> - - <item><p>The <code>style</code> attribute takes a space-separated list of - style hints. Processing tools should adjust their behavior according to - those style hints they understand.</p></item> - - <item><p>The <code>link</code> element can have attributes from external - namespaces. See <link xref="mal_external"/> for more information - on external-namespace attributes.</p></item> - </list> -</section> -<!-- END notes --> - - -<!-- BEGIN examples --> -<section id="examples"> - <title>Examples</title> - - <p>Link to another page in the same document:</p> - - <example> - <code><![CDATA[ -See <link xref="mal_attr_link"/> for information on linking attributes. -]]></code> - <p>See <link xref="mal_attr_link"/> for information on linking attributes.</p> - </example> - - <p>Link to a section in the same page:</p> - - <example> - <code><![CDATA[ -See <link xref="#processing"/> for details on automatic link text. -]]></code> - <p>See <link xref="#processing"/> for details on automatic link text.</p> - </example> - - <p>Link to a section in another page:</p> - - <example> - <code><![CDATA[ -See <link xref="mal_inline#processing"/> for more processing expectations. -]]></code> - <p>See <link xref="mal_inline#processing"/> for more processing expectations.</p> - </example> - - <p>Link to an external resource:</p> - - <example> - <code><![CDATA[ -See the <link href="http://www.w3.org/TR/REC-xml-names/">XML Namespaces -recommendation</link>. -]]></code> - <p>See the <link href="http://www.w3.org/TR/REC-xml-names/">XML Namespaces - recommendation</link>.</p> - </example> -</section> -<!-- END examples --> - - -<!-- BEGIN processing --> -<section id="processing"> - <title>Processing Expectations</title> - - <p>A <code>link</code> element is displayed as hyperlink which can be - clicked on or otherwise activated to take the user to another page, - document, or resource. In certain environments, such as print, it - may not be possible to make links activatable. In these cases, the - target of the link may be displayed in the rendered output.</p> - - <p>The target of <code>link</code> element is determined from the - <code>xref</code> and <code>href</code> exactly as it is for other - inline elements. See <link xref="mal_attr_link"/> for information - on determining the link target.</p> - - <p>If the <code>link</code> element is non-empty, its contents are - displayed as normal. Otherwise, automatic link text is generated - as follows:</p> - - <list> - <item><p>If the <code>link</code> element has an <code>xref</code> - attribute that points to a page or section in the same document:</p> - - <list> - <item><p>If the <code>link</code> element has a <code>role</code> - attribute, and that page or section has an - <link xref="mal_info_title">informational title</link> with the - <code>type</code> attribute set to <code>"link"</code> and the - <code>role</code> set to the same value as the <code>role</code> - attribute of the <code>link</code> element, then the contents - of that <code>title</code> element are used.</p></item> - - <item><p>Otherwise, if that page or section has an - <link xref="mal_info_title">informational title</link> with the - <code>type</code> attribute set to <code>"link"</code> and without - a <code>role</code> attribute, the contents of that <code>title</code> - element are used.</p></item> - - <item><p>Otherwise, the contents of the primary title of that page - page or section are used.</p></item> - </list> - </item> - - <item><p>Otherwise, if the <code>link</code> element has an <code>xref</code> - attribute that points to a portion of another document, and the processing - tool knows how to generate link contents, that content is used.</p></item> - - <item><p>Otherwise, the link target is used as text content.</p></item> - </list> -</section> -<!-- END processing --> - - -<!-- BEGIN comparison --> -<section id="comparison"> - <title>Comparison to Other Formats</title> - - <p>The <code>link</code> element combines the functionality of the - <code href="http://www.docbook.org/tdg/en/html/link.html">link</code>, - <code href="http://www.docbook.org/tdg/en/html/xref.html">xref</code>, and - <code href="http://www.docbook.org/tdg/en/html/ulink.html">ulink</code> - elements in DocBook. For the <code>link</code> and <code>xref</code> - elements, DocBook provides the <code>endterm</code> attribute to select - an alternative element from which to take content. Mallard does not - provide this feature, although it allows you to select from alternative - titles for the linked-to element.</p> - - <p>DocBook provides the <code>xrefstyle</code> attribute to control how - automatic link text is generated. The behavior of this attribute is - unspecified. Rather than attempt to use style hints, Mallard allows - writers to specify exact alternative link contents. Alternative link - contents are important in languages with case declensions.</p> -</section> -<!-- END comparison --> - -</page> diff --git a/doc/mallard/C/mal_inline_media.page b/doc/mallard/C/mal_inline_media.page deleted file mode 100644 index 9a8cb15..0000000 --- a/doc/mallard/C/mal_inline_media.page +++ /dev/null @@ -1,152 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="mal_inline_media"> - -<info> - <link type="guide" xref="mal_inline#elements"/> - - <revision version="0.1" date="2009-05-03" status="review"/> - - <credit type="author"> - <name>Shaun McCance</name> - <email>shaunm@gnome.org</email> - <years>2007-2009</years> - </credit> - - <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" /> - - <desc>Insert an image, video, or other multimedia object.</desc> -</info> - -<title>Inline Multimedia Objects</title> - -<synopsis><code mime="application/relax-ng-compact-syntax"> -mal_inline_media = element media { - <link xref="mal_attr_link">mal_attr_link</link> ?, - attribute style { xsd:NMTOKENS } ?, - attribute type { "image" | "video" | "audio" | "application" } ?, - attribute mime { text } ?, - attribute src { text }, - attribute height { text } ?, - attribute width { text } ?, - attribute * - (mal:* | local:*) { text } *, - - <link xref="mal_inline">mal_inline</link> -} -</code></synopsis> - -<p>Use the <code>media</code> element to insert an image, video, or other -multimedia object into your document. Since not all display tools will be -able to display all types of objects, you can provide fallback elements in -the contents of a <code>media</code> element. See <link xref="#processing"/> -for details on how fallback elements are handled.</p> - - -<!-- BEGIN notes --> -<section id="notes"> - <title>Notes</title> - <list> - <item><p>The <code>media</code> element can contain a mixture of text and - any <link xref="mal_inline">general inline elements</link>.</p></item> - - <item><p>The <code>media</code> element can occur in any - general inline context, including inside most - <link xref="mal_inline">inline elements</link>, some - <link xref="mal_block#basic">basic block elements</link>, and certain - <link xref="mal_info">informational elements</link>.</p></item> - - <item><p>The <code>media</code> element can link to other pages or documents. - See <link xref="mal_attr_link"/> for more information.</p></item> - - <item><p>The <code>style</code> attribute takes a space-separated list of - style hints. Processing tools should adjust their behavior according to - those style hints they understand.</p></item> - - <item><p>The <code>mime</code> attribute takes a valid MIME type for the - object that is being inserted.</p></item> - - <item><p>The <code>media</code> element can have attributes from external - namespaces. See <link xref="mal_external"/> for more information - on external-namespace attributes.</p></item> - - <item><p>The <code>media</code> element may also be used in a block context. - See <link xref="mal_block_media"/> for more information.</p></item> - </list> -</section> -<!-- END notes --> - - -<!-- BEGIN examples --> -<section id="examples"> - <title>Examples</title> - - <p>Use <code>media</code> to insert an image into your document:</p> - - <example> - <code><![CDATA[ -<p><media type="image" mime="image/png" src="figures/mallard.png"> -Drake, the Mallard mascot -</media></p> -]]></code> - <p><media type="image" mime="image/png" src="figures/mallard.png"> - Drake, the Mallard mascot - </media></p> - </example> -</section> -<!-- END examples --> - - -<!-- BEGIN processing --> -<section id="processing"> - <title>Processing Expectations</title> - - <p>When a <code>media</code> element occurs in an inline context, it is displayed - inline. The exact rendering of a <code>media</code> element will depend on the - <code>type</code> and <code>mime</code> attributes. It may be necessary to add - controls for audio and video objects.</p> - - <p>The <code>application</code> type is intended for embedding interactive - applications in documents. There are currently no specific recommendations - for displaying application objects. Behavior may vary according to the - type of application being embedded.</p> - - <p>Some display tools will not be able to display all types of objects. - For example, a printed document will not be able to display video or play - back audio. Even when a display tool can display the type of object, it - may not be able to work with the given MIME type for technical or other - reasons.</p> - - <p>When a display tool cannot display a <code>media</code> element, it - displays the child elements of the element, as if the <code>media</code> - element itself were replaced by its children. The child elements may consist - of simply another <code>media</code> element referencing a different type of - content. When processing any child <code>media</code> elements, display tools - may need to fall back further to their child elements.</p> - - <p>In some display media, multimedia objects can have alternate text. This - may be displayed when a user hovers over the object, or it may be provided - to assistive technologies. When displaying in such a medium, display tools - should extract the text value of a <code>media</code> element by processing - its child elements, and recursively processing any child <code>media</code> - elements, as if it can not display any types of <code>media</code> elements.</p> -</section> -<!-- END processing --> - - -<!-- BEGIN comparison --> -<section id="comparison"> - <title>Comparison to Other Formats</title> - - <p>The <code>media</code> element can be used in place of the DocBook elements - <code xref="http://www.docbook.org/tdg/en/html/audiooobject.html">audioobject</code>, - <code xref="http://www.docbook.org/tdg/en/html/imageobject.html">imageobject</code>, and - <code xref="http://www.docbook.org/tdg/en/html/videoobject.html">videoobject</code>. - DocBook uses the - <code xref="http://www.docbook.org/tdg/en/html/inlinemediaobject.html">inlinemediaobject</code> - element to provide alternative objects. In Mallard, alternative objects are - nested, obviating the need for a container element.</p> -</section> -<!-- END comparison --> - - -</page> diff --git a/doc/mallard/C/mal_inline_output.page b/doc/mallard/C/mal_inline_output.page deleted file mode 100644 index c15336d..0000000 --- a/doc/mallard/C/mal_inline_output.page +++ /dev/null @@ -1,170 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="mal_inline_output"> - -<info> - <link type="guide" xref="mal_inline#elements"/> - - <revision version="0.1" date="2008-12-17" status="review"/> - - <credit type="author"> - <name>Shaun McCance</name> - <email>shaunm@gnome.org</email> - <years>2008-2009</years> - </credit> - - <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" /> - - <desc>Mark up the output from a computer program.</desc> -</info> - -<title>Computer Output</title> - -<synopsis><code mime="application/relax-ng-compact-syntax"> -mal_inline_output = element output { - <link xref="mal_attr_link">mal_attr_link</link> ?, - attribute style { xsd:NMTOKENS } ?, - attribute * - (mal:* | local:*) { text } *, - - <link xref="mal_inline">mal_inline</link> -} -</code></synopsis> - -<p>Use the <code>output</code> element to mark up text that is output -by a computer program. Typically, this is text output in a command-line -environment, although you may use the <code>output</code> element for -computer-generated text in a text box or similar control in a graphical -application. For messages and other labels in a graphical application, -use the <code xref="mal_inline_gui">gui</code> element.</p> - -<p>You can use the <code>style</code> attribute to indicate what type of text -is being marked up. Inside a <code xref="mal_block_screen">screen</code> -element, this may be used to format normal text, error text, and prompts -differently.</p> - - -<!-- BEGIN notes --> -<section id="notes"> - <title>Notes</title> - <list> - <item><p>The <code>output</code> element can contain a mixture of text and - any <link xref="mal_inline">general inline elements</link>.</p></item> - - <item><p>The <code>output</code> element can occur in any - general inline context, including inside most - <link xref="mal_inline">inline elements</link>, some - <link xref="mal_block#basic">basic block elements</link>, and certain - <link xref="mal_info">informational elements</link>.</p></item> - - <item><p>The <code>output</code> element can link to other pages or documents. - See <link xref="mal_attr_link"/> for more information.</p></item> - - <item><p>The <code>style</code> attribute takes a space-separated list of - style hints. Processing tools should adjust their behavior according to - those style hints they understand.</p></item> - - <item> - <p>Typical values for the <code>style</code> attribute include:</p> - <table rules="rows"><tr> - <td><p><code>output</code></p></td> - <td><p>Standard output from a running program</p></td> - </tr><tr> - <td><p><code>error</code></p></td> - <td><p>Standard error from a running program</p></td> - </tr><tr> - <td><p><code>prompt</code></p></td> - <td><p>The command prompt for an interactive shell</p></td> - </tr></table> - </item> - - <item><p>The <code>output</code> element can have attributes from external - namespaces. See <link xref="mal_external"/> for more information - on external-namespace attributes.</p></item> - - <item><p>The <code>output</code> element, together with the - <code xref="mal_inline_input">input</code> element, may be used to mark up - the contents of a <code xref="mal_block_screen">screen</code> element, - allowing processing tools to treat them differently.</p></item> - </list> -</section> -<!-- END notes --> - - -<!-- BEGIN examples --> -<section id="examples"> - <title>Examples</title> - - <p>Use <code>output</code> to mark up text generated by a program:</p> - - <example> - <code><![CDATA[ -The output of <cmd>echo $SHELL</cmd> is <output>/bin/bash</output> -if you use the Bourne-again shell. -]]></code> - <p>The output of <cmd>echo $SHELL</cmd> is <output>/bin/bash</output> if - you use the Bourne-again shell.</p> - </example> - - <p>Use <code>output</code> and <code xref="mal_inline_input">input</code> - inside a <code xref="mal_block_screen">screen</code> element:</p> - - <example> - <code><![CDATA[ -<screen> -<output style="prompt">$ </output><input>ls mal_inline_output.xml</input> -<output>mal_inline_output.xml</output> -</screen> -]]></code> -<screen> -<output style="prompt">$ </output><input>ls mal_inline_output.xml</input> -<output>mal_inline_output.xml</output> -</screen> - </example> - - <p>Use <code>output</code> for error text:</p> - - <example> - <code><![CDATA[ -<screen> -<output style="prompt">$ </output><input>ls mal.xml</input> -<output style="error">ls: mal.xml: No such file or directory</output> -</screen> -]]></code> -<screen> -<output style="prompt">$ </output><input>ls mal_inline_computeroutput.xml</input> -<output style="error">ls: mal_inline_computerouput.xml: No such file or directory</output> -</screen> - </example> -</section> -<!-- END examples --> - - -<!-- BEGIN processing --> -<section id="processing"> - <title>Processing Expectations</title> - - <p>Computer output is displayed in a fixed-width or wide font. Fixed-width - fonts tend to have more distinction between visually similar characters. - A border or background color may be used to make the beginning and end of - the output clear.</p> -</section> - - -<!-- BEGIN comparison --> -<section id="comparison"> - <title>Comparison to Other Formats</title> - <p>The <code>output</code> element is similar to the - <code href="http://www.docbook.org/tdg/en/html/computeroutput.html">computeroutput</code> - element in DocBook. When necessary, the <code>output</code> element may be used - with the <code>style</code> attribute <code>"prompt"</code> in place of DocBook's - <code href="http://www.docbook.org/tdg/en/html/prompt.html">prompt</code> - element. In some cases, it may be appropriate to use the <code>output</code> - element with the <code>style</code> attribute <code>"error"</code> in place - of DocBook's - <code href="http://www.docbook.org/tdg/en/html/errorname.html">errorname</code> and - <code href="http://www.docbook.org/tdg/en/html/errortext.html">errortext</code> - elements.</p> -</section> -<!-- END comparison --> - -</page> diff --git a/doc/mallard/C/mal_inline_span.page b/doc/mallard/C/mal_inline_span.page deleted file mode 100644 index 4b55e45..0000000 --- a/doc/mallard/C/mal_inline_span.page +++ /dev/null @@ -1,107 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="mal_inline_span"> - -<info> - <link type="guide" xref="mal_inline#elements"/> - <link type="seealso" xref="mal_attr_link"/> - - <revision version="0.1" date="2009-05-13" status="review"/> - - <credit type="author"> - <name>Shaun McCance</name> - <email>shaunm@gnome.org</email> - <years>2007-2009</years> - </credit> - - <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" /> - - <desc>A generic inline element that can be used for semantic, - localization, and styling purpose.</desc> -</info> - -<title>Spans</title> - -<synopsis><code mime="application/relax-ng-compact-syntax"> -mal_inline_span = element span { - <link xref="mal_attr_link">mal_attr_link</link> ?, - attribute style { xsd:NMTOKENS } ?, - attribute * - (mal:* | local:*) { text } *, - - <link xref="mal_inline">mal_inline</link> -} -</code></synopsis> - -<p>Use the <code>span</code> element to surround a run of text -without using any of the semantic <link xref="mal_inline">inline -elements</link>. This is frequently necessary for extensions -using attributes from external namespaces.</p> - - -<!-- BEGIN notes --> -<section id="notes"> - <title>Notes</title> - <list> - <item><p>The <code>span</code> element can contain a mixture of text and - any <link xref="mal_inline">general inline elements</link>.</p></item> - - <item><p>The <code>span</code> element can occur in any - general inline context, including inside most - <link xref="mal_inline">inline elements</link>, some - <link xref="mal_block#basic">basic block elements</link>, and certain - <link xref="mal_info">informational elements</link>.</p></item> - - <item><p>The <code>span</code> element can link to other pages or documents. - See <link xref="mal_attr_link"/> for more information.</p></item> - - <item><p>The <code>style</code> attribute takes a space-separated list of - style hints. Processing tools should adjust their behavior according to - those style hints they understand.</p></item> - - <item><p>The <code>span</code> element can have attributes from external - namespaces. See <link xref="mal_external"/> for more information - on external-namespace attributes.</p></item> - </list> -</section> -<!-- END notes --> - - -<!-- BEGIN examples --> -<section id="examples"> - <title>Examples</title> - - <p>Use <code>span</code> with an external-namespace attribute to mark a word - as untranslatable using the - <link href="http://www.w3.org/TR/its/">Internationalization Tag Set</link>:</p> - - <example> - <code><![CDATA[ -This <span its:translate="no">word</span> should not be translated.]]></code> - <p>This <span xmlns:its="http://www.w3.org/2005/11/its" its:version="1.0" - its:translate="no">word</span> should not be translated.</p> - </example> -</section> -<!-- END examples --> - - -<!-- BEGIN processing --> -<section id="processing"> - <title>Processing Expectations</title> - - <p>No particular special rendering is required for <code>span</code> elements. - Processing tools may have special processing rules for certain style hints or - external-namespace attributes.</p> -</section> -<!-- END processing --> - - -<!-- BEGIN comparison --> -<section id="comparison"> - <title>Comparison to Other Formats</title> - <p>The <code>span</code> element is similar to the - <code href="http://www.docbook.org/tdg/en/html/phrase.html">phrase</code> - element in DocBook.</p> -</section> -<!-- END comparison --> - -</page> diff --git a/doc/mallard/C/mal_inline_sys.page b/doc/mallard/C/mal_inline_sys.page deleted file mode 100644 index 710a3cf..0000000 --- a/doc/mallard/C/mal_inline_sys.page +++ /dev/null @@ -1,107 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="mal_inline_sys"> - -<info> - <link type="guide" xref="mal_inline#elements"/> - - <revision version="0.1" date="2009-05-13" status="review"/> - - <credit type="author"> - <name>Shaun McCance</name> - <email>shaunm@gnome.org</email> - <years>2008-2009</years> - </credit> - - <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" /> - - <desc>Mark up general identifiers found on computer systems.</desc> -</info> - -<title>System Items</title> - -<synopsis><code mime="application/relax-ng-compact-syntax"> -mal_inline_sys = element sys { - <link xref="mal_attr_link">mal_attr_link</link> ?, - attribute style { xsd:NMTOKENS } ?, - attribute * - (mal:* | local:*) { text } *, - - <link xref="mal_inline">mal_inline</link> -} -</code></synopsis> - -<p>Use the <code>sys</code> element to mark up any type of system item that -isn't covered by other elements such as <code xref="mal_inline_file">file</code>, -<code xref="mal_inline_cmd">cmd</code>, or -<code xref="mal_inline_code">code</code>.</p> - - -<!-- BEGIN notes --> -<section id="notes"> - <title>Notes</title> - <list> - <item><p>The <code>sys</code> element can contain a mixture of text and - any <link xref="mal_inline">general inline elements</link>.</p></item> - - <item><p>The <code>sys</code> element can occur in any - general inline context, including inside most - <link xref="mal_inline">inline elements</link>, some - <link xref="mal_block#basic">basic block elements</link>, and certain - <link xref="mal_info">informational elements</link>.</p></item> - - <item><p>The <code>sys</code> element can link to other pages or documents. - See <link xref="mal_attr_link"/> for more information.</p></item> - - <item><p>The <code>style</code> attribute takes a space-separated list of - style hints. Processing tools should adjust their behavior according to - those style hints they understand.</p></item> - - <item><p>The <code>sys</code> element can have attributes from external - namespaces. See <link xref="mal_external"/> for more information - on external-namespace attributes.</p></item> - </list> -</section> -<!-- END notes --> - - -<!-- BEGIN examples --> -<section id="examples"> - <title>Examples</title> - - <p>Use <code>sys</code> to mark up a domain name:</p> - - <example> - <code><![CDATA[The Linux kernel is hosted on <sys>git.kernel.org</sys>.]]></code> - <p>The Linux kernel is hosted on <sys>git.kernel.org</sys>.</p> - </example> -</section> -<!-- END examples --> - - -<!-- BEGIN processing --> -<section id="processing"> - <title>Processing Expectations</title> - - <p>System items are displayed in a fixed-width font. Fixed-width fonts - tend to have more distinction between visually similar characters. This - is particularly important in system items, since letters often appear - without the context of a known word that helps make them discernable in - normal prose.</p> -</section> -<!-- END processing --> - - -<!-- BEGIN comparison --> -<section id="comparison"> - <title>Comparison to Other Formats</title> - <p>The <code>sys</code> element is similar to the - <code href="http://www.docbook.org/tdg/en/html/systemitem.html">systemitem</code> - element in DocBook. DocBook has gained numerous elements which were once - marked using the <code>class</code> attribute on the <code>systemitem</code> - element. Since Mallard does not provide the level of markup specificity - that DocBook does, the <code>sys</code> element should be used in place - of these and various other elements.</p> -</section> -<!-- END comparison --> - -</page> diff --git a/doc/mallard/C/mal_inline_var.page b/doc/mallard/C/mal_inline_var.page deleted file mode 100644 index 0439f9e..0000000 --- a/doc/mallard/C/mal_inline_var.page +++ /dev/null @@ -1,95 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="mal_inline_var"> - -<info> - <link type="guide" xref="mal_inline#elements"/> - <link type="seealso" xref="mal_inline_cmd"/> - <link type="seealso" xref="mal_inline_code"/> - - <revision version="0.1" date="2009-04-12" status="review"/> - - <credit type="author"> - <name>Shaun McCance</name> - <email>shaunm@gnome.org</email> - <years>2007-2009</years> - </credit> - - <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" /> - - <desc>Mark up placeholder text that should be replaced by the user.</desc> -</info> - -<title>Variable Text</title> - -<synopsis><code mime="application/relax-ng-compact-syntax"> -mal_inline_var = element var { - <link xref="mal_attr_link">mal_attr_link</link> ?, - attribute style { xsd:NMTOKENS } ?, - attribute * - (mal:* | local:*) { text } *, - - <link xref="mal_inline">mal_inline</link> -} -</code></synopsis> - -<p>Use the <code>var</code> element to mark up placeholder text that should be -replaced by the user. This is typically used inside a -<code xref="mal_inline_cmd">cmd</code> or <code xref="mal_inline_code">code</code> -element to indicate a replaceable argument, or within running prose to refer to -an indicated argument.</p> - - -<!-- BEGIN notes --> -<section id="notes"> - <title>Notes</title> - <list> - <item><p>The <code>var</code> element can contain a mixture of text and - any <link xref="mal_inline">general inline elements</link>.</p></item> - - <item><p>The <code>var</code> element can occur in any - general inline context, including inside most - <link xref="mal_inline">inline elements</link>, some - <link xref="mal_block#basic">basic block elements</link>, and certain - <link xref="mal_info">informational elements</link>.</p></item> - - <item><p>The <code>var</code> element can link to other pages or documents. - See <link xref="mal_attr_link"/> for more information.</p></item> - - <item><p>The <code>style</code> attribute takes a space-separated list of - style hints. Processing tools should adjust their behavior according to - those style hints they understand.</p></item> - - <item><p>The <code>var</code> element can have attributes from external - namespaces. See <link xref="mal_external"/> for more information - on external-namespace attributes.</p></item> - - <item><p>See <link xref="mal_inline_cmd"/> and <link xref="mal_inline_code"/> - for examples using <code>var</code>.</p></item> - </list> -</section> -<!-- END notes --> - - -<!-- BEGIN processing --> -<section id="processing"> - <title>Processing Expectations</title> - - <p>Variable text is typically displayed in an italic or oblique font. When - used inside a fixed-width element such as <code xref="mal_inline_cmd">cmd</code> - or <code xref="mal_inline_code">code</code>, it will inherit the fixed-width - font. In running prose, however, the <code>var</code> element does not cause - its contents to be displayed in a fixed-width font.</p> -</section> -<!-- END processing --> - - -<!-- BEGIN comparison --> -<section id="comparison"> - <title>Comparison to Other Formats</title> - <p>The <code>var</code> element is similar to the - <code href="http://www.docbook.org/tdg/en/html/replaceable.html">replaceable</code> - element in DocBook.</p> -</section> -<!-- END comparison --> - -</page> diff --git a/doc/mallard/C/mal_page.page b/doc/mallard/C/mal_page.page deleted file mode 100644 index 451deae..0000000 --- a/doc/mallard/C/mal_page.page +++ /dev/null @@ -1,156 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="mal_page"> - -<info> - <revision version="0.1" date="2009-05-28" status="review"/> - - <credit type="author"> - <name>Shaun McCance</name> - <email>shaunm@gnome.org</email> - <years>2008-2009</years> - </credit> - - <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" /> - - <desc>Individual tutorials, overviews, references, and navigational guides.</desc> -</info> - -<title>Pages</title> - -<synopsis><code mime="application/relax-ng-compact-syntax"> -namespace local = "" -default namespace mal = "http://projectmallard.org/1.0/" -start = mal_page -mal_page = element page { - attribute id { xsd:ID }, - attribute type { "guide" | "topic"} ?, - attribute style { xsd:NMTOKENS } ?, - attribute * - (mal:* | local:*) { text } *, - - <link xref="mal_info">mal_info</link> ?, - <link xref="mal_block_title">mal_block_title</link>, - <link xref="mal_block">mal_block</link> *, - <link xref="mal_section">mal_section</link> * -} -</code></synopsis> - -<p>The <code>page</code> element is the root element of any Mallard page file. -In Mallard, documents are composed of discrete pages which are interlinked -using various linking mechanisms. There are two types of pages in Mallard: -<link xref="#guide">guide pages</link> and <link xref="#topic">topic pages</link>. -Topic pages contain the bulk of the material discussed in a document, whereas -guide pages serve as navigational aids.</p> - - -<!-- BEGIN notes --> -<section id="notes"> - <title>Notes</title> - <list> - <item><p>The <code>page</code> element contains an optional - <code xref="mal_info">info</code> element, a <code xref="mal_block_title">title</code> - element, any <link xref="mal_block">general block content</link>, and - any number of <code xref="mal_section">section</code> elements.</p></item> - - <item><p>The <code>page</code> element is the top-level element in any - Mallard page file, and cannot occur in any other elements.</p></item> - - <item><p>The <code>id</code> attribute takes a unique identifier, which - should match the base file name (without extension) of the file containing - the page.</p></item> - - <item><p>The <code>type</code> attribute takes the values <code>"guide"</code> and - <code>"topic"</code>. <link xref="#guide">Guide pages</link> and <link xref="#topic">topic - pages</link> are discussed below. If the <code>type</code> attribute is - omitted, it is assumed to be <code>"topic"</code>.</p></item> - - <item><p>The <code>style</code> attribute takes a space-separated list of - style hints. Processing tools should adjust their behavior according to - those style hints they understand.</p></item> - - <item><p>The <code>page</code> element can have attributes from external - namespaces. See <link xref="mal_external"/> for more information - on external namespace attributes.</p></item> - </list> -</section> -<!-- END notes --> - - -<!-- BEGIN guide --> -<section id="guide"> - <title>Guide Pages</title> - - <p>Guide pages have the <code>type</code> attribute set to - <code>"guide"</code>. They serve as navigational aids, linking to topics and - other guides. Readers can browse through guides much as they would browse - through container sections in a linear document. Since page can be included - in multiple guides, however, readers are able to reach the same content by - navigating different paths.</p> - - <p>Guide pages have links automatically inserted into their content based - on topic links within their own <code xref="mal_info">info</code> elements - and guide links within the <code>info</code> elements of other pages and - sections. Guide pages can contain sections to help organize content. Each - section in a guide page has automatic links inserted as well. See - <link xref="links#topic"/> for details on automatic topic links.</p> - - <p>Guides also have see also links generated automatically. See - <link xref="links#seealso"/> for more information.</p> - - <p>Generally, guide pages will contain some introductory content to help - readers understand the topics being presented. Introductory content should - be short and concise.</p> -</section> -<!-- END topic --> - - -<!-- BEGIN topic --> -<section id="topic"> - <title>Topic Pages</title> - - <p>Topic pages have the <code>type</code> attribute set to - <code>"topic"</code>, or have no <code>type</code> attribute at all. Topics - contain the bulk of the material in a document. A Topic may be a tutorial, - a conceptual overview, reference material, or any other type of content. - Mallard does not distinguish between different content types, although tools - may introduce special styling based on style hints. Topics are distinguished - from guides only in that their primary purpose is to convey information, - whereas guides serve as navigational aids.</p> - - <p>Topic pages have links automatically inserted to all guides which link - to them. Topic pages can contain sections to help organize material and - present finer-grained chunks of information to the reader. Each section - in a topic page has automatic guide links inserted as well. See - <link xref="links#guide"/> for details on automatic guide links.</p> - - <p>Topics also have see also links generated automatically. See - <link xref="links#seealso"/> for more information.</p> -</section> -<!-- END topic --> - - -<!-- BEGIN processing --> -<section id="processing"> - <title>Processing Expectations</title> - - <p>In on-screen media, a <code>page</code> element is displayed as a single - page. In this case, <em>page</em> is used in the sense of <em>web page</em>: - something which can be read top-to-bottom by scrolling. This should not be - confused with physical pages — one side of a leaf of paper — or with any - fixed-height electronic pages such as those used by word processors and - e-books.</p> - - <p>The <code>info</code> child element is not displayed directly, although - certain informational elements may be displayed or affect aspects of the - page display. In particular, the <code>info</code> element may contain - <code>link</code> elements which will cause automatic links to be inserted - into the displayed output. See <link xref="links"/> for more information.</p> - - <p>The title of a page is displayed prominently at the top, followed by any - child block content, and finally by each child section. Note that automatic - links, style hints, or other special features may insert material or change - the way pages are displayed.</p> -</section> -<!-- END processing --> - -</page> diff --git a/doc/mallard/C/mal_section.page b/doc/mallard/C/mal_section.page deleted file mode 100644 index 963a3e4..0000000 --- a/doc/mallard/C/mal_section.page +++ /dev/null @@ -1,89 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="mal_section"> - -<info> - <revision version="0.1" date="2009-05-28" status="review"/> - - <credit type="author"> - <name>Shaun McCance</name> - <email>shaunm@gnome.org</email> - <years>2008-2009</years> - </credit> - - <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" /> - - <desc>Break up pages into logical chunks to help readers find - information quickly.</desc> -</info> - -<title>Sections</title> - -<synopsis><code mime="application/relax-ng-compact-syntax"> -mal_section = element section { - attribute id { xsd:ID }, - attribute style { xsd:NMTOKENS } ?, - attribute * - (mal:* | local:*) { text } *, - - <link xref="mal_info">mal_info</link> ?, - <link xref="mal_block_title">mal_block_title</link>, - <link xref="mal_block">mal_block</link> *, - mal_section * -} -</code></synopsis> - -<p>A section is a prominent logical part of a page or another section. -Breaking up material into sections can help readers find information -more quickly. In Mallard, sections can take part in -<link xref="links">automatic linking</link> just as pages can.</p> - -<!-- BEGIN notes --> -<section id="notes"> - <title>Notes</title> - <list> - <item><p>The <code>section</code> element contains an optional - <code xref="mal_info">info</code> element, a <code xref="mal_block_title">title</code> - element, any <link xref="mal_block">general block content</link>, and - any number of <code xref="mal_section">section</code> elements.</p></item> - - <item><p>The <code>section</code> can occur in <code xref="mal_page">page</code> - elements and other <code>section</code> elements.</p></item> - - <item><p>The <code>id</code> attribute takes a unique identifier. It should - be distinct from all other <code>id</code> attributes in the same page, - including those on other <code>section</code> elements and on the containing - <code xref="mal_page">page</code> element.</p></item> - - <item><p>The <code>style</code> attribute takes a space-separated list of - style hints. Processing tools should adjust their behavior according to - those style hints they understand.</p></item> - - <item><p>The <code>section</code> element can have attributes from external - namespaces. See <link xref="mal_external"/> for more information - on external-namespace attributes.</p></item> - </list> -</section> -<!-- END notes --> - - -<!-- BEGIN processing --> -<section id="processing"> - <title>Processing Expectations</title> - - <p>Each section is displayed as a block. The title of a section is displayed - prominently, followed by any child block content, and finally by each child - section. Note that automatic links, style hints, or other special features - may insert material or change the way pages are displayed. Sections should - be clearly separated from their surrounding content to make the beginning and - ending of each section obvious. The depth of each section should be clear, - although this may not be feasible for deeply nested sections.</p> - - <p>Sections may have links associated with them. All sections should have - guide links and see also links displayed when applicable. See - <link xref="links#guide"/> and <link xref="links#seealso"/> for more - information. Sections in guide pages have topic links inserted following - their block content. See <link xref="links#topic"/> for more information.</p> -</section> -<!-- END processing --> - -</page> diff --git a/doc/mallard/C/mal_table.page b/doc/mallard/C/mal_table.page deleted file mode 100644 index 9b9abac..0000000 --- a/doc/mallard/C/mal_table.page +++ /dev/null @@ -1,471 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="mal_table"> - -<info> -</info> - -<title>Tables</title> - -<synopsis><code mime="application/relax-ng-compact-syntax"> -mal_table = element table { - attribute style { xsd:NMTOKENS } ?, - attribute * - (mal:* | local:*) { text } *, - attribute frame { - "all" | "none" | - list { ("top" | "bottom" | "left" | "right") * } - } ?, - attribute rules { - "all" | "groups" | "none" | - list { ("rows" | "rowgroups" | "cols" | "colgroups") * } - } ?, - attribute shade { - "all" | "groups" | "none" | - list { ("rows" | "rowgroups" | "cols" | "colgroups") * } - } ?, - - <link xref="mal_block_title">mal_block_title</link> ?, - <link xref="mal_block_desc">mal_block_desc</link> ?, - - ( <link xref="mal_table_col">mal_table_col</link> + | - <link xref="mal_table_col">mal_table_colgroup</link> + - ) ?, - - ( <link xref="mal_table_tr">mal_table_tr</link> + | - ( <link xref="mal_table_tr">mal_table_thead</link> ?, - <link xref="mal_table_tr">mal_table_tbody</link> +, - <link xref="mal_table_tr">mal_table_tfoot</link> ? - ) - ) -} -</code></synopsis> - - -<!-- BEGIN content --> -<section id="content"> - <info> - <revision status="stub"/> - </info> - <title>Content</title> -</section> -<!-- END content --> - - -<!-- BEGIN attributes --> -<section id="attributes"> - <info> - <revision status="stub"/> - </info> - <title>Attributes</title> -</section> -<!-- END attributes --> - - -<!-- BEGIN examples --> -<section id="examples"> - <title>Examples</title> - -<section id="examples-rules"> - <title>The <code>rules</code> Attribute</title> - - <p>Place rules between each row:</p> - - <example> - <code><![CDATA[ -<table frame="all" rules="rows"> - <tr> - <td><p>Mallard</p></td> <td><p>Anas platyrhynchos</p></td> - <td><p>56-65 cm</p></td> <td><p>900-1200 g</p></td> - </tr> - <tr> - <td><p>Eurasian Wigeon</p></td> <td><p>Anas penelope</p></td> - <td><p>45-50 cm</p></td> <td><p>680 g</p></td> - </tr> - <tr> - <td><p>Common Teal</p></td> <td><p>Anas crecca</p></td> - <td><p>34-43 cm</p></td> <td><p>360 g</p></td> - </tr> - <tr> - <td><p>Northern Pintail</p></td> <td><p>Anas acuta</p></td> - <td><p>59-76 cm</p></td> <td><p>450-1360 g</p></td> - </tr> -</table>]]></code> - <table frame="all" rules="rows"> - <tr> - <td><p>Mallard</p></td> <td><p>Anas platyrhynchos</p></td> - <td><p>56-65 cm</p></td> <td><p>900-1200 g</p></td> - </tr> - <tr> - <td><p>Eurasian Wigeon</p></td> <td><p>Anas penelope</p></td> - <td><p>45-50 cm</p></td> <td><p>680 g</p></td> - </tr> - <tr> - <td><p>Common Teal</p></td> <td><p>Anas crecca</p></td> - <td><p>34-43 cm</p></td> <td><p>360 g</p></td> - </tr> - <tr> - <td><p>Northern Pintail</p></td> <td><p>Anas acuta</p></td> - <td><p>59-76 cm</p></td> <td><p>450-1360 g</p></td> - </tr> - </table> - </example> - - <p>Place rules between each colum:</p> - - <example> - <code><![CDATA[ -<table frame="all" rules="cols"> - <tr> - <td><p>Mallard</p></td> <td><p>Anas platyrhynchos</p></td> - <td><p>56-65 cm</p></td> <td><p>900-1200 g</p></td> - </tr> - <tr> - <td><p>Eurasian Wigeon</p></td> <td><p>Anas penelope</p></td> - <td><p>45-50 cm</p></td> <td><p>680 g</p></td> - </tr> - <tr> - <td><p>Common Teal</p></td> <td><p>Anas crecca</p></td> - <td><p>34-43 cm</p></td> <td><p>360 g</p></td> - </tr> - <tr> - <td><p>Northern Pintail</p></td> <td><p>Anas acuta</p></td> - <td><p>59-76 cm</p></td> <td><p>450-1360 g</p></td> - </tr> -</table>]]></code> - <table frame="all" rules="cols"> - <tr> - <td><p>Mallard</p></td> <td><p>Anas platyrhynchos</p></td> - <td><p>56-65 cm</p></td> <td><p>900-1200 g</p></td> - </tr> - <tr> - <td><p>Eurasian Wigeon</p></td> <td><p>Anas penelope</p></td> - <td><p>45-50 cm</p></td> <td><p>680 g</p></td> - </tr> - <tr> - <td><p>Common Teal</p></td> <td><p>Anas crecca</p></td> - <td><p>34-43 cm</p></td> <td><p>360 g</p></td> - </tr> - <tr> - <td><p>Northern Pintail</p></td> <td><p>Anas acuta</p></td> - <td><p>59-76 cm</p></td> <td><p>450-1360 g</p></td> - </tr> - </table> - </example> - - <p>Place rules between each row group:</p> - - <example> - <code><![CDATA[ -<table frame="all" rules="rowgroups cols"> - <tbody> - <tr> - <td><p>Mallard</p></td> <td><p>Anas platyrhynchos</p></td> - <td><p>56-65 cm</p></td> <td><p>900-1200 g</p></td> - </tr> - <tr> - <td><p>Eurasian Wigeon</p></td> <td><p>Anas penelope</p></td> - <td><p>45-50 cm</p></td> <td><p>680 g</p></td> - </tr> - </tbody> - <tbody> - <tr> - <td><p>Common Teal</p></td> <td><p>Anas crecca</p></td> - <td><p>34-43 cm</p></td> <td><p>360 g</p></td> - </tr> - <tr> - <td><p>Northern Pintail</p></td> <td><p>Anas acuta</p></td> - <td><p>59-76 cm</p></td> <td><p>450-1360 g</p></td> - </tr> - </tbody> -</table>]]></code> - <table frame="all" rules="rowgroups cols"> - <tbody> - <tr> - <td><p>Mallard</p></td> <td><p>Anas platyrhynchos</p></td> - <td><p>56-65 cm</p></td> <td><p>900-1200 g</p></td> - </tr> - <tr> - <td><p>Eurasian Wigeon</p></td> <td><p>Anas penelope</p></td> - <td><p>45-50 cm</p></td> <td><p>680 g</p></td> - </tr> - </tbody> - <tbody> - <tr> - <td><p>Common Teal</p></td> <td><p>Anas crecca</p></td> - <td><p>34-43 cm</p></td> <td><p>360 g</p></td> - </tr> - <tr> - <td><p>Northern Pintail</p></td> <td><p>Anas acuta</p></td> - <td><p>59-76 cm</p></td> <td><p>450-1360 g</p></td> - </tr> - </tbody> - </table> - </example> - - <p>Place rules between each column group:</p> - - <example> - <code><![CDATA[ -<table frame="all" rules="rows colgroups"> - <colgroup><col/><col/></colgroup> - <colgroup><col/><col/></colgroup> - <tr> - <td><p>Mallard</p></td> <td><p>Anas platyrhynchos</p></td> - <td><p>56-65 cm</p></td> <td><p>900-1200 g</p></td> - </tr> - <tr> - <td><p>Eurasian Wigeon</p></td> <td><p>Anas penelope</p></td> - <td><p>45-50 cm</p></td> <td><p>680 g</p></td> - </tr> - <tr> - <td><p>Common Teal</p></td> <td><p>Anas crecca</p></td> - <td><p>34-43 cm</p></td> <td><p>360 g</p></td> - </tr> - <tr> - <td><p>Northern Pintail</p></td> <td><p>Anas acuta</p></td> - <td><p>59-76 cm</p></td> <td><p>450-1360 g</p></td> - </tr> -</table>]]></code> - <table frame="all" rules="rows colgroups"> - <colgroup><col/><col/></colgroup> - <colgroup><col/><col/></colgroup> - <tr> - <td><p>Mallard</p></td> <td><p>Anas platyrhynchos</p></td> - <td><p>56-65 cm</p></td> <td><p>900-1200 g</p></td> - </tr> - <tr> - <td><p>Eurasian Wigeon</p></td> <td><p>Anas penelope</p></td> - <td><p>45-50 cm</p></td> <td><p>680 g</p></td> - </tr> - <tr> - <td><p>Common Teal</p></td> <td><p>Anas crecca</p></td> - <td><p>34-43 cm</p></td> <td><p>360 g</p></td> - </tr> - <tr> - <td><p>Northern Pintail</p></td> <td><p>Anas acuta</p></td> - <td><p>59-76 cm</p></td> <td><p>450-1360 g</p></td> - </tr> - </table> - </example> - -</section> - -<section id="examples-shade"> - <title>The <code>shade</code> Attribute</title> - - <p>Shade alternating rows:</p> - - <example> - <code><![CDATA[ -<table frame="all" shade="rows"> - <tr> - <td><p>Mallard</p></td> <td><p>Anas platyrhynchos</p></td> - <td><p>56-65 cm</p></td> <td><p>900-1200 g</p></td> - </tr> - <tr> - <td><p>Eurasian Wigeon</p></td> <td><p>Anas penelope</p></td> - <td><p>45-50 cm</p></td> <td><p>680 g</p></td> - </tr> - <tr> - <td><p>Common Teal</p></td> <td><p>Anas crecca</p></td> - <td><p>34-43 cm</p></td> <td><p>360 g</p></td> - </tr> - <tr> - <td><p>Northern Pintail</p></td> <td><p>Anas acuta</p></td> - <td><p>59-76 cm</p></td> <td><p>450-1360 g</p></td> - </tr> -</table>]]></code> - <table frame="all" shade="rows"> - <tr> - <td><p>Mallard</p></td> <td><p>Anas platyrhynchos</p></td> - <td><p>56-65 cm</p></td> <td><p>900-1200 g</p></td> - </tr> - <tr> - <td><p>Eurasian Wigeon</p></td> <td><p>Anas penelope</p></td> - <td><p>45-50 cm</p></td> <td><p>680 g</p></td> - </tr> - <tr> - <td><p>Common Teal</p></td> <td><p>Anas crecca</p></td> - <td><p>34-43 cm</p></td> <td><p>360 g</p></td> - </tr> - <tr> - <td><p>Northern Pintail</p></td> <td><p>Anas acuta</p></td> - <td><p>59-76 cm</p></td> <td><p>450-1360 g</p></td> - </tr> - </table> - </example> - - <p>Shade alternating columns:</p> - - <example> - <code><![CDATA[ -<table frame="all" shade="cols"> - <tr> - <td><p>Mallard</p></td> <td><p>Anas platyrhynchos</p></td> - <td><p>56-65 cm</p></td> <td><p>900-1200 g</p></td> - </tr> - <tr> - <td><p>Eurasian Wigeon</p></td> <td><p>Anas penelope</p></td> - <td><p>45-50 cm</p></td> <td><p>680 g</p></td> - </tr> - <tr> - <td><p>Common Teal</p></td> <td><p>Anas crecca</p></td> - <td><p>34-43 cm</p></td> <td><p>360 g</p></td> - </tr> - <tr> - <td><p>Northern Pintail</p></td> <td><p>Anas acuta</p></td> - <td><p>59-76 cm</p></td> <td><p>450-1360 g</p></td> - </tr> -</table>]]></code> - <table frame="all" shade="cols"> - <tr> - <td><p>Mallard</p></td> <td><p>Anas platyrhynchos</p></td> - <td><p>56-65 cm</p></td> <td><p>900-1200 g</p></td> - </tr> - <tr> - <td><p>Eurasian Wigeon</p></td> <td><p>Anas penelope</p></td> - <td><p>45-50 cm</p></td> <td><p>680 g</p></td> - </tr> - <tr> - <td><p>Common Teal</p></td> <td><p>Anas crecca</p></td> - <td><p>34-43 cm</p></td> <td><p>360 g</p></td> - </tr> - <tr> - <td><p>Northern Pintail</p></td> <td><p>Anas acuta</p></td> - <td><p>59-76 cm</p></td> <td><p>450-1360 g</p></td> - </tr> - </table> - </example> - - <p>Shade alternating row groups:</p> - - <example> - <code><![CDATA[ -<table frame="all" shade="rowgroups cols"> - <tbody> - <tr> - <td><p>Mallard</p></td> <td><p>Anas platyrhynchos</p></td> - <td><p>56-65 cm</p></td> <td><p>900-1200 g</p></td> - </tr> - <tr> - <td><p>Eurasian Wigeon</p></td> <td><p>Anas penelope</p></td> - <td><p>45-50 cm</p></td> <td><p>680 g</p></td> - </tr> - </tbody> - <tbody> - <tr> - <td><p>Common Teal</p></td> <td><p>Anas crecca</p></td> - <td><p>34-43 cm</p></td> <td><p>360 g</p></td> - </tr> - <tr> - <td><p>Northern Pintail</p></td> <td><p>Anas acuta</p></td> - <td><p>59-76 cm</p></td> <td><p>450-1360 g</p></td> - </tr> - </tbody> -</table>]]></code> - <table frame="all" shade="rowgroups cols"> - <tbody> - <tr> - <td><p>Mallard</p></td> <td><p>Anas platyrhynchos</p></td> - <td><p>56-65 cm</p></td> <td><p>900-1200 g</p></td> - </tr> - <tr> - <td><p>Eurasian Wigeon</p></td> <td><p>Anas penelope</p></td> - <td><p>45-50 cm</p></td> <td><p>680 g</p></td> - </tr> - </tbody> - <tbody> - <tr> - <td><p>Common Teal</p></td> <td><p>Anas crecca</p></td> - <td><p>34-43 cm</p></td> <td><p>360 g</p></td> - </tr> - <tr> - <td><p>Northern Pintail</p></td> <td><p>Anas acuta</p></td> - <td><p>59-76 cm</p></td> <td><p>450-1360 g</p></td> - </tr> - </tbody> - </table> - </example> - - <p>Shade alternating column groups:</p> - - <example> - <code><![CDATA[ -<table frame="all" shade="rows colgroups"> - <colgroup><col/><col/></colgroup> - <colgroup><col/><col/></colgroup> - <tr> - <td><p>Mallard</p></td> <td><p>Anas platyrhynchos</p></td> - <td><p>56-65 cm</p></td> <td><p>900-1200 g</p></td> - </tr> - <tr> - <td><p>Eurasian Wigeon</p></td> <td><p>Anas penelope</p></td> - <td><p>45-50 cm</p></td> <td><p>680 g</p></td> - </tr> - <tr> - <td><p>Common Teal</p></td> <td><p>Anas crecca</p></td> - <td><p>34-43 cm</p></td> <td><p>360 g</p></td> - </tr> - <tr> - <td><p>Northern Pintail</p></td> <td><p>Anas acuta</p></td> - <td><p>59-76 cm</p></td> <td><p>450-1360 g</p></td> - </tr> -</tbody> -</table>]]></code> - <table frame="all" shade="rows colgroups"> - <colgroup><col/><col/></colgroup> - <colgroup><col/><col/></colgroup> - <tr> - <td><p>Mallard</p></td> <td><p>Anas platyrhynchos</p></td> - <td><p>56-65 cm</p></td> <td><p>900-1200 g</p></td> - </tr> - <tr> - <td><p>Eurasian Wigeon</p></td> <td><p>Anas penelope</p></td> - <td><p>45-50 cm</p></td> <td><p>680 g</p></td> - </tr> - <tr> - <td><p>Common Teal</p></td> <td><p>Anas crecca</p></td> - <td><p>34-43 cm</p></td> <td><p>360 g</p></td> - </tr> - <tr> - <td><p>Northern Pintail</p></td> <td><p>Anas acuta</p></td> - <td><p>59-76 cm</p></td> <td><p>450-1360 g</p></td> - </tr> - </table> - </example> - -</section> -</section> -<!-- END examples --> - - -<!-- BEGIN design --> -<section id="design"> - <info> - <revision status="stub"/> - </info> - <title>Design Notes</title> -</section> -<!-- END design --> - - -<!-- BEGIN html --> -<section id="html"> - <info> - <revision status="stub"/> - </info> - <title>Comparison to HTML</title> -</section> -<!-- END html --> - - -<!-- BEGIN docbook --> -<section id="docbook"> - <info> - <revision status="stub"/> - </info> - <title>Comparison to DocBook</title> -</section> -<!-- END docbook --> - -</page> diff --git a/doc/mallard/C/mal_table_col.page b/doc/mallard/C/mal_table_col.page deleted file mode 100644 index 094b6ff..0000000 --- a/doc/mallard/C/mal_table_col.page +++ /dev/null @@ -1,24 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="mal_table_col"> - -<info> - <link type="guide" xref="mal_block#tables"/> -</info> - -<title>Columns and Column Groups</title> - -<synopsis><code mime="application/relax-ng-compact-syntax"> -mal_table_col = element col { - attribute style { xsd:NMTOKENS } ?, - attribute * - (mal:* | local:*) { text } * -} -mal_table_colgroup = element colgroup { - attribute style { xsd:NMTOKENS } ?, - attribute * - (mal:* | local:*) { text } *, - - mal_table_col * -} -</code></synopsis> - -</page> diff --git a/doc/mallard/C/mal_table_td.page b/doc/mallard/C/mal_table_td.page deleted file mode 100644 index 54b4868..0000000 --- a/doc/mallard/C/mal_table_td.page +++ /dev/null @@ -1,22 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="mal_table_td"> - -<info> - <link type="guide" xref="mal_block#tables"/> -</info> - -<title>Table Cells</title> - -<synopsis><code mime="application/relax-ng-compact-syntax"> -mal_table_td = element td { - attribute style { xsd:NMTOKENS } ?, - attribute * - (mal:* | local:*) { text } *, - attribute rowspan { text } ?, - attribute colspan { text } ?, - - <link xref="mal_block">mal_block</link> + -} -</code></synopsis> - -</page> diff --git a/doc/mallard/C/mal_table_tr.page b/doc/mallard/C/mal_table_tr.page deleted file mode 100644 index 9119e6b..0000000 --- a/doc/mallard/C/mal_table_tr.page +++ /dev/null @@ -1,38 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="mal_table_tr"> - -<info> - <link type="guide" xref="mal_block#tables"/> -</info> - -<title>Rows and Row Groups</title> - -<synopsis><code mime="application/relax-ng-compact-syntax"> -mal_table_tr = element tr { - attribute style { xsd:NMTOKENS } ?, - attribute * - (mal:* | local:*) { text } *, - - <link xref="mal_table_td">mal_table_td</link> * -} -mal_table_thead = element thead { - attribute style { xsd:NMTOKENS } ?, - attribute * - (mal:* | local:*) { text } *, - - mal_table_tr + -} -mal_table_tbody = element tbody { - attribute style { xsd:NMTOKENS } ?, - attribute * - (mal:* | local:*) { text } *, - - mal_table_tr + -} -mal_table_tfoot = element tfoot { - attribute style { xsd:NMTOKENS } ?, - attribute * - (mal:* | local:*) { text } *, - - mal_table_tr + -} -</code></synopsis> - -</page> diff --git a/doc/mallard/C/principle-guide.page b/doc/mallard/C/principle-guide.page deleted file mode 100644 index 47e7fe0..0000000 --- a/doc/mallard/C/principle-guide.page +++ /dev/null @@ -1,15 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="principle-guide"> - -<info> - <desc>Ensure the reader doesn't get lost in a link swarm</desc> - - <link type="guide" xref="principles#reader"/> - - <revision version="0.1" date="2007-02-26" status="stub"/> -</info> - -<title>Guide the Reader</title> - -</page> diff --git a/doc/mallard/C/principle-justenough.page b/doc/mallard/C/principle-justenough.page deleted file mode 100644 index b0a897c..0000000 --- a/doc/mallard/C/principle-justenough.page +++ /dev/null @@ -1,14 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="principle-justenough"> - -<info> - <revision version="0.1" date="2007-02-26" status="stub"/> - <link type="guide" xref="principles#writer"/> - <link type="guide" xref="principles#hacker"/> - <desc>Provide just enough markup to mark up what's important</desc> -</info> - -<title>Just Enough Markup</title> - -</page> diff --git a/doc/mallard/C/principle-redundancy.page b/doc/mallard/C/principle-redundancy.page deleted file mode 100644 index 5c5cc4b..0000000 --- a/doc/mallard/C/principle-redundancy.page +++ /dev/null @@ -1,13 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="principle-redundancy"> - -<info> - <revision version="0.1" date="2007-02-26" status="stub"/> - <link type="guide" xref="principles#writer"/> - <desc>Avoid forcing writers to write the same thing twice</desc> -</info> - -<title>Reduce Redundancy</title> - -</page> diff --git a/doc/mallard/C/principles.page b/doc/mallard/C/principles.page deleted file mode 100644 index ca24eaa..0000000 --- a/doc/mallard/C/principles.page +++ /dev/null @@ -1,58 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="guide" - id="principles"> - -<info> - <revision version="0.1" date="2007-02-21" status="stub"/> - - <credit type="author"> - <name>Shaun McCance</name> - <email>shaunm@gnome.org</email> - <years>2008-2009</years> - </credit> - - <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" /> - - <desc>The guiding principles behind the design of Mallard.</desc> -</info> - -<title>Design Principles</title> - -<comment> - <cite date="2008-11-10">Shaun McCance</cite> - <p>Add intro content</p> - <p>Add principles: pluggability, implementation speed, l10n, digestible info</p> -</comment> - -<section id="reader"> - <info> - <title type="link">Principles for the Reader</title> - </info> - - <title>For the Reader</title> - - <p>Readers are the ultimate arbiters of the quality of a documentation - system. The best efforts of the writers and hackers are wasted if the - documention doesn't help the reader to find the information she needs - quickly. The needs of the reader trump all other requirements.</p> -</section> - -<section id="writer"> - <info> - <title type="link">Principles for the Writer</title> - </info> - <title>For the Writer</title> - <comment> - <cite date="2007-02-27">Shaun McCance</cite> - <p>Add</p> - </comment> -</section> - -<section id="hacker"> - <info> - <title type="link">Principles for the Hacker</title> - </info> - <title>For the Hacker</title> -</section> - -</page> diff --git a/doc/mallard/C/spec.page b/doc/mallard/C/spec.page deleted file mode 100644 index 55e066d..0000000 --- a/doc/mallard/C/spec.page +++ /dev/null @@ -1,27 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - type="guide" - id="spec"> - -<info> - <link type="topic" xref="mal_page"/> - <link type="topic" xref="mal_section"/> - - <revision version="0.1" date="2007-02-21" status="stub"/> - - <credit type="author"> - <name>Shaun McCance</name> - <email>shaunm@gnome.org</email> - <years>2009</years> - </credit> - - <desc>Complete specification of the Mallard XML vocabulary.</desc> -</info> - -<title>Language Specification</title> - -<comment> - <cite date="2007-02-20">Shaun McCance</cite> - <p>Add some intro text</p> -</comment> - -</page> diff --git a/doc/mallard/C/tenminutes.page b/doc/mallard/C/tenminutes.page deleted file mode 100644 index 26a158c..0000000 --- a/doc/mallard/C/tenminutes.page +++ /dev/null @@ -1,117 +0,0 @@ -<page xmlns="http://projectmallard.org/1.0/" - xmlns:e="http://projectmallard.org/experimental/" - type="topic" - id="tenminutes"> - -<info> - <revision version="0.1" date="2009-06-16" status="incomplete"/> - - <credit type="author"> - <name>Shaun McCance</name> - <email>shaunm@gnome.org</email> - <years>2008-2009</years> - </credit> - - <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" /> - - <desc>Create a multiple-page document in only ten minutes.</desc> -</info> - -<title>Ten Minute Tour</title> - -<comment> - <cite date="2009-06-16">shaunm</cite> - <p>This is draft material. I'm not happy with the tone yet.</p> -</comment> - -<p>In this page, we will present how to create a simple multiple-page Mallard -document. We will create a document for the fictitious <app>Beanstalk</app> -application, which allows you to plant magic beans.</p> - -<p>A Mallard document is composed of multiple independent pages. -<link xref="mal_page#topic">Topic pages</link> present some piece of information -to the reader. This might be a tutorial, a conceptual overview, reference material, -or any other type of written content. <link xref="mal_page#guide">Guide pages</link> -serve as the navigational glue between topics, helping readers find and explore -content.</p> - -<p>We can begin making a Mallard document by writing a front page for our -document. Generally, the front page of any document will be a guide page, -as its purpose is to help users navigate to other content. In Mallard, the -front page of any document is named <file>index.page</file>.</p> - -<listing> - <title><file>index.page</file></title> - <code><![CDATA[ -<page xmlns="http://projectmallard.org/1.0/" - type="guide" - id="index"> -<title>Beanstalk Help</title> -</page>]]></code> -</listing> - -<p>This simple example is a valid Mallard guide page. Taken alone, it is -also a valid Mallard document, although it's rather useless. We can add -another page to the document by creating a new page file.</p> - -<listing> - <title><file>planting.page</file></title> - <code><![CDATA[ -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="planting"> -<title>Planting Beans</title> -</page>]]></code> -</listing> - -<p>Notice that we have set the <code>type</code> attribute to <code>"guide"</code> -in <file>index.page</file> and to <code>"topic"</code> in <file>planting.page</file>. -This specifies that <file>index.page</file> is a guide page, which will allow it to -have automatic links to other pages. Currently, we have two standalone pages without -interlinking. We can have <file>index.page</file> link to <file>planting.page</file>.</p> - -<listing> - <title><file>planting.page</file></title> - <code><![CDATA[ -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="planting"> -]]><e:hi><![CDATA[<info> - <link type="guide" xref="index"/> -</info>]]></e:hi><![CDATA[ -<title>Planting Beans</title> -</page>]]></code> -</listing> - -<comment> - <cite date="2009-06-16">shaunm</cite> - <p>Explain the linking and introduce the next example.</p> -</comment> - -<listing> - <title><file>planting.page</file></title> - <code><![CDATA[ -<page xmlns="http://projectmallard.org/1.0/" - type="topic" - id="planting"> -<info> - <link type="guide" xref="index"/> -</info> -<title>Planting Beans</title>]]><e:hi><![CDATA[ -<p>By the end of this page, you will be able to plant your magic -beans and nurture them into a bean sprout.</p> -<steps> - <item><p>Dig a hole 5cm deep.</p></item> - <item><p>Place your magic beans in the hole.</p></item> - <item><p>Fill the hole with clean dirt and pat it level.</p></item> - <item><p>Water daily.</p></item> -</steps>]]></e:hi><![CDATA[ -</page>]]></code> -</listing> - -<comment> - <cite date="2009-06-16">shaunm</cite> - <p>Fill in more content.</p> -</comment> - -</page> |
