Attached below is the latest version of the Documentation Style
Sheet. It now contains a new section designed to aid translators.
It also contains a guide for the Translation Project Chiefs. It is in
a semi-complete state; expect regular updates during the coming week.
The founder/head of every Translation Project must read the new Style
Sheet. The founder/head of every Translation Project must provide an
Addendum to the Style Sheet, in his native tongue. Each Addendum will
codify certain important style specifications that I was unable to
detail in the Style Sheet itself.
--
John Weiss
#This file was created by <candide> Sun Apr 18 21:25:04 1999
#LyX 1.0 (C) 1995-1999 Matthias Ettrich and the LyX Team
\lyxformat 2.15
\textclass article
\language default
\inputencoding latin1
\fontscheme default
\graphics dvips
\paperfontsize 12
\spacing single
\papersize letterpaper
\paperpackage a4
\use_geometry 0
\use_amsmath 0
\paperorientation portrait
\secnumdepth 3
\tocdepth 3
\paragraph_separation indent
\defskip medskip
\quotes_language english
\quotes_times 2
\papercolumns 1
\papersides 1
\paperpagestyle plain
\layout Title
Documentation Project Style Sheet
\layout Author
by John Weiss
\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
all documentation writers should follow.
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
The Style Sheet for LyX documentation (hereafter known as the Style Sheet)
applies to
\emph on
all
\emph default
forms of LyX documenation, regardless of language.
There is a section for translators in the Style Sheet, towards the end.
\emph on
Read the entire Style Sheet!
\emph default
Even if you are a translator, I assume you know enough English to comprehend
this document.
\layout Section
Preliminaries
\layout Subsection
Version
\layout Standard
All documenters and translators should be using version 1.0.1 or later as
of April 1, 1999.
\layout Subsection
Never Translate the Style Sheet
\layout Standard
This Style Sheet has only one copy, and one version: the one you are reading
presently.
\emph on
Never
\emph default
translate it.
\layout Standard
If you are a translator, read section
\protected_separator
\begin_inset LatexCommand \ref{sec:translations}
\end_inset
.
\layout Section
Fonts
\layout Standard
Since this is the easiest section, I'll start here.
\layout Standard
This is how you should fontify text in the manuals:
\layout List
\labelwidthstring MMMMMMMM
\emph on
Emphasized
\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
Do not overemphasize your text.
\end_deeper
\layout List
\labelwidthstring MMMMMMMM
\family typewriter
Typewriter
\family default
program names, file names,
\family typewriter
man
\family default
-page names, LaTeX code, LaTeX commands, LaTeX package names, and LyX code
and functions
\layout List
\labelwidthstring MMMMMMMM
\family sans
Sans
\protected_separator
Serif
\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
special terms
\begin_inset Quotes erd
\end_inset
\layout List
\labelwidthstring MMMMMMMM
\noun on
Noun
\protected_separator
Style
\noun default
people's names
\layout List
\labelwidthstring MMMMMMMM
\family sans
\bar under
U
\bar default
nderlined
\protected_separator
Sans
\protected_separator
Serif
\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
\bar under
WARNING!
\bar default
--- When you do this, make sure you
\emph on
only
\emph default
shut off the underlining.
Too many people send in things that look like:
\newline
\family sans
\bar under
T
\family default
\bar default
his
\newline
\SpecialChar \ldots{}
i.
\protected_separator
e.
\protected_separator
they not only shut off underlining, they turned off sans-serif, too!
\emph on
Don't do that!
\emph default
Make sure the entire word is still in
\family sans
Sans-Serif
\family default
after you shut off the underlining.
\end_deeper
\layout List
\labelwidthstring MMMMMMMM
\series bold
Bold
\series default
Unused.
\begin_deeper
\layout Standard
If you want to emphasize any text, use
\emph on
Emphasized
\emph default
.
LaTeX will put many things boldface on its own, such as
\family sans
Section
\family default
s, certain parts of equations, et cetera.
\layout Standard
Repeat: do not use boldface.
\end_deeper
\layout Standard
Here are some examples:
\layout Enumerate
The function
\family typewriter
math-mode
\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
Typewriter
\family default
.
\layout Enumerate
However,
\family sans
\bar under
M
\bar default
ath
\protected_separator
mode
\family default
is a menu item in the
\family sans
\bar under
M
\bar default
ath
\family default
menu, so it appears in
\family sans
Sans
\protected_separator
Serif
\family default
.
Notice the use of
\family sans
\bar under
U
\bar default
nderlined
\protected_separator
Sans
\protected_separator
Serif
\family default
for the accelerator keys.
\layout Enumerate
Consider the following excerpt from the introduction of one of the manuals:
\begin_deeper
\layout Quotation
\family sans
Return
\family default
and
\family sans
Enter
\family default
both refer to the same key.
Some keyboards label the
\family sans
Return
\family default
key as
\begin_inset Quotes eld
\end_inset
Return,
\begin_inset Quotes erd
\end_inset
others as
\begin_inset Quotes eld
\end_inset
Enter,
\begin_inset Quotes erd
\end_inset
still others have two keys.
LyX treats all of them as the same key, so we'll use
\family sans
Return
\family default
and
\family sans
Enter
\family default
interchangeably.
\layout Standard
Notice that the key name,
\family sans
Return
\family default
, is in
\family sans
Sans
\protected_separator
Serif
\family default
, but
\emph on
only
\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
Take the following command:
\begin_deeper
\layout Standard
\family typewriter
lpr -P
\family default
\emph on
printername
\layout Standard
Notice that the argument to the
\family typewriter
-P
\family default
option is in
\emph on
Roman Italics
\emph default
(i.e.
emphasized).
This is a case where you don't use
\family typewriter
Typewriter
\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
\family typewriter
lpr -Pduaneps
\family default
\begin_inset Quotes erd
\end_inset
, you'd leave it in
\family typewriter
Typewriter
\family default
.
\end_deeper
\layout Enumerate
Any LaTeX commands and code, and any
\emph on
unsupported
\emph default
LaTeX package names get set in
\family typewriter
Typewriter
\family default
.
For example,
\begin_inset Quotes eld
\end_inset
\family typewriter
multicol
\family default
\begin_inset Quotes erd
\end_inset
is the name of an unsupported LaTeX package, but
\begin_inset Quotes eld
\end_inset
\family sans
book
\family default
\begin_inset Quotes erd
\end_inset
is a supported LaTeX class.
\layout Section
Special Typography
\layout Standard
Do the following:
\layout Description
Multi-word
\protected_separator
names Use a
\family sans
Protected
\protected_separator
Blank
\family default
between the words for menu and widget names.
E.
\protected_separator
g.:
\family sans
Save
\protected_separator
As
\family default
, not
\family sans
Save As
\family default
.
\begin_deeper
\layout Standard
This holds for things in
\family typewriter
Typewriter
\family default
as well as
\family sans
Sans
\protected_separator
Serif
\family default
, with one caveat.
If you have a long code example, one that can't simply be inlined and put
in
\family typewriter
Typewriter
\family default
, put that in a
\family sans
LyX
\protected_separator
Code
\family default
environment.
\layout Standard
I want the
\family sans
Protected
\protected_separator
Blank
\family default
so that the name doesn't get split between two lines, which is visually
disruptive.
If something with a
\family sans
Protected
\protected_separator
Blank
\family default
is near the end of a line and overflows the margin, use a
\family typewriter
\backslash
sloppypar
\family default
in that parargraph (consult a LaTeX book for more about
\begin_inset Quotes eld
\end_inset
\family typewriter
\backslash
sloppypar
\family default
\begin_inset Quotes erd
\end_inset
) or manually add a hypenation point.
\end_deeper
\layout Description
Special
\protected_separator
Terms These are things like the following:
\begin_deeper
\layout Itemize
\family sans
HFill
\family default
\layout Itemize
\family sans
VFill
\family default
\layout Itemize
\family sans
Table
\protected_separator
Float
\layout Itemize
\family sans
Figure
\protected_separator
Float
\begin_deeper
\layout Standard
Use
\family sans
Sans
\protected_separator
Serif
\family default
font and, in the case of
\family sans
HFill
\family default
and
\family sans
VFill
\family default
, capitalize the first two letters.
\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
\protected_separator
Serif
\family default
for them.
\end_deeper
\end_deeper
\layout Description
Terminology Note the following:
\layout Itemize
PostScript® is a registered trademark of Adobe Corp.
\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
postscript®,
\begin_inset Quotes erd
\end_inset
or
\begin_inset Quotes eld
\end_inset
Postscript®
\begin_inset Quotes erd
\end_inset
but
\begin_inset Quotes eld
\end_inset
PostScript®
\begin_inset Quotes erd
\end_inset
- both of them capitalized, in the default font (i.
\protected_separator
.e.
\protected_separator
Roman).
If you must, cut and paste it from here.
\begin_deeper
\layout Standard
I am going to say this again:
\layout Standard
\added_space_top 0.37cm \added_space_bottom 0.51cm \align center
\size larger
\emph on
You must put the ® after PostScript® or we'll get sued!
\layout Standard
I mean it! American companies like to sue anything that moves.
If LyX gets in trouble because
\emph on
you
\emph default
forgot the ®, I will come after you with a running chainsaw.
Got it?
\end_deeper
\layout Itemize
It's a
\bar under
popup
\bar default
;
\begin_inset Quotes eld
\end_inset
widget
\begin_inset Quotes erd
\end_inset
and
\begin_inset Quotes eld
\end_inset
dialog box
\begin_inset Quotes erd
\end_inset
are programmer terms, so don't use them.
\layout Itemize
The word
\begin_inset Quotes eld
\end_inset
popup
\begin_inset Quotes erd
\end_inset
should be in Roman.
There should be no
\family sans
Protected
\protected_separator
Blank
\family default
between the popup's name and the word
\begin_inset Quotes eld
\end_inset
popup.
\begin_inset Quotes erd
\end_inset
Example:
\begin_inset Quotes eld
\end_inset
\SpecialChar \ldots{}
\family sans
Paragraph
\protected_separator
Layout
\family default
popup\SpecialChar \ldots{}
\begin_inset Quotes erd
\end_inset
.
Anything else is
\emph on
wrong.
\layout Itemize
The thing below the menu and above the editing window is the
\bar under
toolbar
\bar default
.
\begin_deeper
\layout Standard
As for the terms
\begin_inset Quotes eld
\end_inset
popup
\begin_inset Quotes erd
\end_inset
and
\begin_inset Quotes eld
\end_inset
toolbar
\begin_inset Quotes erd
\end_inset
, if at some point I (or a future editor) need to change those,
\emph on
I'll
\emph default
take care of that.
That's the editor's job, after all.
I want all of you, however, to use those terms.
It will make any future switch much, much easier for the either me or my
successor(s).
\end_deeper
\layout Description
Menu
\protected_separator
Items When quick-referencing an item in a menu, use the menu separator:
\begin_inset Quotes eld
\end_inset
\SpecialChar \menuseparator
\begin_inset Quotes erd
\end_inset
.
Example:
\family sans
File\SpecialChar \menuseparator
Save
\family default
.
Notice that there are
\emph on
no spaces
\emph default
around the
\begin_inset Quotes eld
\end_inset
\SpecialChar \menuseparator
\begin_inset Quotes erd
\end_inset
and that it's in
\family sans
Sans
\protected_separator
Serif
\family default
, just like the menu and item names.
\begin_deeper
\layout Enumerate
The reason why I want no spaces around the
\begin_inset Quotes eld
\end_inset
\SpecialChar \menuseparator
\begin_inset Quotes erd
\end_inset
is to prevent LyX from splitting terms across lines.
The same goes for using
\family sans
Protected
\protected_separator
Blank
\family default
s between multi-word terms.
The split would be visually disruptive.
\layout Enumerate
A
\begin_inset Quotes eld
\end_inset
\SpecialChar \menuseparator
\begin_inset Quotes erd
\end_inset
goes between menu names and item names
\emph on
only
\emph default
.
(Yes, submenus are okay, too).
\layout Enumerate
\emph on
NEVER
\emph default
put
\begin_inset Quotes eld
\end_inset
\SpecialChar \menuseparator
\begin_inset Quotes erd
\end_inset
between menu items and popup names.
Example:
\begin_inset Quotes eld
\end_inset
\family sans
\bar under
L
\bar default
ayout\SpecialChar \menuseparator
P
\bar under
a
\bar default
per\SpecialChar \menuseparator
Paper
\protected_separator
Popup
\family default
\begin_inset Quotes erd
\end_inset
\emph on
IS STRICTLY FORBIDDEN!
\emph default
\begin_deeper
\layout Standard
Use
\begin_inset Quotes eld
\end_inset
\SpecialChar \ldots{}
the
\family sans
Paper
\family default
popup (opened via
\family sans
\bar under
L
\bar default
ayout\SpecialChar \menuseparator
P
\bar under
a
\bar default
per
\family default
)\SpecialChar \ldots{}
\begin_inset Quotes erd
\end_inset
or something similar.
If you mentioned how to open the popup in an earlier sentence, someplace
else in the paragraph, you needn't do it repeatedly.
\end_deeper
\layout Enumerate
\emph on
NEVER
\emph default
put
\begin_inset Quotes eld
\end_inset
\SpecialChar \menuseparator
\begin_inset Quotes erd
\end_inset
between popup names and any popup widget.
Example:
\begin_inset Quotes eld
\end_inset
\family sans
Paper
\protected_separator
Popup\SpecialChar \menuseparator
P
\bar under
o
\bar default
rtrait
\family default
\begin_inset Quotes erd
\end_inset
\emph on
IS STRICTLY FORBIDDEN!
\begin_deeper
\layout Standard
Use
\begin_inset Quotes eld
\end_inset
\SpecialChar \ldots{}
the
\family sans
P
\bar under
o
\bar default
rtrait
\family default
button on the
\family sans
Paper
\family default
popup\SpecialChar \ldots{}
\begin_inset Quotes erd
\end_inset
or something similar.
If it's clear where the button is, you don't need to keep repeating the
popup's name.
\end_deeper
\layout Enumerate
\emph on
NEVER
\emph default
put
\begin_inset Quotes eld
\end_inset
\SpecialChar \menuseparator
\begin_inset Quotes erd
\end_inset
between menu items and any popup widget.
Example:
\begin_inset Quotes eld
\end_inset
\family sans
\bar under
L
\bar default
ayout\SpecialChar \menuseparator
P
\bar under
a
\bar default
per\SpecialChar \menuseparator
P
\bar under
o
\bar default
rtrait
\family default
\begin_inset Quotes erd
\end_inset
\emph on
IS STRICTLY FORBIDDEN!
\begin_deeper
\layout Standard
If you really, really need to name a widget, the popup its on, and the menu
item used to open the popup, then write it out:
\begin_inset Quotes eld
\end_inset
\SpecialChar \ldots{}
the
\family sans
P
\bar under
o
\bar default
rtrait
\family default
button (on the
\family sans
Paper
\family default
popup, opened using
\family sans
\bar under
L
\bar default
ayout\SpecialChar \menuseparator
P
\bar under
a
\bar default
per
\family default
)\SpecialChar \ldots{}
\begin_inset Quotes erd
\end_inset
\end_deeper
\end_deeper
\layout Description
Note
\protected_separator
Boxes LyX has a feature for adding comments to a popup that appear only
within the LyX GUI.
Here's one:
\begin_inset Info These should NEVER appear in the manuals.
\end_inset
.
You will see nothing in a printout of the Style Sheet.
Therefore, they have no place in the manuals.
Period.
If you have a parenthetical comment you want to make, the reader should
see it too.
Use an Author's Note (see section
\begin_inset LatexCommand \ref{sec:author-notes}
\end_inset
) in place of the Note-Boxes (or whatever they're called).
\layout Description
\begin_inset Quotes eld
\end_inset
(\SpecialChar \ldots{}
)
\begin_inset Quotes erd
\end_inset
,
\protected_separator
\begin_inset Quotes eld
\end_inset
[\SpecialChar \ldots{}
]
\begin_inset Quotes erd
\end_inset
\protected_separator
and
\protected_separator
\begin_inset Quotes eld
\end_inset
{\SpecialChar \ldots{}
}
\begin_inset Quotes erd
\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
(\SpecialChar \ldots{}
)
\begin_inset Quotes erd
\end_inset
, around any aside, remark, or parenthetical expression.
The bracket,
\begin_inset Quotes eld
\end_inset
[\SpecialChar \ldots{}
]
\begin_inset Quotes erd
\end_inset
, is used only within quotations (see section
\protected_separator
\begin_inset LatexCommand \ref{sec:quote}
\end_inset
).
The brace,
\begin_inset Quotes eld
\end_inset
{\SpecialChar \ldots{}
}
\begin_inset Quotes erd
\end_inset
, is never used.
Therefore never use
\begin_inset Quotes eld
\end_inset
[\SpecialChar \ldots{}
]
\begin_inset Quotes erd
\end_inset
or
\begin_inset Quotes eld
\end_inset
{\SpecialChar \ldots{}
}
\begin_inset Quotes erd
\end_inset
unless otherwise specified by this Style Sheet.
\layout Section
Keys
\layout Standard
The canonical keyboard contains these keys:
\layout Itemize
\family sans
C-
\family default
or
\family sans
Control-
\family default
\layout Itemize
\family sans
S-
\family default
or
\family sans
Shift-
\family default
\layout Itemize
\family sans
M-
\family default
or
\family sans
Meta-
\family default
\begin_deeper
\layout Standard
Self-explanatory.
Be lazy and
\emph on
use the abbreviations
\emph default
whenever possible.
\end_deeper
\layout Itemize
\family sans
F1 F2 F3 F4 F5 F6 F7 F8 F9 F10 F11 F12
\begin_deeper
\layout Standard
The function keys.
Most modern keyboards have all 12.
\end_deeper
\layout Itemize
\family sans
Esc
\family default
\begin_deeper
\layout Standard
The
\begin_inset Quotes eld
\end_inset
Escape key.
\begin_inset Quotes erd
\end_inset
\end_deeper
\layout Itemize
\family sans
Insert
\family default
\family sans
Delete
\family default
\family sans
Home
\family default
\family sans
End
\family default
\family sans
PageUp
\family default
\family sans
PageDown
\begin_deeper
\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
\family sans
Left Right Up Down
\begin_deeper
\layout Standard
The four standard motion keys.
There is no need to put the word
\begin_inset Quotes eld
\end_inset
arrow
\begin_inset Quotes erd
\end_inset
anywhere, since that's obvious.
\begin_float footnote
\end_deeper
\layout Standard
Same goes for
\begin_inset Quotes eld
\end_inset
cursor key
\begin_inset Quotes erd
\end_inset
.
Even the word
\begin_inset Quotes eld
\end_inset
key
\begin_inset Quotes erd
\end_inset
after one of these may be redundant in certain situations.
\end_float
\layout Itemize
\family sans
Return
\family default
and
\family sans
Enter
\family default
\begin_deeper
\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
Return
\family default
over
\family sans
Enter
\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
You do not need to explain everywhere what the
\family sans
Meta
\family default
key is or where the
\family sans
Left
\family default
key is, et cetera.
The user isn't stupid.
Also, someone will document anything that isn't clear (e.
\protected_separator
g.
\protected_separator
the
\family sans
Meta
\family default
vs.
\family sans
Alt
\family default
problem) someplace in the introduction.
No need for you to repeat someone else's work.
\layout Standard
LyX does not support kyboards missing any of the keys described above, with
one exception.
LyX can support a keyboard missing
\family sans
F11
\family default
and
\family sans
F12
\family default
.
There is a keyboard accelerator for
\family sans
F10
\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
Mice
\layout Standard
The word
\begin_inset Quotes eld
\end_inset
mouse
\begin_inset Quotes erd
\end_inset
and any description of the 3 mice buttons have no special handling.
Don't typeset them in any other font than the default, which is Roman.
Exception: you're writing an Author's Note (see section
\begin_inset LatexCommand \ref{sec:author-notes}
\end_inset
) and you need to mention something about the mouse.
Since the rest of the note is in
\emph on
Emphasized
\emph default
, your description of
\begin_inset Quotes eld
\end_inset
middle mouse button
\begin_inset Quotes erd
\end_inset
should be emphasized, as well.
There are a couple of other cases like this one; use your judgement.
\layout Standard
There are only 3 mouse buttons.
The use of them and of the mouse itself is obvious.
There are few nonstandard things we do with the mouse.
Therefore, there's no need to make the word
\begin_inset Quotes eld
\end_inset
mouse
\begin_inset Quotes erd
\end_inset
or
\begin_inset Quotes eld
\end_inset
mouse button
\begin_inset Quotes erd
\end_inset
stand out.
\layout Section
Cross-References and Labels
\layout Standard
Use the following labelling conventions:
\layout List
\labelwidthstring 00.00.0000
sec:xxx Use this for
\family sans
Section
\family default
s as well as
\family sans
Chapter
\family default
s,
\family sans
Subsection
\family default
s,
\family sans
Subsubsection
\family default
s, etc.
\layout List
\labelwidthstring 00.00.0000
eqn:xxx Use this for Equations, should you need to create any.
\layout List
\labelwidthstring 00.00.0000
tbl:xxxx Use this for tables inside of a table float.
\layout List
\labelwidthstring 00.00.0000
fig:xxx Use this for figures inside of figure floats.
\layout Standard
Additionally, you should put the label at one of two locations:
\layout Enumerate
The
\emph on
beginning of the paragraph
\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
If there is no paragraph after a section heading, put it at the
\emph on
end of the last line.
\emph default
\begin_deeper
\layout Standard
Example: You have a
\family sans
Section
\family default
which is immediately followed by a
\family sans
Subsection
\family default
heading.
This is a case where you need to put the label at the end of the
\family sans
Section
\family default
heading.
I know it looks ugly; not much we can do about that, though.
\end_deeper
\layout Section
Content --- What Goes Where
\layout Standard
This is
\emph on
very
\emph default
important, so PAY ATTENTION!
\layout Standard
I do not want
\family typewriter
Tutorial.lyx
\family default
,
\family typewriter
Reference.lyx
\family default
, and
\family typewriter
UserGuide.lyx
\family default
to all repeat the same dumbed-down drivel, like the manuals for certain
commercial wordprocessors do.
That's useless.
It's a waste of our time, too.
I want the manuals to dovetail together, to interface with one another.
In principle, we use
\family typewriter
Reference.lyx
\family default
as a base and build the others on it.
\layout Standard
You see, in the 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
\family typewriter
Main.lyx
\family default
.
They tried to explain what their new feature did, but then needed to explain
how to bind keys to it, how to use it, provide examples,
\layout Quote
...and on
\layout Quote
...and on
\layout Quote
...and on.
\layout Standard
The result was a totally bloated, totally unnavigable
\family typewriter
Main.lyx
\family default
.
I wanted to change, which is why I ended up as editor of the DocTeam.
In that time, I started a major reworking, which included the writing of
\family typewriter
UserGuide.lyx
\family default
, over half of which is my own work.
I don't want all that work to be for nothing.
I don't want the docs to fall back into a mess.
\layout Standard
With that in mind, I have some instructions for how to keep things organized:
\layout List
\labelwidthstring 00.00.0000
\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
\family typewriter
UserGuide.lyx
\family default
This file is complete.
Any changes should be for updates
\emph on
only
\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
\family typewriter
Extended.lyx
\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
article
\begin_inset Quotes erd
\end_inset
from the author of the feature.
Also, anyone who writes a
\family typewriter
.layout
\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
Note, however, that you are
\emph on
not
\emph default
excused from following this Style Sheet just because the sections of
\family typewriter
Extended.lyx
\family default
are in the form of a journal article.
\end_deeper
\layout List
\labelwidthstring 00.00.0000
\family typewriter
Tutorial.lyx
\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
\family typewriter
Customization.lyx
\family default
It's a mess.
Complete disaster! (
\emph on
sob
\emph default
!)
\newline
Someday, a complete description of how to write new
\family typewriter
.layout
\family default
files will be in here.
And a description of the new
\family typewriter
.lyxrc
\family default
format.
And a description of how to tailor LyX for use with languages other than
English, or how to use LyX in a multi-lingual setting.
And how to customize your keyboard bindings.
Plenty of stuff to do!
\layout List
\labelwidthstring 00.00.0000
\family typewriter
Reference.lyx
\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
Reference Manual
\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!
\layout Section
Writing Style: The Primary Manuals
\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
Language
\layout Standard
All contributions to the
\emph on
primary
\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
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
it's so.
We've had some discussions and misunderstandings on the Developers' List
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
Nota Bene: by
\emph on
primary
\emph default
documentation, I exclude the translations.
Right now, we don't have enough people to cover the manuals in one language,
let alone more than one.
Subsequently, the tranlsations tend to be just that --- translations of
the English 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
for more info.
\layout Subsection
General Stylistic Guidelines
\layout Standard
Everything in this section is
\emph on
mandatory to all documenters
\emph default
, regardless the language you're writing in.
\layout Subsubsection
Typography
\layout Enumerate
Use the typography rules outlined in the beginning sections of this document.
\layout Enumerate
Don't, however, mimic the typography of this file.
Yes, the Style Sheet doesn't follow the Style Sheet (grin).
\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
An example is in the
\emph on
User's Guide
\emph default
.
There is a footnote using the
\family typewriter
multcols
\family default
command to divide a long
\family sans
Itemize
\family default
environment into 3 columns.
It adds some LaTeX commands to the online version, the so-called
\begin_inset Quotes eld
\end_inset
Evil Red Text
\begin_inset Quotes erd
\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.
\layout Standard
The old menu separator,
\begin_inset Quotes eld
\end_inset
->
\begin_inset Quotes erd
\end_inset
, was another example.
The characters
\begin_inset Quotes eld
\end_inset
->
\begin_inset Quotes erd
\end_inset
didn't look all that great in printed versions.
Online, however, it was a reasonable approximation of an arrow regardless
of screen font.
This is a case where the printed version took a slight appearance hit for
the benefit of the online version.
\begin_float footnote
\end_deeper
\layout Standard
Note that we have simce replaced the
\begin_inset Quotes eld
\end_inset
->
\begin_inset Quotes erd
\end_inset
characters with the true menu separator,
\begin_inset Quotes eld
\end_inset
\SpecialChar \menuseparator
\begin_inset Quotes erd
\end_inset
.
\end_float
\layout Enumerate
When in doubt, compromise.
\begin_deeper
\layout Standard
When in doubt, use good judgement.
\end_deeper
\layout Subsubsection
Semantics
\layout Enumerate
You are
\begin_inset Quotes eld
\end_inset
we
\begin_inset Quotes erd
\end_inset
.
\begin_deeper
\layout Standard
When you speak, you speak for the entire LyX Team, so use
\begin_inset Quotes eld
\end_inset
we
\begin_inset Quotes erd
\end_inset
instead of
\begin_inset Quotes eld
\end_inset
I
\begin_inset Quotes erd
\end_inset
.
\end_deeper
\layout Enumerate
The reader is
\begin_inset Quotes eld
\end_inset
you
\begin_inset Quotes erd
\end_inset
.
\begin_deeper
\layout Standard
Whenever you want to say something to the reader, use
\begin_inset Quotes eld
\end_inset
you,
\begin_inset Quotes erd
\end_inset
not some contorted construction to avoid being too informal.
\end_deeper
\layout Enumerate
Use the term
\begin_inset Quotes eld
\end_inset
mouse
\begin_inset Quotes erd
\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
Use the term
\begin_inset Quotes eld
\end_inset
cursor
\begin_inset Quotes erd
\end_inset
for the little blinking vertical bar that indicates where text can/will
appear next.
\layout Enumerate
When in doubt, compromise.
\begin_deeper
\layout Standard
When in doubt, use good judgement.
\end_deeper
\layout Subsubsection
Commentary from the Author (i.
\protected_separator
e.: You)
\layout Standard
\begin_inset LatexCommand \label{sec:author-notes}
\end_inset
I want to make it easy for everyone when it comes to documenting things.
Some features are incomplete.
Some you might not know everything about.
Sometimes, you may want to comminucate something to me or the reader or
other DocTeam members.
Sometimes, you may want to
\begin_inset Quotes eld
\end_inset
speak for yourself;
\begin_inset Quotes erd
\end_inset
you want to say something that is your personal opinion and using
\begin_inset Quotes eld
\end_inset
we
\begin_inset Quotes erd
\end_inset
would be inappropriate.
\layout Standard
For occasions like those, I've designed two mechanisms:
\layout Description
Personal
\protected_separator
Notes: These are footnotes.
They begin with the following:
\begin_deeper
\layout Standard
\begin_inset Quotes eld
\end_inset
Note from
\noun on
Name of Person
\noun default
:
\begin_inset Quotes erd
\end_inset
\layout Standard
\SpecialChar \ldots{}
using the
\noun on
Noun Style
\noun default
for the person's name and without the quotes.
The rest of the footnote is the actual comment.
\layout Standard
Use these when you need to quote a comment by someone (usually yourself),
and need to identify that person.
\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.
That means putting the quoted text in a
\family sans
Quotation
\family default
paragraph environment, without any leading
\begin_inset Quotes eld
\end_inset
Note from
\noun on
Name of Person
\noun default
:
\begin_inset Quotes erd
\end_inset
.
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
Quotation
\family default
.
\end_deeper
\layout Description
Author's
\protected_separator
Notes: These go in the body of the text, in brackets,
\begin_inset Quotes eld
\end_inset
[]
\begin_inset Quotes erd
\end_inset
, not any other form of parentheses.
The bracket are in the default character style, but the note itself is
emphasized.
Begin with the words,
\begin_inset Quotes eld
\end_inset
\emph on
Author's Note:
\emph default
\begin_inset Quotes erd
\end_inset
and end with
\begin_inset Quotes eld
\end_inset
---
\begin_inset Quotes erd
\end_inset
followed by your initials.
Here's an example: [
\emph on
Author's Note: This is an example note.
---jw
\emph default
].
\begin_deeper
\layout Standard
The form of the Author's Note, by the way, isn't a suggestion or request.
It is
\emph on
mandatory
\emph default
.
All Author's Notes must begin with this text, verbatim:
\begin_inset Quotes eld
\end_inset
[
\emph on
Author's Note:
\emph default
\begin_inset Quotes erd
\end_inset
.
Abbreviations to
\begin_inset Quotes eld
\end_inset
AN
\begin_inset Quotes erd
\end_inset
are or any other variant are forbidden.
The Author's Note must end with an
\family typewriter
em
\family default
-dash, which is 3
\begin_inset Quotes eld
\end_inset
-
\begin_inset Quotes erd
\end_inset
characters:
\begin_inset Quotes eld
\end_inset
---
\begin_inset Quotes erd
\end_inset
.
Do not use 2 or 1
\begin_inset Quotes eld
\end_inset
-
\begin_inset Quotes erd
\end_inset
; you must use 3.
\layout Standard
You should use these for the following purposes:
\layout Itemize
You need to contradict something you just wrote because the feature isn't
quite ready yet, but you want to document what it will do.
\layout Itemize
You need to leave a note for yourself.
\layout Itemize
You need to leave a note for the editor or the other DocTeam members.
\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
Author's Notes are inherently transient, and should disapear as a manual
matures.
\end_deeper
\layout Description
Footnotes: 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.
\begin_deeper
\layout Paragraph*
Mixing Footnotes and Personal Notes
\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
Quotation
\family default
paragraph environment.
\layout Paragraph*
Mixing Footnotes and Author's Notes
\layout Standard
Author's Notes should never go in footnotes.
Or, I'd like that to be the case.
I need to look at the docs yet and come to a decision on this.
\layout Paragraph*
Mixing Personal Notes and Author's Notes
\layout Standard
Forbidden; these two are mutually exclusive.
\layout Standard
When using these three mechanisms, in addition to rigorously following their
descriptions, please use them properly.
I have listed some additional restrictions above.
Some of you may balk at these restrictions.
Nevertheless, there is a reason for them: if you have an overwhemling desire
to mix or modify footnotes, Personal Notes, and Author's Notes, you shouldn't
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.
\end_deeper
\layout Paragraph*
Summary of Use:
\layout Itemize
Personal Notes:
\newline
A
\emph on
short
\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
\protected_separator
\begin_inset LatexCommand \ref{sec:quote}
\end_inset
].
\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.
Author's Notes are supposed to disappear as a manual matures.
\layout Itemize
Plain Footnotes:
\newline
Used for text fragments that almost fit into the flow of the text\SpecialChar \ldots{}
but not
quite.
\layout Subsubsection
\begin_inset LatexCommand \label{sec:quote}
\end_inset
Quoting Yourself and Others
\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
Any time you wish to quote someone, be it yourself or someone else, there
are standard rules one follows:
\layout Itemize
The body of the quote belongs in a
\family sans
Quotation
\family default
environment.
\layout Itemize
The sentences prior to the quote should flow logically and smoothly into
the quote.
\layout Itemize
The sentences immediately following the quote should continue the flow of
the text.
\layout Itemize
You must,
\emph on
must
\emph default
credit the original author of the quote in the sentences immediately before
or after the quote.
\layout Itemize
Crediting the original author of the quote should not, however, disrupt
the flow of the text.
\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
[\SpecialChar \ldots{}
]
\begin_inset Quotes erd
\end_inset
.
This is an ellipsis in square brackets.
\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
[\SpecialChar \ldots{}
]
\begin_inset Quotes erd
\end_inset
followed by the sentence's punctuation mark.
\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
[\SpecialChar \ldots{}
]
\begin_inset Quotes erd
\end_inset
.
\layout Itemize
The quote must be grammatically correct.
\begin_deeper
\layout Itemize
If the original is wrong, you must correct it.
\layout Itemize
If omitting part of the quote
\begin_inset Quotes eld
\end_inset
breaks
\begin_inset Quotes erd
\end_inset
it, you must correct the problem.
\layout Itemize
For missing words (e.
\protected_separator
g.
\protected_separator
\begin_inset Quotes eld
\end_inset
the
\begin_inset Quotes erd
\end_inset
goes missing), place the word in square brackets,
\begin_inset Quotes eld
\end_inset
[\SpecialChar \ldots{}
]
\begin_inset Quotes erd
\end_inset
and insert in the quote where needed.
\layout Itemize
For mangled word order, correct the mangled text, following it with the
text
\begin_inset Quotes eld
\end_inset
[sic]
\begin_inset Quotes erd
\end_inset
.
\end_deeper
\layout Itemize
Spelling in the quote must be correct.
Correct any misspelled words and place the text
\begin_inset Quotes eld
\end_inset
[sic]
\begin_inset Quotes erd
\end_inset
after the corrected word.
\layout Itemize
Back-to-back bracket blocks merge together.
Example:
\begin_inset Quotes eld
\end_inset
[\SpecialChar \ldots{}
][the]
\begin_inset Quotes erd
\end_inset
is wrong.
It should be
\begin_inset Quotes eld
\end_inset
[\SpecialChar \ldots{}
the]
\begin_inset Quotes erd
\end_inset
.
\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
[sic]
\begin_inset Quotes erd
\end_inset
after the last mistake.
\layout Subsubsection
Coverage
\layout Standard
When describing a new feature or
\family typewriter
*.layout
\family default
file, be sure to:
\layout Enumerate
Be
\emph on
clear, concise,
\emph default
and
\emph on
to the point
\emph default
.
KISS =
\begin_inset Quotes eld
\end_inset
Keep It Short and Sweet
\begin_inset Quotes erd
\end_inset
(or,
\begin_inset Quotes eld
\end_inset
Keep It Simple, Stupid!
\begin_inset Quotes erd
\end_inset
)
\begin_deeper
\layout Itemize
Do
\emph on
not
\emph default
write paragraph after paragraph of verbage.
\layout Itemize
Get to the point.
\layout Itemize
Take a look at the manual for a commercial word processor --- it's a fine
example of how
\series bold
NOT
\series default
to write documentation.
It's all pithy, substanceless verbage, and its
\emph on
utterly useless!
\emph default
\end_deeper
\layout Enumerate
Avoid being pedantic like The Plauge!
\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
other part of the manual
\begin_inset Quotes erd
\end_inset
is incomplete or empty, refer to it.
Someone will fill it in.
\layout Enumerate
On the other hand, BE THOROUGH!
\begin_deeper
\layout Enumerate
You are documenting
\emph on
features
\emph default
, not widgets, not how the source code is organized.
\layout Enumerate
Stay on topic --- one
\family sans
Section
\family default
should cover
\emph on
one
\emph default
feature.
Use
\family sans
Subsection
\family default
s and further subdivisions to group things if you're documenting several
related features in a single
\family sans
Section
\family default
.
\layout Enumerate
Describe EVERYTHING related to that feature, no matter where it is.
\begin_deeper
\layout Enumerate
Example: Paragraph Indenting.
Several popups control its behavior.
You would document
\emph on
all
\emph default
of this: which popups control it, when you use which setting on which popup
to do which operation, et cetera, et cetera, et cetera.
\layout Enumerate
Note from
\noun on
John Weiss
\noun default
:
\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 get
\emph on
really
\emph default
cranky when that happens, because it means
\emph on
I
\emph default
end up fixing it.
Bad help is worse than no help at all.
\begin_deeper
\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
Remember, there are people who will reference
\emph on
your
\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
When in doubt, compromise.
\begin_deeper
\layout Standard
When in doubt, use good judgement.
\end_deeper
\layout Subsubsection
NEVER NEVER
\emph on
NEVER EVER
\emph default
Treat the Reader as if She is Stupid
\layout Enumerate
No dumbing-down!
\layout Enumerate
No talking down to the reader!
\layout Enumerate
The reader is smart enough to know what a mouse is.
\layout Enumerate
The reader is smart enough to know how to use a keyboard, including the
\family sans
Shift-
\family default
,
\family sans
Control-
\family default
, and
\family sans
Meta-
\family default
keys.
(
\emph on
I
\emph default
explain that
\family sans
Meta-
\family default
is the
\family sans
Alt-
\family default
key on many keyboards in the introductions of every one of the manuals,
so you don't need to.)
\layout Enumerate
The reader is smart enough to know that
\begin_inset Quotes eld
\end_inset
at the cursor
\begin_inset Quotes erd
\end_inset
means
\begin_inset Quotes eld
\end_inset
where the text cursor is sitting right now, in the buffer currently visible.
\begin_inset Quotes erd
\end_inset
\size small
(Anything more than the word
\begin_inset Quotes eld
\end_inset
cursor
\begin_inset Quotes erd
\end_inset
is, IMO, superfluous and I will delete it.
So, save yourself the typing, save me the editing, and save the reader
the strain of sifting through extra verbage that adds no content.)
\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
\begin_inset LatexCommand \label{sec:english-only}
\end_inset
Tips for the English Version
\layout Standard
When contributing to the primary --- i.
\protected_separator
e.
\protected_separator
the English language version --- of the LyX manuals, keep the following
in mind.
\layout Subsubsection
Write as if You're Talking with a Friend.
\layout Enumerate
Think that way when you write.
Play the dialogue in your mind.
\layout Enumerate
Be as informal as you please (without being rude).
\layout Subsubsection
AVOID the Passive Voice
\layout Enumerate
No:
\begin_inset Quotes eld
\end_inset
It is felt that this name best explains the command's purpose.
\begin_inset Quotes erd
\end_inset
You know full well who wrote the command:
\begin_inset Quotes eld
\end_inset
The LyX Team felt ...
\begin_inset Quotes erd
\end_inset
Or, better yet,
\begin_inset Quotes eld
\end_inset
We felt that ...
\begin_inset Quotes erd
\end_inset
\layout Enumerate
Things don't happen by magic - somebody or something did it.
Only politicians use the passive voice to cover up actions.
If LyX reformats a paragraph, write,
\begin_inset Quotes eld
\end_inset
LyX reformatted the paragraph.
\begin_inset Quotes erd
\end_inset
If
\family typewriter
ispell
\family default
makes changes, write,
\begin_inset Quotes eld
\end_inset
\family typewriter
ispell
\family default
changes the document.
\begin_inset Quotes erd
\end_inset
\begin_deeper
\layout Standard
Rule of thumb: any sentence you can express as,
\begin_inset Quotes eld
\end_inset
It was done by foo,
\begin_inset Quotes erd
\end_inset
you can express as,
\begin_inset Quotes eld
\end_inset
Foo did it.
\begin_inset Quotes erd
\end_inset
Much nicer.
\end_deeper
\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.
Some people think it makes speech better.
It doesn't.
It makes speech byzantine.
With a little effort, you can wean yourself off of it.
\layout Enumerate
I
\emph on
will make you rewrite
\emph default
anything in the passive voice.
It's awkward and hard to read.
\layout Enumerate
Note to non-Americans:
\begin_deeper
\layout Standard
Using passive voice is generally considered bad style in the U.
\protected_separator
S.
\protected_separator
as it is too easy to obfuscate your words with it.
It also bloats sentences, often unnecessarily.
\end_deeper
\layout Subsubsection
Short Sentences.
Short Paragraphs.
\layout Standard
In English, there is a grammatical error known as the
\begin_inset Quotes eld
\end_inset
run-on sentence.
\begin_inset Quotes erd
\end_inset
Those of us who grew up with English learned in school to avoid stringing
7 clauses together with the word
\begin_inset Quotes eld
\end_inset
and.
\begin_inset Quotes erd
\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
In general, stick to short sentences in written English.
Getting rid of passive void (
\begin_inset Quotes eld
\end_inset
\SpecialChar \ldots{}
was done by\SpecialChar \ldots{}
\begin_inset Quotes erd
\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
While I'm talking about paragraphs, I'll apply the
\begin_inset Quotes eld
\end_inset
shorter is better
\begin_inset Quotes erd
\end_inset
motto to them.
At the time I started with the manuals (and this Style Sheet), I didn't
pay too much attention to paragraph size.
I've since become a big proponent of short paragraphs, with one idea per
paragraph.
While long, flowing, multi-concept paragraphs can be nice in novels, we're
writing manuals here, folks.
Our goal is rapid information location and comprehension, not a literary
prize.
\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
breathing room.
\begin_inset Quotes erd
\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
To reiterate, yet again, something I said before:
\layout Quote
When in doubt, compromise.
\layout Quote
When in doubt, use good judgement.
\layout Standard
Hopefully, you've got the idea.
\layout Section
Translations
\layout Subsection
Introduction
\layout Standard
by
\noun on
John Weiss
\begin_float footnote
\layout Standard
This introductory section is, far more than the rest of the Style Sheet,
my own personal opinions and experience.
\end_float
\layout Standard
\begin_inset LatexCommand \label{sec:translations}
\end_inset
As of version 1.0.*, LyX now has translations of the manuals into several
languages.
These translations are in varying stages of completion.
Since I can speak German fluently (on most days), I decided to give das
deutsche Übersetzung a look.
Some parts showed the telltale signs of literal translation.
Those passages, while correct, simply didn't flow smoothly, didn't
\begin_inset Quotes eld
\end_inset
read
\begin_inset Quotes erd
\end_inset
quite right.
Other parts, in contrast, were not literal.
Instead, the translation captured the intent of the originals better than
the originals did!
\layout Standard
I said in a recent email to the LyX Developer's Mailing List that translation
is a very tricky business.
In the very same email message, I inadvertently gave an example.
Consider the following German sentence:
\layout Quotation
Ich kenne hauptsächlich den akademischen Schreibstyl des germansitisches
Fachbereichs.
\layout Standard
Loosly translated into English, this reads:
\layout Quotation
I primarily know the writing style for the academic field of germanic language,
literature, and culture.
\layout Standard
The literal translation, however, is:
\layout Quotation
I know primarily the academic writing style of the Germanistic field of
study.
\layout Standard
I suppose I could have explained the word
\begin_inset Quotes eld
\end_inset
Germanistic.
\begin_inset Quotes erd
\end_inset
I would have written instead,
\begin_inset Quotes eld
\end_inset
[\SpecialChar \ldots{}
] of the field of study of germanic language, literature, and culture.
\begin_inset Quotes erd
\end_inset
Either way, the literal translation is unwieldy.
It means
\emph on
exactly
\emph default
the same as the loose translation.
It's even grammatically correct.
Ask any native English speaker which one
\emph on
sounds
\emph default
correct, and she'll pick the loose translation.
\layout Standard
The manuals are all liberally seasoned with humor.
Humor, however, is nearly impossible to translate.
Even jokes told in person sometimes won't translate.
I have a prime example of this, within two cultures with a common heritage:
American and German.
\begin_float footnote
\layout Standard
Believe it or not, my non-American colleagues, it's true! There has always
been a healthy and steady migration of Germans to the United States, dating
back to the beginning.
200 years ago, during the founding of my country, the state of Pennsylvania
seriously considered making German its official language.
\end_float
\layout Standard
My alma mater, Middlebury College, and the Universität Mainz have a long-standin
g relationship of academic exchange.
Middlebury students would matriculate at Mainz as part of a semester or
year study-abroad program.
When they had a substantial number of
\begin_inset Quotes eld
\end_inset
Midd kids
\begin_inset Quotes erd
\end_inset
in a lecture, the Mainz professors would hold an additional
\begin_inset Quotes eld
\end_inset
tutorium
\begin_inset Quotes erd
\end_inset
for them.
I was in such a lecture, in the area of
\begin_inset Quotes eld
\end_inset
Volkskunde.
\begin_inset Quotes erd
\end_inset
\layout Standard
The reason why the Mainz professors offered tutoriums to the Midd kids is
itself a lesson in cultural difference.
In lectures of any kind, Americans sit silent, taking notes on the lecture.
If one has a question, one raises one's hand, or says,
\begin_inset Quotes eld
\end_inset
Excuse me,
\begin_inset Quotes erd
\end_inset
and waits for the professor to respond.
For the students to talk to one another during the lecture, even to ask
one another a question, is considerer rude.
Germans students, however, regularly whisper to each other, discussing
the lecture or asking each other questions while the professor is speaking.
As long as this side-dialogue between students does not disturb anyone
or dominate the entirety of the class, no one thinks anything of it.
\layout Standard
Let's return to
\begin_inset Quotes eld
\end_inset
Volkskunde.
\begin_inset Quotes erd
\end_inset
It's a subfield of
\begin_inset Quotes eld
\end_inset
Germanistic
\begin_inset Quotes erd
\end_inset
that concerns itself with the cultural anthropology of Germans, specifically
folklore, traditional dress, farmhouse architecture, furniture design\SpecialChar
\ldots{}
you
get the idea.
There were about 5 of us Midd kids in this particular course and the tutorium
as well.
For about half the semester, we wondered why Dr.
\protected_separator
F.
(not his real name of course) even held the tutorium.
He seemed utterly disinterested in it, and us.
Then, about mid-semester, he suddenly repeated his previous sentence with
utter exasperation, punctuating it with the German-equivalent of a
\begin_inset Quotes eld
\end_inset
Get it?
\begin_inset Quotes erd
\end_inset
It suddenly dawned on us: he was telling a joke.
We got it, and burst out laughing.
Dr.
\protected_separator
F.
smiled a relieved smile.
He had been spending the entire semester cracking jokes (a fact we realized
later) to these seemingly humorless Americans who did nothing but sit there
and diligently transscribe his every word.
He had been using all of the verbal cues that say,
\begin_inset Quotes eld
\end_inset
This is a joke,
\begin_inset Quotes erd
\end_inset
\SpecialChar \ldots{}
to another German.
Americans use different cues, however.
Within short order, Dr.
\protected_separator
F.
figured out how to use those American verbal cues, and the tutorium became
much more fun for everyone.
\layout Standard
If deciphering the verbal cues for humor is hard to do face-to-face, how
can one hope to translate jokes or witty remarks that are dead on a page?
Translation is a
\emph on
very
\emph default
tricky business, indeed.
\layout Standard
There is a second problem with a direct translation of the original LyX
Documentation.
The original major contributors are mostly American, with Australians and
Canadians comprising most of the rest.
These three nations have a common cultural trait: we are very friendly
with strangers.
Americans, in fact, have a strong cultural desire to be everyone's friend.
Formality in everyday interactions is seen as at best haughty, at worst
hostile.
Writing that addresses the reader but contains no emotion is considered
dry and boring.
\layout Standard
When I began the Documentation Project, I wanted to create
\begin_inset Quotes eld
\end_inset
un-manuals,
\begin_inset Quotes erd
\end_inset
manuals that
\emph on
weren't
\emph default
boring.
They would engaged the reader, as if in friendly conversation.
I realize now, however, that the LyX Documentation engage the reader as
if it were a friendly conversation held in America.
Or Australia.
Or Canada.
Now, this won't be a problem in the English-speaking world, by and large.
A direct, literal translation of this style of writing, however, may not
work.
It may strike the reader, in another country speaking a different tongue,
as overly friendly.
In some parts of the world, that excessive friendliness is inappropriate
and considered rude.
\layout Standard
So, now we have a third pitfall of overly direct translation.
Translating a style or tone literally may have the opposite effect in another
country.
One must translate the
\emph on
intent
\emph default
of the style, the impact the original author wanted to have, not the tools
he used.
\layout Standard
As I said, translation is a
\emph on
very
\emph default
tricky business.
\layout Standard
\hfill
\noun on
John Weiss
\noun default
, April 6, 1999
\layout Subsection
Rules of the Translating Trade
\layout Standard
While translating anything, there are certain
\begin_inset Quotes eld
\end_inset
tools of the trade
\begin_inset Quotes erd
\end_inset
you should use.
They will help you greatly.
\layout Subsubsection
Translate one paragraph at a time.
\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
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
roughly
\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
You will not translate it correctly on the first try.
\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.
Nevertheless, overconfidence can lead you astray.
There will be some sentences, no matter how few, that will simply confound
you.
\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
When in doubt, write down all of the meanings for a word.
\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, write down all of its meanings.
No, don't copy the dictionary entry verbatim, silly! Summarize the word's
translations.
\layout Subsubsection
Using context, fix the meanings on the next pass.
\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
Fix the grammar only after you've finished translating the sentence.
\layout Standard
If there's a mystery phrase in the middle of a sentence, you can't translate
the entire sentence.
Why try grammatically arrange the words you translated already? You may
need to restructure the sentence a second time once you figure out how
to translate that mystery phrase.
Better to wait until you've completely translated the sentence to clean
up its grammar.
That way, you do so only once.
\layout Subsubsection
If you can't translate it, skip it and come back to it on the next pass.
\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
Translate the meaning first.
The rest can wait.
\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
is the only
\emph default
important part of the original document.
Lose that, and you lose the very point of performing the translation.
\layout Subsubsection
You cannot translate rhyme, plays on words, metaphors, slang\SpecialChar \ldots{}
.
\layout Standard
There is an old problem that arises when translating poetry.
Do you keep the rhyming scheme at all costs, or do you throw it away and
try to preserve the meaning? At the turn of the century, a pretty-sounding
translation was deemed more important than an accurate one.
Modern thought is that it is more important to translate the meaning.
No one will care that it sounds nice if it no longer means the same thing
as the original.
\layout Standard
One can make a similar argument for translating metaphors, puns, jokes,
and slang.
Just because the source uses slang in the 3rd sentence of paragraph 9 doesn't
mean your translation should use slang in that same sentence, too.
In fact, it shouldn't.
In formal writing, the use of slang has an intent beyond the meaning of
the actual slang.
The very fact that slang appears in conjunction with the surrounding text
carries additional connotations.
A translation of the slang may not be appropriate in the context of your
own culture.
The same applies for humor, for metaphors, puns or plays on words.
\layout Standard
The purpose of a manual is conveying information.
Anything extraneous to the meaning, the information content, is expendable.
\layout Subsubsection
Prepositions are
\emph on
not
\emph default
translatable.
\layout Standard
Most European languages have this funny part of speech called a preposition.
One uses them in combination with nouns to indicate relationship or state.
Most of us who speak a European language take them for granted.
Some languages, like Finnish, change the case of the noun in place of using
a preposition.
Hungarian, being in the same language family as Finnish, may do something
similar.
\begin_float footnote
\layout Standard
Note from
\noun on
John Weiss
\noun default
: I don't know this for sure.
Anyone care to verify this?
\end_float
\layout Standard
No, I don't care what you're English teacher or professor told you; the
prepositions in your native tongue have no direct translation into English,
and vice versa.
Let's look at an example:
\begin_inset Quotes eld
\end_inset
in
\begin_inset Quotes erd
\end_inset
.
This one we all inherited from Latin.
The German
\begin_inset Quotes eld
\end_inset
in
\begin_inset Quotes erd
\end_inset
, however, translates to the English
\begin_inset Quotes eld
\end_inset
in
\begin_inset Quotes erd
\end_inset
,
\begin_inset Quotes eld
\end_inset
from
\begin_inset Quotes erd
\end_inset
\emph on
or
\emph default
\begin_inset Quotes eld
\end_inset
to
\begin_inset Quotes erd
\end_inset
, depending on usage.
Going from English to French,
\begin_inset Quotes eld
\end_inset
in
\begin_inset Quotes erd
\end_inset
can become, amongst other things,
\begin_inset Quotes eld
\end_inset
dans
\begin_inset Quotes erd
\end_inset
and
\begin_inset Quotes eld
\end_inset
á
\begin_inset Quotes erd
\end_inset
(or should that be
\begin_inset Quotes eld
\end_inset
a
\begin_inset Quotes erd
\end_inset
?).
\layout Standard
Pick up your MyMotherTongue-to-English dictionary.
Look up any preposition in your language.
More often than not, it will translate to more than one English one.
Pick one of those, and look it up in the English side of the dictionary.
Now pick one of the translations given back into your native language.
There will likely be more than one! Now flip back to the other side of
the dictionary.
Keep repeating this process; you will quite likely conduct a strange walk
through your dictionary.
\begin_float footnote
\layout Standard
Note from
\noun on
John Weiss
\noun default
: I speak from experience, having inadvertently performed this excercise
on more than one occasion!
\end_float
\layout Standard
So, just give up.
Give up now translating prepositions using a dictionary.
Use the context of the word in its sentence.
Use good judgement.
Use your experience listening to and reading English as spoken by native
speakers.
Then pick whatever seems like the correct preposition.
\begin_float footnote
\layout Standard
Note from
\noun on
John Weiss
\noun default
: This is what I do (or end up doing) when translating to/from German or
French.
\end_float
\layout Subsubsection
Abandon all hope, ye who encounter idioms.
\layout Standard
In every language, human beings use idioms.
In every language, those idioms share a common property.
Decompose any idiom into its constituent words, look at the meaning of
those words, and there is no way to reconstruct the idiom.
In other words, the word-for-word interpretation of any idiom makes no
sense whatsoever.
\layout Standard
Unless you have a dictionary
\emph on
specifically for
\emph default
translating English-language idioms, give up now.
If you find that, despite your best efforts, one phrase in one sentence
just refuses to translate into anything that makes any sense whatsoever,
ignore it.
Seriously! Declare the gibberish portion an idiom, snip it out of the sentence,
then fix rest of the sentence and paragraph.
You can often omit idioms this way without hurting the translation too
seriously.
\layout Standard
Now, for a few idioms, just for fun!
\layout Standard
If an American exclaims that someone is
\begin_inset Quotes eld
\end_inset
dumber than a sack of hammers,
\begin_inset Quotes erd
\end_inset
it's pretty obvious what they're saying.
But what about the verb,
\begin_inset Quotes eld
\end_inset
to knock,
\begin_inset Quotes erd
\end_inset
applied to a person? One Brit may say to another,
\begin_inset Quotes eld
\end_inset
I'll knock you up around 7:30,
\begin_inset Quotes erd
\end_inset
to indicate he'll be viditing the other's apartment at 7:30.
In America, however, if one student says to another,
\begin_inset Quotes eld
\end_inset
Did you hear? The class president knocked up his girlfriend,
\begin_inset Quotes erd
\end_inset
they're describing someone's impending --- and unplanned --- parenthood.
If a German exclaims,
\begin_inset Quotes eld
\end_inset
Ich glaub' mich knutsch ein Elch,
\begin_inset Quotes erd
\end_inset
(literal translation: I believe an elk is smooching me) --- well, you're
on you're own here!
\layout Subsection
Tips for the Translators
\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
\protected_separator
\begin_inset LatexCommand \ref{sec:english-only}
\end_inset
.
There are additional rules and regulations that follow those first few.
\layout Subsubsection
Write as if you are explaining LyX to a colleague you know well.
\layout Enumerate
Think that way when you write.
Play the dialogue in your mind.
\layout Enumerate
Use a conversational style in your writing.
Pretend you are teaching LyX to a colleague you know well.
\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
AVOID Snobby, Academic, Specialized, or
\begin_inset Quotes eld
\end_inset
Dead
\begin_inset Quotes erd
\end_inset
Writing.
\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.
There is nothing wrong with passive voice, and people use it frequently
in everyday conversation.
Nevertheless, your translation of the LyX manuals must avoid
\begin_inset Quotes eld
\end_inset
dead
\begin_inset Quotes erd
\end_inset
writing.
\layout Standard
In Germany, there is a magazine known as
\begin_inset Quotes gld
\end_inset
Der Spiegel.
\begin_inset Quotes grd
\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
Der Spiegel
\begin_inset Quotes grd
\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
dead
\begin_inset Quotes erd
\end_inset
in the sense that they are seldom used by normal people in everyday speech.
\layout Standard
We who write the LyX manuals, original or translated, see to
\emph on
inform
\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
Keep the Writing Simple.
\layout Standard
For the English version, I wrote,
\begin_inset Quotes eld
\end_inset
Use short sentences and short paragraphs.
\begin_inset Quotes erd
\end_inset
What if, however, short sentences and paragraphs are something only children
use in your language? What if short sentences imply rudeness in yet another
language? Naturally, you would not want to use them in your translation.
\layout Standard
Nevertheless, the translations of the LyX manuals should be as clear as
the originals.
So, for our foreign colleagues, we apply this rule: Keep your sentences
and paragraphs as short as makes sense.
\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
When in doubt, compromise.
\layout Quote
When in doubt, use good judgement.
\layout Subsubsection
Translators must follow the Style Sheet, too!
\layout Standard
Everything in this manual ---
\emph on
except section
\protected_separator
\begin_inset LatexCommand \ref{sec:english-only}
\end_inset
\emph default
--- applies to every LyX documenter, no matter what the language.
\layout Subsubsection
Use
\family sans
Quote
\family default
or
\family sans
Quotation
\family default
, whichever is appropriate for your language.
\layout Standard
Section
\protected_separator
\begin_inset LatexCommand \ref{sec:quote}
\end_inset
explains how to quote someone (or yourself) in the manuals.
For your native language, you should not follow all of the rules in that
section.
Specifically, that section insists that you use the
\family sans
Quotation
\family default
paragraph environment for quotes.
LyX, however, has two environments for quotes:
\layout Description
\family sans
Quotation
\family default
indents the first line of each paragraph of the quote.
\layout Description
\family sans
Quote
\family default
adds extra space between each paragraph of the quote instead of indenting.
\layout Standard
Use whichever one obeys your languages's quoting style.
\layout Subsubsection
Quote text the way you're supposed to in your language.
\layout Standard
Section
\protected_separator
\begin_inset LatexCommand \ref{sec:quote}
\end_inset
explains how to quote someone (or yourself) in the manuals.
For your native language, you should not follow all of the rules in that
section.
Specifically, that section describes how to handle omissions from or correct
mistakes in the original, full text you're quoting.
In English, we use the square bracket,
\begin_inset Quotes eld
\end_inset
[\SpecialChar \ldots{}
]
\begin_inset Quotes erd
\end_inset
, to encapsulate such corrections.
We also use different quotation marks, and have special handling for quote
within a quote.
\layout Standard
Your native language has its own typography rules for quoting someone.
You should follow those rules.
\layout Subsubsection
The English versions of the manuals are not Sacred Text.
\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
accurately
\emph default
and
\emph on
completely
\emph default
convey all of the information contained in the English versions.
\layout Subsubsection
\begin_inset LatexCommand \label{sec:accuracy}
\end_inset
Any information in the LyX manuals must also be in the translations.
\layout Standard
This falls under translating the orignals accurately and completely.
\layout Itemize
Omitting any feature description is
\emph on
stricly forbidden
\emph default
.
\layout Itemize
Misrepresenting or misdescribing any LyX feature or operation
\emph on
must be avoided
\emph default
.
\layout Itemize
The translation
\emph on
cannot
\emph default
outpace the original.
\newline
If no one has documented new feature in the primary LyX manuals (i.
\protected_separator
e.
\protected_separator
the English versions), do not do so in the translations.
If you're really looking for something to do, either:
\begin_deeper
\layout Itemize
\SpecialChar \ldots{}
focus on translating something you haven't yet,
\newline
OR
\layout Itemize
\SpecialChar \ldots{}
update or repair the primary manual.
\layout Standard
If you cannot or do not want to do one of the above, then take a break.
Wait for the main manuals to catch up before translating anything else.
\end_deeper
\layout Subsubsection
What you cannot translate, you may omit (usually).
\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{}
usually.
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
There may be special cases where omitting part of a sentence or paragraph
violates rule
\protected_separator
\begin_inset LatexCommand \ref{sec:accuracy}
\end_inset
.
In those cases,
\emph on
do not omit!
\emph default
You must try and translate those tricky spots.
\layout Subsubsection
Translators may add their own fluff to the information content.
\layout Standard
After you do strip away all of the idioms, metaphors, slang, humor, and
other
\begin_inset Quotes eld
\end_inset
expendable text,
\begin_inset Quotes erd
\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
read, that engages the reader.
It may take the form of humor, or metaphors, or sayings.
Whatever you add, it should be
\begin_inset Quotes eld
\end_inset
in context.
\begin_inset Quotes erd
\end_inset
It should not clash with the explanation of LyX features and functions.
\layout Subsection
For Translation Project Chiefs
\layout Subsubsection
The First Is In Charge
\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
only
\emph default
person translating the LyXDocs, that automatically makes you the Translation
Project Chief.
\layout Standard
Amongst other things, that means that you must read this section and perform
the tasks described here.
\layout Subsubsection
Read the Style Sheet
\layout Standard
No documenter is excused from following the Style Sheet, not even you.
\layout Standard
Actually, it is
\emph on
especially
\emph default
important that the Translation Project Chiefs read the Style Sheet.
\layout Subsubsection
Make your translators read the Style Sheet
\layout Standard
No documenter is excused from following the Style Sheet.
\layout Standard
Since your translation team is translating, they know
\emph on
some
\emph default
English, at least.
Therefore, they should be able to read the Style Sheet.
\layout Subsubsection
Provide an
\begin_inset Quotes eld
\end_inset
Addendum
\begin_inset Quotes erd
\end_inset
to this Style Sheet
\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
That's where you, as head of a LyXDoc Translation Team, come in.
\layout Standard
Every Translation Team Chief is
\emph on
required
\emph default
to write an Addendum to the official Documentation Style sheet, with specifics
issues affecting your language.
(You are, after all, the LyX Team expert on your native language.) You will
follow these guidelines when writing the Addendum:
\layout Enumerate
Name the file
\newline
\family typewriter
DocStyle_Lang_<cn>.lyx
\family default
\newline
\SpecialChar \ldots{}
where
\begin_inset Quotes eld
\end_inset
\family typewriter
<cn>
\family default
\begin_inset Quotes erd
\end_inset
is the two-letter code for your language.
This is the same two-letter code that goes on the end of the translated
manuals.
Example:
\begin_inset Quotes eld
\end_inset
\family typewriter
_de
\family default
\begin_inset Quotes erd
\end_inset
for German,
\begin_inset Quotes eld
\end_inset
\family typewriter
_sv
\family default
\begin_inset Quotes erd
\end_inset
for Swedish, and
\begin_inset Quotes eld
\end_inset
\family typewriter
_ru
\family default
\begin_inset Quotes erd
\end_inset
for Russian.
\layout Enumerate
Do not worry about where the file goes.
The CVS maintainers will locate all documentation and Style Sheet Addenda
in the same place.
\layout Enumerate
Document Properties:
\begin_deeper
\layout Enumerate
Use the document class
\begin_inset Quotes eld
\end_inset
\family sans
article
\family default
\begin_inset Quotes erd
\end_inset
.
\layout Enumerate
Use one column, single-sided pages, plain page style, single-spacing and
a medium paragraph skip.
\layout Enumerate
Use margins, indentation/paragraph separation, language, and encoding appropriat
e for your language.
\layout Enumerate
Use the default font and a 12-point font size.
\end_deeper
\layout Enumerate
The title of the Addendum:
\begin_deeper
\layout Enumerate
The title will use the
\begin_inset Quotes eld
\end_inset
\family sans
Title
\family default
\begin_inset Quotes erd
\end_inset
paragraph environment.
\layout Enumerate
The title will be written in your native language.
\layout Enumerate
In your native tongue, the title will read:
\begin_deeper
\layout Standard
\family typewriter
Documentation Project Style Sheet:
\newline
Addendum for the <foo> Translation Project
\layout Standard
(Replace
\begin_inset Quotes eld
\end_inset
\family typewriter
<foo>
\family default
\begin_inset Quotes erd
\end_inset
with the name of your language.)
\end_deeper
\layout Enumerate
If your language is a European language that borrows from Latin, you shouldn't
need to translate the word
\begin_inset Quotes eld
\end_inset
Adddendum.
\begin_inset Quotes erd
\end_inset
\layout Enumerate
If your language has no ties to Latin (e.
\protected_separator
g.: Japanese, possibly Russian), or
\begin_inset Quotes eld
\end_inset
Addendum
\begin_inset Quotes erd
\end_inset
translates into your langauge as
\begin_inset Quotes eld
\end_inset
appendix,
\begin_inset Quotes erd
\end_inset
do the following:
\begin_deeper
\layout Enumerate
Replace
\begin_inset Quotes eld
\end_inset
Addendum
\begin_inset Quotes erd
\end_inset
with the translation into your native language of the word
\begin_inset Quotes eld
\end_inset
Supplement.
\begin_inset Quotes erd
\end_inset
\layout Enumerate
If
\begin_inset Quotes eld
\end_inset
Supplement
\begin_inset Quotes erd
\end_inset
also fails to translate well, try
\begin_inset Quotes eld
\end_inset
Additions.
\begin_inset Quotes erd
\end_inset
\layout Enumerate
Whatever you choose to replace
\begin_inset Quotes eld
\end_inset
Addendum,
\begin_inset Quotes erd
\end_inset
it must not have the same translation as the word
\begin_inset Quotes eld
\end_inset
appendix.
\begin_inset Quotes erd
\end_inset
\end_deeper
\end_deeper
\layout Enumerate
Below the title, in the
\begin_inset Quotes eld
\end_inset
\family sans
Author
\family default
\begin_inset Quotes erd
\end_inset
paragraph environment, place your name.
\layout Enumerate
There will be no abstract.
\layout Enumerate
The first
\family sans
Section
\family default
of the Addendum:
\begin_deeper
\layout Standard
The first thing you will do is forcefully encourage and cajole the reader
to stop reading the
\begin_inset Quotes eld
\end_inset
Addendum
\begin_inset Quotes erd
\end_inset
and go read the Style Sheet.
The reader should not return to the
\begin_inset Quotes eld
\end_inset
Addendum
\begin_inset Quotes erd
\end_inset
until he has read
\emph on
and
\emph default
understood the Style Sheet proper.
\end_deeper
\layout Subsubsection
Addendum: \SpecialChar \ldots{}
\begin_inset Quotes eld
\end_inset
Yes, we mean now.
\begin_inset Quotes erd
\end_inset
\SpecialChar \ldots{}
\layout Standard
Throughout the manuals, the DocTeam has used the following sentences:
\layout Quote
If you haven't read the <
\emph on
Foo
\emph default
> manual, go read it.
Yes, we mean now.
\layout Standard
This sentence will be tricky to translate, since it contains non-translatable
connotations.
Here's what those two sentences, sitting alone in their own paragraph,
mean:
\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
Intro
\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
You do not need to perform this command twice.
\begin_inset Quotes erd
\end_inset
\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
go read it,
\begin_inset Quotes erd
\end_inset
is firm, yet polite.
The reader may choose to ignore it.
By following with,
\begin_inset Quotes eld
\end_inset
Yes, we mean now,
\begin_inset Quotes erd
\end_inset
we imply two things.
First, we add some
\begin_inset Quotes eld
\end_inset
resistive force
\begin_inset Quotes erd
\end_inset
to the command.
That second sentence reinforces the command, making it a bit harder to
ignore.
Second, the sentence itself implies a certain sense of urgency.
You cannot merely wait until later to fulfil that command.
The brief pragraph, and its sudden end, add still further subtle reinforcement
to the command,
\begin_inset Quotes eld
\end_inset
go do the required reading before using this manual.
\begin_inset Quotes erd
\end_inset
\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 Standard
In the
\begin_inset Quotes eld
\end_inset
Addendum
\begin_inset Quotes erd
\end_inset
that you're writing, make a
\family sans
Section
\family default
(or
\family sans
Subsection
\family default
or whatever) for this issue.
Pick an appropriate translation for,
\begin_inset Quotes eld
\end_inset
If you haven't read the <
\emph on
Foo
\emph default
> manual, go read it.
Yes, we mean now.
\begin_inset Quotes erd
\end_inset
Add it, translated and untranslated, to the section.
Describe to your translators why you chose to translate these two sentences
the way you did.
\layout Subsubsection
Addendum: Forcefulness
\layout Standard
The Idea:
\layout Itemize
Use forcefulness as is appropriate in your culture.
\layout Itemize
Remain polite.
\layout Itemize
Don't sound like you're bullying
\layout Itemize
Don't sound like you're shouting
\layout Itemize
Don't sound like you're threatening.
\layout Itemize
If the translation of the English versions sounds like it's violating those
rules, something didn't translate right.
Modify appropriately.
\layout Itemize
Specify all of this in the Addendum, in its own section.
Explain these issues.
Provide examples.
Ask on the Developer's List if you need help.
\layout Standard
More to come\SpecialChar \ldots{}
\layout Subsubsection
Addendum: Resolve
\family sans
Quote
\family default
vs.
\family sans
Quotation
\family default
Issue
\layout Itemize
Make a new
\family sans
Section
\family default
for the issue of quoting.
\layout Itemize
Decide whether
\family sans
Quote
\family default
or
\family sans
Quotation
\family default
is the correct paragraph environment for your language.
\layout Itemize
In the Addendum, specify which one to use.
\layout Standard
More to come\SpecialChar \ldots{}
\layout Subsubsection
Addendum #5: Descibe Proper Quoting in Your Language.
\layout Itemize
English has its own typography and style for quoting others.
Your language does too.
\layout Itemize
Find out what that style is for your language, if you don't know already.
\layout Itemize
In the section of the Addendum covering quoting, specify this style, in
detail.
\layout Standard
More to come\SpecialChar \ldots{}
\layout Subsubsection
Addendum: Translations of Style Sheet Terminology
\layout Itemize
Standardize translations of the phrases
\begin_inset Quotes eld
\end_inset
Note from
\noun on
foo
\noun default
\begin_inset Quotes erd
\end_inset
and
\begin_inset Quotes eld
\end_inset
Author's Note
\begin_inset Quotes erd
\end_inset
.
\layout Itemize
The rest of these tools should remain the same, i.
\protected_separator
e.
\protected_separator
don't change the typography, only the words used.
\layout Standard
More to come\SpecialChar \ldots{}
\layout Subsubsection
Addendum: Font Issues
\layout Itemize
The fonts:
\newline
\family typewriter
Typewriter
\newline
\family sans
Sans Serif
\newline
\family default
Roman
\newline
\emph on
Emphasized (actually Italics)
\newline
\emph default
\bar under
Underlined
\bar default
\newline
\series bold
Bold
\series default
\newline
\noun on
Noun (actually Small Caps)
\begin_deeper
\layout Standard
\SpecialChar \ldots{}
exist for all languages that use the Roman alphabet.
\layout Itemize
Do they exist for Greek? How about Cyrillic?
\layout Itemize
They almost certainly do not exist for Devanagri, Chinese, Korean, Japanese,
Hebrew, Arabic\SpecialChar \ldots{}
\end_deeper
\layout Itemize
This raises an interesting point: how do you follow the font-scheme specified
in this Style Sheet if your language doesn't have certain fonts?
\layout Itemize
If you need to answer the previous question, make a special
\family sans
Section
\family default
in the Addendum for this issue.
\layout Itemize
Stick to the font specifications in this Style Sheet as best you can, whenever
you can.
\layout Itemize
Guidelines for
\begin_inset Quotes eld
\end_inset
translating
\begin_inset Quotes erd
\end_inset
fonts,
\newline
or
\newline
What to do when a fond doesn't exist:
\begin_deeper
\layout List
\labelwidthstring MMMMMMMM
Roman Use the font that typesetters in your language use for printing books,
manual, etc.
\layout List
\labelwidthstring MMMMMMMM
\noun on
Noun
\protected_separator
Style
\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
\emph on
Emphasized
\emph default
Use the font with which your language normally emphasizes text.
\begin_deeper
\layout Standard
Use a font that is different from your language's equivalent of
\series bold
Boldface
\series default
.
In other words, your
\family sans
Section
\family default
,
\family sans
Subsection
\family default
and similar headers will be in one typeface, perhaps
\series bold
Boldface
\series default
, perhaps not.
Whatever that font is, avoid using it for
\emph on
Emphasized
\emph default
if at all possible!
\end_deeper
\layout List
\labelwidthstring MMMMMMMM
\family typewriter
Typewriter
\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
Typewriter
\family default
.
\layout List
\labelwidthstring MMMMMMMM
\family sans
Sans
\protected_separator
Serif
\family default
Pick any other font that is different from the ones you're using in place
of
\emph on
Emphasized
\emph default
,
\series bold
Boldface
\series default
, and
\family typewriter
Typewriter
\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
Typewriter
\family default
.
Only do this, however, if your alphabet/writing system has very few fonts
to pick from.
\end_deeper
\layout Standard
More to come\SpecialChar \ldots{}
\the_end
