Home >

Writing rules: Formatting

Formatting

In all texts we frequently identify functions, buttons, dialog boxes, menus etc. We also frequently refer to other sections, chapters or manuals. In all these cases, the names are written with a special typeface.

In order to reuse and share text elements - and for obvious consistency reasons - we must format our texts identically.

The various editors used allow for different functionality. For this reason, the specifications below provide three alternatives, one for a generic text editor and plain HTML, and the others for an XML editor using the DocBook or DITA document type definitions.

Topics

  • Dialog boxes
  • Menus, submenus and commands
  • Icons
  • Physical buttons
  • Modes, views and panes
  • References
  • File and folder names
  • User input
  • Computer code and program listings

Lists

Bullet and ordered lists with an initial phrase or word

Many lists are used to explain specific words or phrases. A typical example is the list of parameters in a dialog box. The text in the list is normal, but the initial phrase or word must be formatted. This initial phrase or word is provided on a separate line in the list.

  • Generic editor and plain HTML: Use bold characters.
  • XML DocBook: Use tag ><guilabel>.
  • XML DITA: TBD

Examples of accepted formatting

  • Print

    This function allows you to send the active document on a local printer.

  • Exit

    Click this command to close the application

Lists to provide call-outs in an illustration

The is regarded “best practice” to use call-out identifiers in the illustrations, and to identify each call-out in an ordered list. All call-outs shall use upper roman characters. For this reason, the list must be ordered with similar characters.

  • Generic editor and plain HTML: Use italic on all text in the list.
  • XML DocBook: Use italic on all text in the list.
  • XML DITA: Use italic on all text in the list.

Examples of accepted formatting

  1. This character identifies the first call-out identifier.
  2. This character identifies the second call-out identifier.

Note

Some call-out lists may contain more information than simply the identification of each item in the illustration. In such cases, treat the information as a part of the normal text, and do not use italics.

Dialog boxes

As general rule, we follow the recommendations from Microsoft for dialog box formatting.

For terminology, see Dialog boxes.

Dialog box and tab names

  • Generic editor and plain HTML: Use bold characters.
  • XML DocBook: Use tag <guilabel>.
  • XML DITA: <dialogname> and <tabname>

Examples of accepted formatting

The Publish dialog box is opened by clicking Publish on the File menu.

In the Navigation dialog box, click the Speed tab.

Dialog box texts and labels

  • Generic editor and plain HTML: Use bold characters.
  • XML DocBook: Use tag <guilabel>.
  • XML DITA: TBD

Note that the same formatting is made on the available options in the dialog box, for example in a drop-down list box.

Examples of accepted formatting

Select the Spaces text box.

In the Font box, select the font you want to use.

In the Item list, click Desktop.

Dialog box buttons

  • Generic editor and plain HTML: Use bold characters.
  • XML DocBook: Use tag <guibutton>.
  • XML DITA: TBD

Examples of accepted formatting

To close the Publish dialog box, click Close.

Note

We do not write the word button unless it is important to emphasize that it is in fact a button.

Menus, submenus and commands

Menus are general terms divided into submenus and commands. On some of our products we also use menu buttons.

For terminology, see Menus.

Menus

  • Generic editor and plain HTML: Use bold characters.
  • XML DocBook: Use tag <guilmenu>.
  • XML DITA: TBD

Examples of accepted formatting

The Publish dialog box is opened by clicking Publish on the File menu.

On the File menu, click Open.

Submenus

  • Generic editor and plain HTML: Use bold characters.
  • XML DocBook: Use tag <guisubmenu> immediately after a <guilmenu> tag. The stylesheet automatically inserts an arrow.
  • XML DITA: TBD

Examples of accepted formatting

To open the PDF dialog box, click File → Publish → PDF.

On the View menu, click Toolbars, and then Menu bar.

Commands

  • Generic editor and plain HTML: Use bold characters.
  • XML DocBook: Use tag <guilmenuitem> immediately after a <guilmenu> tag. The stylesheet automatically inserts an arrow.
  • XML DITA: TBD

Examples of accepted formatting

To open the PDF dialog box, click File → Publish → PDF.

On the View menu, click Toolbars, and then Menu bar.

Menu buttons

Some of our products do not use the familiar menus known from most Windows programs. Instead, the menus are designed with a number of buttons arranged vertically.

  • Generic editor and plain HTML: Use bold characters.
  • XML DocBook: Use tag <guibutton>.
  • XML DITA: TBD

