698 lines
32 KiB
HTML
698 lines
32 KiB
HTML
|
<!DOCTYPE html>
|
||
|
|
<html>
|
||
|
|
<head>
|
||
|
|
<meta charset="utf-8">
|
||
|
|
<title>
|
||
|
|
style-guide -
|
||
|
|
Live Systems Manual
|
||
|
|
</title>
|
||
|
|
<meta http-equiv="Content-Type" content="text/html;charset=utf-8">
|
||
|
|
<meta name="dc.title" content="Live Systems Manual" />
|
||
|
|
<meta name="dc.author" content="Live Systems Project <debian-live@lists.debian.org>" />
|
||
|
|
<meta name="dc.publisher" content="Live Systems Project <debian-live@lists.debian.org>" />
|
||
|
|
<meta name="dc.date" content="2015-09-22" />
|
||
|
|
<meta name="dc.rights" content="Copyright: Copyright (C) 2006-2015 Live Systems Project \\ License: This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. \\ \\ This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. \\ \\ You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/. \\ \\ The complete text of the GNU General Public License can be found in /usr/share/common-licenses/GPL-3 file." />
|
||
|
|
|
||
|
|
<meta name="generator" content="SiSU 7.2.1_pre_rel of 2019w35/4 (2019-09-05) (n*x and Ruby!)" />
|
||
|
|
<link rel="generator" href="http://www.sisudoc.org/" />
|
||
|
|
<link rel="shortcut icon" href="../_sisu/image/rb7.ico" />
|
||
|
|
|
||
|
|
<link href="../../_sisu/css/html.css" rel="stylesheet">
|
||
|
|
</head>
|
||
|
|
<body lang="en">
|
||
|
|
<a name="top" id="top"></a><table summary="segment navigation band with banner" bgcolor="#ffffff" width="100%"><tr>
|
||
|
|
<td width="20%" align="left">
|
||
|
|
<table summary="home button / home information" border="0" cellpadding="3" cellspacing="0">
|
||
|
|
<tr><td align="left" bgcolor="#ffffff">
|
||
|
|
<p class="tiny_left"><a href="http://debian-live.alioth.debian.org/manual" target="_top">
|
||
|
|
Live manual
|
||
|
|
</a></p>
|
||
|
|
<p class="tiny_left"><a href="http://debian-live.alioth.debian.org" target="_top">
|
||
|
|
Live Systems
|
||
|
|
</a></p>
|
||
|
|
</td></tr>
|
||
|
|
</table>
|
||
|
|
</td>
|
||
|
|
<td width="75%" align="center">
|
||
|
|
|
||
|
|
<table summary="segment navigation available documents types: toc,doc,pdf,concordance" border="0" cellpadding="3" cellspacing="0">
|
||
|
|
<tr>
|
||
|
|
<td align="center" bgcolor="#ffffff">
|
||
|
|
|
||
|
|
|
||
|
|
</tr></table>
|
||
|
|
</td>
|
||
|
|
<td width="5%" align="right">
|
||
|
|
<table summary="segment navigation pre/next" border="0" cellpadding="3" cellspacing="0">
|
||
|
|
<tr>
|
||
|
|
<td align="center" bgcolor="#ffffff">
|
||
|
|
<a href="examples.en.html" target="_top">
|
||
|
|
<img border="0" width="22" height="22" src="../../_sisu/image_sys/arrow_prev_red.png" alt="<< previous" />
|
||
|
|
</a>
|
||
|
|
</td>
|
||
|
|
<td align="center" bgcolor="#ffffff">
|
||
|
|
<a href="toc.en.html" target="_top">
|
||
|
|
<img border="0" width="22" height="22" src="../../_sisu/image_sys/arrow_up_red.png" alt="toc" />
|
||
|
|
</a>
|
||
|
|
</td>
|
||
|
|
<td align="center" bgcolor="#ffffff">
|
||
|
|
<a href="metadata.en.html" target="_top">
|
||
|
|
<img border="0" width="22" height="22" src="../../_sisu/image_sys/arrow_next_red.png" alt="next >>" />
|
||
|
|
</a>
|
||
|
|
</td>
|
||
|
|
<td>
|
||
|
|
</td></tr>
|
||
|
|
</table>
|
||
|
|
</td></tr>
|
||
|
|
</table><div class="content0">
|
||
|
|
<h1 class="tiny">
|
||
|
|
Live Systems Manual
|
||
|
|
</h1>
|
||
|
|
</div><div class="content0">
|
||
|
|
<h1 class="tiny">
|
||
|
|
Style guide
|
||
|
|
</h1>
|
||
|
|
</div><div class="content0"><div class="substance">
|
||
|
|
<label class="ocn"><a href="#926" class="lnkocn">926</a></label>
|
||
|
|
<h1 class="norm" id="926"><a name="926"></a>
|
||
|
|
19. Style guide
|
||
|
|
</h1>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#927" class="lnkocn">927</a></label>
|
||
|
|
<p class="bold" id="927"><a name="927"></a> <a id="hc19.1"></a>
|
||
|
|
<a name="c19.1" ></a><a name="h19.1" ></a>19.1 Guidelines for authors
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#928" class="lnkocn">928</a></label>
|
||
|
|
<p class="i0" id="928">
|
||
|
|
This section deals with some general considerations to be taken into account when writing technical documentation for <i>live-manual</i>. They are divided into linguistic features and recommended procedures.
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#929" class="lnkocn">929</a></label>
|
||
|
|
<p class="i0" id="929">
|
||
|
|
<b>Note:</b> Authors should first read <a href="about-manual.en.html#how-to-contribute">Contributing to this document</a>
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#930" class="lnkocn">930</a></label>
|
||
|
|
<p class="bold" id="930"><a name="930"></a> <a id="hc19.1.1"></a>
|
||
|
|
<a name="c19.1.1" ></a><a name="h19.1.1" ></a>19.1.1 Linguistic features
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#931" class="lnkocn">931</a></label>
|
||
|
|
<ul>
|
||
|
|
<li class="bullet" id="931">
|
||
|
|
<i>Use plain English</i>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#932" class="lnkocn">932</a></label>
|
||
|
|
<p class="i0" id="932">
|
||
|
|
Keep in mind that a high percentage of your readers are not native speakers of English. So as a general rule try to use short, meaningful sentences, followed by a full stop.
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#933" class="lnkocn">933</a></label>
|
||
|
|
<p class="i0" id="933">
|
||
|
|
This does not mean that you have to use a simplistic, naive style. It is a suggestion to try to avoid, as much as possible, complex subordinate sentences that make the text difficult to understand for non-native speakers of English.
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#934" class="lnkocn">934</a></label>
|
||
|
|
<ul>
|
||
|
|
<li class="bullet" id="934">
|
||
|
|
<i>Variety of English</i>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#935" class="lnkocn">935</a></label>
|
||
|
|
<p class="i0" id="935">
|
||
|
|
The most widely spread varieties of English are British and American so it is very likely that most authors will use either one or the other. In a collaborative environment, the ideal variety would be "International English" but it is very difficult, not to say impossible, to decide on which variety among all the existing ones, is the best to use.
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#936" class="lnkocn">936</a></label>
|
||
|
|
<p class="i0" id="936">
|
||
|
|
We expect that different varieties may mix without creating misunderstandings but in general terms you should try to be coherent and before deciding on using British, American or any other English flavour at your discretion, please take a look at how other people write and try to imitate them.
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#937" class="lnkocn">937</a></label>
|
||
|
|
<ul>
|
||
|
|
<li class="bullet" id="937">
|
||
|
|
<i>Be balanced</i>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#938" class="lnkocn">938</a></label>
|
||
|
|
<p class="i0" id="938">
|
||
|
|
Do not be biased. Avoid including references to ideologies completely unrelated to <i>live-manual</i>. Technical writing should be as neutral as possible. It is in the very nature of scientific writing.
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#939" class="lnkocn">939</a></label>
|
||
|
|
<ul>
|
||
|
|
<li class="bullet" id="939">
|
||
|
|
<i>Be politically correct</i>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#940" class="lnkocn">940</a></label>
|
||
|
|
<p class="i0" id="940">
|
||
|
|
Try to avoid sexist language as much as possible. If you need to make references to the third person singular preferably use "they" rather than "he" or "she" or awkward inventions such as "s/he", "s(he)" and the like.
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#941" class="lnkocn">941</a></label>
|
||
|
|
<ul>
|
||
|
|
<li class="bullet" id="941">
|
||
|
|
<i>Be concise</i>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#942" class="lnkocn">942</a></label>
|
||
|
|
<p class="i0" id="942">
|
||
|
|
Go straight to the point and do not wander around aimlessly. Give as much information as necessary but do not give more information than necessary, this is to say, do not explain unnecessary details. Your readers are intelligent. Presume some previous knowledge on their part.
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#943" class="lnkocn">943</a></label>
|
||
|
|
<ul>
|
||
|
|
<li class="bullet" id="943">
|
||
|
|
<i>Minimize translation work</i>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#944" class="lnkocn">944</a></label>
|
||
|
|
<p class="i0" id="944">
|
||
|
|
Keep in mind that whatever you write will have to be translated into several other languages. This implies that a number of people will have to do an extra work if you add useless or redundant information.
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#945" class="lnkocn">945</a></label>
|
||
|
|
<ul>
|
||
|
|
<li class="bullet" id="945">
|
||
|
|
<i>Be coherent</i>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#946" class="lnkocn">946</a></label>
|
||
|
|
<p class="i0" id="946">
|
||
|
|
As suggested before, it is almost impossible to standardize a collaborative document into a perfectly unified whole. However, every effort on your side to write in a coherent way with the rest of the authors will be appreciated.
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#947" class="lnkocn">947</a></label>
|
||
|
|
<ul>
|
||
|
|
<li class="bullet" id="947">
|
||
|
|
<i>Be cohesive</i>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#948" class="lnkocn">948</a></label>
|
||
|
|
<p class="i0" id="948">
|
||
|
|
Use as many text-forming devices as necessary to make your text cohesive and unambiguous. (Text-forming devices are linguistic markers such as connectors).
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#949" class="lnkocn">949</a></label>
|
||
|
|
<ul>
|
||
|
|
<li class="bullet" id="949">
|
||
|
|
<i>Be descriptive</i>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#950" class="lnkocn">950</a></label>
|
||
|
|
<p class="i0" id="950">
|
||
|
|
It is preferable to describe the point in one or several paragraphs than merely using a number of sentences in a typical "changelog" style. Describe it! Your readers will appreciate it.
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#951" class="lnkocn">951</a></label>
|
||
|
|
<ul>
|
||
|
|
<li class="bullet" id="951">
|
||
|
|
<i>Dictionary</i>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#952" class="lnkocn">952</a></label>
|
||
|
|
<p class="i0" id="952">
|
||
|
|
Look up the meaning of words in a dictionary or encyclopedia if you do not know how to express certain concepts in English. But keep in mind that a dictionary can either be your best friend or can turn into your worst enemy if you do not know how to use it correctly.
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#953" class="lnkocn">953</a></label>
|
||
|
|
<p class="i0" id="953">
|
||
|
|
English has the largest vocabulary that exists (with over one million words). Many of these words are borrowings from other languages. When looking up the meaning of words in a bilingual dictionary the tendency of a non-native speaker of English is to choose the one that sounds more similar in their mother tongue. This often turns into an excessively formal discourse which does not sound quite natural in English.
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#954" class="lnkocn">954</a></label>
|
||
|
|
<p class="i0" id="954">
|
||
|
|
As a general rule, if a concept can be expressed using different synonyms, it is a good advice to choose the first word proposed by the dictionary. If in doubt, choosing words of Germanic origin (Usually monosyllabic words) is often the right thing to do. Be warned that these two techniques might produce a rather informal discourse but at least your choice of words will be of wide use and generally accepted.
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#955" class="lnkocn">955</a></label>
|
||
|
|
<p class="i0" id="955">
|
||
|
|
Using a dictionary of collocations is recommended. They are extremely helpful when it comes to know which words usually occur together.
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#956" class="lnkocn">956</a></label>
|
||
|
|
<p class="i0" id="956">
|
||
|
|
Again it is a good practice to learn from the work of others. Using a search engine to check how other authors use certain expressions may help a lot.
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#957" class="lnkocn">957</a></label>
|
||
|
|
<ul>
|
||
|
|
<li class="bullet" id="957">
|
||
|
|
<i>False friends, idioms and other idiomatic expressions</i>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#958" class="lnkocn">958</a></label>
|
||
|
|
<p class="i0" id="958">
|
||
|
|
Watch out for false friends. No matter how proficient you are in a foreign language you cannot help falling from time to time in the trap of the so called "false friends", words that look similar in two languages but whose meanings or uses might be completely different.
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#959" class="lnkocn">959</a></label>
|
||
|
|
<p class="i0" id="959">
|
||
|
|
Try to avoid idioms as much as possible. "Idioms" are expressions that may convey a completely different meaning from what their individual words seem to mean. Sometimes, idioms might be difficult to understand even for native speakers of English!
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#960" class="lnkocn">960</a></label>
|
||
|
|
<ul>
|
||
|
|
<li class="bullet" id="960">
|
||
|
|
<i>Avoid slang, abbreviations, contractions...</i>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#961" class="lnkocn">961</a></label>
|
||
|
|
<p class="i0" id="961">
|
||
|
|
Even though you are encouraged to use plain, everyday English, technical writing belongs to the formal register of the language.
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#962" class="lnkocn">962</a></label>
|
||
|
|
<p class="i0" id="962">
|
||
|
|
Try to avoid slang, unusual abbreviations that are difficult to understand and above all contractions that try to imitate the spoken language. Not to mention typical irc and family friendly expressions.
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#963" class="lnkocn">963</a></label>
|
||
|
|
<p class="bold" id="963"><a name="963"></a> <a id="hc19.1.2"></a>
|
||
|
|
<a name="c19.1.2" ></a><a name="h19.1.2" ></a>19.1.2 Procedures
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#964" class="lnkocn">964</a></label>
|
||
|
|
<ul>
|
||
|
|
<li class="bullet" id="964">
|
||
|
|
<i>Test before write</i>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#965" class="lnkocn">965</a></label>
|
||
|
|
<p class="i0" id="965">
|
||
|
|
It is important that authors test their examples before adding them to <i>live-manual</i> to ensure that everything works as described. Testing on a clean chroot or VM can be a good starting point. Besides, it would be ideal if the tests were then carried out on different machines with different hardware to spot possible problems that may arise.
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#966" class="lnkocn">966</a></label>
|
||
|
|
<ul>
|
||
|
|
<li class="bullet" id="966">
|
||
|
|
<i>Examples</i>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#967" class="lnkocn">967</a></label>
|
||
|
|
<p class="i0" id="967">
|
||
|
|
When providing an example try to be as specific as you can. An example is, after all, just an example.
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#968" class="lnkocn">968</a></label>
|
||
|
|
<p class="i0" id="968">
|
||
|
|
It is often better to use a line that only applies to a specific case than using abstractions that may confuse your readers. In this case you can provide a brief explanation of the effects of the proposed example.
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#969" class="lnkocn">969</a></label>
|
||
|
|
<p class="i0" id="969">
|
||
|
|
There may be some exceptions when the example suggests using some potentially dangerous commands that, if misused, may cause data loss or other similar undesirable effects. In this case you should provide a thorough explanation of the possible side effects.
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#970" class="lnkocn">970</a></label>
|
||
|
|
<ul>
|
||
|
|
<li class="bullet" id="970">
|
||
|
|
<i>External links</i>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#971" class="lnkocn">971</a></label>
|
||
|
|
<p class="i0" id="971">
|
||
|
|
Links to external sites should only be used when the information on those sites is crucial when it comes to understanding a special point. Even so, try to use links to external sites as sparsely as possible. Internet links are likely to change from time to time resulting in broken links and leaving your arguments in an incomplete state.
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#972" class="lnkocn">972</a></label>
|
||
|
|
<p class="i0" id="972">
|
||
|
|
Besides, people who read the manual offline will not have the chance to follow those links.
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#973" class="lnkocn">973</a></label>
|
||
|
|
<ul>
|
||
|
|
<li class="bullet" id="973">
|
||
|
|
<i>Avoid branding and things that violate the license under which the manual is published</i>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#974" class="lnkocn">974</a></label>
|
||
|
|
<p class="i0" id="974">
|
||
|
|
Try to avoid branding as much as possible. Keep in mind that other downstream projects might make use of the documentation you write. So you are complicating things for them if you add certain specific material.
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#975" class="lnkocn">975</a></label>
|
||
|
|
<p class="i0" id="975">
|
||
|
|
<i>live-manual</i> is licensed under the GNU GPL. This has a number of implications that apply to the distribution of the material (of any kind, including copyrighted graphics or logos) that is published with it.
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#976" class="lnkocn">976</a></label>
|
||
|
|
<ul>
|
||
|
|
<li class="bullet" id="976">
|
||
|
|
<i>Write a first draft, revise, edit, improve, redo if necessary</i>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#977" class="lnkocn">977</a></label>
|
||
|
|
<p class="i0" id="977">
|
||
|
|
- Brainstorm!. You need to organize your ideas first in a logical sequence of events.
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#978" class="lnkocn">978</a></label>
|
||
|
|
<p class="i0" id="978">
|
||
|
|
- Once you have somehow organized those ideas in your mind write a first draft.
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#979" class="lnkocn">979</a></label>
|
||
|
|
<p class="i0" id="979">
|
||
|
|
- Revise grammar, syntax and spelling. Keep in mind that the proper names of the releases, such as <b>buster</b> or <b>sid</b>, should not be capitalized when referred to as code names. In order to check the spelling you can run the "spell" target. i.e. <tt>make spell</tt>
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#980" class="lnkocn">980</a></label>
|
||
|
|
<p class="i0" id="980">
|
||
|
|
- Improve your statements and redo any part if necessary.
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#981" class="lnkocn">981</a></label>
|
||
|
|
<ul>
|
||
|
|
<li class="bullet" id="981">
|
||
|
|
<i>Chapters</i>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#982" class="lnkocn">982</a></label>
|
||
|
|
<p class="i0" id="982">
|
||
|
|
Use the conventional numbering system for chapters and subtitles. e.g. 1, 1.1, 1.1.1, 1.1.2 ... 1.2, 1.2.1, 1.2.2 ... 2, 2.1 ... and so on. See markup below.
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#983" class="lnkocn">983</a></label>
|
||
|
|
<p class="i0" id="983">
|
||
|
|
If you have to enumerate a series of steps or stages in your description, you can also use ordinal numbers: First, second, third ... or First, Then, After that, Finally ... Alternatively you can use bulleted items.
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#984" class="lnkocn">984</a></label>
|
||
|
|
<ul>
|
||
|
|
<li class="bullet" id="984">
|
||
|
|
<i>Markup</i>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#985" class="lnkocn">985</a></label>
|
||
|
|
<p class="i0" id="985">
|
||
|
|
And last but not least, <i>live-manual</i> uses <a href="http://www.sisudoc.org/">SiSU</a> to process the text files and produce a multiple format output. It is recommended to take a look at <a href="http://www.sisudoc.org/sisu/en/html/sisu_manual/markup.html">SiSU's manual</a> to get familiar with its markup, or else type:
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#986" class="lnkocn">986</a></label>
|
||
|
|
<p class="code" id="986">
|
||
|
|
$ sisu --help markup<br>
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#987" class="lnkocn">987</a></label>
|
||
|
|
<p class="i0" id="987">
|
||
|
|
Here are some markup examples that may prove useful:
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#988" class="lnkocn">988</a></label>
|
||
|
|
<p class="i0" id="988">
|
||
|
|
- For emphasis/bold text:
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#989" class="lnkocn">989</a></label>
|
||
|
|
<p class="code" id="989">
|
||
|
|
*{foo}* or !{foo}!<br>
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#990" class="lnkocn">990</a></label>
|
||
|
|
<p class="i0" id="990">
|
||
|
|
produces: <b>foo</b> or <b>foo</b>. Use it to emphasize certain key words.
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#991" class="lnkocn">991</a></label>
|
||
|
|
<p class="i0" id="991">
|
||
|
|
- For italics:
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#992" class="lnkocn">992</a></label>
|
||
|
|
<p class="code" id="992">
|
||
|
|
/{foo}/<br>
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#993" class="lnkocn">993</a></label>
|
||
|
|
<p class="i0" id="993">
|
||
|
|
produces: <i>foo</i>. Use them e.g. for the names of Debian packages.
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#994" class="lnkocn">994</a></label>
|
||
|
|
<p class="i0" id="994">
|
||
|
|
- For monospace:
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#995" class="lnkocn">995</a></label>
|
||
|
|
<p class="code" id="995">
|
||
|
|
#{foo}#<br>
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#996" class="lnkocn">996</a></label>
|
||
|
|
<p class="i0" id="996">
|
||
|
|
produces: <tt>foo</tt>. Use it e.g. for the names of commands. And also to highlight some key words or things like paths.
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#997" class="lnkocn">997</a></label>
|
||
|
|
<p class="i0" id="997">
|
||
|
|
- For code blocks:
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#998" class="lnkocn">998</a></label>
|
||
|
|
<p class="code" id="998">
|
||
|
|
code{<br><br>
|
||
|
|
$ foo<br>
|
||
|
|
# bar<br><br>
|
||
|
|
}code<br>
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#999" class="lnkocn">999</a></label>
|
||
|
|
<p class="i0" id="999">
|
||
|
|
produces:
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#1000" class="lnkocn">1000</a></label>
|
||
|
|
<p class="code" id="1000">
|
||
|
|
$ foo<br>
|
||
|
|
# bar<br>
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#1001" class="lnkocn">1001</a></label>
|
||
|
|
<p class="i0" id="1001">
|
||
|
|
Use <tt>code{</tt> to open and <tt>}code</tt> to close the tags. It is important to remember to leave a space at the beginning of each line of code.
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#1002" class="lnkocn">1002</a></label>
|
||
|
|
<p class="bold" id="1002"><a name="1002"></a> <a id="hguidelines-translators"></a>
|
||
|
|
<a name="h19.2" ></a><a name="guidelines-translators" ></a>19.2 Guidelines for translators
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#1003" class="lnkocn">1003</a></label>
|
||
|
|
<p class="i0" id="1003">
|
||
|
|
This section deals with some general considerations to be taken into account when translating the contents of <i>live-manual</i>.
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#1004" class="lnkocn">1004</a></label>
|
||
|
|
<p class="i0" id="1004">
|
||
|
|
As a general recommendation, translators should have read and understood the translation rules that apply to their specific languages. Usually, translation groups and mailing lists provide information on how to produce translated work that complies with Debian quality standards.
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#1005" class="lnkocn">1005</a></label>
|
||
|
|
<p class="i0" id="1005">
|
||
|
|
<b>Note:</b> Translators should also read <a href="about-manual.en.html#how-to-contribute">Contributing to this document</a>. In particular the section <a href="about-manual.en.html#translation">Translation</a>
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#1006" class="lnkocn">1006</a></label>
|
||
|
|
<p class="bold" id="1006"><a name="1006"></a> <a id="hc19.2.1"></a>
|
||
|
|
<a name="c19.2.1" ></a><a name="h19.2.1" ></a>19.2.1 Translation hints
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#1007" class="lnkocn">1007</a></label>
|
||
|
|
<ul>
|
||
|
|
<li class="bullet" id="1007">
|
||
|
|
<i>Comments</i>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#1008" class="lnkocn">1008</a></label>
|
||
|
|
<p class="i0" id="1008">
|
||
|
|
The role of the translator is to convey as faithfully as possible the meaning of words, sentences, paragraphs and texts as written by the original authors into their target language.
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#1009" class="lnkocn">1009</a></label>
|
||
|
|
<p class="i0" id="1009">
|
||
|
|
So they should refrain from adding personal comments or extra bits of information of their own. If they want to add a comment for other translators working on the same documents, they can leave it in the space reserved for that. That is, the header of the strings in the <b>po</b> files preceded by a number sign <b>#</b>. Most graphical translation programs can automatically handle those types of comments.
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#1010" class="lnkocn">1010</a></label>
|
||
|
|
<ul>
|
||
|
|
<li class="bullet" id="1010">
|
||
|
|
<i>TN, Translator's Note</i>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#1011" class="lnkocn">1011</a></label>
|
||
|
|
<p class="i0" id="1011">
|
||
|
|
It is perfectly acceptable however, to include a word or an expression in brackets in the translated text if, and only if, that makes the meaning of a difficult word or expression clearer to the reader. Inside the brackets the translator should make evident that the addition was theirs using the abbreviation "TN" or "Translator's Note".
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#1012" class="lnkocn">1012</a></label>
|
||
|
|
<ul>
|
||
|
|
<li class="bullet" id="1012">
|
||
|
|
<i>Impersonal sentences</i>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#1013" class="lnkocn">1013</a></label>
|
||
|
|
<p class="i0" id="1013">
|
||
|
|
Documents written in English make an extensive use of the impersonal form "you". In some other languages that do not share this characteristic, this might give the false impression that the original texts are directly addressing the reader when they are actually not doing so. Translators must be aware of that fact and reflect it in their language as accurately as possible.
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#1014" class="lnkocn">1014</a></label>
|
||
|
|
<ul>
|
||
|
|
<li class="bullet" id="1014">
|
||
|
|
<i>False friends</i>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#1015" class="lnkocn">1015</a></label>
|
||
|
|
<p class="i0" id="1015">
|
||
|
|
The trap of "false friends" explained before especially applies to translators. Double check the meaning of suspicious false friends if in doubt.
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#1016" class="lnkocn">1016</a></label>
|
||
|
|
<ul>
|
||
|
|
<li class="bullet" id="1016">
|
||
|
|
<i>Markup</i>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#1017" class="lnkocn">1017</a></label>
|
||
|
|
<p class="i0" id="1017">
|
||
|
|
Translators working initially with <b>pot</b> files and later on with <b>po</b> files will find many markup features in the strings. They can translate the text anyway, as long as it is translatable, but it is extremely important that they use exactly the same markup as the original English version.
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#1018" class="lnkocn">1018</a></label>
|
||
|
|
<ul>
|
||
|
|
<li class="bullet" id="1018">
|
||
|
|
<i>Code blocks</i>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#1019" class="lnkocn">1019</a></label>
|
||
|
|
<p class="i0" id="1019">
|
||
|
|
Even though the code blocks are usually untranslatable, including them in the translation is the only way to score a 100% complete translation. And even though it means more work at first because it might require the intervention of the translators if the code changes, it is the best way, in the long run, to identify what has already been translated and what has not when checking the integrity of the .po files.
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#1020" class="lnkocn">1020</a></label>
|
||
|
|
<ul>
|
||
|
|
<li class="bullet" id="1020">
|
||
|
|
<i>Newlines</i>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#1021" class="lnkocn">1021</a></label>
|
||
|
|
<p class="i0" id="1021">
|
||
|
|
The translated texts need to have the exact same newlines as the original texts. Be careful to press the "Enter" key or type <b>\n</b> if they appear in the original files. These newlines often appear, for instance, in the code blocks.
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#1022" class="lnkocn">1022</a></label>
|
||
|
|
<p class="i0" id="1022">
|
||
|
|
Make no mistake, this does not mean that the translated text needs to have the same length as the English version. That is nearly impossible.
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#1023" class="lnkocn">1023</a></label>
|
||
|
|
<ul>
|
||
|
|
<li class="bullet" id="1023">
|
||
|
|
<i>Untranslatable strings</i>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#1024" class="lnkocn">1024</a></label>
|
||
|
|
<p class="i0" id="1024">
|
||
|
|
Translators should never translate:
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#1025" class="lnkocn">1025</a></label>
|
||
|
|
<p class="i0" id="1025">
|
||
|
|
- The code names of releases (which should be written in lowercase)
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#1026" class="lnkocn">1026</a></label>
|
||
|
|
<p class="i0" id="1026">
|
||
|
|
- The names of programs
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#1027" class="lnkocn">1027</a></label>
|
||
|
|
<p class="i0" id="1027">
|
||
|
|
- The commands given as examples
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#1028" class="lnkocn">1028</a></label>
|
||
|
|
<p class="i0" id="1028">
|
||
|
|
- Metadata (often between colons <b>:metadata:</b>)
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#1029" class="lnkocn">1029</a></label>
|
||
|
|
<p class="i0" id="1029">
|
||
|
|
- Links
|
||
|
|
</p>
|
||
|
|
</div><div class="substance">
|
||
|
|
<label class="ocn"><a href="#1030" class="lnkocn">1030</a></label>
|
||
|
|
<p class="i0" id="1030">
|
||
|
|
- Paths
|
||
|
|
</p>
|
||
|
|
</div></div><br><div class="main_column">
|
||
|
|
<table summary="segment navigation band" bgcolor="#ffffff" width="100%"><tr>
|
||
|
|
<td width="70%" align="center">
|
||
|
|
|
||
|
|
<table summary="segment navigation available documents types: toc,doc,pdf,concordance" border="0" cellpadding="3" cellspacing="0">
|
||
|
|
<tr>
|
||
|
|
<td align="center" bgcolor="#ffffff">
|
||
|
|
|
||
|
|
|
||
|
|
</tr></table>
|
||
|
|
</td>
|
||
|
|
<td width="5%" align="right">
|
||
|
|
<table summary="segment navigation pre/next" border="0" cellpadding="3" cellspacing="0">
|
||
|
|
<tr>
|
||
|
|
<td align="center" bgcolor="#ffffff">
|
||
|
|
<a href="examples.en.html" target="_top">
|
||
|
|
<img border="0" width="22" height="22" src="../../_sisu/image_sys/arrow_prev_red.png" alt="<< previous" />
|
||
|
|
</a>
|
||
|
|
</td>
|
||
|
|
<td align="center" bgcolor="#ffffff">
|
||
|
|
<a href="toc.en.html" target="_top">
|
||
|
|
<img border="0" width="22" height="22" src="../../_sisu/image_sys/arrow_up_red.png" alt="toc" />
|
||
|
|
</a>
|
||
|
|
</td>
|
||
|
|
<td align="center" bgcolor="#ffffff">
|
||
|
|
<a href="metadata.en.html" target="_top">
|
||
|
|
<img border="0" width="22" height="22" src="../../_sisu/image_sys/arrow_next_red.png" alt="next >>" />
|
||
|
|
</a>
|
||
|
|
</td>
|
||
|
|
<td>
|
||
|
|
</td></tr>
|
||
|
|
</table>
|
||
|
|
</td></tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
</div><div class="main_column">
|
||
|
|
|
||
|
|
<a name="bottom" id="bottom"></a>
|
||
|
|
<a name="end" id="end"></a>
|
||
|
|
</div></div></body>
|
||
|
|
</html>
|