~mixxxdevelopers/mixxx/manual

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
.. include:: /shortcuts.rstext

Guidelines for Mixxx Manual writers
***********************************

.. sectionauthor:: S.Brandt <s.brandt@mixxx.org>

What is the intended outcome of the manual?
===========================================
A user who doesn\'t know Mixxx yet should be able to mix two tracks from its
music library in the shortest possible time. Assuming he will be more motivated
to explore the software and get creative.

(Future) characteristics of the Mixxx manual:

**User-friendly**
  Easy to use when, where, and how you need it. Examine, how someone else is
  using the application. Watch someone else use the manual (preferably someone
  who has never seen it before). Be consistent with the instructional design so
  users can follow a set pattern. Don't use the terms you use as a developer,
  try to find the terminology of the user.

**Based on sound learning principles**
  For example users should actually learn from it, not just refer to it. Use
  the KISS principle; keep it sweet and simple. Too much information can be
  overwhelming, so present one concept at a time. Explain simple features in a
  matrix.

**Motivational**
  Keeps users willing to push forward to higher levels. Present general concepts
  first to provide a frame of reference. Then move to more complex topics.

Group problems the user might hit in a particular task right there with the
instruction for that task. Do not force a user to go to a separate
“Troubleshooting” section. We can have such separate sections, but as a author
you should duplicate pitfalls and problems and include a solution in the task.

Technical conventions
=====================

Line Widths
-----------

Please configure your editor to have a max column-width of 80-columns. While it
is not a strict requirement, 80-column cleanliness makes it easy to tile
multiple buffers of code across a laptop screen, which provides significant
efficiency gains to developers.

Screenshots
-----------

Use english language settings when creating screen-shots of the Mixxx interface.
This might change if we ever have true
`i18n <https://en.wikipedia.org/wiki/Internationalization_and_localization>`_.
The preferred file format is PNG. **Don't add shadows** to application window
screen-shots as they are added automatically to the document with style-sheets.

Always include descriptive alt text and a figure description. The latter will be
numbered in the PDF export. That sets them apart from the text below.
Place screen-shots above the context you are going to explain.

Screenshots should only show the necessary area and not the entire screen where
not necessary. Use annotation on the screenshot if necessary to emphasize
elements, use color ``#FF1F90`` if possible for consistency.

.. rst:directive:: figure

   Use this directive to place images like Screen-shots. Example markup: ::

    .. figure:: /_static/icons/mixxx-icon.png
       :width: 64px
       :align: center
       :height: 64px
       :alt: Alternate text on mouse over
       :figclass: pretty-figures

       Insert descriptive caption here

Nice screenshot tools with build-in editor for annotations:

* MacOSX: `Skitch <http://evernote.com/skitch/>`_
* Linux: `Shutter <http://shutter-project.org/>`_
* Windows: `PickPic <http://www.picpick.org/download>`_ or
  `Screenshotcaptor <http://www.donationcoder.com/Software/Mouser/screenshotcaptor/>`_

Alternatively, import your screenshots into
`Inkscape <http://inkscape.org/>`_, add annotations and export as .png to
:file:`/static`. Then save the original work as .svg to :file:`/static` as well,
so any future contributor can work on your annotations at a later time.

File naming
-----------

As the manual grows over the time with new versions of Mixxx and new screenshots,
it is important to have files named consistently. Save files to the
:file:`/static` folder or create a sub-folder in there.

::

   Mixxx-<major><minor>-<where>-<what>.png

This scheme makes it easy to know which version a screenshot was taken from and
where it belongs and if it must replaced, like e.g.
:file:`Mixxx-111-Preferences-Recording.png`

.. warning:: Do not include any dot in the file names of your screenshots your
             file name or you wont be able to generate PDF with LaTeX.

Double quotes
-------------

Use curly double quotes (“ ”). Avoid typewriter double quotes (" ")
produced by the convenient quotation mark button on your keyboard.
For details and key combinations, see
`Wikipedia <https://en.wikipedia.org/wiki/Quotation_mark#Typing_quotation_marks_on_a_computer_keyboard>`_
and
`maxeroni.com <http://maxeroni.com/2011/10/18/proper-quotation-marks-%E2%80%93-rules-of-typography-1/>`_ .

Admonitions
-----------

The following admonitions are in use:

.. rst:directive:: note

   For anything that should receive a bit more attention. Example markup: ::

      .. note::
         a note

.. rst:directive:: hint

   For supplementary information that lightens the work load. Example markup: ::

      .. hint::
         a helpful hint

.. rst:directive:: seealso

   For references to other documents or websites if they need special attention.
   References to other documents can also be included in the text inline.
   Example markup: ::

      .. seealso::
         a reference and inline link `Google <https://google.com>`_

.. rst:directive:: warning

  Recommended over :rst:dir:`note` for anything that needs to be done with
  caution. Example markup: ::

      .. warning::
         a warning

.. rst:directive:: todo

   Allow inserting todo items into documents and to keep a
   :ref:`automatically generated TODO list <todo-list>` Example markup: ::

      .. todo::
         some task

Substitution
------------

Replacement images or text can be included in the text. They are added through
a substitution (aka alias). This may be appropriate when the replacement image
or text is repeated many times throughout one or more documents, especially if
it may need to change later.

