track document samples used

1 files changed, 364 insertions, 0 deletions

diff --git a/markup/pod/live-manual/media/text/it/appendix_style-guide.ssi b/markup/pod/live-manual/media/text/it/appendix_style-guide.ssi
new file mode 100644
index 0000000..1bba13e
--- /dev/null
+++ b/markup/pod/live-manual/media/text/it/appendix_style-guide.ssi
@@ -0,0 +1,364 @@
+:B~ Style guide
+
+1~style-guide Style guide
+
+2~ Guidelines for authors
+
+This section deals with some general considerations to be taken into account
+when writing technical documentation for live-manual. They are divided into
+linguistic features and recommended procedures.
+
+*{Note:}* Authors should first read {Contributing to this document}#how-to-contribute
+
+3~ Linguistic features
+
+_* /{Use plain English}/
+
+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.
+
+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.
+
+_* /{Variety of English}/
+
+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.
+
+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.
+
+_* /{Be balanced}/
+
+Do not be biased. Avoid including references to ideologies completely
+unrelated to live-manual. Technical writing should be as neutral as
+possible. It is in the very nature of scientific writing.
+
+_* /{Be politically correct}/
+
+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.
+
+_* /{Be concise}/
+
+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.
+
+_* /{Minimize translation work}/
+
+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.
+
+_* /{Be coherent}/
+
+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.
+
+_* /{Be cohesive}/
+
+Use as many text-forming devices as necessary to make your text cohesive and
+unambiguous. (Text-forming devices are linguistic markers such as
+connectors).
+
+_* /{Be descriptive}/
+
+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.
+
+_* /{Dictionary}/
+
+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.
+
+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.
+
+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.
+
+Using a dictionary of collocations is recommended. They are extremely
+helpful when it comes to know which words usually occur together.
+
+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.
+
+_* /{False friends, idioms and other idiomatic expressions}/
+
+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.
+
+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!
+
+_* /{Avoid slang, abbreviations, contractions...}/
+
+Even though you are encouraged to use plain, everyday English, technical
+writing belongs to the formal register of the language.
+
+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.
+
+3~ Procedures
+
+_* /{Test before write}/
+
+It is important that authors test their examples before adding them to
+live-manual 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.
+
+_* /{Examples}/
+
+When providing an example try to be as specific as you can. An example is,
+after all, just an example.
+
+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.
+
+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.
+
+_* /{External links}/
+
+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.
+
+Besides, people who read the manual offline will not have the chance to
+follow those links.
+
+_* /{Avoid branding and things that violate the license under which the
+manual is published}/
+
+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.
+
+live-manual 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.
+
+_* /{Write a first draft, revise, edit, improve, redo if necessary}/
+
+ - Brainstorm!. You need to organize your ideas first in a logical sequence
+   of events.
+
+ - Once you have somehow organized those ideas in your mind write a first
+   draft.
+
+ - Revise grammar, syntax and spelling. Keep in mind that the proper names
+   of the releases, such as ${testing} or sid, should not be capitalized
+   when referred to as code names. In order to check the spelling you can
+   run the "spell" target. i.e. #{make spell}#
+
+ - Improve your statements and redo any part if necessary.
+
+_* /{Chapters}/
+
+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.
+
+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.
+
+_* /{Markup}/
+
+And last but not least, live-manual uses {SiSU}http://www.sisudoc.org/ to
+process the text files and produce a multiple format output. It is
+recommended to take a look at {SiSU's
+manual}http://www.sisudoc.org/sisu/en/html/sisu_manual/markup.html to get
+familiar with its markup, or else type:
+
+code{
+
+ $ sisu --help markup
+
+}code
+
+Here are some markup examples that may prove useful:
+
+ - For emphasis/bold text:
+
+code{
+
+*{foo}* or !{foo}!
+
+}code
+
+produces: *{foo}* or !{foo}!. Use it to emphasize certain key words.
+
+ - For italics:
+
+code{
+
+/{foo}/
+
+}code
+
+produces: /{foo}/.  Use them e.g. for the names of Debian packages.
+
+ - For monospace:
+
+code{
+
+#{foo}#
+
+}code
+
+produces: #{foo}#. Use it e.g. for the names of commands. And also to
+highlight some key words or things like paths.
+
+ - For code blocks:
+
+code{
+
+ code{
+
+  $ foo
+  # bar
+
+ }code
+
+}code
+
+produces:
+
+code{
+
+ $ foo
+ # bar
+
+}code
+
+Use #{code{}# to open and #{}code}# to close the tags. It is important to
+remember to leave a space at the beginning of each line of code.
+
+2~guidelines-translators Guidelines for translators
+
+This section deals with some general considerations to be taken into account
+when translating the contents of live-manual.
+
+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.
+
+*{Note:}* Translators should also read {Contributing to this document}#how-to-contribute. In particular the section {Translation}#translation
+
+3~ Translation hints
+
+_* /{Comments}/
+
+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.
+
+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 *{po}* files
+preceded by a number sign *{#}*. Most graphical translation programs can
+automatically handle those types of comments.
+
+_* /{TN, Translator's Note}/
+
+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".
+
+_* /{Impersonal sentences}/
+
+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.
+
+_* /{False friends}/
+
+The trap of "false friends" explained before especially applies to
+translators. Double check the meaning of suspicious false friends if in
+doubt.
+
+_* /{Markup}/
+
+Translators working initially with *{pot}* files and later on with *{po}*
+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.
+
+_* /{Code blocks}/
+
+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.
+
+_* /{Newlines}/
+
+The translated texts need to have the exact same newlines as the original
+texts. Be careful to press the "Enter" key or type *{\n}* if they appear in
+the original files. These newlines often appear, for instance, in the code
+blocks.
+
+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.
+
+_* /{Untranslatable strings}/
+
+Translators should never translate:
+
+ - The code names of releases (which should be written in lowercase)
+
+ - The names of programs
+
+ - The commands given as examples
+
+ - Metadata (often between colons *{:metadata:}*)
+
+ - Links
+
+ - Paths