manual/xml/formatting_conventions.xml

   1 <?xml version="1.0" standalone="no"?>
   2
   3 <!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
   4
   5 ]>
   6
   7 <section id="sn-formatting-conventions">
   8   <title>Formatting Conventions</title>
   9   <section id="typography">
  10     <title>Typography</title>
  11     <para>
  12       This manual uses a few conventions to indicate key commands, menu
  13       choices and other user interactions:
  14     </para>
  15
  16     <para>
  17       Key commands such as <keycombo><keycap>Ctrl</keycap><keycap>a</keycap>
  18       </keycombo> mean "Hold down the Ctrl key and press the 'a' key". New
  19       and important terms are written like this.
  20     </para>
  21
  22     <para>
  23       The names of on-screen buttons are shown like this
  24       <guibutton>Button</guibutton>
  25     </para>
  26
  27     <para>
  28       The name of a menu item is shown like <guimenuitem>This</guimenuitem>,
  29       and nested menu items will appear like <menuchoice>
  30       <guimenu>Menu</guimenu> <guisubmenu>Sub Menu</guisubmenu>
  31       </menuchoice>
  32     </para>
  33   </section>
  34
  35   <section id="admonitions">
  36     <title>Admonitions</title>
  37     <para>
  38       Admonitions are set apart from the main text and are meant to draw
  39       your attention to pieces of information. In the order of how critical
  40       the information is to you, these items are marked as follows:
  41     </para>
  42
  43     <note>
  44       <title>Note</title>
  45       <para>
  46         A note is typically information that you need to understand the
  47         behavior of Ardour.
  48       </para>
  49     </note>
  50     <tip><title>Tip</title>
  51       <para>
  52         A tip is typically an alternative way of performing a task.
  53       </para>
  54     </tip>
  55     <important>
  56       <title>Important</title>
  57       <para>
  58         The important admonition is used to draw attention to parts of the
  59         interface that may be overlooked or certain settings that are vital
  60         in determining the behaviour of ardour.
  61       </para>
  62     </important>
  63
  64     <warning>
  65       <title>Warning</title>
  66       <para>
  67         The warning admonition is used where an action may result in
  68         consequences that are unintended or permanent such as changes to the
  69         session that can not be undone or the removal of files.
  70       </para>
  71     </warning>
  72   </section>
  73
  74   <section id="mouse-buttons">
  75     <title>Mouse Buttons</title>
  76     <para>
  77       You might be used to terms like "right mouse button", "left mouse
  78       button" etc. These are widely used, but they can be very confusing for
  79       left-handed people, or people using mice with many buttons arranged in
  80       an unconventional way. Ardour is typically used with mice equipped
  81       with at least 3 buttons that can be remapped for left- and
  82       right-handed users, making it hard to unambiguously define "left" and
  83       "right" in a useful way.
  84     </para>
  85
  86     <para>
  87       If you are right-handed and use a conventional mouse, then
  88       <mousebutton>Button1</mousebutton> corresponds to "left mouse button",
  89       <mousebutton>Button2</mousebutton> to "middle mouse button" and
  90       <mousebutton>Button3</mousebutton> to "right mouse button". Otherwise,
  91       the numbered button nomenclature refers to the same button numbers as
  92       defined by your X Window configuration.
  93     </para>
  94
  95     <para>
  96       If you see instructions to use <keycombo><keycap>Ctrl</keycap>
  97       <mousebutton>Button1</mousebutton> </keycombo> , it means "Hold down
  98       the <keycap>Ctrl</keycap> key and click
  99       <mousebutton>Button1</mousebutton> ".
 100     </para>
 101   </section>
 102
 103   <section id="select-choose">
 104     <title>Select/Choose</title>
 105     <para>
 106       In conventional English, "select" and "choose" are often used as
 107       synonyms. In this manual, we use them to mean quite different things:
 108     </para>
 109
 110     <variablelist>
 111       <title></title>
 112       <varlistentry>
 113         <term>Select</term>
 114         <listitem>
 115           <para>
 116             When you select something, it will stay selected. Putting a
 117             check-mark in a box, for example, would be referred to as
 118             "selecting" that box. This is also true for menu items that
 119             enable or disable options ("select Big Clock from the Windows
 120             menu", for example) and various editing functions.
 121           </para>
 122         </listitem>
 123       </varlistentry>
 124
 125       <varlistentry>
 126         <term>Choose</term>
 127         <listitem>
 128           <para>
 129             "Choosing" involves clicking or using the keyboard to accomplish
 130             a one-time action. A command to save the current session might
 131             be described as, "Choose Save from the Session menu.
 132           </para>
 133         </listitem>
 134       </varlistentry>
 135     </variablelist>
 136   </section>
 137 <!--
 138         <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
 139                 href="Some_Subsection.xml" />
 140         -->
 141 </section>