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