~ubuntu-branches/ubuntu/hardy/xubuntu-docs/hardy-updates

<?xml version="1.0" encoding="UTF-8"?>

<!--<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 

        "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [

<!ENTITY % xinclude SYSTEM "../../libs/xinclude.mod">

%xinclude;

<!ENTITY % globalent SYSTEM "../../libs/global.ent">

%globalent;

]>-->

<sect1 id="conventions" status="complete">

    <title>Conventions</title>

    <para>

        <emphasis role="bold">The following admonitions will be found throughout the book:</emphasis>

    </para>

    <note>

        <para>A note presents interesting, sometimes technical, pieces of information related to the

            surrounding discussion.</para>

    </note>

    <tip>

        <para>A tip offers advice or an easier way of doing something.</para>

    </tip>

    <caution>

        <para>A caution alerts the reader to potential problems and helps avoid them.</para><!-- Direct referencing in a non-instructional context is bad. -->

    </caution>

    <warning>

        <para>A warning advises the reader of a hazard condition that may arise in a given scenario.</para>

    </warning>

    <para>

        <emphasis role="bold">Cross-reference conventions for print will be displayed as follows:</emphasis>

    </para>

    <itemizedlist>

        <listitem>

            <para>Internal references will look like this: <xref linkend="sect-acknowledge"/>. The

                numeral contained within square braces is the [page number].</para>

        </listitem>

        <listitem>

            <para>External references, such as those pointing to a Web site, will look like <ulink url="http://www.ubuntulinux.org">this</ulink>.</para>

        </listitem>

    </itemizedlist>

    <note>

        <para>PDF, HTML, and XHTML versions of this document will use hyperlinks to handle cross-referencing.</para>

    </note>

    <para>

        <emphasis role="bold">Type conventions will be displayed as follows:</emphasis>

    </para>

    <itemizedlist>

        <listitem>

            <para>File names or paths to directories will be shown in <filename>monospace</filename> type.</para>

        </listitem>

        <listitem>

            <para>Commands that you type at a prompt will be displayed in <command>bold</command> type.</para>

        </listitem>

        <listitem>

            <para>Options that you click, select, or choose in a user interface will be shown in

                <filename>monospace</filename> type.</para>

        </listitem>

        <listitem>

            <para>When variables, parameters, SGML tags, etc. are contained within a paragraph of

                text, they will be shown in <filename>monospace</filename> type. Otherwise, they will

                use the normal type.</para>

        </listitem>

    </itemizedlist>

    <para>

        <emphasis role="bold">Menu selections, mouse actions, and keyboard short-cuts:</emphasis>

    </para>

    <itemizedlist>

        <listitem>

            <para>A sequence of menu selections will be displayed as follows: <menuchoice>

                    <guimenu>

                        <accel>F</accel>ile</guimenu>

                    <guimenuitem>

                        <accel>O</accel>pen</guimenuitem>

                </menuchoice>

            </para>

        </listitem>

        <listitem>

            <para>Mouse actions shall assume a right-handed mouse configuration. The terms

                <quote><mousebutton>click</mousebutton></quote> and

                <quote><mousebutton>double-click</mousebutton></quote> refer to using the

                left mouse button. The term

                <quote><mousebutton>right-click</mousebutton></quote> refers to using the

                right mouse button. The term

                <quote><mousebutton>middle-click</mousebutton></quote> refers to using the

                middle mouse button, pressing down on the scroll wheel, or pressing both

                the left and right buttons simultaneously, based on the design of your mouse.</para>

        </listitem>

        <listitem>

            <para>Keyboard short-cut combinations will be displayed as follows: <keycombo>

                    <keycap>Ctrl</keycap><keycap>N</keycap></keycombo>. Where the conventions for <quote>Control</quote>,

                <quote>Shift,</quote> and <quote>Alternate</quote> keys will be

                <keycap>Ctrl</keycap>, <keycap>Shift</keycap>, and <keycap>Alt</keycap>, respectively,

                and shall mean the first key is to be held down while pressing the second key.</para>

        </listitem>

    </itemizedlist>

    <para>

        <emphasis role="bold">Code conventions:</emphasis>

    </para>

    <itemizedlist>

        <listitem>

            <para>Code and mark-up samples will be formatted in a grey block.</para>

        </listitem>

        <listitem>

            <para>Sometimes, lines of code or mark-up examples will be longer than the page width. To

                avoid having them run off the page, the slash character &quot;\&quot; is used

                to denote a soft line break. This means that the line of code is meant to

                be on one line, but for print formatting, it has been broken across two or more lines.</para>

        </listitem>

    </itemizedlist>

</sect1>