[back]
[Copyright Notice]
[Contents]
[next]
Debiandoc-SGML Markup Manual - Chapter 4
Marked-up inline text and character style markup
Ordinary text (called `inline text' in this document) may
contain a elements for special formatting and
cross-referencing. Inline text appears in chapter, appendix
and section titles, in the copyright summary, inside
paragraphs and in other similar places.
There are a number of elements for denoting special
significance of certain pieces of text. For all of them the
end of the special text must be marked up explicitly, by
using an explicit end tag
<element>, the abbreviated end tag
for closing the innermost element </> or
the slash / which finishes the most abbreviated
form of element markup (see SGML markup and metacharacters, chapter 1).
- <em> - emphasis
- Indicates that the contained text is more important or
more significant than that surrounding it.
Typically this will be represented by italics if
available, or emboldened or underlined text, or in
plain text formats with no character highlighting
available by surrounding the text with asterisks like
*this*.
- <strong> - more emphasis
- Indicates that the contained text is even more
important or even more significant than that
surrounding it.
Typically this will be represented by bold if
available or in plain text formats with no character
highlighting available by surrounding the text with
asterisks like *this*.
- <var> - metasyntactic variable
- Indicates that the contained text is a metasyntactic
variable. Ie, it is the name of an object or piece of
syntax which when actually used would have a real
value substituted.
Typically this will be represented by italics, or in
plain text formats by surrounding the text with angle
brackets like <this>. If several metasyntactic
variables appear one after the other they should each
be given their own <var> element.
- <package> - package name
- Indicates that the contained text is the name of a
Debian package.
This will usually be rendered using a fixed-width
font; in plain-text formats quotes may be used around
the element.
- <prgn> - name of a program or well-known file
- Indicates that the contained text is the name of a
program, a well-known filename (usually without paths),
a function or some similar thing which has a name in
the computer.
In output formats where character highlighting and
various font styles are available this is usually
represented by using a fixed-width font. In plain text
output formats these names are not specially marked at
all, as they occur frequently and introducing quoting
would disrupt the flow of the text.
- <file> - full file or directory name
- Indicates that the contained text is the full pathname
of a file, buffer, directory, etc.
This will usually be rendered using a fixed-width
font; in plain-text formats quotes may be used around
the element.
- <tt> - code or output fragment, command string
- Indicates that the contained text is a general string
which came out of or is going in to a computer. It
should be used for command strings or code fragments
that should be displayed inline and wordrapped (see
also Examples, section 5.2 for an alternative), and so
forth. It is frequently necessary to introduce
metasyntactic variables into these strings, in which
case they should be made part of the
<tt> element rather than elements
alongside it.
This will usually be rendered using a fixed-width
font; in plain-text formats quotes may be used around
the element.
- <qref id="refid"> - quiet reference
- Produces a `quiet reference' to the named reference
id (see Cross-references, section 4.2). This should be used where a
cross-reference would be useful if not intrusive, but
where it is not essential and should be left out if it
would need to intrude on the text.
In formats where cross-references can be made
non-intrusively by making a region of text a hyperlink
without introducing in-line text this element will
cause its contained text to become a hyperlink to the
target of the cross-reference. In other formats this
element will not have any effect.
There are a number of elements for introducing
cross-references either to other parts of the same document
or to other documents.
The intra-document cross-references are based on a scheme of
reference identifiers. Each chapter, appendix, section,
subsection etc. may have an id attribute giving its
reference id - for example <chapt id="spong">
specifies that the chapter or appendix being started has
reference id spong. This reference id can then be
referred to in other parts of the document using the special
cross-referencing elements.
The reference identifier will also be used for generating
filenames and reference tokens for formats such as HTML
which produce several output files; if no reference ids are
specified then the chapter, appendix and section numbers
will be used. It is a good idea to give at least all your
chapter and appendix reference ids so that the filenames
will not change if you change the order of the chapters,
appendices or sections in your document.
- <ref id="refid"> - intra-document cross reference
- This generates a cross-reference within the same
document to the chapter, appendix or section with id
refid.
The <ref> element does not have any
contents; the chapter, appendix or section number and
title and its page number or whatever is appropriate
for the output format will be inserted into the text
at the point where the tag appears.
Syntactically the cross reference is a noun phrase,
suitable for uses like (see <ref
id="...">) or further info is
in <ref id="...">..
- <manref name="name" section="section"> - manpage
- Generates a cross-reference to the manpage for
name in section section. This
tag does not have any contents; text describing the
page, typically
name(section), will be
inserted at the point where <manref>
appears.
- <email> - email address
- Indicates that the contained text is an email address.
The contents of the tag should be just the text of the
email address itself; character style markup and
cross-references are forbidden. Usually the end tag
</email> may not be omitted, but it may
be left out when it appears in an
<author> as the end of the
<author>, implied by the start of the
next element, will imply the end of the email
address.
In some formats this will generate a true
cross-reference which might (for example) be used to
send email to the address quoted. In others it will
just mark the text specially, usually including angle
brackets < > around it.
- <ftpsite> - anonymous FTP site name
- <ftppath> - path on most recently named FTP site
- <ftpsite> indicates that the content of
the element is the DNS name of an anonymous FTP site,
and <ftppath> that it is a pathname on
that site. Both elements may not contain any
character style markup or cross-references.
Typically both elements will be rendered in a fixed
width font; if possible, the <ftppath>
will be made into a functional hyperlink to the named
file or directory on the most recent
<ftpsite>.
<ftppath> must always have been
preceded by a <ftpsite> in the same
chapter or appendix, but once one site has been named
several paths may be appear.
- <httpsite> - HTTP site name
- <httppath> - path on most recently named HTTP site
- <httpsite> indicates that the content
of the element is the DNS name of an HTTP site, and
<httppath> that it is a pathname on
that site. Both elements may not contain any
character style markup or cross-references.
Typically both elements will be rendered in a fixed
width font; if possible, the <httppath>
will be made into a functional hyperlink to the named
file or directory on the most recent
<httpsite>.
<httppath> must always have been
preceded by a <httpsite> in the same
chapter or appendix, but once one site has been named
several paths may be appear.
- <url id="id" name="name"> - URL
- Generates a cross-reference to the URL with the
indicated id and uses the optional
name in the document as reference
indicator. This tag does not have any contents.
Typically this element will be rendered in a fixed
width font; if possible, id will be made
into a functional hyperlink using name as
place holder.
Footnotes may appear in most inline text, and are indicated
by <footnote>...</footnote>.
The text of the footnote itself will be removed and placed
elsewhere (where depends on the format), and replaced with a
reference or hyperlink to the footnote.
The contents of the footnote should be one or more
paragraphs; the start of the first paragraph need not be
marked explicitly. Inline markup elements such as character
style do not take effect on the contents of footnotes
defined inside them - the footnote gets a `clean slate'.
Footnotes may be nested, but this is rarely a good idea.
[back]
[Copyright Notice]
[Contents]
[next]
Debiandoc-SGML Markup Manual
29 January 1999
Ian Jackson ijackson@gnu.ai.mit.edu
Ardo van Rangelrooij ardo@debian.org