-#LyX 1.3 created this file. For more info see http://www.lyx.org/
-\lyxformat 221
+#LyX 1.5.0svn created this file. For more info see http://www.lyx.org/
+\lyxformat 276
+\begin_document
+\begin_header
\textclass article
\language english
\inputencoding latin1
-\fontscheme default
+\font_roman default
+\font_sans default
+\font_typewriter default
+\font_default_family default
+\font_sc false
+\font_osf false
+\font_sf_scale 100
+\font_tt_scale 100
\graphics dvips
\paperfontsize 12
-\spacing single
-\papersize Default
-\paperpackage a4
-\use_geometry 0
+\spacing single
+\papersize default
+\use_geometry false
\use_amsmath 0
-\use_natbib 0
-\use_numerical_citations 0
+\use_esint 0
+\cite_engine basic
+\use_bibtopic false
\paperorientation portrait
\secnumdepth 3
\tocdepth 3
\paragraph_separation indent
\defskip medskip
\quotes_language english
-\quotes_times 2
\papercolumns 1
\papersides 1
\paperpagestyle plain
+\tracking_changes false
+\output_changes false
+\end_header
-\layout Title
+\begin_body
+\begin_layout Title
Documentation Project Style Sheet
-\layout Author
+\end_layout
+\begin_layout Author
by John Weiss
-\layout Abstract
+\end_layout
+\begin_layout Abstract
This article is a style sheet.
It describes, with examples, how the documentation should look and sound.
The first few sections explain the font conventions and typography conventions
Those sections also contain examples.
It also explains the purpose of each of the different manuals.
Follow it not merely to the letter, but also in spirit.
-\layout Abstract
+\end_layout
+\begin_layout Abstract
The Style Sheet for LyX documentation (hereafter known as the Style Sheet)
- applies to
-\emph on
+ applies to
+\emph default
+
+\emph on
all
-\emph default
+\emph default
forms of LyX documenation, regardless of language.
There is a section for translators in the Style Sheet, towards the end.
+
+\emph default
-\emph on
+\emph on
Read the entire Style Sheet!
-\emph default
+\emph default
Even if you are a translator, I assume you know enough English to comprehend
this document.
-\layout Section
+\end_layout
+\begin_layout Section
Questions and Clarifications
-\layout Standard
+\end_layout
+\begin_layout Standard
After the second version of this Style Sheet grew uncomfortably large, the
LyX DocTeam decided it needed to lose some excess weight.
It seems the Style Sheet began to specify too many special cases, too many
On the other hand, contributors to the documents were discovering many
creative ways of misinterpreting the Style Sheet specifications.
Therefore:
-\layout Quote
+\end_layout
-If you have any questions about anything in the Style Sheet,
-\emph on
+\begin_layout Quote
+If you have any questions about anything in the Style Sheet,
+\emph default
+
+\emph on
ask first, write second!
-\layout Standard
+\end_layout
+\begin_layout Standard
Field all questions to the LyX Developer's Mailing List.
There are seasoned DocTeam members who can answer your questions.
If you have any problems with the Style Sheet itself, also contact the
mailing list.
-\layout Section
+\end_layout
+\begin_layout Section
Fonts
-\layout Standard
+\end_layout
+\begin_layout Standard
We'll start with the easiest section, yet also the most important.
-\layout Standard
+\end_layout
+\begin_layout Standard
This is how you should fontify text in the manuals:
-\layout List
-\labelwidthstring MMMMMMMM
+\end_layout
+\begin_layout List
+\labelwidthstring MMMMMMMM
-\emph on
+\emph on
Emphasized
-\emph default
+\emph default
general emphasis, generic arguments, titles of books, names the other manuals
and of their sections, and notes from the authors
-\begin_deeper
-\layout Standard
+\end_layout
+\begin_deeper
+\begin_layout Standard
Do not overemphasize your text.
-\end_deeper
-\layout List
-\labelwidthstring MMMMMMMM
+\end_layout
+\end_deeper
+\begin_layout List
+\labelwidthstring MMMMMMMM
-\family typewriter
+\family typewriter
Typewriter
-\family default
- program names, file names,
-\family typewriter
+\family default
+ program names, file names,
+\family default
+
+\family typewriter
man
-\family default
+\family default
-page names, LaTeX code, LaTeX commands, LaTeX package names, and LyX code
and functions
-\layout List
-\labelwidthstring MMMMMMMM
+\end_layout
+\begin_layout List
+\labelwidthstring MMMMMMMM
-\family sans
-Sans\SpecialChar ~
+\family sans
+Sans\InsetSpace ~
Serif
-\family default
+\family default
menu, button, or popup names, the names/lables of all widgets in a popup,
the names of keyboard keys, and certain
\begin_inset Quotes eld
-\end_inset
+\end_inset
special terms
\begin_inset Quotes erd
-\end_inset
+\end_inset
-\layout List
-\labelwidthstring MMMMMMMM
+\end_layout
+\begin_layout List
+\labelwidthstring MMMMMMMM
-\noun on
-Noun\SpecialChar ~
+\noun on
+Noun\InsetSpace ~
Style
-\noun default
+\noun default
people's names
-\layout List
-\labelwidthstring MMMMMMMM
+\end_layout
+\begin_layout List
+\labelwidthstring MMMMMMMM
-\family sans
-\bar under
+\family sans
+\bar under
U
-\bar default
-nderlined\SpecialChar ~
-Sans\SpecialChar ~
+\bar default
+nderlined\InsetSpace ~
+Sans\InsetSpace ~
Serif
-\family default
+\family default
Rich Fields added this to mimick the underlining of letters in the menus
and on buttons.
It helps to highlight the accelerator keys, and human brains store information
best when they see it frequently.
-\begin_deeper
-\layout Description
+\end_layout
-WARNING! --- When you do this, make sure you
-\emph on
+\begin_deeper
+\begin_layout Description
+WARNING! --- When you do this, make sure you
+\emph default
+
+\emph on
only
-\emph default
+\emph default
shut off the underlining.
Too many people send in things that look like:
-\newline
+\newline
-\family sans
-\bar under
+\family sans
+\bar under
T
-\family default
-\bar default
+\family default
+\bar default
his
-\newline
+\newline
\SpecialChar \ldots{}
-i.\SpecialChar ~
-e.\SpecialChar ~
-they not only shut off underlining, they turned off
-\family sans
-Sans\SpecialChar ~
+i.\InsetSpace ~
+e.\InsetSpace ~
+they not only shut off underlining, they turned off
+\family default
+
+\family sans
+Sans\InsetSpace ~
Serif
-\family default
-, too!
-\emph on
+\family default
+, too!
+\emph default
+
+\emph on
Don't do that!
-\emph default
- Make sure the entire word is still in
-\family sans
-Sans\SpecialChar ~
+\emph default
+ Make sure the entire word is still in
+\family default
+
+\family sans
+Sans\InsetSpace ~
Serif
-\family default
+\family default
after you shut off the underlining.
-\end_deeper
-\layout List
-\labelwidthstring MMMMMMMM
+\end_layout
+\end_deeper
+\begin_layout List
+\labelwidthstring MMMMMMMM
-\series bold
+\series bold
Bold
-\series default
+\series default
Unused.
-\begin_deeper
-\layout Standard
+\end_layout
-If you want to emphasize any text, use
-\emph on
+\begin_deeper
+\begin_layout Standard
+If you want to emphasize any text, use
+\emph default
+
+\emph on
Emphasized
-\emph default
+\emph default
.
- LaTeX will put many things boldface on its own, such as
-\family sans
+ LaTeX will put many things boldface on its own, such as
+\family default
+
+\family sans
Section
-\family default
+\family default
s, certain parts of equations, et cetera.
-\layout Standard
+\end_layout
+\begin_layout Standard
Repeat: do not use boldface.
-\end_deeper
-\layout Standard
+\end_layout
+\end_deeper
+\begin_layout Standard
Here are some examples:
-\layout Enumerate
+\end_layout
-The function
-\family typewriter
+\begin_layout Enumerate
+The function
+\family default
+
+\family typewriter
math-mode
-\family default
+\family default
appears in configuration files and in the LyX source.
Therefore, it (and all other LyX function names) count as code and is set
- in
-\family typewriter
+ in
+\family default
+
+\family typewriter
Typewriter
-\family default
+\family default
.
-\layout Enumerate
+\end_layout
-However,
-\family sans
-\bar under
+\begin_layout Enumerate
+However,
+\family default
+
+\family sans
+\bar under
M
-\bar default
-ath\SpecialChar ~
+\bar default
+ath\InsetSpace ~
mode
-\family default
- is a menu item in the
-\family sans
-\bar under
+\family default
+ is a menu item in the
+\family default
+
+\family sans
+\bar under
M
-\bar default
+\bar default
ath
-\family default
- menu, so it appears in
-\family sans
-Sans\SpecialChar ~
+\family default
+ menu, so it appears in
+\family default
+
+\family sans
+Sans\InsetSpace ~
Serif
-\family default
+\family default
.
- Notice the use of
-\family sans
-\bar under
+ Notice the use of
+\family default
+
+\family sans
+\bar under
U
-\bar default
-nderlined\SpecialChar ~
-Sans\SpecialChar ~
+\bar default
+nderlined\InsetSpace ~
+Sans\InsetSpace ~
Serif
-\family default
+\family default
for the accelerator keys.
-\layout Enumerate
+\end_layout
+\begin_layout Enumerate
Consider the following excerpt from the introduction of one of the manuals:
-\begin_deeper
-\layout Quotation
+\end_layout
+\begin_deeper
+\begin_layout Quotation
-\family sans
+\family sans
Return
-\family default
- and
-\family sans
+\family default
+ and
+\family default
+
+\family sans
Enter
-\family default
+\family default
both refer to the same key.
- Some keyboards label the
-\family sans
+ Some keyboards label the
+\family default
+
+\family sans
Return
-\family default
+\family default
key as
\begin_inset Quotes eld
-\end_inset
+\end_inset
Return,
\begin_inset Quotes erd
-\end_inset
+\end_inset
others as
\begin_inset Quotes eld
-\end_inset
+\end_inset
Enter,
\begin_inset Quotes erd
-\end_inset
+\end_inset
still others have two keys.
- LyX treats all of them as the same key, so we'll use
-\family sans
+ LyX treats all of them as the same key, so we'll use
+\family default
+
+\family sans
Return
-\family default
- and
-\family sans
+\family default
+ and
+\family default
+
+\family sans
Enter
-\family default
+\family default
interchangeably.
-\layout Standard
+\end_layout
-Notice that the key name,
-\family sans
+\begin_layout Standard
+Notice that the key name,
+\family default
+
+\family sans
Return
-\family default
-, is in
-\family sans
-Sans\SpecialChar ~
+\family default
+, is in
+\family default
+
+\family sans
+Sans\InsetSpace ~
Serif
-\family default
-, but
-\emph on
+\family default
+, but
+\emph default
+
+\emph on
only
-\emph default
+\emph default
when it references the key itself! When I described how the manufacturer
chose to label its keyboard, I used Roman and put the word in quotes.
There is a semantic difference.
-\end_deeper
-\layout Enumerate
+\end_layout
+\end_deeper
+\begin_layout Enumerate
Take the following command:
-\begin_deeper
-\layout Standard
+\end_layout
+\begin_deeper
+\begin_layout Standard
-\family typewriter
+\family typewriter
lpr -P
-\family default
-\emph on
+\family default
+\emph on
printername
-\layout Standard
+\end_layout
-Notice that the argument to the
-\family typewriter
+\begin_layout Standard
+Notice that the argument to the
+\family default
+
+\family typewriter
-P
-\family default
- option is in
-\emph on
+\family default
+ option is in
+\emph default
+
+\emph on
Roman Italics
-\emph default
+\emph default
(i.e.
emphasized).
- This is a case where you don't use
-\family typewriter
+ This is a case where you don't use
+\family default
+
+\family typewriter
Typewriter
-\family default
+\family default
for code, because you want the generic argument label to stand out.
On the other hand, if you were specifying an argument, for example,
\begin_inset Quotes eld
-\end_inset
+\end_inset
-\family typewriter
+\family typewriter
lpr -Pduaneps
-\family default
+\family default
\begin_inset Quotes erd
-\end_inset
+\end_inset
-, you'd leave it in
-\family typewriter
+, you'd leave it in
+\family default
+
+\family typewriter
Typewriter
-\family default
+\family default
.
-\end_deeper
-\layout Enumerate
+\end_layout
-Any LaTeX commands and code, and any
-\emph on
+\end_deeper
+\begin_layout Enumerate
+Any LaTeX commands and code, and any
+\emph default
+
+\emph on
unsupported
-\emph default
- LaTeX package names get set in
-\family typewriter
+\emph default
+ LaTeX package names get set in
+\family default
+
+\family typewriter
Typewriter
-\family default
+\family default
.
For example,
\begin_inset Quotes eld
-\end_inset
+\end_inset
-\family typewriter
+\family typewriter
multicol
-\family default
+\family default
\begin_inset Quotes erd
-\end_inset
+\end_inset
is the name of an unsupported LaTeX package, but
\begin_inset Quotes eld
-\end_inset
+\end_inset
-\family sans
+\family sans
book
-\family default
+\family default
\begin_inset Quotes erd
-\end_inset
+\end_inset
is a supported LaTeX class.
-\layout Section
+\end_layout
+\begin_layout Section
Keys
-\layout Standard
+\end_layout
+\begin_layout Standard
The canonical keyboard contains these keys:
-\layout Itemize
+\end_layout
+\begin_layout Itemize
-\family sans
+\family sans
C-
-\family default
- or
-\family sans
+\family default
+ or
+\family default
+
+\family sans
Control-
-\family default
+\family default
-\layout Itemize
+\end_layout
+\begin_layout Itemize
-\family sans
+\family sans
S-
-\family default
- or
-\family sans
+\family default
+ or
+\family default
+
+\family sans
Shift-
-\family default
+\family default
-\layout Itemize
+\end_layout
+\begin_layout Itemize
-\family sans
+\family sans
M-
-\family default
- or
-\family sans
+\family default
+ or
+\family default
+
+\family sans
Meta-
-\family default
+\family default
-\begin_deeper
-\layout Standard
+\end_layout
+\begin_deeper
+\begin_layout Standard
Self-explanatory.
- Be lazy and
-\emph on
+ Be lazy and
+\emph default
+
+\emph on
use the abbreviations
-\emph default
+\emph default
whenever possible.
-\end_deeper
-\layout Itemize
+\end_layout
+\end_deeper
+\begin_layout Itemize
-\family sans
+\family sans
F1 F2 F3 F4 F5 F6 F7 F8 F9 F10 F11 F12
-\begin_deeper
-\layout Standard
+\end_layout
+\begin_deeper
+\begin_layout Standard
The function keys.
Most modern keyboards have all 12.
-\end_deeper
-\layout Itemize
+\end_layout
+\end_deeper
+\begin_layout Itemize
-\family sans
+\family sans
Esc
-\family default
+\family default
-\begin_deeper
-\layout Standard
+\end_layout
+\begin_deeper
+\begin_layout Standard
The
\begin_inset Quotes eld
-\end_inset
+\end_inset
Escape key.
\begin_inset Quotes erd
-\end_inset
+\end_inset
-\end_deeper
-\layout Itemize
+\end_layout
+\end_deeper
+\begin_layout Itemize
-\family sans
+\family sans
Insert
-\family default
+\family default
+
+\family default
-\family sans
+\family sans
Delete
-\family default
+\family default
+
+\family default
-\family sans
+\family sans
Home
-\family default
+\family default
+
+\family default
-\family sans
+\family sans
End
-\family default
+\family default
+
+\family default
-\family sans
+\family sans
PageUp
-\family default
+\family default
+
+\family default
-\family sans
+\family sans
PageDown
-\begin_deeper
-\layout Standard
+\end_layout
+\begin_deeper
+\begin_layout Standard
These are the 6 keys that appear above the cursor keys on many PC keyboards.
Consider them as part of the standard motion keys.
-\end_deeper
-\layout Itemize
+\end_layout
+\end_deeper
+\begin_layout Itemize
-\family sans
+\family sans
Left Right Up Down
-\begin_deeper
-\layout Standard
+\end_layout
+\begin_deeper
+\begin_layout Standard
The four standard motion keys.
There is no need to put the word
\begin_inset Quotes eld
-\end_inset
+\end_inset
arrow
\begin_inset Quotes erd
-\end_inset
+\end_inset
anywhere, since that's obvious.
\begin_inset Foot
-collapsed true
-
-\layout Standard
+status collapsed
+\begin_layout Standard
Same goes for
\begin_inset Quotes eld
-\end_inset
+\end_inset
cursor key
\begin_inset Quotes erd
-\end_inset
+\end_inset
.
Even the word
\begin_inset Quotes eld
-\end_inset
+\end_inset
key
\begin_inset Quotes erd
-\end_inset
+\end_inset
after one of these may be redundant in certain situations.
-\end_inset
+\end_layout
+
+\end_inset
-\end_deeper
-\layout Itemize
+\end_layout
+\end_deeper
+\begin_layout Itemize
-\family sans
+\family sans
Return
-\family default
- and
-\family sans
+\family default
+ and
+\family default
+
+\family sans
Enter
-\family default
+\family default
-\begin_deeper
-\layout Standard
+\end_layout
+\begin_deeper
+\begin_layout Standard
I won't throw a hissy fit if you use one instead of the other.
- I'd prefer if you used
-\family sans
+ I'd prefer if you used
+\family default
+
+\family sans
Return
-\family default
- over
-\family sans
+\family default
+ over
+\family default
+
+\family sans
Enter
-\family default
+\family default
, but it's okay if you slip up and forget.
Since these two keys are bound to the same function in LyX, it doesn't
really matter.
-\end_deeper
-\layout Standard
+\end_layout
-You do not need to explain everywhere what the
-\family sans
+\end_deeper
+\begin_layout Standard
+You do not need to explain everywhere what the
+\family default
+
+\family sans
Meta
-\family default
- key is or where the
-\family sans
+\family default
+ key is or where the
+\family default
+
+\family sans
Left
-\family default
+\family default
key is, et cetera.
The user isn't stupid.
- Also, someone will document anything that isn't clear (e.\SpecialChar ~
-g.\SpecialChar ~
-the
-\family sans
+ Also, someone will document anything that isn't clear (e.\InsetSpace ~
+g.\InsetSpace ~
+the
+\family default
+
+\family sans
Meta
-\family default
+\family default
vs.
+
+\family default
-\family sans
+\family sans
Alt
-\family default
+\family default
problem) someplace in the introduction.
No need for you to repeat someone else's work.
-\layout Standard
+\end_layout
+\begin_layout Standard
LyX does not support keyboards missing any of the keys described above,
with one exception.
- LyX can support a keyboard missing
-\family sans
+ LyX can support a keyboard missing
+\family default
+
+\family sans
F11
-\family default
- and
-\family sans
+\family default
+ and
+\family default
+
+\family sans
F12
-\family default
+\family default
.
- There is a keyboard accelerator for
-\family sans
+ There is a keyboard accelerator for
+\family default
+
+\family sans
F10
-\family default
+\family default
, but this is the only function key LyX assumes exists.
Nevertheless, these details are of minor, if any, concern for the documentation.
Assume the aforementioned keys exist.
-\layout Section
+\end_layout
+\begin_layout Section
Mice
-\layout Standard
+\end_layout
+\begin_layout Standard
The word
\begin_inset Quotes eld
-\end_inset
+\end_inset
mouse
\begin_inset Quotes erd
-\end_inset
+\end_inset
and any description of the 3 mouse buttons have no special handling.
Don't typeset them in any other font than the default, which is Roman.
-\layout Standard
+\end_layout
+\begin_layout Standard
Exception: you're writing an Author's Note (see section
-\begin_inset LatexCommand \ref{sec:author-notes}
-
-\end_inset
+\begin_inset LatexCommand ref
+reference "sec:author-notes"
+\end_inset
) and you need to mention something about the mouse.
- Since the rest of the note is in
-\emph on
+ Since the rest of the note is in
+\emph default
+
+\emph on
Emphasized
-\emph default
+\emph default
, your description of
\begin_inset Quotes eld
-\end_inset
+\end_inset
middle mouse button
\begin_inset Quotes erd
-\end_inset
+\end_inset
should be emphasized, as well.
There are a couple of other cases like this one; use your judgement.
-\layout Standard
+\end_layout
+\begin_layout Standard
There are only 3 mouse buttons.
The use of them and of the mouse itself is obvious.
There are few --- if any --- nonstandard things we do with the mouse.
Therefore, there's no need to make the word
\begin_inset Quotes eld
-\end_inset
+\end_inset
mouse
\begin_inset Quotes erd
-\end_inset
+\end_inset
or
\begin_inset Quotes eld
-\end_inset
+\end_inset
mouse button
\begin_inset Quotes erd
-\end_inset
+\end_inset
stand out.
-\layout Section
+\end_layout
+\begin_layout Section
Special Typography
-\layout Standard
+\end_layout
+\begin_layout Standard
Do the following:
-\layout Description
+\end_layout
-Multi-word\SpecialChar ~
-names Use a
-\family sans
-Protected\SpecialChar ~
+\begin_layout Description
+Multi-word\InsetSpace ~
+names Use a
+\family default
+
+\family sans
+Protected\InsetSpace ~
Blank
-\family default
+\family default
between the words for menu and widget names.
- E.\SpecialChar ~
-g.:
-\family sans
-Save\SpecialChar ~
+ E.\InsetSpace ~
+g.:
+\family default
+
+\family sans
+Save\InsetSpace ~
As
-\family default
-, not
-\family sans
+\family default
+, not
+\family default
+
+\family sans
Save As
-\family default
+\family default
.
-\begin_deeper
-\layout Standard
+\end_layout
-This holds for things in
-\family typewriter
+\begin_deeper
+\begin_layout Standard
+This holds for things in
+\family default
+
+\family typewriter
Typewriter
-\family default
- as well as
-\family sans
-Sans\SpecialChar ~
+\family default
+ as well as
+\family default
+
+\family sans
+Sans\InsetSpace ~
Serif
-\family default
+\family default
, with one caveat.
If you have a long code example, one that can't simply be inlined and put
- in
-\family typewriter
+ in
+\family default
+
+\family typewriter
Typewriter
-\family default
-, put that in a
-\family sans
-LyX\SpecialChar ~
+\family default
+, put that in a
+\family default
+
+\family sans
+LyX\InsetSpace ~
Code
-\family default
+\family default
environment.
-\layout Standard
+\end_layout
-I want the
-\family sans
-Protected\SpecialChar ~
+\begin_layout Standard
+I want the
+\family default
+
+\family sans
+Protected\InsetSpace ~
Blank
-\family default
+\family default
so that the name doesn't get split between two lines, which is visually
disruptive.
- If something with a
-\family sans
-Protected\SpecialChar ~
+ If something with a
+\family default
+
+\family sans
+Protected\InsetSpace ~
Blank
-\family default
- is near the end of a line and overflows the margin, use a
-\family typewriter
+\family default
+ is near the end of a line and overflows the margin, use a
+\family default
+
+\family typewriter
-\backslash
+\backslash
sloppypar
-\family default
+\family default
in that parargraph (consult a LaTeX book for more about
\begin_inset Quotes eld
-\end_inset
+\end_inset
-\family typewriter
+\family typewriter
-\backslash
+\backslash
sloppypar
-\family default
+\family default
\begin_inset Quotes erd
-\end_inset
+\end_inset
) or manually add a hypenation point.
-\end_deeper
-\layout Description
+\end_layout
-Special\SpecialChar ~
+\end_deeper
+\begin_layout Description
+Special\InsetSpace ~
Terms These are things like the following:
-\begin_deeper
-\layout Itemize
+\end_layout
+\begin_deeper
+\begin_layout Itemize
-\family sans
+\family sans
HFill
-\family default
+\family default
-\layout Itemize
+\end_layout
+\begin_layout Itemize
-\family sans
+\family sans
VFill
-\family default
+\family default
-\layout Itemize
+\end_layout
+\begin_layout Itemize
-\family sans
-Table\SpecialChar ~
+\family sans
+Table\InsetSpace ~
Float
-\layout Itemize
+\end_layout
+\begin_layout Itemize
-\family sans
-Figure\SpecialChar ~
+\family sans
+Figure\InsetSpace ~
Float
-\begin_deeper
-\layout Standard
+\end_layout
-Use
-\family sans
-Sans\SpecialChar ~
+\begin_deeper
+\begin_layout Standard
+Use
+\family default
+
+\family sans
+Sans\InsetSpace ~
Serif
-\family default
- font and, in the case of
-\family sans
-HFill
-\family default
-and
-\family sans
+\family default
+ font and, in the case of
+\family default
+
+\family sans
+HFill
+\family default
+
+and
+\family default
+
+\family sans
VFill
-\family default
+\family default
, capitalize the first two letters.
-\layout Standard
+\end_layout
+\begin_layout Standard
Why are these terms special? They are concepts which the seasoned LaTeX-pert
is familiar with, but which the new LyX user is not.
- I want them to stand out from the rest of the text, hence the use of
-\family sans
-Sans\SpecialChar ~
+ I want them to stand out from the rest of the text, hence the use of
+\family default
+
+\family sans
+Sans\InsetSpace ~
Serif
-\family default
+\family default
for them.
-\end_deeper
-\end_deeper
-\layout Standard
+\end_layout
+\end_deeper
+\end_deeper
+\begin_layout Standard
Seasoned LyX Team Members: Are there other terms that require this special
status? On the other hand, should we eliminate this style completely?
-\layout Description
+\end_layout
+\begin_layout Description
Terminology Note the following:
-\layout Itemize
-
+\end_layout
+\begin_layout Itemize
\begin_inset Quotes eld
-\end_inset
+\end_inset
dialog
\begin_inset Quotes erd
-\end_inset
+\end_inset
not
\begin_inset Quotes eld
-\end_inset
+\end_inset
popup
\begin_inset Quotes erd
-\end_inset
+\end_inset
or
\begin_inset Quotes eld
-\end_inset
+\end_inset
window
\begin_inset Quotes erd
-\end_inset
+\end_inset
.
\begin_inset Quotes eld
-\end_inset
+\end_inset
Confirmation alert
\begin_inset Quotes erd
-\end_inset
+\end_inset
not
\begin_inset Quotes eld
-\end_inset
+\end_inset
dialog
\begin_inset Quotes erd
-\end_inset
+\end_inset
.
-\layout Itemize
+\end_layout
+
+\begin_layout Itemize
+PostScript® is a registered trademark of Adobe Corp.
-PostScript® is a registered trademark of Adobe Corp.
+\emph default
-\emph on
-You must put the ® after it or we'll get sued!
-\emph default
+\emph on
+You must put the ® after it or we'll get sued!
+\emph default
I also want it written as seen here, always capitalized.
Not
\begin_inset Quotes eld
-\end_inset
+\end_inset
-postscript®,
+postscript®,
\begin_inset Quotes erd
-\end_inset
+\end_inset
or
\begin_inset Quotes eld
-\end_inset
+\end_inset
-Postscript®
+Postscript®
\begin_inset Quotes erd
-\end_inset
+\end_inset
but
\begin_inset Quotes eld
-\end_inset
+\end_inset
-PostScript®
+PostScript®
\begin_inset Quotes erd
-\end_inset
+\end_inset
- - both of them capitalized, in the default font (i.\SpecialChar ~
-.e.\SpecialChar ~
+ - both of them capitalized, in the default font (i.\InsetSpace ~
+.e.\InsetSpace ~
Roman).
If you must, cut and paste it from here.
-\begin_deeper
-\layout Standard
+\end_layout
+\begin_deeper
+\begin_layout Standard
I am going to say this again:
-\layout Standard
-\added_space_top 0.37cm \added_space_bottom 0.51cm \align center
+\end_layout
+
+\begin_layout Standard
+\begin_inset VSpace 0.37cm
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\align center
+
+\size larger
+\emph on
+You must put the ® after PostScript® or we'll get sued!
+\end_layout
+
+\begin_layout Standard
+\begin_inset VSpace 0.51cm
+\end_inset
+
-\size larger
-\emph on
-You must put the ® after PostScript® or we'll get sued!
-\layout Standard
+\end_layout
+\begin_layout Standard
I mean it! American companies like to sue anything that moves.
- We could get in
-\emph on
+ We could get in
+\emph default
+
+\emph on
major trouble
-\emph default
- by forgetting that ®.
+\emph default
+ by forgetting that ®.
So, don't.
Got it?
-\end_deeper
-\layout Itemize
+\end_layout
+\end_deeper
+\begin_layout Itemize
Similarly, if you use any other registered trademark in any documentation,
- put the ® after it, too.
-\layout Description
+ put the ® after it, too.
+\end_layout
-Menu\SpecialChar ~
+\begin_layout Description
+Menu\InsetSpace ~
Items When quick-referencing an item in a menu, use the menu separator:
\begin_inset Quotes eld
-\end_inset
+\end_inset
\SpecialChar \menuseparator
\begin_inset Quotes erd
-\end_inset
+\end_inset
.
- Example:
-\family sans
+ Example:
+\family default
+
+\family sans
File\SpecialChar \menuseparator
Save
-\family default
+\family default
.
- Notice that there are
-\emph on
+ Notice that there are
+\emph default
+
+\emph on
no spaces
-\emph default
+\emph default
around the
\begin_inset Quotes eld
-\end_inset
+\end_inset
\SpecialChar \menuseparator
\begin_inset Quotes erd
-\end_inset
+\end_inset
- and that it's in
-\family sans
-Sans\SpecialChar ~
+ and that it's in
+\family default
+
+\family sans
+Sans\InsetSpace ~
Serif
-\family default
+\family default
, just like the menu and item names.
-\begin_deeper
-\layout Enumerate
+\end_layout
+\begin_deeper
+\begin_layout Enumerate
The reason why I want no spaces around the
\begin_inset Quotes eld
-\end_inset
+\end_inset
\SpecialChar \menuseparator
\begin_inset Quotes erd
-\end_inset
+\end_inset
is to prevent LyX from splitting terms across lines.
- The same goes for using
-\family sans
-Protected\SpecialChar ~
+ The same goes for using
+\family default
+
+\family sans
+Protected\InsetSpace ~
Blank
-\family default
+\family default
s between multi-word terms.
The split would be visually disruptive.
-\layout Enumerate
+\end_layout
+\begin_layout Enumerate
A
\begin_inset Quotes eld
-\end_inset
+\end_inset
\SpecialChar \menuseparator
\begin_inset Quotes erd
-\end_inset
+\end_inset
- goes between menu names and item names
-\emph on
+ goes between menu names and item names
+\emph default
+
+\emph on
only
-\emph default
+\emph default
.
(Yes, submenus are okay, too).
-\layout Enumerate
+\end_layout
+\begin_layout Enumerate
-\emph on
+\emph on
NEVER
-\emph default
+\emph default
put
\begin_inset Quotes eld
-\end_inset
+\end_inset
\SpecialChar \menuseparator
\begin_inset Quotes erd
-\end_inset
+\end_inset
between menu items and dialog names.
Example:
\begin_inset Quotes eld
-\end_inset
+\end_inset
-\family sans
-\bar under
+\family sans
+\bar under
L
-\bar default
+\bar default
ayout\SpecialChar \menuseparator
P
-\bar under
+\bar under
a
-\bar default
+\bar default
per\SpecialChar \menuseparator
-Paper\SpecialChar ~
+Paper\InsetSpace ~
Dialog
-\family default
+\family default
\begin_inset Quotes erd
-\end_inset
+\end_inset
+
+\emph default
-\emph on
+\emph on
IS STRICTLY FORBIDDEN!
-\emph default
+\emph default
-\begin_deeper
-\layout Standard
+\end_layout
+\begin_deeper
+\begin_layout Standard
-\emph on
+\emph on
NEVER
-\emph default
+\emph default
put
\begin_inset Quotes eld
-\end_inset
+\end_inset
\SpecialChar \menuseparator
\begin_inset Quotes erd
-\end_inset
+\end_inset
between popup names and any dialog.
Example:
\begin_inset Quotes eld
-\end_inset
+\end_inset
-\family sans
-Paper\SpecialChar ~
+\family sans
+Paper\InsetSpace ~
Dialog\SpecialChar \menuseparator
P
-\bar under
+\bar under
o
-\bar default
+\bar default
rtrait
-\family default
+\family default
\begin_inset Quotes erd
-\end_inset
+\end_inset
+
+\emph default
-\emph on
+\emph on
IS STRICTLY FORBIDDEN!
-\layout Standard
+\end_layout
+\begin_layout Standard
-\emph on
+\emph on
NEVER
-\emph default
+\emph default
put
\begin_inset Quotes eld
-\end_inset
+\end_inset
\SpecialChar \menuseparator
\begin_inset Quotes erd
-\end_inset
+\end_inset
between menu items and any dialog.
Example:
\begin_inset Quotes eld
-\end_inset
+\end_inset
-\family sans
-\bar under
+\family sans
+\bar under
L
-\bar default
+\bar default
ayout\SpecialChar \menuseparator
P
-\bar under
+\bar under
a
-\bar default
+\bar default
per\SpecialChar \menuseparator
P
-\bar under
+\bar under
o
-\bar default
+\bar default
rtrait
-\family default
+\family default
\begin_inset Quotes erd
-\end_inset
+\end_inset
+
+\emph default
-\emph on
+\emph on
IS STRICTLY FORBIDDEN!
-\layout Standard
+\end_layout
+\begin_layout Standard
Either write out the description, or use context to eliminate any need to
repeat menu items, dialog names, etc.
-\end_deeper
-\end_deeper
-\layout Description
+\end_layout
-Note\SpecialChar ~
+\end_deeper
+\end_deeper
+\begin_layout Description
+Note\InsetSpace ~
Boxes LyX has a feature for adding comments that appear only within
the LyX GUI.
Here's one:
-\begin_inset Note
-collapsed true
-
-\layout Standard
+\begin_inset Note Note
+status collapsed
+\begin_layout Standard
These should NEVER appear in the manuals.
-\end_inset
+\end_layout
+
+\end_inset
.
You will see nothing in a printout of the Style Sheet.
Therefore, they have no place in the manuals.
Period.
-\begin_deeper
-\layout Standard
+\end_layout
+\begin_deeper
+\begin_layout Standard
If you have a parenthetical comment you want to make, the reader should
see it too, even in the printed version.
Use an Author's Note (see section
-\begin_inset LatexCommand \ref{sec:author-notes}
-
-\end_inset
+\begin_inset LatexCommand ref
+reference "sec:author-notes"
+\end_inset
) in place of the Note-Boxes.
-\end_deeper
-\layout Description
-
+\end_layout
+\end_deeper
+\begin_layout Description
\begin_inset Quotes eld
-\end_inset
+\end_inset
(\SpecialChar \ldots{}
)
\begin_inset Quotes erd
-\end_inset
+\end_inset
-,\SpecialChar ~
+,\InsetSpace ~
\begin_inset Quotes eld
-\end_inset
+\end_inset
[\SpecialChar \ldots{}
]
\begin_inset Quotes erd
-\end_inset
+\end_inset
-\SpecialChar ~
-and\SpecialChar ~
+\InsetSpace ~
+and\InsetSpace ~
\begin_inset Quotes eld
-\end_inset
+\end_inset
{\SpecialChar \ldots{}
}
\begin_inset Quotes erd
-\end_inset
+\end_inset
I have recently been corrected about the use of parentheses.
Standard English typesetting uses the normal parentheses,
\begin_inset Quotes eld
-\end_inset
+\end_inset
(\SpecialChar \ldots{}
)
\begin_inset Quotes erd
-\end_inset
+\end_inset
, around any aside, remark, or parenthetical expression.
The bracket,
\begin_inset Quotes eld
-\end_inset
+\end_inset
[\SpecialChar \ldots{}
]
\begin_inset Quotes erd
-\end_inset
+\end_inset
-, is used only within quotations (see section\SpecialChar ~
+, is used only within quotations (see section\InsetSpace ~
-\begin_inset LatexCommand \ref{sec:quote}
-
-\end_inset
+\begin_inset LatexCommand ref
+reference "sec:quote"
+\end_inset
).
The brace,
\begin_inset Quotes eld
-\end_inset
+\end_inset
{\SpecialChar \ldots{}
}
\begin_inset Quotes erd
-\end_inset
+\end_inset
, is never used.
Therefore, never use
\begin_inset Quotes eld
-\end_inset
+\end_inset
[\SpecialChar \ldots{}
]
\begin_inset Quotes erd
-\end_inset
+\end_inset
or
\begin_inset Quotes eld
-\end_inset
+\end_inset
{\SpecialChar \ldots{}
}
\begin_inset Quotes erd
-\end_inset
+\end_inset
unless otherwise specified by this Style Sheet.
-\layout Description
+\end_layout
+\begin_layout Description
Dashes: Be sure to use the correct one.
A single
\begin_inset Quotes eld
-\end_inset
+\end_inset
-\family typewriter
+\family typewriter
-
-\family default
+\family default
\begin_inset Quotes erd
-\end_inset
+\end_inset
character is not a dash, it's a hyphen.
Use it only as a hyphen.
-\begin_deeper
-\layout Standard
+\end_layout
+\begin_deeper
+\begin_layout Standard
Instead, use an
\begin_inset Quotes eld
-\end_inset
+\end_inset
en-dash
\begin_inset Quotes erd
-\end_inset
+\end_inset
or an
\begin_inset Quotes eld
-\end_inset
+\end_inset
em- dash.
\begin_inset Quotes erd
-\end_inset
+\end_inset
Two back-to-back
\begin_inset Quotes eld
-\end_inset
+\end_inset
-\family typewriter
+\family typewriter
-
-\family default
+\family default
\begin_inset Quotes erd
-\end_inset
+\end_inset
characters form the en-dash.
Three
\begin_inset Quotes eld
-\end_inset
+\end_inset
-\family typewriter
+\family typewriter
-
-\family default
+\family default
\begin_inset Quotes erd
-\end_inset
+\end_inset
characters create an em-dash, which is slightly longer than the en-dash.
In the printed version of any document, LyX will combine the two or three
\begin_inset Quotes eld
-\end_inset
+\end_inset
-\family typewriter
+\family typewriter
-
-\family default
+\family default
\begin_inset Quotes erd
-\end_inset
+\end_inset
characters into a single, unbroken line.
-\end_deeper
-\layout Section
+\end_layout
+\end_deeper
+\begin_layout Section
Cross-References and Labels
-\layout Standard
+\end_layout
+\begin_layout Standard
Use the following labelling conventions:
-\layout List
-\labelwidthstring 00.00.0000
+\end_layout
-sec:xxx Use this for
-\family sans
+\begin_layout List
+\labelwidthstring 00.00.0000
+sec:xxx Use this for
+\family default
+
+\family sans
Section
-\family default
-s as well as
-\family sans
+\family default
+s as well as
+\family default
+
+\family sans
Chapter
-\family default
-s,
-\family sans
+\family default
+s,
+\family default
+
+\family sans
Subsection
-\family default
-s,
-\family sans
+\family default
+s,
+\family default
+
+\family sans
Subsubsection
-\family default
+\family default
s, etc.
-\layout List
-\labelwidthstring 00.00.0000
+\end_layout
-eqn:xxx Use this for Equations, should you need to create any.
-\layout List
+\begin_layout List
\labelwidthstring 00.00.0000
+eqn:xxx Use this for Equations, should you need to create any.
+\end_layout
-tbl:xxxx Use this for tables inside of a table float.
-\layout List
+\begin_layout List
\labelwidthstring 00.00.0000
+tbl:xxxx Use this for tables inside of a table float.
+\end_layout
+\begin_layout List
+\labelwidthstring 00.00.0000
fig:xxx Use this for figures inside of figure floats.
-\layout Standard
+\end_layout
+\begin_layout Standard
Additionally, you should put the label at one of two locations:
-\layout Enumerate
+\end_layout
-The
-\emph on
+\begin_layout Enumerate
+The
+\emph default
+
+\emph on
beginning of the paragraph
-\emph default
+\emph default
, after a section heading, or at the beginning of captions, etc.
It should be the first thing on the first line.
Don't put a space betweeen it and the first word.
-\layout Enumerate
+\end_layout
-If there is no paragraph after a section heading, put it at the
-\emph on
+\begin_layout Enumerate
+If there is no paragraph after a section heading, put it at the
+\emph default
+
+\emph on
end of the last line.
-\emph default
+\emph default
-\begin_deeper
-\layout Standard
+\end_layout
-Example: You have a
-\family sans
+\begin_deeper
+\begin_layout Standard
+Example: You have a
+\family default
+
+\family sans
Section
-\family default
- which is immediately followed by a
-\family sans
+\family default
+ which is immediately followed by a
+\family default
+
+\family sans
Subsection
-\family default
+\family default
heading.
- This is a case where you need to put the label at the end of the
-\family sans
+ This is a case where you need to put the label at the end of the
+\family default
+
+\family sans
Section
-\family default
+\family default
heading.
I know it looks ugly; not much we can do about that, though.
-\end_deeper
-\layout Section
+\end_layout
+\end_deeper
+\begin_layout Section
Content --- What Goes Where
-\layout Standard
+\end_layout
-This is
-\emph on
+\begin_layout Standard
+This is
+\emph default
+
+\emph on
very
-\emph default
+\emph default
important to anyone documenting a new feature.
If you need to add new documentation, pay attention.
-\layout Standard
+\end_layout
+\begin_layout Standard
In the dim and distant past, whenever someone wanted to document a new feature
they added, they either wrote a mini-doc and stuck it into the documentation
directory, or they added a new section to the lone manual.
The result was a totally bloated, totally unnavigable, and incomplete manual
orbitted by a swarm of tiny, incomplete mini-docs.
I don't want the docs to fall back into that mess.
-\layout Standard
+\end_layout
+\begin_layout Standard
With that in mind, I have some instructions for how to keep things organized:
-\layout List
-\labelwidthstring 00.00.0000
+\end_layout
+\begin_layout List
+\labelwidthstring 00.00.0000
-\family typewriter
-Intro.lyx
-\family default
+\family typewriter
+Intro.lyx
+\family default
+
Please, don't touch this file.
It's essentially complete, anyhow.
Only the editor(s) should make changes to this, as this file contains info
about how to contribute to the doc project.
That's really the only stuff that should need to change, and even then,
only when a new maintainer comes along.
-\layout List
-\labelwidthstring 00.00.0000
+\end_layout
+\begin_layout List
+\labelwidthstring 00.00.0000
-\family typewriter
-UserGuide.lyx
-\family default
+\family typewriter
+UserGuide.lyx
+\family default
+
This file is complete.
- Any changes should be for updates
-\emph on
+ Any changes should be for updates
+\emph default
+
+\emph on
only
-\emph default
+\emph default
.
DO NOT ADD new features to here willy-nilly.
Let the editor decide if --- and when --- new sections go in here.
Place any new features in\SpecialChar \ldots{}
-\layout List
-\labelwidthstring 00.00.0000
+\end_layout
+\begin_layout List
+\labelwidthstring 00.00.0000
-\family typewriter
+\family typewriter
Extended.lyx
-\family default
+\family default
This is where all new features go from now on.
It's in the style of a bound journal --- each section is an
\begin_inset Quotes eld
-\end_inset
+\end_inset
article
\begin_inset Quotes erd
-\end_inset
+\end_inset
from the author of the feature.
- Also, anyone who writes a
-\family typewriter
+ Also, anyone who writes a
+\family default
+
+\family typewriter
.layout
-\family default
+\family default
file for a new document class should write a section describing that new
class and how to use it.
That also goes here.
-\begin_deeper
-\layout Standard
+\end_layout
-Note, however, that you are
-\emph on
+\begin_deeper
+\begin_layout Standard
+Note, however, that you are
+\emph default
+
+\emph on
not
-\emph default
- excused from following this Style Sheet just because the sections of
-\family typewriter
+\emph default
+ excused from following this Style Sheet just because the sections of
+\family default
+
+\family typewriter
Extended.lyx
-\family default
+\family default
are in the form of a journal article.
-\end_deeper
-\layout List
-\labelwidthstring 00.00.0000
+\end_layout
+\end_deeper
+\begin_layout List
+\labelwidthstring 00.00.0000
-\family typewriter
+\family typewriter
Tutorial.lyx
-\family default
+\family default
This file is complete.
Do not change or add to without permission of the Documenation Project
Editor.
-\layout List
-\labelwidthstring 00.00.0000
+\end_layout
+\begin_layout List
+\labelwidthstring 00.00.0000
-\family typewriter
+\family typewriter
Customization.lyx
-\family default
+\family default
This document describes advanced features, most of which alter the look,
feel, and behavior of LyX.
This manual is still a bit incomplete, although that may change soon.
Check for updates often.
-\begin_deeper
-\layout Standard
+\end_layout
-If you are unsure whether or not something belongs in
-\family typewriter
+\begin_deeper
+\begin_layout Standard
+If you are unsure whether or not something belongs in
+\family default
+
+\family typewriter
Customization.lyx
-\family default
-, then, most-likely, it
-\emph on
+\family default
+, then, most-likely, it
+\emph default
+
+\emph on
really
-\emph default
- belongs in
-\family typewriter
+\emph default
+ belongs in
+\family default
+
+\family typewriter
Extended.lyx
-\family default
+\family default
.
Again, let the current editor of the LyX documentation decide if your new
- section should be migrated to
-\family typewriter
+ section should be migrated to
+\family default
+
+\family typewriter
Customization.lyx
-\family default
+\family default
.
-\end_deeper
-\layout List
-\labelwidthstring 00.00.0000
+\end_layout
+\end_deeper
+\begin_layout List
+\labelwidthstring 00.00.0000
-\family typewriter
+\family typewriter
Reference.lyx
-\family default
+\family default
I'd prefer to completely finish this one before doing anything else, but
that's unrealistic.
- LyX keeps changing so much that I think the
-\emph on
+ LyX keeps changing so much that I think the
+\emph default
+
+\emph on
Reference Manual
-\emph default
+\emph default
will be the last one completed.
However, I'd like it if the developer's would add entries anytime they
create a new function or popup.
That would help things immensely!
-\begin_deeper
-\layout Standard
+\end_layout
-Note that the
-\emph on
+\begin_deeper
+\begin_layout Standard
+Note that the
+\emph default
+
+\emph on
Reference Manual
-\emph default
+\emph default
follows this Style Sheet for the most part.
There are, however, additional rules to follow when making new entries.
- At the top of this manual, there are examples of and a template for
-\emph on
+ At the top of this manual, there are examples of and a template for
+\emph default
+
+\emph on
Reference Manual
-\emph default
+\emph default
entries.
Use them.
-\end_deeper
-\layout Section
+\end_layout
+\end_deeper
+\begin_layout Section
Writing Style: The Primary Manuals
-\layout Standard
+\end_layout
+\begin_layout Standard
While I want to make contributing to the Documentation Project as painless
as possible for newcomers, I also want the newcomers to be painless on
the existing Documentation Team! Ergo, I've written this section to give
some flavor to guide everyone's individual style.
-\layout Subsection
+\end_layout
+\begin_layout Subsection
Language
-\layout Standard
+\end_layout
-All contributions to the
-\emph on
+\begin_layout Standard
+All contributions to the
+\emph default
+
+\emph on
primary
-\emph default
+\emph default
LyX documentation must be in English.
I don't care if it's British, Australian, or American English.
The DocTeam editor will proofread for glaring mistakes and fix them.
-\layout Standard
+\end_layout
+\begin_layout Standard
Don't get hung up on semantics.
English is a flexible language, and just because your Mothertongue-to-English
dictionary gives only one translation for a word doesn't necessarily mean
because of this very problem.
If something is unclear (or just plain weird) due to a translation problem,
one of the American/British/Australian developers can fix it.
-\layout Standard
+\end_layout
-Nota Bene: by
-\emph on
+\begin_layout Standard
+Nota Bene: by
+\emph default
+
+\emph on
primary
-\emph default
+\emph default
documentation, I exclude the translations.
We usually don't have enough people to cover the manuals in one language,
let alone more than one.
version of the LyX manuals.
The translation efforts require have their own set of guidelines.
See section
-\begin_inset LatexCommand \ref{sec:translations}
-
-\end_inset
+\begin_inset LatexCommand ref
+reference "sec:translations"
+\end_inset
for more info.
-\layout Subsection
+\end_layout
+\begin_layout Subsection
Wearing Many Hats:
-\newline
-Commentary from the Author (i.\SpecialChar ~
+\newline
+Commentary from the Author (i.\InsetSpace ~
e.: You)
-\layout Standard
+\end_layout
-
-\begin_inset LatexCommand \label{sec:author-notes}
-
-\end_inset
+\begin_layout Standard
+\begin_inset LatexCommand label
+name "sec:author-notes"
+\end_inset
I want to make it easy for everyone when it comes to documenting things.
Some features are incomplete.
other DocTeam members.
Sometimes, you may want to
\begin_inset Quotes eld
-\end_inset
+\end_inset
speak for yourself;
\begin_inset Quotes erd
-\end_inset
+\end_inset
you want to say something that is your personal opinion and using
\begin_inset Quotes eld
-\end_inset
+\end_inset
we
\begin_inset Quotes erd
-\end_inset
+\end_inset
would be inappropriate.
-\layout Standard
+\end_layout
+\begin_layout Standard
In short, when you contribute to the LyX Docs, you wear many hats.
-\layout Standard
+\end_layout
+\begin_layout Standard
For occasions when you need to switch hats, I've designed some special mechanism
s.
-\layout Subsubsection
+\end_layout
-Personal\SpecialChar ~
+\begin_layout Subsubsection
+Personal\InsetSpace ~
Notes: The
\begin_inset Quotes eld
-\end_inset
+\end_inset
Me
\begin_inset Quotes erd
-\end_inset
+\end_inset
Hat
-\layout Standard
+\end_layout
+\begin_layout Standard
These are footnotes.
They begin with the following:
-\layout Quote
+\end_layout
+\begin_layout Quote
Note from
-\noun on
+\noun on
Name of Person
-\noun default
+\noun default
:
-\layout Standard
+\end_layout
+\begin_layout Standard
\SpecialChar \ldots{}
using the
-\noun on
+\noun on
Noun Style
-\noun default
+\noun default
for the person's name and without the quotes.
The rest of the footnote is the actual comment.
-\layout Standard
+\end_layout
+\begin_layout Standard
Use these when you need to quote a comment by someone (usually yourself),
and need to identify that person.
This includes occasions when you need wear the
\begin_inset Quotes eld
-\end_inset
+\end_inset
me
\begin_inset Quotes erd
-\end_inset
+\end_inset
- hat, i.\SpecialChar ~
-e.\SpecialChar ~
+ hat, i.\InsetSpace ~
+e.\InsetSpace ~
to speak for yourself instead of for the LyX Team.
-\layout Standard
+\end_layout
+\begin_layout Standard
If the comment is too large to put in a footnote, don't use a Personal Note.
When quoting more than about 3 sentences or 5 lines of text, use a bona
fide quote.
Don't use any leading
\begin_inset Quotes eld
-\end_inset
+\end_inset
Note from
-\noun on
+\noun on
Name of Person
-\noun default
+\noun default
:
\begin_inset Quotes erd
-\end_inset
+\end_inset
in that case.
In a real quote, you'll give credit to the original speaker in either the
- paragraph before or after the body of the
-\family sans
+ paragraph before or after the body of the
+\family default
+
+\family sans
Quotation
-\family default
+\family default
.
-\layout Subsubsection
+\end_layout
-Author's\SpecialChar ~
+\begin_layout Subsubsection
+Author's\InsetSpace ~
Notes: The
\begin_inset Quotes eld
-\end_inset
+\end_inset
Author
\begin_inset Quotes erd
-\end_inset
+\end_inset
Hat
-\layout Standard
+\end_layout
+\begin_layout Standard
There will be times when you are not speaking for the LyX Team, yet you
are not entirely speaking for yourself.
Instead, you are speaking on behalf of the manual itself, as the author
of the manual.
Some examples of when you might need to do this are:
-\layout Itemize
+\end_layout
+\begin_layout Itemize
You need to contradict something you just wrote because the feature isn't
quite ready yet, but you wanted to document what it will do.
-\layout Itemize
+\end_layout
+\begin_layout Itemize
You need to leave a note for yourself.
-\layout Itemize
+\end_layout
+\begin_layout Itemize
You need to leave a note for the editor or the other DocTeam members.
-\layout Itemize
+\end_layout
+\begin_layout Itemize
You need to point out something about the manuals to the reader, something
that doesn't fit into the context of the current paragraph.
-\layout Standard
+\end_layout
+\begin_layout Standard
At such times, you are wearing your
\begin_inset Quotes eld
-\end_inset
+\end_inset
I am the Author
\begin_inset Quotes erd
-\end_inset
+\end_inset
hat, if you will.
-\layout Standard
+\end_layout
+\begin_layout Standard
The typography for an
\begin_inset Quotes eld
-\end_inset
+\end_inset
Author's Note
\begin_inset Quotes erd
-\end_inset
+\end_inset
is as follows:
-\layout Itemize
+\end_layout
+\begin_layout Itemize
They go in the body of the text, in brackets,
\begin_inset Quotes eld
-\end_inset
+\end_inset
[]
\begin_inset Quotes erd
-\end_inset
+\end_inset
, not any other form of parentheses.
The bracket are in the default character style.
-\layout Itemize
+\end_layout
+\begin_layout Itemize
The text of the note itself, however, is emphasized.
-\layout Itemize
+\end_layout
+\begin_layout Itemize
Begin with the words,
\begin_inset Quotes eld
-\end_inset
+\end_inset
-\emph on
+\emph on
Author's Note:
-\emph default
+\emph default
\begin_inset Quotes erd
-\end_inset
+\end_inset
and end with an em-dash,
\begin_inset Quotes eld
-\end_inset
+\end_inset
---
\begin_inset Quotes erd
-\end_inset
+\end_inset
, followed by your initials.
-\layout Standard
+\end_layout
+\begin_layout Standard
Here's an example: [
-\emph on
+\emph on
Author's Note: This is an example note.
---jw
-\emph default
+\emph default
].
-\layout Standard
+\end_layout
+\begin_layout Standard
The form of the Author's Note, by the way, isn't a suggestion or request.
- It is
-\emph on
+ It is
+\emph default
+
+\emph on
mandatory
-\emph default
+\emph default
.
All Author's Notes must begin with this text, verbatim:
\begin_inset Quotes eld
-\end_inset
+\end_inset
[
-\emph on
+\emph on
Author's Note:
-\emph default
+\emph default
\begin_inset Quotes erd
-\end_inset
+\end_inset
.
Abbreviations to
\begin_inset Quotes eld
-\end_inset
+\end_inset
AN
\begin_inset Quotes erd
-\end_inset
+\end_inset
are or any other variant are forbidden.
The Author's Note must end with an em-dash, which is 3
\begin_inset Quotes eld
-\end_inset
+\end_inset
-
\begin_inset Quotes erd
-\end_inset
+\end_inset
characters:
\begin_inset Quotes eld
-\end_inset
+\end_inset
---
\begin_inset Quotes erd
-\end_inset
+\end_inset
.
Do not use 2 or 1
\begin_inset Quotes eld
-\end_inset
+\end_inset
-
\begin_inset Quotes erd
-\end_inset
+\end_inset
; you must use 3 (and 5 is right out).
-\layout Standard
-
+\end_layout
+\begin_layout Standard
\begin_inset Quotes eld
-\end_inset
+\end_inset
Author's Notes
\begin_inset Quotes erd
-\end_inset
+\end_inset
are inherently transient, and should disapear as a manual matures.
-\layout Subsubsection
+\end_layout
+\begin_layout Subsubsection
Footnotes:
-\layout Standard
+\end_layout
+\begin_layout Standard
You are also free to use footnotes on their own in addition to the Personal
Notes and/or Author's Notes.
I've frequently used footnotes to \SpecialChar \ldots{}
well, to comment on parts of a section
without putting the commentary into the body of the text.
-\layout Paragraph*
+\end_layout
+\begin_layout Paragraph*
Mixing Footnotes and Personal Notes
-\layout Standard
+\end_layout
+\begin_layout Standard
Personal Notes always go in footnotes, and should be 5 lines or fewer.
Any larger quotation should be quoted properly, using the rules of standard
English.
- Place quotes in a
-\family sans
+ Place quotes in a
+\family default
+
+\family sans
Quotation
-\family default
+\family default
paragraph environment.
-\layout Paragraph*
+\end_layout
+\begin_layout Paragraph*
Mixing Footnotes and Author's Notes
-\layout Standard
+\end_layout
-Author's Notes should
-\emph on
+\begin_layout Standard
+Author's Notes should
+\emph default
+
+\emph on
never
-\emph default
+\emph default
go in footnotes.
-\layout Paragraph*
+\end_layout
+\begin_layout Paragraph*
Mixing Personal Notes and Author's Notes
-\layout Standard
+\end_layout
+\begin_layout Standard
Forbidden; these two are mutually exclusive.
-\layout Subsubsection
+\end_layout
+\begin_layout Subsubsection
Summary of Use
-\layout Itemize
+\end_layout
+\begin_layout Itemize
Personal Notes:
-\newline
-A
-\emph on
+\newline
+A
+\emph default
+
+\emph on
short
-\emph default
+\emph default
opinion --- yours or another LyX developer's --- about anything.
Anywhere in the manuals you wish to speak for yourself instead the the
LyX Team, use this.
- If you have a long rant, however, quote yourself (see section\SpecialChar ~
+ If you have a long rant, however, quote yourself (see section\InsetSpace ~
-\begin_inset LatexCommand \ref{sec:quote}
-
-\end_inset
+\begin_inset LatexCommand ref
+reference "sec:quote"
+\end_inset
).
-\layout Itemize
+\end_layout
+\begin_layout Itemize
Author's Note:
-\newline
-Use this to describe things in LyX (or the manuals) that may change in the
- future or are somehow incomplete.
+\newline
+Use this to describe things in LyX (or the manuals) that may
+ change in the future or are somehow incomplete.
Author's Notes are supposed to disappear as a manual matures.
-\layout Itemize
+\end_layout
+\begin_layout Itemize
Plain Footnotes:
-\newline
-Used for text fragments that almost fit into the flow of the text\SpecialChar \ldots{}
-but not
- quite.
-\layout Standard
+\newline
+Used for text fragments that almost fit into the flow of
+ the text\SpecialChar \ldots{}
+but not quite.
+\end_layout
+\begin_layout Standard
When using these three mechanisms, in addition to rigorously following their
descriptions, please use them properly.
I listed some additional restrictions previously.
be using any of them.
More specifically, you're trying to use a hammer to drive in a screw.
What you want to say probably needs to go into the main body of the text.
-\layout Subsection
+\end_layout
+\begin_layout Subsection
General Stylistic Guidelines
-\layout Standard
+\end_layout
-Everything in this section is
-\emph on
+\begin_layout Standard
+Everything in this section is
+\emph default
+
+\emph on
mandatory to all documenters
-\emph default
+\emph default
, regardless the language you're writing in.
-\layout Subsubsection
+\end_layout
+\begin_layout Subsubsection
Typography
-\layout Enumerate
+\end_layout
+\begin_layout Enumerate
Use the typography rules outlined in the beginning sections of this document.
-\layout Enumerate
+\end_layout
+\begin_layout Enumerate
Don't, however, mimic the typography of this file.
Yes, the Style Sheet doesn't follow the Style Sheet (grin).
-\layout Enumerate
+\end_layout
+\begin_layout Enumerate
There is some typographic freedom in those rules in earlier sections.
Use that freedom wisely.
Most importanly, never sacrifice the online appearance for the printed
appearance and vice versa.
-\begin_deeper
-\layout Standard
+\end_layout
-An example is in the
-\emph on
+\begin_deeper
+\begin_layout Standard
+An example is in the
+\emph default
+
+\emph on
User's Guide
-\emph default
+\emph default
.
- There is a footnote using the
-\family typewriter
+ There is a footnote using the
+\family default
+
+\family typewriter
multcols
-\family default
- command to divide a long
-\family sans
+\family default
+ command to divide a long
+\family default
+
+\family sans
Itemize
-\family default
+\family default
environment into 3 columns.
It adds some LaTeX commands to the online version, the so-called
\begin_inset Quotes eld
-\end_inset
+\end_inset
Evil Red Text
\begin_inset Quotes erd
-\end_inset
+\end_inset
that some so vehemently oppose.
Without it, however, that footnote takes up over two pages, most of which
is empty space.
This is an example of permitting a little ugliness in the online version
to get the printed version to look right.
-\end_deeper
-\layout Enumerate
+\end_layout
+\end_deeper
+\begin_layout Enumerate
When in doubt, compromise.
-\begin_deeper
-\layout Standard
+\end_layout
+\begin_deeper
+\begin_layout Standard
When in doubt, use good judgement.
-\end_deeper
-\layout Subsubsection
+\end_layout
+\end_deeper
+\begin_layout Subsubsection
Semantics
-\layout Enumerate
+\end_layout
+\begin_layout Enumerate
You are
\begin_inset Quotes eld
-\end_inset
+\end_inset
we
\begin_inset Quotes erd
-\end_inset
+\end_inset
.
-\begin_deeper
-\layout Standard
+\end_layout
+\begin_deeper
+\begin_layout Standard
When you speak, you speak for the entire LyX Team, so use
\begin_inset Quotes eld
-\end_inset
+\end_inset
we
\begin_inset Quotes erd
-\end_inset
+\end_inset
instead of
\begin_inset Quotes eld
-\end_inset
+\end_inset
I
\begin_inset Quotes erd
-\end_inset
+\end_inset
.
-\end_deeper
-\layout Enumerate
+\end_layout
+\end_deeper
+\begin_layout Enumerate
The reader is
\begin_inset Quotes eld
-\end_inset
+\end_inset
you
\begin_inset Quotes erd
-\end_inset
+\end_inset
.
-\begin_deeper
-\layout Standard
+\end_layout
+\begin_deeper
+\begin_layout Standard
Whenever you want to say something to the reader, use
\begin_inset Quotes eld
-\end_inset
+\end_inset
you,
\begin_inset Quotes erd
-\end_inset
+\end_inset
not some contorted construction to avoid being too informal.
-\end_deeper
-\layout Enumerate
+\end_layout
+\end_deeper
+\begin_layout Enumerate
Use the term
\begin_inset Quotes eld
-\end_inset
+\end_inset
mouse
\begin_inset Quotes erd
-\end_inset
+\end_inset
for both the physical pointing object (mouse, joystick, touch pad, track
ball, etc.) and the mouse cursor which the physical object moves about the
screen.
-\layout Enumerate
+\end_layout
+\begin_layout Enumerate
Use the term
\begin_inset Quotes eld
-\end_inset
+\end_inset
cursor
\begin_inset Quotes erd
-\end_inset
+\end_inset
for the little blinking vertical bar that indicates where text can/will
appear next.
-\layout Enumerate
+\end_layout
+\begin_layout Enumerate
When in doubt, compromise.
-\begin_deeper
-\layout Standard
+\end_layout
+\begin_deeper
+\begin_layout Standard
When in doubt, use good judgement.
-\end_deeper
-\layout Subsubsection
+\end_layout
-
-\begin_inset LatexCommand \label{sec:quote}
-
-\end_inset
+\end_deeper
+\begin_layout Subsubsection
+\begin_inset LatexCommand label
+name "sec:quote"
+\end_inset
Quoting Yourself and Others
-\layout Standard
+\end_layout
+\begin_layout Standard
In some cases, you'll have something to say, an opinion of yours.
Since this is your opinion, you're not speaking for the LyX Team.
You have so much to say, in fact, that it won't fit into a Personal Note
or an Author's Note.
In these cases you want to quote yourself.
-\layout Standard
+\end_layout
+\begin_layout Standard
Any time you wish to quote someone, be it yourself or someone else, there
are standard rules one follows.
Every language has its own rules.
You should follow the rules that apply to the language of the document
to which you are contributing.
-\layout Standard
+\end_layout
+\begin_layout Standard
This creates a problem for the primary documentation.
The primary documentation is written in English, yet the contributors come
from many countries.
The quoting rules for English (well, American English, at least) are outlined
- in the following
-\family sans
-Figure\SpecialChar ~
+ in the following
+\family default
+
+\family sans
+Figure\InsetSpace ~
Float
-\family default
+\family default
, for your convenience.
Read them if you need to.
-\layout Standard
-
+\end_layout
+\begin_layout Standard
\begin_inset Float figure
placement htbp
wide false
-collapsed true
-
-\layout Standard
+sideways false
+status collapsed
+\begin_layout Standard
Quoting rules for English:
-\layout Itemize
+\end_layout
-The body of the quote belongs in a
-\family sans
+\begin_layout Itemize
+The body of the quote belongs in a
+\family default
+
+\family sans
Quotation
-\family default
+\family default
environment.
-\layout Itemize
+\end_layout
+\begin_layout Itemize
The sentences prior to the quote should flow logically and smoothly into
the quote.
-\layout Itemize
+\end_layout
+\begin_layout Itemize
The sentences immediately following the quote should continue the flow of
the text.
-\layout Itemize
+\end_layout
-You must,
-\emph on
+\begin_layout Itemize
+You must,
+\emph default
+
+\emph on
must
-\emph default
+\emph default
credit the original author of the quote in the sentences immediately before
or after the quote.
-\layout Itemize
+\end_layout
+\begin_layout Itemize
Crediting the original author of the quote should not, however, disrupt
the flow of the text.
-\layout Itemize
+\end_layout
+\begin_layout Itemize
If you omit text from the beginning of the first sentence in the quote,
the quote must start with the text
\begin_inset Quotes eld
-\end_inset
+\end_inset
[\SpecialChar \ldots{}
]
\begin_inset Quotes erd
-\end_inset
+\end_inset
.
This is an ellipsis in square brackets.
-\layout Itemize
+\end_layout
+\begin_layout Itemize
If you omit text from the end of the last sentence in the quote, the quote
must end with the text
\begin_inset Quotes eld
-\end_inset
+\end_inset
[\SpecialChar \ldots{}
]
\begin_inset Quotes erd
-\end_inset
+\end_inset
followed by the sentence's punctuation mark.
-\layout Itemize
+\end_layout
+\begin_layout Itemize
If you omit any text from the middle of the quote, be it whole sentences
or parts of sentences, replace it with the text
\begin_inset Quotes eld
-\end_inset
+\end_inset
[\SpecialChar \ldots{}
]
\begin_inset Quotes erd
-\end_inset
+\end_inset
.
-\layout Itemize
+\end_layout
+\begin_layout Itemize
The quote must be grammatically correct.
-\begin_deeper
-\layout Itemize
+\end_layout
+\begin_deeper
+\begin_layout Itemize
If the original is wrong, you must correct it.
-\layout Itemize
+\end_layout
+\begin_layout Itemize
If omitting part of the quote
\begin_inset Quotes eld
-\end_inset
+\end_inset
breaks
\begin_inset Quotes erd
-\end_inset
+\end_inset
it, you must correct the problem.
-\layout Itemize
+\end_layout
-For missing words (e.\SpecialChar ~
-g.\SpecialChar ~
+\begin_layout Itemize
+For missing words (e.\InsetSpace ~
+g.\InsetSpace ~
\begin_inset Quotes eld
-\end_inset
+\end_inset
the
\begin_inset Quotes erd
-\end_inset
+\end_inset
goes missing), place the word in square brackets,
\begin_inset Quotes eld
-\end_inset
+\end_inset
[\SpecialChar \ldots{}
]
\begin_inset Quotes erd
-\end_inset
+\end_inset
and insert in the quote where needed.
-\layout Itemize
+\end_layout
+\begin_layout Itemize
For mangled word order, correct the mangled text, following it with the
text
\begin_inset Quotes eld
-\end_inset
+\end_inset
[sic]
\begin_inset Quotes erd
-\end_inset
+\end_inset
.
-\end_deeper
-\layout Itemize
+\end_layout
+\end_deeper
+\begin_layout Itemize
Spelling in the quote must be correct.
Correct any misspelled words and place the text
\begin_inset Quotes eld
-\end_inset
+\end_inset
[sic]
\begin_inset Quotes erd
-\end_inset
+\end_inset
after the corrected word.
-\layout Itemize
+\end_layout
+\begin_layout Itemize
Back-to-back bracket blocks merge together.
Example:
\begin_inset Quotes eld
-\end_inset
+\end_inset
[\SpecialChar \ldots{}
][the]
\begin_inset Quotes erd
-\end_inset
+\end_inset
is wrong.
It should be
\begin_inset Quotes eld
-\end_inset
+\end_inset
[\SpecialChar \ldots{}
the]
\begin_inset Quotes erd
-\end_inset
+\end_inset
.
-\layout Itemize
+\end_layout
+\begin_layout Itemize
If you correct the spelling in 2 or more consecutive words, you can get
away with one
\begin_inset Quotes eld
-\end_inset
+\end_inset
[sic]
\begin_inset Quotes erd
-\end_inset
+\end_inset
after the last mistake.
-\end_inset
+\end_layout
+\end_inset
-\layout Subsubsection
+\end_layout
+
+\begin_layout Subsubsection
Coverage
-\layout Standard
+\end_layout
-When describing a new feature or
-\family typewriter
+\begin_layout Standard
+When describing a new feature or
+\family default
+
+\family typewriter
*.layout
-\family default
+\family default
file, be sure to:
-\layout Enumerate
-
-Be
-\emph on
-clear, concise,
-\emph default
-and
-\emph on
+\end_layout
+
+\begin_layout Enumerate
+Be
+\emph default
+
+\emph on
+clear, concise,
+\emph default
+
+and
+\emph default
+
+\emph on
to the point
-\emph default
+\emph default
.
KISS =
\begin_inset Quotes eld
-\end_inset
+\end_inset
Keep It Short and Sweet
\begin_inset Quotes erd
-\end_inset
+\end_inset
(or,
\begin_inset Quotes eld
-\end_inset
+\end_inset
Keep It Simple, Stupid!
\begin_inset Quotes erd
-\end_inset
+\end_inset
)
-\begin_deeper
-\layout Itemize
+\end_layout
-Do
-\emph on
+\begin_deeper
+\begin_layout Itemize
+Do
+\emph default
+
+\emph on
not
-\emph default
+\emph default
write paragraph after paragraph of verbage.
-\layout Itemize
+\end_layout
+\begin_layout Itemize
Get to the point.
-\layout Itemize
+\end_layout
+\begin_layout Itemize
Take a look at the manual for a commercial word processor --- it's a fine
- example of how
-\series bold
+ example of how
+\series default
+
+\series bold
NOT
-\series default
+\series default
to write documentation.
- It's all pithy, substanceless verbage, and its
-\emph on
+ It's all pithy, substanceless verbage, and its
+\emph default
+
+\emph on
utterly useless!
-\emph default
+\emph default
-\end_deeper
-\layout Enumerate
+\end_layout
+\end_deeper
+\begin_layout Enumerate
Avoid being pedantic like The Plague!
-\layout Enumerate
+\end_layout
+\begin_layout Enumerate
In the same vein, don't write more than you have to.
You're not working in a vacuum --- refer freely to other parts of the manual
(and other parts of other manuals).
Even if that
\begin_inset Quotes eld
-\end_inset
+\end_inset
other part of the manual
\begin_inset Quotes erd
-\end_inset
+\end_inset
is incomplete or empty, refer to it.
Someone will fill it in eventually.
-\layout Enumerate
+\end_layout
+\begin_layout Enumerate
On the other hand, BE THOROUGH!
-\begin_deeper
-\layout Enumerate
+\end_layout
-You are documenting
-\emph on
+\begin_deeper
+\begin_layout Enumerate
+You are documenting
+\emph default
+
+\emph on
features
-\emph default
+\emph default
, not widgets, not how the source code is organized.
-\layout Enumerate
+\end_layout
+\begin_layout Enumerate
Group by feature, not by widget.
-\layout Enumerate
+\end_layout
-Stay on topic --- one
-\family sans
+\begin_layout Enumerate
+Stay on topic --- one
+\family default
+
+\family sans
Section
-\family default
- should cover
-\emph on
+\family default
+ should cover
+\emph default
+
+\emph on
one
-\emph default
+\emph default
feature.
- Use
-\family sans
+ Use
+\family default
+
+\family sans
Subsection
-\family default
+\family default
s and further subdivisions to group things if you're documenting several
- related features in a single
-\family sans
+ related features in a single
+\family default
+
+\family sans
Section
-\family default
+\family default
.
-\layout Enumerate
+\end_layout
+\begin_layout Enumerate
Describe EVERYTHING related to that feature, no matter where it is.
-\begin_deeper
-\layout Enumerate
+\end_layout
+\begin_deeper
+\begin_layout Enumerate
Example: Paragraph Indenting.
Several popups control its behavior.
- You would document
-\emph on
+ You would document
+\emph default
+
+\emph on
all
-\emph default
+\emph default
of this: which popups control it, when you use which setting on which popup
to do which operation, et cetera.
-\layout Enumerate
+\end_layout
+\begin_layout Enumerate
Note from
-\noun on
+\noun on
John Weiss
-\noun default
+\noun default
:
-\newline
+\newline
I've had people only document one popup --- literally.
This added off-topic information and only described half of the feature,
since other menus, popups, and even unbound functions contained additional
stuff.
-\newline
-I got
-\emph on
+\newline
+I got
+\emph default
+
+\emph on
really
-\emph default
- cranky when that happens, because it means
-\emph on
-I
-\emph default
+\emph default
+ cranky when that happens, because it means
+\emph default
+
+\emph on
+I
+\emph default
+
ended up fixing it.
Bad help is worse than no help at all.
-\begin_deeper
-\layout Standard
+\end_layout
+\begin_deeper
+\begin_layout Standard
These remarks still hold true: you'll piss of the DocTeam editor if you
do things wrong, because he'll have to fix your mistakes.
-\end_deeper
-\end_deeper
-\layout Enumerate
+\end_layout
-Remember, there are people who will reference
-\emph on
+\end_deeper
+\end_deeper
+\begin_layout Enumerate
+Remember, there are people who will reference
+\emph default
+
+\emph on
your
-\emph default
+\emph default
section, just as you're referencing someone else's.
You do want what you write to be useful, don't you?
-\end_deeper
-\layout Enumerate
+\end_layout
+\end_deeper
+\begin_layout Enumerate
When in doubt, compromise.
-\begin_deeper
-\layout Standard
+\end_layout
+\begin_deeper
+\begin_layout Standard
When in doubt, use good judgement.
-\end_deeper
-\layout Subsubsection
+\end_layout
-NEVER NEVER
-\emph on
+\end_deeper
+\begin_layout Subsubsection
+NEVER NEVER
+\emph default
+
+\emph on
NEVER EVER
-\emph default
+\emph default
Treat the Reader as if She is Stupid
-\layout Enumerate
+\end_layout
+\begin_layout Enumerate
No dumbing-down.
-\layout Enumerate
+\end_layout
+\begin_layout Enumerate
No talking down to the reader.
-\layout Enumerate
+\end_layout
+\begin_layout Enumerate
The reader is smart enough to know what a mouse is.
-\layout Enumerate
+\end_layout
+\begin_layout Enumerate
The reader is smart enough to know how to use a keyboard, including the
+
+\family default
-\family sans
+\family sans
Shift-
-\family default
-,
-\family sans
+\family default
+,
+\family default
+
+\family sans
Control-
-\family default
-, and
-\family sans
+\family default
+, and
+\family default
+
+\family sans
Meta-
-\family default
+\family default
keys.
(The introduction of most of the manuals takes care of the
\begin_inset Quotes eld
-\end_inset
+\end_inset
-\family sans
+\family sans
Meta-
-\family default
- is the
-\family sans
+\family default
+ is the
+\family default
+
+\family sans
Alt-
-\family default
+\family default
key
\begin_inset Quotes erd
-\end_inset
+\end_inset
issue, so you don't need to.)
-\layout Enumerate
+\end_layout
+\begin_layout Enumerate
The reader is smart enough to know that
\begin_inset Quotes eld
-\end_inset
+\end_inset
at the cursor
\begin_inset Quotes erd
-\end_inset
+\end_inset
means
\begin_inset Quotes eld
-\end_inset
+\end_inset
where the text cursor is sitting right now, in the buffer currently visible.
\begin_inset Quotes erd
-\end_inset
+\end_inset
-\size small
+\size small
(Anything more than the word
\begin_inset Quotes eld
-\end_inset
+\end_inset
cursor
\begin_inset Quotes erd
-\end_inset
+\end_inset
is, IMO, superfluous and wll be deleted .
So, save yourself the typing, save the editor the cutting, and save the
reader the strain of sifting through extra verbage that adds no content.)
-\layout Enumerate
+\end_layout
+\begin_layout Enumerate
Rule of thumb: the reader is not an imbecile.
The reader is merely lost; point them in the right direction, and they
can take it from there.
-\layout Subsection
+\end_layout
+\begin_layout Subsection
Tips for the English Version
-\layout Standard
-
-
-\begin_inset LatexCommand \label{sec:english-only}
+\end_layout
-\end_inset
+\begin_layout Standard
+\begin_inset LatexCommand label
+name "sec:english-only"
+\end_inset
-When contributing to the primary --- i.\SpecialChar ~
-e.\SpecialChar ~
+When contributing to the primary --- i.\InsetSpace ~
+e.\InsetSpace ~
the English language version ---
of the LyX manuals, keep the following in mind.
-\layout Subsubsection
+\end_layout
+\begin_layout Subsubsection
Write as if You're Talking with a Friend.
-\layout Enumerate
+\end_layout
+\begin_layout Enumerate
Think that way when you write.
Play the dialogue in your mind.
-\layout Enumerate
+\end_layout
+\begin_layout Enumerate
Be as informal as you please (without being rude).
-\layout Subsubsection
+\end_layout
+\begin_layout Subsubsection
AVOID the Passive Voice
-\layout Enumerate
+\end_layout
+\begin_layout Enumerate
No:
\begin_inset Quotes eld
-\end_inset
+\end_inset
It is felt that this name best explains the command's purpose.
\begin_inset Quotes erd
-\end_inset
+\end_inset
We know full well who wrote the command:
\begin_inset Quotes eld
-\end_inset
+\end_inset
The LyX Team felt ...
\begin_inset Quotes erd
-\end_inset
+\end_inset
Or, better yet,
\begin_inset Quotes eld
-\end_inset
+\end_inset
We felt that ...
\begin_inset Quotes erd
-\end_inset
+\end_inset
-\layout Enumerate
+\end_layout
+\begin_layout Enumerate
Things don't happen by magic - somebody or something did it.
Only politicians use the passive voice to cover up who did something.
If LyX reformats a paragraph, write,
\begin_inset Quotes eld
-\end_inset
+\end_inset
LyX reformatted the paragraph.
\begin_inset Quotes erd
-\end_inset
+\end_inset
- If
-\family typewriter
+ If
+\family default
+
+\family typewriter
ispell
-\family default
+\family default
makes changes, write,
\begin_inset Quotes eld
-\end_inset
+\end_inset
-\family typewriter
+\family typewriter
ispell
-\family default
+\family default
changes the document.
\begin_inset Quotes erd
-\end_inset
+\end_inset
-\begin_deeper
-\layout Standard
+\end_layout
+\begin_deeper
+\begin_layout Standard
Rule of thumb: any sentence you can express as,
\begin_inset Quotes eld
-\end_inset
+\end_inset
It was done by foo,
\begin_inset Quotes erd
-\end_inset
+\end_inset
you can express as,
\begin_inset Quotes eld
-\end_inset
+\end_inset
Foo did it.
\begin_inset Quotes erd
-\end_inset
+\end_inset
Much nicer.
-\end_deeper
-\layout Enumerate
+\end_layout
+\end_deeper
+\begin_layout Enumerate
I know it's tough.
We all hear way, way too much garbage English on the TV every day in the
passive voice.
It doesn't.
It makes speech baroque, if not outright byzantine.
With a little effort, you can wean yourself off of it.
-\layout Enumerate
+\end_layout
-I
-\emph on
+\begin_layout Enumerate
+I
+\emph default
+
+\emph on
will make you rewrite
-\emph default
+\emph default
anything in the passive voice.
It's awkward and hard to read.
-\layout Enumerate
+\end_layout
+\begin_layout Enumerate
Note to non-Americans:
-\begin_deeper
-\layout Standard
+\end_layout
-Using passive voice is generally considered bad style in the U.\SpecialChar ~
-S.\SpecialChar ~
+\begin_deeper
+\begin_layout Standard
+Using passive voice is generally considered bad style in the U.\InsetSpace ~
+S.\InsetSpace ~
as it is
too easy to obfuscate your words with it.
It also bloats sentences, often unnecessarily.
-\end_deeper
-\layout Subsubsection
+\end_layout
+\end_deeper
+\begin_layout Subsubsection
Short Sentences.
Short Paragraphs.
-\layout Standard
+\end_layout
+\begin_layout Standard
In English, there is a grammatical error known as the
\begin_inset Quotes eld
-\end_inset
+\end_inset
run-on sentence.
\begin_inset Quotes erd
-\end_inset
+\end_inset
The classic example of a run-on sentence is 7 clauses strung together with
the word
\begin_inset Quotes eld
-\end_inset
+\end_inset
and.
\begin_inset Quotes erd
-\end_inset
+\end_inset
There are, however, less obvious run-on sentences, ones using too many
subordinate clauses.
Such sentences may look elegant because they are complex.
However, they are also extremely difficult to read because they are so
complex.
-\layout Standard
+\end_layout
+\begin_layout Standard
In general, stick to short sentences in written English.
Getting rid of passive voice (
\begin_inset Quotes eld
-\end_inset
+\end_inset
\SpecialChar \ldots{}
was done by\SpecialChar \ldots{}
\begin_inset Quotes erd
-\end_inset
+\end_inset
) shortens and simplifies them.
Hacking apart sentences with many dependent clauses is another way to shorten
sentences.
There are ways to do this yet still have a smooth-flowing paragraph.
-\layout Standard
+\end_layout
+\begin_layout Standard
While I'm talking about paragraphs, I'll apply the
\begin_inset Quotes eld
-\end_inset
+\end_inset
shorter is better
\begin_inset Quotes erd
-\end_inset
+\end_inset
motto to them, as well.
At the time I started with the manuals (and this Style Sheet), I didn't
writing manuals.
Our goal is rapid information location and comprehension, not a literary
prize.
-\layout Standard
+\end_layout
+\begin_layout Standard
There is a single exception to the short sentence, short paragraph rule.
Particularly complex ideas may need more
\begin_inset Quotes eld
-\end_inset
+\end_inset
breathing room.
\begin_inset Quotes erd
-\end_inset
+\end_inset
However, you shouldn't encounter such complex ideas often when documenting
LyX.
Try to keep things short, and use your judgement as needed.
-\layout Standard
+\end_layout
+\begin_layout Standard
To reiterate, yet again, something I said before:
-\layout Quote
+\end_layout
+\begin_layout Quote
When in doubt, compromise.
-\layout Quote
+\end_layout
+\begin_layout Quote
When in doubt, use good judgement.
-\layout Standard
+\end_layout
+\begin_layout Standard
Hopefully, you've got the idea (grin).
-\layout Section
+\end_layout
+\begin_layout Section
Translations
-\layout Subsection
+\end_layout
+\begin_layout Subsection
Rules of the Translating Trade
-\layout Standard
+\end_layout
+\begin_layout Standard
While translating anything, there are certain
\begin_inset Quotes eld
-\end_inset
+\end_inset
tools of the trade
\begin_inset Quotes erd
-\end_inset
+\end_inset
you should use.
They will help you greatly.
-\layout Subsubsection
+\end_layout
+\begin_layout Subsubsection
Translate one paragraph at a time.
-\layout Standard
+\end_layout
+\begin_layout Standard
Most people translate word by word.
Clearly, you lose all context if you do that.
A word may have multiple meanings.
You can't tell which unless you look at the rest of the sentence.
-\layout Standard
+\end_layout
+\begin_layout Standard
There is another level to the context issue, however.
Your dictionary may translate multiple English words the same way.
- All those words mean
-\emph on
+ All those words mean
+\emph default
+
+\emph on
roughly
-\emph default
+\emph default
the same thing.
Each one, however, covers a different shade of meaning, a different mood
or intent.
It is often difficult to resolve those shades of meaning in the context
of even one sentence.
A paragraph, however, will provide that context.
-\layout Subsubsection
+\end_layout
+\begin_layout Subsubsection
You will not translate it correctly on the first try.
-\layout Standard
+\end_layout
+\begin_layout Standard
Alright, I admit that you may be able to translate some of the sentences
at first glance.
If you know a language well, you may even understand over half of the text.
Nevertheless, overconfidence can lead you astray.
There will be some sentences, no matter how few, that will simply confound
you.
-\layout Standard
+\end_layout
+\begin_layout Standard
It is generally a good idea to make multiple passes over a paragraph you're
translating.
Even if you translate the entire paragraph on the first pass, make a second
one.
You'll often improve upon your first attempt.
-\layout Subsubsection
+\end_layout
+\begin_layout Subsubsection
When in doubt, write down all of the meanings for a word.
-\layout Standard
+\end_layout
+\begin_layout Standard
You can often translate tricky parts of a text using the context of the
surrounding sentences.
So, if you hit a word or phrase you don't know, translate it more than
Picking the most likely translations, summarize them in one to three words
in place of an
\begin_inset Quotes eld
-\end_inset
+\end_inset
exact
\begin_inset Quotes erd
-\end_inset
+\end_inset
translation.
-\layout Subsubsection
+\end_layout
+\begin_layout Subsubsection
Using context, fix the meanings on the next pass.
-\layout Standard
+\end_layout
+\begin_layout Standard
This is where your multiple translations of a single word become useful.
Using the other sentences you translated, you can now translate that mystery--s
entence without reconsulting your dictionary.
-\layout Subsubsection
+\end_layout
+\begin_layout Subsubsection
Fix the grammar only after you've finished translating the sentence.
-\layout Standard
+\end_layout
+\begin_layout Standard
If there's a mystery phrase in the middle of a sentence, you can't translate
the entire sentence.
Why grammatically rearrange the words you translated already? You may need
Better to wait until you've completely translated the sentence to clean
up its grammar.
That way, you do so only once.
-\layout Subsubsection
+\end_layout
+\begin_layout Subsubsection
If you can't translate it, skip it and come back to it on the next pass.
-\layout Standard
+\end_layout
+\begin_layout Standard
Remember the earlier discussion of context and its immense usefulness? There
is no sin in making multiple passes over a tricky passage.
-\layout Subsubsection
+\end_layout
+\begin_layout Subsubsection
Translate the meaning first.
The rest can wait.
-\layout Standard
+\end_layout
+\begin_layout Standard
The information content of the text under translation is the most important
part.
- This is especially important for a manual, where the information
-\emph on
+ This is especially important for a manual, where the information
+\emph default
+
+\emph on
is the only
-\emph default
+\emph default
important part of the original document.
Lose that, and you lose the very point of performing the translation.
-\layout Subsection
+\end_layout
+\begin_layout Subsection
Tips for the Translators
-\layout Standard
+\end_layout
+\begin_layout Standard
Those of you contributing to a translation of the LyX manuals must follow
a modified set of rules.
- The first few rules are analogous to those in section\SpecialChar ~
-
-\begin_inset LatexCommand \ref{sec:english-only}
+ The first few rules are analogous to those in section\InsetSpace ~
-\end_inset
+\begin_inset LatexCommand ref
+reference "sec:english-only"
+\end_inset
.
There are additional rules and regulations that follow those first few.
-\layout Subsubsection
+\end_layout
+\begin_layout Subsubsection
Write as if you are explaining LyX to a colleague you know well.
-\layout Enumerate
+\end_layout
+\begin_layout Enumerate
Think that way when you write.
Play the dialogue in your mind.
-\layout Enumerate
+\end_layout
+\begin_layout Enumerate
Use a conversational style in your writing.
Pretend you are teaching LyX to a colleague you know well.
-\layout Enumerate
+\end_layout
+\begin_layout Enumerate
Use a style that is polite without being too formal.
If, in your culture, informal language is appropriate to use with a colleague,
use informal speech in the translation of the manual.
-\layout Subsubsection
+\end_layout
+\begin_layout Subsubsection
AVOID Snobby, Academic, Specialized, or
\begin_inset Quotes eld
-\end_inset
+\end_inset
Dead
\begin_inset Quotes erd
-\end_inset
+\end_inset
Writing.
-\layout Standard
+\end_layout
+\begin_layout Standard
In English, the passive voice appears formal, dry, barren.
It also often adds unnecessary complexity.
In other langauges, however, this is not the case.
in everyday conversation.
Nevertheless, your translation of the LyX manuals must avoid
\begin_inset Quotes eld
-\end_inset
+\end_inset
dead
\begin_inset Quotes erd
-\end_inset
+\end_inset
writing.
-\layout Standard
+\end_layout
+\begin_layout Standard
In Germany, there is a magazine known as
\begin_inset Quotes gld
-\end_inset
+\end_inset
Der Spiegel.
\begin_inset Quotes grd
-\end_inset
+\end_inset
The writing in it is so complex, it is extremely difficult for non-native
German speakers to understand.
While sophisticated, the writing style of
\begin_inset Quotes gld
-\end_inset
+\end_inset
Der Spiegel
\begin_inset Quotes grd
-\end_inset
+\end_inset
is not what a German uses in everyday conversation.
Nor is the writing style for a Russian mathematics journal.
Such specialized or overly-sophisticated styles are
\begin_inset Quotes eld
-\end_inset
+\end_inset
dead
\begin_inset Quotes erd
-\end_inset
+\end_inset
in the sense that they are seldom used by normal people in everyday speech.
-\layout Standard
+\end_layout
-We who write the LyX manuals, original or translated, seek to
-\emph on
+\begin_layout Standard
+We who write the LyX manuals, original or translated, seek to
+\emph default
+
+\emph on
inform
-\emph default
+\emph default
.
If we write in a style only a few people use, and use seldomly, we will
fail to inform.
Use a writing style that mirrors everyday speech (without being vulgar,
of course).
-\layout Subsubsection
+\end_layout
+\begin_layout Subsubsection
Keep the Writing Simple.
-\layout Standard
+\end_layout
+\begin_layout Standard
For the English version, I wrote,
\begin_inset Quotes eld
-\end_inset
+\end_inset
Use short sentences and short paragraphs.
\begin_inset Quotes erd
-\end_inset
+\end_inset
What if, however, short sentences and paragraphs are something only children
use in your language? What if, in yet another language, short sentences
imply rudeness? Naturally, you would not want to use them in your translation.
-\layout Standard
+\end_layout
+\begin_layout Standard
Nevertheless, the translations of the LyX manuals should be as clear as
the originals.
So, for our international colleagues, we apply this rule: Keep your sentences
and paragraphs as short as makes sense.
-\layout Standard
+\end_layout
+\begin_layout Standard
Remember: we're translating manuals here, folks.
Our goal is rapid information location and comprehension, not a literary
prize.
Try to keep your writing concise yet smooth-flowing.
And use your judgement as needed:
-\layout Quote
+\end_layout
+\begin_layout Quote
When in doubt, compromise.
-\layout Quote
+\end_layout
+\begin_layout Quote
When in doubt, use good judgement.
-\layout Subsubsection
+\end_layout
+\begin_layout Subsubsection
Translators must follow the Style Sheet, too!
-\layout Standard
+\end_layout
-Everything in this manual ---
-\emph on
-except section\SpecialChar ~
-
-\begin_inset LatexCommand \ref{sec:english-only}
+\begin_layout Standard
+Everything in this manual ---
+\emph default
+
+\emph on
+except section\InsetSpace ~
-\end_inset
+\begin_inset LatexCommand ref
+reference "sec:english-only"
+\end_inset
-\emph default
+\emph default
--- applies to every LyX documenter, no matter what the language.
-\layout Subsubsection
+\end_layout
+\begin_layout Subsubsection
Translators must read the Style Sheet Supplement for their language.
-\layout Standard
+\end_layout
+\begin_layout Standard
For every translation project, there is a Supplement to the Style Sheet.
It will be named:
-\layout Quote
+\end_layout
+\begin_layout Quote
-\family typewriter
+\family typewriter
DocStyle_Supplement_<cn>.lyx
-\layout Standard
+\end_layout
+\begin_layout Standard
\SpecialChar \ldots{}
where
\begin_inset Quotes eld
-\end_inset
+\end_inset
-\family typewriter
+\family typewriter
<cn>
-\family default
+\family default
\begin_inset Quotes erd
-\end_inset
+\end_inset
is your language's two-letter locale code.
The Translation Project Chief for your language wrote this.
If he hasn't, pester him to do so! <
-\emph on
+\emph on
wink!
-\emph default
+\emph default
>
-\layout Subsubsection
+\end_layout
+\begin_layout Subsubsection
The English versions of the manuals are not Sacred Text.
-\layout Standard
+\end_layout
+\begin_layout Standard
You do not need to translate everything word for word.
In fact, you shouldn't.
Keep to the spirit of the originals, not the letter.
- Be as creative as you want, as long as you
-\emph on
+ Be as creative as you want, as long as you
+\emph default
+
+\emph on
accurately
-\emph default
- and
-\emph on
+\emph default
+ and
+\emph default
+
+\emph on
completely
-\emph default
+\emph default
convey all of the information contained in the English versions.
-\layout Subsubsection
+\end_layout
+\begin_layout Subsubsection
Any information in the LyX manuals must also be in the translations.
-\layout Standard
-
+\end_layout
-\begin_inset LatexCommand \label{sec:accuracy}
-
-\end_inset
+\begin_layout Standard
+\begin_inset LatexCommand label
+name "sec:accuracy"
+\end_inset
This falls under translating the orignals accurately and completely.
-\layout Itemize
+\end_layout
+\begin_layout Itemize
Omitting any feature description is
-\emph on
- stricly forbidden
-\emph default
+\emph default
+
+\emph on
+stricly forbidden
+\emph default
.
-\layout Itemize
+\end_layout
-Misrepresenting or misdescribing any LyX feature or operation
-\emph on
+\begin_layout Itemize
+Misrepresenting or misdescribing any LyX feature or operation
+\emph default
+
+\emph on
must be avoided
-\emph default
+\emph default
.
-\layout Itemize
+\end_layout
-The translation
-\emph on
+\begin_layout Itemize
+The translation
+\emph default
+
+\emph on
cannot
-\emph default
+\emph default
outpace the original.
-\newline
-If no one has documented new feature in the primary LyX manuals (i.\SpecialChar ~
-e.\SpecialChar ~
-the English
- versions), do not do so in the translations.
+\newline
+If no one has documented new feature in the primary
+ LyX manuals (i.\InsetSpace ~
+e.\InsetSpace ~
+the English versions), do not do so in the translations.
If you're really looking for something to do, either:
-\begin_deeper
-\layout Itemize
+\end_layout
+\begin_deeper
+\begin_layout Itemize
\SpecialChar \ldots{}
focus on translating something you haven't yet,
-\newline
+\newline
OR
-\layout Itemize
+\end_layout
+\begin_layout Itemize
\SpecialChar \ldots{}
update or repair the primary manual.
-\layout Standard
+\end_layout
+\begin_layout Standard
If you cannot or do not want to do one of the above, then take a break.
Relax.
Wait for the main manuals to catch up before translating anything else.
-\end_deeper
-\layout Subsubsection
+\end_layout
+\end_deeper
+\begin_layout Subsubsection
What you cannot translate, you may omit (usually).
-\layout Standard
+\end_layout
+\begin_layout Standard
Prepositions, idioms, metaphors, slang, Oh My! There's a jungle of potentially
untranslatable text you may face.
Happily, none of these untranslatables are essential to the original text\SpecialChar \ldots{}
If you can't translate a phrase or two, try omitting them.
If the rest of the paragraph still makes sense, then don't worry about
the omission.
-\layout Standard
+\end_layout
+\begin_layout Standard
There may be special cases where omitting part of a sentence or paragraph
- violates rule\SpecialChar ~
-
-\begin_inset LatexCommand \ref{sec:accuracy}
+ violates rule\InsetSpace ~
-\end_inset
+\begin_inset LatexCommand ref
+reference "sec:accuracy"
+\end_inset
.
- In those cases,
-\emph on
+ In those cases,
+\emph default
+
+\emph on
do not omit!
-\emph default
+\emph default
You must try and translate those tricky spots.
-\layout Subsubsection
+\end_layout
+\begin_layout Subsubsection
Translators may add their own fluff to the information content.
-\layout Standard
+\end_layout
+\begin_layout Standard
After you do strip away all of the idioms, metaphors, slang, humor, and
other
\begin_inset Quotes eld
-\end_inset
+\end_inset
expendable text,
\begin_inset Quotes erd
-\end_inset
+\end_inset
you may find that your translated manual is dull and dry.
Why not add your own fluff? Add text that makes the manual a pleasure to
It may take the form of humor, or metaphors, or sayings.
Whatever you add, it should be
\begin_inset Quotes eld
-\end_inset
+\end_inset
in context.
\begin_inset Quotes erd
-\end_inset
+\end_inset
It should not clash with the explanation of LyX features and functions.
-\layout Subsection
+\end_layout
+\begin_layout Subsection
For Translation Project Chiefs
-\layout Subsubsection
+\end_layout
+\begin_layout Subsubsection
The First Is In Charge
-\layout Standard
+\end_layout
+\begin_layout Standard
If you were the first person to start translating the manuals, you're the
LyXDoc Translation Project Chief for your language.
- If you are the
-\emph on
+ If you are the
+\emph default
+
+\emph on
only
-\emph default
+\emph default
person translating the LyXDocs, that automatically makes you the Translation
Project Chief.
-\layout Standard
+\end_layout
+\begin_layout Standard
Amongst other things, that means that you must read this section and perform
the tasks described here.
-\layout Standard
+\end_layout
-If you are a member of a LyX Documentation Translation Team, but
-\emph on
+\begin_layout Standard
+If you are a member of a LyX Documentation Translation Team, but
+\emph default
+
+\emph on
are not
-\emph default
+\emph default
its Chief, you may stop reading.
The remainder of this section will be of no interest to you.
If you came to the Style Sheet from the Supplement for your language, you
may return to it.
-\layout Standard
+\end_layout
+\begin_layout Standard
If you have not read the Style Sheet Supplement for your language, you should
read it now.
-\layout Subsubsection
+\end_layout
+\begin_layout Subsubsection
Read the Style Sheet
-\layout Standard
+\end_layout
+\begin_layout Standard
No documenter is excused from following the Style Sheet, not even a Translation
Project Chief.
-\layout Standard
+\end_layout
-Actually, it is
-\emph on
+\begin_layout Standard
+Actually, it is
+\emph default
+
+\emph on
especially
-\emph default
+\emph default
important that the Translation Project Chiefs read the Style Sheet.
-\layout Subsubsection
+\end_layout
+\begin_layout Subsubsection
Make your translators read the Style Sheet
-\layout Standard
+\end_layout
+\begin_layout Standard
No documenter is excused from following the Style Sheet.
-\layout Standard
+\end_layout
-Since your translation team is translating, they know
-\emph on
+\begin_layout Standard
+Since your translation team is translating, they know
+\emph default
+
+\emph on
some
-\emph default
+\emph default
English, at least.
Therefore, they should be able to read the Style Sheet.
-\layout Subsubsection
+\end_layout
+\begin_layout Subsubsection
Provide a
\begin_inset Quotes eld
-\end_inset
+\end_inset
Supplement
\begin_inset Quotes erd
-\end_inset
+\end_inset
to this Style Sheet
-\layout Standard
+\end_layout
+\begin_layout Standard
There are parts of this Style Sheet that are English-specific.
I have tried to provide a general, language-independent description of
certain details in this section.
Unfortunately, that general description doesn't cover the specifics of
each language.
-\layout Standard
+\end_layout
+\begin_layout Standard
That's where you, as head of a LyXDoc Translation Team, come in.
-\layout Standard
+\end_layout
-Every Translation Team Chief is
-\emph on
+\begin_layout Standard
+Every Translation Team Chief is
+\emph default
+
+\emph on
required
-\emph default
+\emph default
to write a Supplement to the official Documentation Style Sheet, with specifics
issues affecting your language.
(You are, after all, the LyX Team expert on your native tongue.) Follow
these guidelines when writing the Supplement:
-\layout Enumerate
+\end_layout
+\begin_layout Enumerate
Name the file:
-\newline
+\newline
-\family typewriter
+\family typewriter
DocStyle_Supplement_<cn>.lyx
-\family default
+\family default
-\newline
+\newline
\SpecialChar \ldots{}
where
\begin_inset Quotes eld
-\end_inset
+\end_inset
-\family typewriter
+\family typewriter
<cn>
-\family default
+\family default
\begin_inset Quotes erd
-\end_inset
+\end_inset
is the two-letter code for your language.
This is the same two-letter code that is part of the filenames for the
translated manuals.
Example:
\begin_inset Quotes eld
-\end_inset
+\end_inset
-\family typewriter
+\family typewriter
_de
-\family default
+\family default
\begin_inset Quotes erd
-\end_inset
+\end_inset
for German,
\begin_inset Quotes eld
-\end_inset
+\end_inset
-\family typewriter
+\family typewriter
_sv
-\family default
+\family default
\begin_inset Quotes erd
-\end_inset
+\end_inset
for Swedish, and
\begin_inset Quotes eld
-\end_inset
+\end_inset
-\family typewriter
+\family typewriter
_ru
-\family default
+\family default
\begin_inset Quotes erd
-\end_inset
+\end_inset
for Russian.
-\layout Enumerate
+\end_layout
+\begin_layout Enumerate
Do not worry about where the file goes.
The CVS maintainers will locate all documentation and Style Sheet Supplements
in an appropriate place.
-\layout Enumerate
+\end_layout
+\begin_layout Enumerate
Document Properties:
-\begin_deeper
-\layout Itemize
+\end_layout
+\begin_deeper
+\begin_layout Itemize
For consistency, use the same document class and other document properties
as the Style Sheet.
\begin_inset Foot
-collapsed true
-
-\layout Standard
+status collapsed
-Specifically, check the settings in the
-\family sans
+\begin_layout Standard
+Specifically, check the settings in the
+\family default
+
+\family sans
Document Layout
-\family default
+\family default
popup.
Use those in your Supplement.
-\end_inset
+\end_layout
+
+\end_inset
-\layout Itemize
+\end_layout
+\begin_layout Itemize
Exceptions: Use margins, indentation/paragraph separation, language, and
encoding appropriate for your language.
-\end_deeper
-\layout Enumerate
+\end_layout
+\end_deeper
+\begin_layout Enumerate
The title of the Supplement:
-\begin_deeper
-\layout Itemize
+\end_layout
+\begin_deeper
+\begin_layout Itemize
The title will use the
\begin_inset Quotes eld
-\end_inset
+\end_inset
-\family sans
+\family sans
Title
-\family default
+\family default
\begin_inset Quotes erd
-\end_inset
+\end_inset
paragraph environment.
In your native tongue, the title will read:
-\begin_deeper
-\layout Standard
+\end_layout
+\begin_deeper
+\begin_layout Standard
-\family typewriter
+\family typewriter
Documentation Project Style Sheet:
-\newline
+\newline
Supplement for the <foo> Translation Project
-\layout Standard
+\end_layout
+\begin_layout Standard
(Replace
\begin_inset Quotes eld
-\end_inset
+\end_inset
-\family typewriter
+\family typewriter
<foo>
-\family default
+\family default
\begin_inset Quotes erd
-\end_inset
+\end_inset
with the name of your language.)
-\end_deeper
-\layout Itemize
+\end_layout
+\end_deeper
+\begin_layout Itemize
If, in your language,
\begin_inset Quotes eld
-\end_inset
+\end_inset
supplement
\begin_inset Quotes erd
-\end_inset
+\end_inset
translates into
\begin_inset Quotes eld
-\end_inset
+\end_inset
appendix,
\begin_inset Quotes erd
-\end_inset
+\end_inset
we have a problem.
In English,
\begin_inset Quotes eld
-\end_inset
+\end_inset
Supplement
\begin_inset Quotes erd
-\end_inset
+\end_inset
and
\begin_inset Quotes eld
-\end_inset
+\end_inset
Appendix
\begin_inset Quotes erd
-\end_inset
+\end_inset
have somewhat different meanings.
An appendix is an extra part of a document.
A supplement is an extra document.
-\begin_deeper
-\layout Standard
+\end_layout
+\begin_deeper
+\begin_layout Standard
Choose a replacement word accordingly.
Whatever you choose to replace
\begin_inset Quotes eld
-\end_inset
+\end_inset
Supplement,
\begin_inset Quotes erd
-\end_inset
+\end_inset
it must not have the same translation as the word
\begin_inset Quotes eld
-\end_inset
+\end_inset
appendix.
\begin_inset Quotes erd
-\end_inset
+\end_inset
-\end_deeper
-\end_deeper
-\layout Enumerate
+\end_layout
+\end_deeper
+\end_deeper
+\begin_layout Enumerate
Below the title, in the
\begin_inset Quotes eld
-\end_inset
+\end_inset
-\family sans
+\family sans
Author
-\family default
+\family default
\begin_inset Quotes erd
-\end_inset
+\end_inset
paragraph environment, place your name.
-\begin_deeper
-\layout Standard
+\end_layout
+\begin_deeper
+\begin_layout Standard
There will be no abstract.
-\end_deeper
-\layout Enumerate
+\end_layout
-The first
-\family sans
+\end_deeper
+\begin_layout Enumerate
+The first
+\family default
+
+\family sans
Section
-\family default
+\family default
of the Supplement:
-\begin_deeper
-\layout Standard
+\end_layout
+\begin_deeper
+\begin_layout Standard
The first thing you will do is strongly yet politely encourage the reader
to stop reading the
\begin_inset Quotes eld
-\end_inset
+\end_inset
Supplement
\begin_inset Quotes erd
-\end_inset
+\end_inset
and go read the Style Sheet.
The reader should not return to the
\begin_inset Quotes eld
-\end_inset
+\end_inset
Supplement
\begin_inset Quotes erd
-\end_inset
+\end_inset
- until he has read
-\emph on
+ until he has read
+\emph default
+
+\emph on
and
-\emph default
+\emph default
understood the Style Sheet proper.
-\end_deeper
-\layout Subsubsection
+\end_layout
+\end_deeper
+\begin_layout Subsubsection
Keep the Supplement Succinct
-\layout Standard
+\end_layout
+\begin_layout Standard
This Style Sheet is already very detailed.
DocTeam members all have a lot to read.
We don't want to place an extra burden on translators.
Therefore, keep the Supplement as short as you can without losing information.
-\layout Subsubsection
+\end_layout
+\begin_layout Subsubsection
Font Issues
-\layout Standard
+\end_layout
-The second
-\family sans
+\begin_layout Standard
+The second
+\family default
+
+\family sans
Section
-\family default
+\family default
will be about font issues\SpecialChar \ldots{}
if you have any.
Not all Translation Project Chiefs will need to deal with this issue.
The fonts:
-\layout Itemize
+\end_layout
+\begin_layout Itemize
-\family typewriter
+\family typewriter
Typewriter
-\layout Itemize
+\end_layout
+\begin_layout Itemize
-\family sans
+\family sans
Sans Serif
-\layout Itemize
+\end_layout
+\begin_layout Itemize
Roman
-\newline
+\newline
-\emph on
+\emph on
Emphasized (actually Italics)
-\layout Itemize
+\end_layout
+\begin_layout Itemize
-\bar under
+\bar under
Underlined
-\layout Itemize
+\end_layout
+\begin_layout Itemize
-\series bold
+\series bold
Bold
-\layout Itemize
+\end_layout
+\begin_layout Itemize
-\noun on
+\noun on
Noun (actually Small Caps)
-\layout Standard
+\end_layout
+\begin_layout Standard
\SpecialChar \ldots{}
certainly exist for all languages that use the Roman alphabet.
Do they exist, however, for Greek? How about Cyrillic? These different
fonts almost certainly do not exist for Devanagri, Chinese, Korean, Japanese,
Hebrew, Arabic, and other scripts.
-\layout Standard
+\end_layout
+\begin_layout Standard
There will be some languages for which following the font-scheme specified
in this Style Sheet may not be possible.
If you are the Translation Project Chief for such a language, you have
extra work.
-\layout Standard
+\end_layout
+\begin_layout Standard
In the font section of the Supplement, you will provide a new typographic
style, designed specifically for your writing system.
For consistency, the title of this section in every Supplement should translate
into English as
\begin_inset Quotes eld
-\end_inset
+\end_inset
fonts.
\begin_inset Quotes erd
-\end_inset
+\end_inset
Before adding anything to this section, however, determine what this new
typographic style will look like.
Stick to the font specifications in this Style Sheet as best you can, whenever
you can.
When you cannot, use the following suggestions:
-\layout Itemize
+\end_layout
+\begin_layout Itemize
Guidelines for
\begin_inset Quotes eld
-\end_inset
+\end_inset
translating
\begin_inset Quotes erd
-\end_inset
+\end_inset
fonts,
-\newline
+\newline
or
-\newline
+\newline
What to do when a font doesn't exist:
-\begin_deeper
-\layout List
-\labelwidthstring MMMMMMMM
+\end_layout
+\begin_deeper
+\begin_layout List
+\labelwidthstring MMMMMMMM
Roman Use the font that typesetters in your language use for printing books,
manuals, etc.
This will typically be the default font LyX (and LaTeX) uses in your language.
-\layout List
-\labelwidthstring MMMMMMMM
+\end_layout
+\begin_layout List
+\labelwidthstring MMMMMMMM
-\noun on
-Noun\SpecialChar ~
+\noun on
+Noun\InsetSpace ~
Style
-\noun default
+\noun default
This is for people's names.
If there is special font for names in your alphabet/writing system, use
it in place of this.
Otherwise, write names in the default font, typeset according to the rules
of your language.
-\layout List
-\labelwidthstring MMMMMMMM
+\end_layout
+\begin_layout List
+\labelwidthstring MMMMMMMM
-\emph on
+\emph on
Emphasized
-\emph default
+\emph default
Use the font with which your language normally emphasizes text.
-\begin_deeper
-\layout Standard
+\end_layout
-Use a font that is different from your language's equivalent of
-\series bold
+\begin_deeper
+\begin_layout Standard
+Use a font that is different from your language's equivalent of
+\series default
+
+\series bold
Boldface
-\series default
+\series default
.
- In other words, your
-\family sans
+ In other words, your
+\family default
+
+\family sans
Section
-\family default
-,
-\family sans
+\family default
+,
+\family default
+
+\family sans
Subsection
-\family default
- and similar headers will be in one typeface, perhaps
-\series bold
+\family default
+ and similar headers will be in one typeface, perhaps
+\series default
+
+\series bold
Boldface
-\series default
+\series default
, perhaps not.
- Whatever that font is, avoid using it for
-\emph on
+ Whatever that font is, avoid using it for
+\emph default
+
+\emph on
Emphasized
-\emph default
+\emph default
if at all possible!
-\end_deeper
-\layout List
-\labelwidthstring MMMMMMMM
+\end_layout
+\end_deeper
+\begin_layout List
+\labelwidthstring MMMMMMMM
-\family typewriter
+\family typewriter
Typewriter
-\family default
+\family default
Pick up a computer program manual written in your language.
It will use a special typeface for filenames, for command names, program
names, and such.
- Use that same font in place of
-\family typewriter
+ Use that same font in place of
+\family default
+
+\family typewriter
Typewriter
-\family default
+\family default
.
-\layout List
-\labelwidthstring MMMMMMMM
+\end_layout
+\begin_layout List
+\labelwidthstring MMMMMMMM
-\family sans
-Sans\SpecialChar ~
+\family sans
+Sans\InsetSpace ~
Serif
-\family default
+\family default
Pick any other font that is different from the ones you're using in place
- of
-\emph on
+ of
+\emph default
+
+\emph on
Emphasized
-\emph default
-,
-\series bold
+\emph default
+,
+\series default
+
+\series bold
Boldface
-\series default
-, and
-\family typewriter
+\series default
+, and
+\family default
+
+\family typewriter
Typewriter
-\family default
+\family default
.
If you're unlucky, and your language's writing system doesn't have enough
- fonts, use the same font you picked to replace
-\family typewriter
+ fonts, use the same font you picked to replace
+\family default
+
+\family typewriter
Typewriter
-\family default
+\family default
.
Only do this, however, if your alphabet/writing system has very few fonts
to pick from.
-\layout List
-\labelwidthstring MMMMMMMM
+\end_layout
+\begin_layout List
+\labelwidthstring MMMMMMMM
-\family sans
-\bar under
+\family sans
+\bar under
U
-\bar default
-nderlined\SpecialChar ~
-Sans\SpecialChar ~
+\bar default
+nderlined\InsetSpace ~
+Sans\InsetSpace ~
Serif
-\family default
+\family default
Don't worry about this one.
-\begin_deeper
-\layout Standard
+\end_layout
+\begin_deeper
+\begin_layout Standard
If you use some special font on-screen to highlight the accelerator keys
for menus, buttons, and other widgets, you might want to mimic that in
the translations.
It is not required, however.
Therefore, if you can't mimic this typographic convention in your native
writing system, don't.
-\end_deeper
-\end_deeper
-\layout Standard
+\end_layout
+\end_deeper
+\end_deeper
+\begin_layout Standard
Note that you may also want to describe fonts that your Translation Team
- should
-\emph on
+ should
+\emph default
+
+\emph on
never
-\emph default
+\emph default
use.
For example, no contributer to the English/European versions may ever use
+
+\series default
-\series bold
+\series bold
Boldface
-\series default
+\series default
, as this is used for section-headings.
Since there are enough other fonts, we who use the Roman alphabet and its
- variants can afford to omit
-\series bold
+ variants can afford to omit
+\series default
+
+\series bold
Boldface
-\series default
+\series default
.
-\layout Standard
+\end_layout
+\begin_layout Standard
Once you have determined which fonts in your native writing system will
replace one or more of the above, propose it to the LyX Developer's Mailing
List.
also okay.
Go ahead and describe the typographic standard you created in the Supplement.
-\layout Standard
+\end_layout
+\begin_layout Standard
Remember: stick to the font specifications in this Style Sheet as best you
can, whenever you can.
-\layout Subsubsection
+\end_layout
-Quoting Style and the
-\family sans
+\begin_layout Subsubsection
+Quoting Style and the
+\family default
+
+\family sans
Quote
-\family default
+\family default
vs.
+
+\family default
-\family sans
+\family sans
Quotation
-\family default
+\family default
Issue
-\layout Standard
+\end_layout
+\begin_layout Standard
The next section of the Supplement will cover the issue of quoting.
Give it an appropriate title.
-\layout Standard
+\end_layout
+\begin_layout Standard
One of the first things you should do in that section is resolve the following
issue:
-\layout Itemize
+\end_layout
-Decide whether
-\family sans
+\begin_layout Itemize
+Decide whether
+\family default
+
+\family sans
Quote
-\family default
- or
-\family sans
+\family default
+ or
+\family default
+
+\family sans
Quotation
-\family default
+\family default
is the correct paragraph environment for your language.
-\layout Itemize
+\end_layout
+\begin_layout Itemize
In the Supplement, specify which one to use.
-\layout Standard
+\end_layout
+\begin_layout Standard
English has its own typography and style for quoting others.
- The Style Sheet describes that typography in section\SpecialChar ~
-
-\begin_inset LatexCommand \ref{sec:quote}
+ The Style Sheet describes that typography in section\InsetSpace ~
-\end_inset
+\begin_inset LatexCommand ref
+reference "sec:quote"
+\end_inset
.
Your language also has a specific typography and style for quotations.
Describe that style in this section of the Supplement, too.
Naturally, you do not need to go overboard.
- Section\SpecialChar ~
+ Section\InsetSpace ~
-\begin_inset LatexCommand \ref{sec:quote}
-
-\end_inset
+\begin_inset LatexCommand ref
+reference "sec:quote"
+\end_inset
of this Style Sheet is overly detailed for a good reason.
Authors of the primary LyX manuals are not necessarily native English speakers.
speakers of your language.
Therefore, discuss proper quoting style of your native tongue to an appropriate
level of detail.
-\layout Subsubsection
+\end_layout
+\begin_layout Subsubsection
Translations of Style Sheet Terminology
-\layout Standard
+\end_layout
+\begin_layout Standard
In the Supplement, you must provide a standard translation of certain key
phrases for the members of your Translation Team.
Place this in a section following the one about quotations.
-\layout Standard
+\end_layout
+\begin_layout Standard
In particular, standardize the translations of the phrases:
-\layout Itemize
+\end_layout
+\begin_layout Itemize
Note from
-\noun on
+\noun on
<foo>:
-\layout Itemize
+\end_layout
+\begin_layout Itemize
-\emph on
+\emph on
Author's Note:
-\layout Standard
+\end_layout
-Do
-\emph on
+\begin_layout Standard
+Do
+\emph default
+
+\emph on
not
-\emph default
+\emph default
change the typography of the
\begin_inset Quotes eld
-\end_inset
+\end_inset
Personal Note
\begin_inset Quotes erd
-\end_inset
+\end_inset
and
\begin_inset Quotes eld
-\end_inset
+\end_inset
Author's Note,
\begin_inset Quotes erd
-\end_inset
+\end_inset
however.
Only provide a translation for the opening phrases.
Insist that the members of your Translation Team use these two tools correctly.
-\layout Standard
+\end_layout
+\begin_layout Standard
While we are discussing proper use of the
\begin_inset Quotes eld
-\end_inset
+\end_inset
Personal Note
\begin_inset Quotes erd
-\end_inset
+\end_inset
and
\begin_inset Quotes eld
-\end_inset
+\end_inset
Author's Note
\begin_inset Quotes erd
-\end_inset
+\end_inset
in translations, let's talk about a related problem.
The
\begin_inset Quotes eld
-\end_inset
+\end_inset
Author's Note
\begin_inset Quotes erd
-\end_inset
+\end_inset
is meant to be a note from the author of a manual to the reader.
- In the case of a translation, however, the translator is
-\emph on
+ In the case of a translation, however, the translator is
+\emph default
+
+\emph on
not
-\emph default
+\emph default
the author! How then should a translator translate an
\begin_inset Quotes eld
-\end_inset
+\end_inset
Author's Note?
\begin_inset Quotes erd
-\end_inset
+\end_inset
-\layout Standard
+\end_layout
+\begin_layout Standard
You, as Translation Project Chief, must decide.
You can forbid translation of pre-existing
\begin_inset Quotes eld
-\end_inset
+\end_inset
Author's Notes,
\begin_inset Quotes erd
-\end_inset
+\end_inset
omitting them entirely instead.
You could tell your translators to read any
\begin_inset Quotes eld
-\end_inset
+\end_inset
Author's Note
\begin_inset Quotes erd
-\end_inset
+\end_inset
they may encounter, understand it, then write their own
\begin_inset Quotes eld
-\end_inset
+\end_inset
Author's Note
\begin_inset Quotes erd
-\end_inset
+\end_inset
about the situation, not as a translation but as a personal opinion.
You may decide on some other policy.
-\layout Standard
+\end_layout
-Whatever you decide, codify your policy in its own
-\family sans
+\begin_layout Standard
+Whatever you decide, codify your policy in its own
+\family default
+
+\family sans
Section
-\family default
- or
-\family sans
+\family default
+ or
+\family default
+
+\family sans
Subsection
-\family default
+\family default
or whatever.
Place it near the section where you translated
\begin_inset Quotes eld
-\end_inset
+\end_inset
Personal Note
\begin_inset Quotes erd
-\end_inset
+\end_inset
and
\begin_inset Quotes eld
-\end_inset
+\end_inset
Author's Note
\begin_inset Quotes erd
-\end_inset
+\end_inset
.
-\layout Subsubsection
+\end_layout
+\begin_layout Subsubsection
Lost in Translation
-\layout Standard
+\end_layout
-After describing all of the previous issues, create a new
-\family sans
+\begin_layout Standard
+After describing all of the previous issues, create a new
+\family default
+
+\family sans
Section
-\family default
+\family default
.
Give it the name,
\begin_inset Quotes eld
-\end_inset
+\end_inset
Lost in Translation,
\begin_inset Quotes erd
-\end_inset
+\end_inset
or something similar.
-\layout Standard
+\end_layout
+\begin_layout Standard
In this section you will discuss any common English metaphors, humor, connotatio
n, or other difficult to translate text.
Try to balance brevity and completeness.
- Devote a
-\family sans
+ Devote a
+\family default
+
+\family sans
Subsection
-\family default
- --- or even
-\family sans
+\family default
+ --- or even
+\family default
+
+\family sans
Subsubsection
-\family default
+\family default
s --- to each specific issue.
-\layout Subsubsection
+\end_layout
+\begin_layout Subsubsection
\SpecialChar \ldots{}
\begin_inset Quotes eld
-\end_inset
+\end_inset
Yes, we mean now.
\begin_inset Quotes erd
-\end_inset
+\end_inset
\SpecialChar \ldots{}
-\layout Standard
+\end_layout
+\begin_layout Standard
Throughout the manuals, the DocTeam has used the following sentences:
-\layout Quote
+\end_layout
+\begin_layout Quote
If you haven't read the <
-\emph on
+\emph on
Foo
-\emph default
+\emph default
> manual, go read it.
Yes, we mean now.
-\layout Standard
+\end_layout
+\begin_layout Standard
This sentence will be tricky to translate, since it contains non-translatable
connotations.
Therefore, create a
-\family sans
- Subsection
-\family default
+\family default
+
+\family sans
+Subsection
+\family default
for this issue in your
\begin_inset Quotes eld
-\end_inset
+\end_inset
Lost in Translation
\begin_inset Quotes erd
-\end_inset
+\end_inset
section.
Present the
\begin_inset Quotes eld
-\end_inset
+\end_inset
\SpecialChar \ldots{}
Yes, we mean now\SpecialChar \ldots{}
\begin_inset Quotes erd
-\end_inset
+\end_inset
sentences, then present a translation, along with any explanation you feel
necessary.
-\layout Standard
+\end_layout
+\begin_layout Standard
Here's what those two sentences, sitting alone in their own paragraph, mean:
-\layout Standard
+\end_layout
+\begin_layout Standard
The first sentence uses the English conditional followed by an imperative.
We, as the LyX team, are commanding the reader to go back to another manual.
- For example, the
-\emph on
+ For example, the
+\emph default
+
+\emph on
Intro
-\emph default
+\emph default
manual is a prerequisite for all of the other manuals.
The conditional clause preceeding the command means,
\begin_inset Quotes eld
-\end_inset
+\end_inset
You do not need to perform this command twice.
\begin_inset Quotes erd
-\end_inset
+\end_inset
-\layout Standard
+\end_layout
+\begin_layout Standard
The second sentence adds force to the command.
Culturally, the imperative tense of a verb in English is not necessarily
forceful.
The way we wrote that command,
\begin_inset Quotes eld
-\end_inset
+\end_inset
go read it,
\begin_inset Quotes erd
-\end_inset
+\end_inset
is firm, yet polite.
The reader may choose to ignore it.
By following with,
\begin_inset Quotes eld
-\end_inset
+\end_inset
Yes, we mean now,
\begin_inset Quotes erd
-\end_inset
+\end_inset
we imply two things.
First, we add some
\begin_inset Quotes eld
-\end_inset
+\end_inset
resistive force
\begin_inset Quotes erd
-\end_inset
+\end_inset
to the command.
That second sentence reinforces the command, making it a bit harder to
The brief pragraph, and its sudden end, add still further subtle reinforcement
to the command,
\begin_inset Quotes eld
-\end_inset
+\end_inset
go do the required reading before using this manual.
\begin_inset Quotes erd
-\end_inset
+\end_inset
-\layout Standard
+\end_layout
+\begin_layout Standard
Note that all of this commanding and reinforcing is nevertheless in a polite
format.
Furthermore, it is in a subtle form.
We are commanding the reader to do something, but in an indirect fashion.
This way, the reader does not feel like we are bullying him.
-\layout Subsubsection
+\end_layout
+\begin_layout Subsubsection
Firm Convincing vs.
Rudeness
-\layout Standard
+\end_layout
+\begin_layout Standard
In the same part of the Supplement that you place the
\begin_inset Quotes eld
-\end_inset
+\end_inset
\SpecialChar \ldots{}
Yes, we mean now\SpecialChar \ldots{}
\begin_inset Quotes erd
-\end_inset
+\end_inset
translation, discuss the English version's use of
\begin_inset Quotes eld
-\end_inset
+\end_inset
firm convincing.
\begin_inset Quotes erd
-\end_inset
+\end_inset
-\layout Standard
+\end_layout
+\begin_layout Standard
You see, here in America, we often say that everything is permitted unless
explicitly banned by law.
As a result, manuals for computer software are frequently ignored and the
software subsequently blamed for not being
\begin_inset Quotes eld
-\end_inset
+\end_inset
user-friendly.
\begin_inset Quotes erd
-\end_inset
+\end_inset
This is where the use of
\begin_inset Quotes eld
-\end_inset
+\end_inset
firm convincing
\begin_inset Quotes erd
-\end_inset
+\end_inset
comes in.
-\layout Standard
+\end_layout
+\begin_layout Standard
We who wrote the manuals added sentences insisting that the reader not ignore
certain parts of the documentation.
We wrote in a manner that was polite, yet firmly asserted that the user
was misusing the software if he did not read the manual correctly.
We did not, however, want to sound threatening, coercive, or bullying.
-\layout Standard
+\end_layout
+\begin_layout Standard
In your culture, cajoling the reader into using the manuals correctly may
not be necessary.
It may, in fact, be outright rude.
The translation may sound weird, or rude, or hostile.
Therefore, you and your translation team will face many sentences that
you cannot translate.
-\layout Standard
+\end_layout
+\begin_layout Standard
You, the Translation Project Chief, must discuss this issue.
Try and find parts of the original manuals where some friendly but firm
convincing does not translate properly.
Use these cases as the basis for examples of the problem.
- Be sure to then offer a solution (i.\SpecialChar ~
-e.\SpecialChar ~
+ Be sure to then offer a solution (i.\InsetSpace ~
+e.\InsetSpace ~
how you want such sentences translated.)
If stumped, ask for help on the LyX Developer's List.
-\layout Subsubsection
+\end_layout
+\begin_layout Subsubsection
Anything Else?
-\layout Standard
+\end_layout
+\begin_layout Standard
You can add more sections to the Supplement if you need to discuss other
issues.
There may be policies or guidelines that you want to set for your Translation
Team.
- Be careful, however! Keep the Supplement
-\emph on
+ Be careful, however! Keep the Supplement
+\emph default
+
+\emph on
short
-\emph default
+\emph default
.
-\the_end
+\end_layout
+
+\end_body
+\end_document
projects / lyx.git / blobdiff