Examples of accepted formatting

Up start calibration, click Calibration on the Setup menu.

Click Range on the Main menu to select the vertical area of the water column covered by the echogram.

Remember that we do not write the word “button” unless it is important to emphasize the fact that it is a button.

Icons

Use only used to describe a graphic representation of an object that a user can select and open, such as a drive, disk, folder, document or program.
Microsoft Manual of Style, page 311

  • Generic editor and plain HTML: Use bold characters.
  • XML DocBook: Use tag <guiicon>.
  • XML DITA: TBD

Examples of accepted formatting

Click the Word icon.

Buttons

These are physical buttons on keyboards and operating panels.

All buttons

  • Generic editor and plain HTML: Use bold characters.
  • XML DocBook: Use tag <keycap>.
  • XML DITA: Use tag <keycap>.

Examples of accepted formatting

To start the print process, press Enter.

Press Power on the Operating Panel.

Button combinations

  • Generic editor and plain HTML: Use bold characters.
  • XML DocBook: Use a <keycombo> tag containing two (or more) <keycap> tags. The stylesheet will automatically insert the “+” character.
  • XML DITA: TBD

Examples of accepted formatting

To save, press Alt+S.

Modes, views and panes

Each product can offer several different types of modes. Each mode – or presentation – may then contain different views and/or panes.

For terminology, see: Identifying various modes

All mode types

  • Generic editor and plain HTML: Use italic characters.
  • XML DocBook: Use inline tag <phrase role=”mode”> .
  • XML DITA: Use tag <mode>.

Examples of accepted formatting

To open the Wide mode, click Mode → Wide.

Set the system to Test mode to do the offline tests.

In order to see the map, choose the Geographical presentation mode.

All view types

  • Generic editor and plain HTML: Use italic characters.
  • XML DocBook: Use inline tag <phrase role=”mode”> .
  • XML DITA: Use tag <viewname>.

Examples of accepted formatting

To echogram is shown in the Main view.

All pane types

  • Generic editor and plain HTML: Use italic characters.
  • XML DocBook: Use inline tag <phrase role=”mode”> .
  • XML DITA: Use tag <panename>.

Examples of accepted formatting

To click the button to open the Colour scale information pane.

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. In XML, references within the same book are automatically formatted correctly.

The formatting specified here is for the name of the section or book that you refer to.

For more information about referencing, see: Creating references

Reference to section or chapter titles in same book

  • Generic editor and plain HTML: Use italic characters.
  • XML DocBook: Use inline tag <phrase role=”sectitle”> .
  • XML DITA: TBD.

Examples of accepted formatting

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

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

Note

References within a book shall always include a page number!

Reference to another book or document

  • Generic editor and plain HTML: Use italic characters.
  • XML DocBook: Use inline tag <phrase role=”doctitle”> .
  • XML DITA: Use tag <doctitle>.

Examples of accepted formatting

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

File and folder names

File names

  • Generic editor and plain HTML: Courier New 10 pt.
  • XML DocBook: Use inline tag <filename>.
  • XML DITA: TBD.

Examples of accepted formatting

To edit the configuration, open the setup.txt file in folder c:/product.

Folder names

  • Generic editor and plain HTML: Courier New 10 pt.
  • XML DocBook: Use inline tag <filename>.
  • XML DITA: TBD.

Examples of accepted formatting

To edit the configuration, open the setup.txt file in folder c:/product.

User input

This formatting is used whenever you need to specify some text that the end user need to type.

  • Generic editor and plain HTML: Courier New 10 pt.
  • XML DocBook: Use inline tag <userinput>.
  • XML DITA: TBD.

Examples of accepted formatting

In the Input box, type Test.

Computer code and program listings

This formatting is used whenever you need to recreate computer code, for example a program listing or the text output from a computer.

Computer output

  • Generic editor and plain HTML: Courier New 10 pt.
  • XML DocBook: Use inline tag <computeroutput>.
  • XML DITA: TBD.

Program listing

  • Generic editor and plain HTML: Courier New 10 pt.
  • XML DocBook: Use inline tag <programlisting>.
  • XML DITA: TBD.

The <programlisting> element is a block element, which means that it is used by itself.

This element is displayed "verbatim". This means that white space and line-breaks within the content of this element are significant and retained.


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