Home >

Writing rules: References

Creating references

It is often necessary to refer the reader to other sections or chapters in the manual, to an illustration, or even to a separate document or manual.

  • For PDF output, only refer to page numbers!
  • For CHM output, do not include page numbers!
  • Use a full stop after the reference only if the text forms a full sentence.

To create a page reference to a chapter, section, table or illustration within the same document, we shall always refer to titles together with page numbers, and never to figure numbers or paragraph numbers by themselves.

Avoid phrases like “as shown below” or “in the illustration above”. If illustrations are moved or replaced, either automatically or by purpose, such phrases may only confuse the reader. If you must refer to an illustration, use a caption, and refer to the caption and page numbers.

To present page or section references, the following methods are available:

  • Inline references
    • Page references within the same document
    • Reference to section or chapter within the same document, but without page number
    • Reference to another document or manual
  • Bullet list with title "Topics"
  • Bullet list with title "Related topics"
  • Bullet list with special "arrow" bullets

Page reference within the same document

For page references within the same document, use XML tags <xref> or <link>.

Example:

For more information about this feature, refer to Operational modes on page 25.

In Microsoft Word, use italics as indicated in the example.

Reference to section or chapter within the same document, but without page number

To reference a section or chapter within the same document, but without providing the page number, place the title you refer to inside XML inline tag <phrase role=”sectitle”>.

In XML, you can automatically reuse the referenced title by using the <xref> tag and role="titleonly".

Example:

For more information about this feature, refer to chapter Operational modes.

In Microsoft Word, use italics as indicated in the example.

Note: Avoid this type of reference!

Reference to another document or manual

To reference another document or manual, place the title you refer to inside the XML <phrase role=”doctitle”> inline tag.

Example:

For more information about this feature, refer to the EM 3002 Installation manual.

In Microsoft Word, use italics as indicated in the example.

Bullet list with title "Topics"

This method is typically used at the beginning of a chapter and/or section to create a local table of contents.

Use a standard bullet list (XML Docbook <itemizedlist>), and use title "Topics". The title must be set with style "GenericTitle". Observe the writing rules related to titles and captions.

Example:

Topics
Operational modes on page 25
Getting started on page 44

Note that each reference does not have a full stop, as these are not full sentences.

Do not place inline references in bullet lists.

Bullet list with title "Related topics"

This method is typically used at the end of a topic to create a summarized list of references. It is also frequently used after a "Topics" list at the beginning of a chapter or section.

Use a standard bullet list (XML Docbook <itemizedlist>), and use title “Related topics”. The title must be set with style "GenericTitle". Observe the writing rules related to titles and captions.

Example:

Related topics
Operational modes on page 25
Getting started on page 44

Note that each reference does not have a full stop, as these are not full sentences.

Do not place inline references in bullet lists.

Bullet list with special "arrow" bullets

This method is typically used within the body text when you wish to place one or more page references as separate elements.

Use a standard bullet list (XML Docbook <itemizedlist>), but do not use a title. Instead, apply role="related" to the itemized list.

Example:

Operational modes on page 25
Getting started on page 44

Note that each reference does not have a full stop, as these are not full sentences.

Do not place inline references in bullet lists.


Writing rules

Related topics

Standards for writing and grammar rules

  • Microsoft Style Guide, 4th Edition, Microsoft Press, Washington, 2012, ISBN 978-0-7356-4871-5
  • Chicago manual of Style, 16th Edition, University of Chicago Press, Chicago, 2012, ISBN 978-0-226-10420-1

Topics