All replacements are kept in the file :file:`shortcuts.rstext` which is included
at the beginning of each file in which a substitution is used.

To use an alias for the Mixxx logo, simply put the definition into
:file:`shortcuts.rstext`.

::

   .. |logo| image:: /_static/icons/mixxx-icon.png

Using this image alias, you can insert it easily in the text with ``|logo|`` ,
like this:  |logo|

For a text replacement the code looks similar:

::

   .. |longtext| replace:: Loooooooong text is looooooooong

Using this text alias, you can insert it easily with ``|longtext|`` , like this:
 |longtext| .

.. seealso:: The substitute section in the docs.
             `Here <http://www.thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html#more-about-aliases>`_
             and `also here <http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#substitution-definitions>`_

Headings
--------
Normally, there are no heading levels assigned to certain characters as the
structure is determined from the succession of headings. However, for the Python
documentation, this convention is used which you may follow:

   | ``#`` with overline, for parts
   | ``*`` with overline, for chapters
   | ``=`` for sections
   | ``-`` for subsections
   | ``^`` for subsubsections
   | ``"`` for paragraphs

Of course, you are free to use your own marker characters (see the reST
documentation), and use a deeper nesting level, but keep in mind that most
target formats (HTML, LaTeX) have a limited supported nesting depth.

Paragraph-level markup
----------------------

These directives create short paragraphs and can be used inside information
units as well as normal text:

.. rst:directive:: .. versionadded::  version

   This directive documents the version of the project which added the described
   feature. Example markup: ::

      .. versionadded:: 2.5 Add feature description.

.. rst:directive:: .. versionchanged:: version

   Similar to :rst:dir:`versionadded`, but describes when and what changed in
   the named feature in some way (new parameters, changed side effects, etc.).

Other semantic markup
---------------------
The following roles don't do anything special except formatting the text in a
different style. Nonetheless, use them:

.. rst:role:: guilabel

   Any label used in the interface should be marked with this role, including
   button labels, window titles, field names, menu and menu selection names,
   and even values in selection lists. An accelerator key for the GUI label can
   be included using an ampersand; this will be stripped and displayed
   underlined in the output. To include a literal ampersand, double it. Example
   markup: :guilabel:`&Cancel` ::

     :guilabel:`&Cancel`

.. rst:role:: kbd

   Mark a sequence of keystrokes. Example markup: :kbd:`STRG` + :kbd:`G` ::

     :kbd:`STRG` + :kbd:`G`

.. rst:role:: menuselection

   This is  used to mark a complete sequence of menu selections, including
   selecting submenus and choosing a specific operation. Example markup:
   :menuselection:`Options --> Enable Live Broadcasting` ::

       :menuselection:`Options --> Enable Live Broadcasting`

.. rst:role:: file

   The name of a file or directory. Example markup: :file:`Mixxx/Recordings` ::

       :file:`Mixxx/Recordings`

Meta-information markup
-----------------------

.. rst:directive:: .. sectionauthor:: name <email>

   Identifies the author of the current section and helps to keep track of
   contributions. By default, this markup isn't reflected in the output in any
   way. Example markup: ::

      .. sectionauthor:: Jon Doe <name@domain.tld>

Resources
=========

The user manual for Mixxx is written in `reStructuredText (reST)
<http://docutils.sourceforge.net/rst.html>`_ format using
`Sphinx <http://sphinx-doc.org>`_.

The `Mixxx user manual repostitory <https://code.launchpad.net/~mixxxdevelopers/mixxx/manual>`_
contains the Sphinx source to generate the manual as found at
`<http://mixxx.org/manual/latest/>`_.

Sphinx and RST syntax guides:

* `<http://sphinx-doc.org/rest.html>`_
* `<http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html>`_
* `<http://www.siafoo.net/help/reST>`_
* `<http://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html>`_

Steps for use:

#. Install Sphinx (``python-sphinx`` package in Debian/Ubuntu) and GNU make
#. Install Graphviz, needed to draw some diagrams (``graphviz`` and
   ``libgraphviz4`` package in Debian/Ubuntu, ``graphviz`` on OSX macports,
   http://graphviz.org/Download_windows.php on Windows. There is no need to
   install python-graphviz)
#. Download Mixxx manual source from
   `launchpad.net <https://code.launchpad.net/~mixxxdevelopers/mixxx/manual>`_
#. Edit .rst files in :file:`source/`
#. Run ``make html``
#. Open the file :file:`build/html/index.html` in your Web browser to view the
   results

.. hint:: Run ``make linkcheck`` in the terminal.
   Sphinx will validate all internal and external links in the document, and let
   you know if any links are malformed, or point to dead URLs.

Editors with Restructured Text (reST) syntax highlighting:

* Mac OSX: `Sublime <http://www.sublimetext.com/2>`_
* Linux: `Kate <http://kate-editor.org/>`_ or
  `Retext <http://sourceforge.net/p/retext/>`_
* Windows: `Sublime <http://www.sublimetext.com/2>`_ or
  `Ìntype <http://inotai.com/intype/>`_

Still not enough? Even more resources:
`<http://stackoverflow.com/questions/2746692/restructuredtext-tool-support>`_