[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ 7 ] [ 8 ] [ A ] [ B ] [ next ]
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 2).
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*.
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*.
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.
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.
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 quotes may be used around the element.
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.
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 6.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.
Produces a `quiet reference' to the named reference id (see Cross-references, Section 5.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.
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="...">..
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.
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> 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> 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.
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.
Do not put this tag between <file> and </file>. This is known to break relative link in PDF format.
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.
Comments may appear in most inline text, and are indicated by <comment editor="foo">...</comment>. The text of the comment itself will be removed and placed elsewhere (where depends on the format), and replaced with a reference or hyperlink to the footnote if -m option is used to enable this.
The contents of the comment should be one or more paragraphs; the start of the first paragraph need not be marked explicitly.
[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ 7 ] [ 8 ] [ A ] [ B ] [ next ]
DebianDoc-SGML Manual
2021-01-16mailto:ardo@debian.orgmailto:ijackson@gnu.ai.mit.edu