mirror of
https://git.lyx.org/repos/lyx.git
synced 2024-11-06 11:23:45 +00:00
718027f9a3
git-svn-id: svn://svn.lyx.org/lyx/lyx-devel/trunk@10699 a592a061-630c-0410-9148-cb99ea01b6c8
4803 lines
90 KiB
Plaintext
4803 lines
90 KiB
Plaintext
#LyX 1.4.0cvs created this file. For more info see http://www.lyx.org/
|
||
\lyxformat 245
|
||
\begin_document
|
||
\begin_header
|
||
\textclass article
|
||
\language english
|
||
\inputencoding latin1
|
||
\fontscheme default
|
||
\graphics dvips
|
||
\paperfontsize 12
|
||
\spacing single
|
||
\papersize default
|
||
\use_geometry false
|
||
\use_amsmath 0
|
||
\cite_engine basic
|
||
\use_bibtopic false
|
||
\paperorientation portrait
|
||
\secnumdepth 3
|
||
\tocdepth 3
|
||
\paragraph_separation indent
|
||
\defskip medskip
|
||
\quotes_language english
|
||
\papercolumns 1
|
||
\papersides 1
|
||
\paperpagestyle plain
|
||
\tracking_changes false
|
||
\output_changes true
|
||
\end_header
|
||
|
||
\begin_body
|
||
|
||
\begin_layout Title
|
||
Documentation Project Style Sheet
|
||
\end_layout
|
||
|
||
\begin_layout Author
|
||
by John Weiss
|
||
\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
|
||
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.
|
||
\end_layout
|
||
|
||
\begin_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.
|
||
\end_layout
|
||
|
||
\begin_layout Section
|
||
Questions and Clarifications
|
||
\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
|
||
points of clarification.
|
||
On the other hand, contributors to the documents were discovering many
|
||
creative ways of misinterpreting the Style Sheet specifications.
|
||
Therefore:
|
||
\end_layout
|
||
|
||
\begin_layout Quote
|
||
If you have any questions about anything in the Style Sheet,
|
||
\emph on
|
||
ask first, write second!
|
||
\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.
|
||
\end_layout
|
||
|
||
\begin_layout Section
|
||
Fonts
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
We'll start with the easiest section, yet also the most important.
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
This is how you should fontify text in the manuals:
|
||
\end_layout
|
||
|
||
\begin_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
|
||
\end_layout
|
||
|
||
\begin_deeper
|
||
\begin_layout Standard
|
||
Do not overemphasize your text.
|
||
\end_layout
|
||
|
||
\end_deeper
|
||
\begin_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
|
||
\end_layout
|
||
|
||
\begin_layout List
|
||
\labelwidthstring MMMMMMMM
|
||
|
||
\family sans
|
||
Sans\InsetSpace ~
|
||
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
|
||
|
||
|
||
\end_layout
|
||
|
||
\begin_layout List
|
||
\labelwidthstring MMMMMMMM
|
||
|
||
\noun on
|
||
Noun\InsetSpace ~
|
||
Style
|
||
\noun default
|
||
people's names
|
||
\end_layout
|
||
|
||
\begin_layout List
|
||
\labelwidthstring MMMMMMMM
|
||
|
||
\family sans
|
||
\bar under
|
||
U
|
||
\bar default
|
||
nderlined\InsetSpace ~
|
||
Sans\InsetSpace ~
|
||
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.
|
||
\end_layout
|
||
|
||
\begin_deeper
|
||
\begin_layout Description
|
||
WARNING! --- 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.\InsetSpace ~
|
||
e.\InsetSpace ~
|
||
they not only shut off underlining, they turned off
|
||
\family sans
|
||
Sans\InsetSpace ~
|
||
Serif
|
||
\family default
|
||
, too!
|
||
\emph on
|
||
Don't do that!
|
||
\emph default
|
||
Make sure the entire word is still in
|
||
\family sans
|
||
Sans\InsetSpace ~
|
||
Serif
|
||
\family default
|
||
after you shut off the underlining.
|
||
\end_layout
|
||
|
||
\end_deeper
|
||
\begin_layout List
|
||
\labelwidthstring MMMMMMMM
|
||
|
||
\series bold
|
||
Bold
|
||
\series default
|
||
Unused.
|
||
\end_layout
|
||
|
||
\begin_deeper
|
||
\begin_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.
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
Repeat: do not use boldface.
|
||
\end_layout
|
||
|
||
\end_deeper
|
||
\begin_layout Standard
|
||
Here are some examples:
|
||
\end_layout
|
||
|
||
\begin_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
|
||
.
|
||
\end_layout
|
||
|
||
\begin_layout Enumerate
|
||
However,
|
||
\family sans
|
||
\bar under
|
||
M
|
||
\bar default
|
||
ath\InsetSpace ~
|
||
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\InsetSpace ~
|
||
Serif
|
||
\family default
|
||
.
|
||
Notice the use of
|
||
\family sans
|
||
\bar under
|
||
U
|
||
\bar default
|
||
nderlined\InsetSpace ~
|
||
Sans\InsetSpace ~
|
||
Serif
|
||
\family default
|
||
for the accelerator keys.
|
||
\end_layout
|
||
|
||
\begin_layout Enumerate
|
||
Consider the following excerpt from the introduction of one of the manuals:
|
||
\end_layout
|
||
|
||
\begin_deeper
|
||
\begin_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.
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
Notice that the key name,
|
||
\family sans
|
||
Return
|
||
\family default
|
||
, is in
|
||
\family sans
|
||
Sans\InsetSpace ~
|
||
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_layout
|
||
|
||
\end_deeper
|
||
\begin_layout Enumerate
|
||
Take the following command:
|
||
\end_layout
|
||
|
||
\begin_deeper
|
||
\begin_layout Standard
|
||
|
||
\family typewriter
|
||
lpr -P
|
||
\family default
|
||
\emph on
|
||
printername
|
||
\end_layout
|
||
|
||
\begin_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_layout
|
||
|
||
\end_deeper
|
||
\begin_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.
|
||
\end_layout
|
||
|
||
\begin_layout Section
|
||
Keys
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
The canonical keyboard contains these keys:
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
|
||
\family sans
|
||
C-
|
||
\family default
|
||
or
|
||
\family sans
|
||
Control-
|
||
\family default
|
||
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
|
||
\family sans
|
||
S-
|
||
\family default
|
||
or
|
||
\family sans
|
||
Shift-
|
||
\family default
|
||
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
|
||
\family sans
|
||
M-
|
||
\family default
|
||
or
|
||
\family sans
|
||
Meta-
|
||
\family default
|
||
|
||
\end_layout
|
||
|
||
\begin_deeper
|
||
\begin_layout Standard
|
||
Self-explanatory.
|
||
Be lazy and
|
||
\emph on
|
||
use the abbreviations
|
||
\emph default
|
||
whenever possible.
|
||
\end_layout
|
||
|
||
\end_deeper
|
||
\begin_layout Itemize
|
||
|
||
\family sans
|
||
F1 F2 F3 F4 F5 F6 F7 F8 F9 F10 F11 F12
|
||
\end_layout
|
||
|
||
\begin_deeper
|
||
\begin_layout Standard
|
||
The function keys.
|
||
Most modern keyboards have all 12.
|
||
\end_layout
|
||
|
||
\end_deeper
|
||
\begin_layout Itemize
|
||
|
||
\family sans
|
||
Esc
|
||
\family default
|
||
|
||
\end_layout
|
||
|
||
\begin_deeper
|
||
\begin_layout Standard
|
||
The
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
Escape key.
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
|
||
\end_layout
|
||
|
||
\end_deeper
|
||
\begin_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
|
||
\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_layout
|
||
|
||
\end_deeper
|
||
\begin_layout Itemize
|
||
|
||
\family sans
|
||
Left Right Up Down
|
||
\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
|
||
|
||
arrow
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
anywhere, since that's obvious.
|
||
\begin_inset Foot
|
||
status collapsed
|
||
|
||
\begin_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_layout
|
||
|
||
\end_inset
|
||
|
||
|
||
\end_layout
|
||
|
||
\end_deeper
|
||
\begin_layout Itemize
|
||
|
||
\family sans
|
||
Return
|
||
\family default
|
||
and
|
||
\family sans
|
||
Enter
|
||
\family default
|
||
|
||
\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
|
||
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_layout
|
||
|
||
\end_deeper
|
||
\begin_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.\InsetSpace ~
|
||
g.\InsetSpace ~
|
||
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.
|
||
\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
|
||
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.
|
||
\end_layout
|
||
|
||
\begin_layout Section
|
||
Mice
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
The word
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
mouse
|
||
\begin_inset Quotes erd
|
||
\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.
|
||
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
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.
|
||
\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
|
||
|
||
mouse
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
or
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
mouse button
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
stand out.
|
||
\end_layout
|
||
|
||
\begin_layout Section
|
||
Special Typography
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
Do the following:
|
||
\end_layout
|
||
|
||
\begin_layout Description
|
||
Multi-word\InsetSpace ~
|
||
names Use a
|
||
\family sans
|
||
Protected\InsetSpace ~
|
||
Blank
|
||
\family default
|
||
between the words for menu and widget names.
|
||
E.\InsetSpace ~
|
||
g.:
|
||
\family sans
|
||
Save\InsetSpace ~
|
||
As
|
||
\family default
|
||
, not
|
||
\family sans
|
||
Save As
|
||
\family default
|
||
.
|
||
|
||
\end_layout
|
||
|
||
\begin_deeper
|
||
\begin_layout Standard
|
||
This holds for things in
|
||
\family typewriter
|
||
Typewriter
|
||
\family default
|
||
as well as
|
||
\family sans
|
||
Sans\InsetSpace ~
|
||
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\InsetSpace ~
|
||
Code
|
||
\family default
|
||
environment.
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
I want the
|
||
\family sans
|
||
Protected\InsetSpace ~
|
||
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\InsetSpace ~
|
||
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_layout
|
||
|
||
\end_deeper
|
||
\begin_layout Description
|
||
Special\InsetSpace ~
|
||
Terms These are things like the following:
|
||
\end_layout
|
||
|
||
\begin_deeper
|
||
\begin_layout Itemize
|
||
|
||
\family sans
|
||
HFill
|
||
\family default
|
||
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
|
||
\family sans
|
||
VFill
|
||
\family default
|
||
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
|
||
\family sans
|
||
Table\InsetSpace ~
|
||
Float
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
|
||
\family sans
|
||
Figure\InsetSpace ~
|
||
Float
|
||
\end_layout
|
||
|
||
\begin_deeper
|
||
\begin_layout Standard
|
||
Use
|
||
\family sans
|
||
Sans\InsetSpace ~
|
||
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.
|
||
\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\InsetSpace ~
|
||
Serif
|
||
\family default
|
||
for them.
|
||
\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?
|
||
\end_layout
|
||
|
||
\begin_layout Description
|
||
Terminology Note the following:
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
dialog
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
not
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
popup
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
or
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
window
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
.
|
||
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
Confirmation alert
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
not
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
dialog
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
.
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
PostScript<EFBFBD> is a registered trademark of Adobe Corp.
|
||
|
||
\emph on
|
||
You must put the <20> 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<EFBFBD>,
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
or
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
Postscript<EFBFBD>
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
but
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
PostScript<EFBFBD>
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
- both of them capitalized, in the default font (i.\InsetSpace ~
|
||
.e.\InsetSpace ~
|
||
Roman).
|
||
If you must, cut and paste it from here.
|
||
\end_layout
|
||
|
||
\begin_deeper
|
||
\begin_layout Standard
|
||
I am going to say this again:
|
||
\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 <20> after PostScript<70> or we'll get sued!
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
\begin_inset VSpace 0.51cm
|
||
\end_inset
|
||
|
||
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
I mean it! American companies like to sue anything that moves.
|
||
We could get in
|
||
\emph on
|
||
major trouble
|
||
\emph default
|
||
by forgetting that <20>.
|
||
So, don't.
|
||
Got it?
|
||
\end_layout
|
||
|
||
\end_deeper
|
||
\begin_layout Itemize
|
||
Similarly, if you use any other registered trademark in any documentation,
|
||
put the <20> after it, too.
|
||
\end_layout
|
||
|
||
\begin_layout Description
|
||
Menu\InsetSpace ~
|
||
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\InsetSpace ~
|
||
Serif
|
||
\family default
|
||
, just like the menu and item names.
|
||
\end_layout
|
||
|
||
\begin_deeper
|
||
\begin_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\InsetSpace ~
|
||
Blank
|
||
\family default
|
||
s between multi-word terms.
|
||
The split would be visually disruptive.
|
||
\end_layout
|
||
|
||
\begin_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).
|
||
\end_layout
|
||
|
||
\begin_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 dialog 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\InsetSpace ~
|
||
Dialog
|
||
\family default
|
||
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
|
||
\emph on
|
||
IS STRICTLY FORBIDDEN!
|
||
\emph default
|
||
|
||
\end_layout
|
||
|
||
\begin_deeper
|
||
\begin_layout Standard
|
||
|
||
\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 dialog.
|
||
Example:
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
|
||
\family sans
|
||
Paper\InsetSpace ~
|
||
Dialog\SpecialChar \menuseparator
|
||
P
|
||
\bar under
|
||
o
|
||
\bar default
|
||
rtrait
|
||
\family default
|
||
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
|
||
\emph on
|
||
IS STRICTLY FORBIDDEN!
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
|
||
\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 dialog.
|
||
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!
|
||
\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_layout
|
||
|
||
\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 Note
|
||
status collapsed
|
||
|
||
\begin_layout Standard
|
||
These should NEVER appear in the manuals.
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
.
|
||
You will see nothing in a printout of the Style Sheet.
|
||
Therefore, they have no place in the manuals.
|
||
Period.
|
||
|
||
\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
|
||
|
||
) in place of the Note-Boxes.
|
||
\end_layout
|
||
|
||
\end_deeper
|
||
\begin_layout Description
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
(\SpecialChar \ldots{}
|
||
)
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
,\InsetSpace ~
|
||
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
[\SpecialChar \ldots{}
|
||
]
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
\InsetSpace ~
|
||
and\InsetSpace ~
|
||
|
||
\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\InsetSpace ~
|
||
|
||
\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.
|
||
\end_layout
|
||
|
||
\begin_layout Description
|
||
Dashes: Be sure to use the correct one.
|
||
A single
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
|
||
\family typewriter
|
||
-
|
||
\family default
|
||
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
character is not a dash, it's a hyphen.
|
||
Use it only as a hyphen.
|
||
|
||
\end_layout
|
||
|
||
\begin_deeper
|
||
\begin_layout Standard
|
||
Instead, use an
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
en-dash
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
or an
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
em- dash.
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
Two back-to-back
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
|
||
\family typewriter
|
||
-
|
||
\family default
|
||
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
characters form the en-dash.
|
||
Three
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
|
||
\family typewriter
|
||
-
|
||
\family default
|
||
|
||
\begin_inset Quotes erd
|
||
\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
|
||
|
||
|
||
\family typewriter
|
||
-
|
||
\family default
|
||
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
characters into a single, unbroken line.
|
||
\end_layout
|
||
|
||
\end_deeper
|
||
\begin_layout Section
|
||
Cross-References and Labels
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
Use the following labelling conventions:
|
||
\end_layout
|
||
|
||
\begin_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.
|
||
\end_layout
|
||
|
||
\begin_layout List
|
||
\labelwidthstring 00.00.0000
|
||
eqn:xxx Use this for Equations, should you need to create any.
|
||
\end_layout
|
||
|
||
\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.
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
Additionally, you should put the label at one of two locations:
|
||
\end_layout
|
||
|
||
\begin_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.
|
||
\end_layout
|
||
|
||
\begin_layout Enumerate
|
||
If there is no paragraph after a section heading, put it at the
|
||
\emph on
|
||
end of the last line.
|
||
|
||
\emph default
|
||
|
||
\end_layout
|
||
|
||
\begin_deeper
|
||
\begin_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_layout
|
||
|
||
\end_deeper
|
||
\begin_layout Section
|
||
Content --- What Goes Where
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
This is
|
||
\emph on
|
||
very
|
||
\emph default
|
||
important to anyone documenting a new feature.
|
||
If you need to add new documentation, pay attention.
|
||
|
||
\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.
|
||
No one paid much attention to organization in those days, either.
|
||
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.
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
With that in mind, I have some instructions for how to keep things organized:
|
||
\end_layout
|
||
|
||
\begin_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.
|
||
\end_layout
|
||
|
||
\begin_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{}
|
||
|
||
\end_layout
|
||
|
||
\begin_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.
|
||
\end_layout
|
||
|
||
\begin_deeper
|
||
\begin_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_layout
|
||
|
||
\end_deeper
|
||
\begin_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.
|
||
\end_layout
|
||
|
||
\begin_layout List
|
||
\labelwidthstring 00.00.0000
|
||
|
||
\family typewriter
|
||
Customization.lyx
|
||
\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.
|
||
\end_layout
|
||
|
||
\begin_deeper
|
||
\begin_layout Standard
|
||
If you are unsure whether or not something belongs in
|
||
\family typewriter
|
||
Customization.lyx
|
||
\family default
|
||
, then, most-likely, it
|
||
\emph on
|
||
really
|
||
\emph default
|
||
belongs in
|
||
\family typewriter
|
||
Extended.lyx
|
||
\family default
|
||
.
|
||
Again, let the current editor of the LyX documentation decide if your new
|
||
section should be migrated to
|
||
\family typewriter
|
||
Customization.lyx
|
||
\family default
|
||
.
|
||
\end_layout
|
||
|
||
\end_deeper
|
||
\begin_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!
|
||
\end_layout
|
||
|
||
\begin_deeper
|
||
\begin_layout Standard
|
||
Note that the
|
||
\emph on
|
||
Reference Manual
|
||
\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
|
||
Reference Manual
|
||
\emph default
|
||
entries.
|
||
Use them.
|
||
\end_layout
|
||
|
||
\end_deeper
|
||
\begin_layout Section
|
||
Writing Style: The Primary Manuals
|
||
\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.
|
||
|
||
\end_layout
|
||
|
||
\begin_layout Subsection
|
||
Language
|
||
\end_layout
|
||
|
||
\begin_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.
|
||
\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
|
||
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.
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
Nota Bene: by
|
||
\emph on
|
||
primary
|
||
\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.
|
||
Subsequently, the tranlsations are 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.
|
||
\end_layout
|
||
|
||
\begin_layout Subsection
|
||
Wearing Many Hats:
|
||
\newline
|
||
Commentary from the Author (i.\InsetSpace ~
|
||
e.: You)
|
||
\end_layout
|
||
|
||
\begin_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.
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
In short, when you contribute to the LyX Docs, you wear many hats.
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
For occasions when you need to switch hats, I've designed some special mechanism
|
||
s.
|
||
\end_layout
|
||
|
||
\begin_layout Subsubsection
|
||
Personal\InsetSpace ~
|
||
Notes: The
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
Me
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
Hat
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
These are footnotes.
|
||
They begin with the following:
|
||
\end_layout
|
||
|
||
\begin_layout Quote
|
||
Note from
|
||
\noun on
|
||
Name of Person
|
||
\noun default
|
||
:
|
||
\end_layout
|
||
|
||
\begin_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.
|
||
|
||
\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
|
||
|
||
me
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
hat, i.\InsetSpace ~
|
||
e.\InsetSpace ~
|
||
to speak for yourself instead of for the LyX Team.
|
||
\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
|
||
|
||
Note from
|
||
\noun on
|
||
Name of Person
|
||
\noun default
|
||
:
|
||
\begin_inset Quotes erd
|
||
\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
|
||
Quotation
|
||
\family default
|
||
.
|
||
\end_layout
|
||
|
||
\begin_layout Subsubsection
|
||
Author's\InsetSpace ~
|
||
Notes: The
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
Author
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
Hat
|
||
\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:
|
||
\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.
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
You need to leave a note for yourself.
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
You need to leave a note for the editor or the other DocTeam members.
|
||
\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.
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
At such times, you are wearing your
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
I am the Author
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
hat, if you will.
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
The typography for an
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
Author's Note
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
is as follows:
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
They 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.
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
The text of the note itself, however, is emphasized.
|
||
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
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 an em-dash,
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
---
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
, followed by your initials.
|
||
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
Here's an example: [
|
||
\emph on
|
||
Author's Note: This is an example note.
|
||
---jw
|
||
\emph default
|
||
].
|
||
\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
|
||
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 em-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 (and 5 is right out).
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
Author's Notes
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
are inherently transient, and should disapear as a manual matures.
|
||
\end_layout
|
||
|
||
\begin_layout Subsubsection
|
||
Footnotes:
|
||
\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.
|
||
\end_layout
|
||
|
||
\begin_layout Paragraph*
|
||
Mixing Footnotes and Personal Notes
|
||
\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
|
||
Quotation
|
||
\family default
|
||
paragraph environment.
|
||
\end_layout
|
||
|
||
\begin_layout Paragraph*
|
||
Mixing Footnotes and Author's Notes
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
Author's Notes should
|
||
\emph on
|
||
never
|
||
\emph default
|
||
go in footnotes.
|
||
|
||
\end_layout
|
||
|
||
\begin_layout Paragraph*
|
||
Mixing Personal Notes and Author's Notes
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
Forbidden; these two are mutually exclusive.
|
||
\end_layout
|
||
|
||
\begin_layout Subsubsection
|
||
Summary of Use
|
||
\end_layout
|
||
|
||
\begin_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\InsetSpace ~
|
||
|
||
\begin_inset LatexCommand \ref{sec:quote}
|
||
|
||
\end_inset
|
||
|
||
).
|
||
\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.
|
||
Author's Notes are supposed to disappear as a manual matures.
|
||
\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.
|
||
\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.
|
||
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_layout
|
||
|
||
\begin_layout Subsection
|
||
General Stylistic Guidelines
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
Everything in this section is
|
||
\emph on
|
||
mandatory to all documenters
|
||
\emph default
|
||
, regardless the language you're writing in.
|
||
|
||
\end_layout
|
||
|
||
\begin_layout Subsubsection
|
||
Typography
|
||
\end_layout
|
||
|
||
\begin_layout Enumerate
|
||
Use the typography rules outlined in the beginning sections of this document.
|
||
\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).
|
||
\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.
|
||
\end_layout
|
||
|
||
\begin_deeper
|
||
\begin_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.
|
||
\end_layout
|
||
|
||
\end_deeper
|
||
\begin_layout Enumerate
|
||
When in doubt, compromise.
|
||
\end_layout
|
||
|
||
\begin_deeper
|
||
\begin_layout Standard
|
||
When in doubt, use good judgement.
|
||
\end_layout
|
||
|
||
\end_deeper
|
||
\begin_layout Subsubsection
|
||
Semantics
|
||
\end_layout
|
||
|
||
\begin_layout Enumerate
|
||
You are
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
we
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
.
|
||
\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
|
||
|
||
we
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
instead of
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
I
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
.
|
||
\end_layout
|
||
|
||
\end_deeper
|
||
\begin_layout Enumerate
|
||
The reader is
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
you
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
.
|
||
\end_layout
|
||
|
||
\begin_deeper
|
||
\begin_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_layout
|
||
|
||
\end_deeper
|
||
\begin_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.
|
||
\end_layout
|
||
|
||
\begin_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.
|
||
\end_layout
|
||
|
||
\begin_layout Enumerate
|
||
When in doubt, compromise.
|
||
\end_layout
|
||
|
||
\begin_deeper
|
||
\begin_layout Standard
|
||
When in doubt, use good judgement.
|
||
\end_layout
|
||
|
||
\end_deeper
|
||
\begin_layout Subsubsection
|
||
\begin_inset LatexCommand \label{sec:quote}
|
||
|
||
\end_inset
|
||
|
||
Quoting Yourself and Others
|
||
\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.
|
||
\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.
|
||
|
||
\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\InsetSpace ~
|
||
Float
|
||
\family default
|
||
, for your convenience.
|
||
Read them if you need to.
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
\begin_inset Float figure
|
||
placement htbp
|
||
wide false
|
||
sideways false
|
||
status collapsed
|
||
|
||
\begin_layout Standard
|
||
Quoting rules for English:
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
The body of the quote belongs in a
|
||
\family sans
|
||
Quotation
|
||
\family default
|
||
environment.
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
The sentences prior to the quote should flow logically and smoothly into
|
||
the quote.
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
The sentences immediately following the quote should continue the flow of
|
||
the text.
|
||
\end_layout
|
||
|
||
\begin_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.
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
Crediting the original author of the quote should not, however, disrupt
|
||
the flow of the text.
|
||
\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
|
||
|
||
[\SpecialChar \ldots{}
|
||
]
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
.
|
||
This is an ellipsis in square brackets.
|
||
\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
|
||
|
||
[\SpecialChar \ldots{}
|
||
]
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
followed by the sentence's punctuation mark.
|
||
\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
|
||
|
||
[\SpecialChar \ldots{}
|
||
]
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
.
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
The quote must be grammatically correct.
|
||
|
||
\end_layout
|
||
|
||
\begin_deeper
|
||
\begin_layout Itemize
|
||
If the original is wrong, you must correct it.
|
||
\end_layout
|
||
|
||
\begin_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.
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
For missing words (e.\InsetSpace ~
|
||
g.\InsetSpace ~
|
||
|
||
\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.
|
||
\end_layout
|
||
|
||
\begin_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_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
|
||
|
||
[sic]
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
after the corrected word.
|
||
\end_layout
|
||
|
||
\begin_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
|
||
|
||
.
|
||
\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
|
||
|
||
[sic]
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
after the last mistake.
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
|
||
\end_layout
|
||
|
||
\begin_layout Subsubsection
|
||
Coverage
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
When describing a new feature or
|
||
\family typewriter
|
||
*.layout
|
||
\family default
|
||
file, be sure to:
|
||
\end_layout
|
||
|
||
\begin_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
|
||
|
||
)
|
||
\end_layout
|
||
|
||
\begin_deeper
|
||
\begin_layout Itemize
|
||
Do
|
||
\emph on
|
||
not
|
||
\emph default
|
||
write paragraph after paragraph of verbage.
|
||
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
Get to the point.
|
||
\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
|
||
NOT
|
||
\series default
|
||
to write documentation.
|
||
It's all pithy, substanceless verbage, and its
|
||
\emph on
|
||
utterly useless!
|
||
\emph default
|
||
|
||
\end_layout
|
||
|
||
\end_deeper
|
||
\begin_layout Enumerate
|
||
Avoid being pedantic like The Plague!
|
||
\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
|
||
|
||
other part of the manual
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
is incomplete or empty, refer to it.
|
||
Someone will fill it in eventually.
|
||
\end_layout
|
||
|
||
\begin_layout Enumerate
|
||
On the other hand, BE THOROUGH!
|
||
\end_layout
|
||
|
||
\begin_deeper
|
||
\begin_layout Enumerate
|
||
You are documenting
|
||
\emph on
|
||
features
|
||
\emph default
|
||
, not widgets, not how the source code is organized.
|
||
\end_layout
|
||
|
||
\begin_layout Enumerate
|
||
Group by feature, not by widget.
|
||
\end_layout
|
||
|
||
\begin_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
|
||
.
|
||
\end_layout
|
||
|
||
\begin_layout Enumerate
|
||
Describe EVERYTHING related to that feature, no matter where it is.
|
||
\end_layout
|
||
|
||
\begin_deeper
|
||
\begin_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.
|
||
\end_layout
|
||
|
||
\begin_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 got
|
||
\emph on
|
||
really
|
||
\emph default
|
||
cranky when that happens, because it means
|
||
\emph on
|
||
I
|
||
\emph default
|
||
ended up fixing it.
|
||
Bad help is worse than no help at all.
|
||
\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_layout
|
||
|
||
\end_deeper
|
||
\end_deeper
|
||
\begin_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_layout
|
||
|
||
\end_deeper
|
||
\begin_layout Enumerate
|
||
When in doubt, compromise.
|
||
\end_layout
|
||
|
||
\begin_deeper
|
||
\begin_layout Standard
|
||
When in doubt, use good judgement.
|
||
\end_layout
|
||
|
||
\end_deeper
|
||
\begin_layout Subsubsection
|
||
NEVER NEVER
|
||
\emph on
|
||
NEVER EVER
|
||
\emph default
|
||
Treat the Reader as if She is Stupid
|
||
\end_layout
|
||
|
||
\begin_layout Enumerate
|
||
No dumbing-down.
|
||
\end_layout
|
||
|
||
\begin_layout Enumerate
|
||
No talking down to the reader.
|
||
\end_layout
|
||
|
||
\begin_layout Enumerate
|
||
The reader is smart enough to know what a mouse is.
|
||
\end_layout
|
||
|
||
\begin_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.
|
||
(The introduction of most of the manuals takes care of the
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
|
||
\family sans
|
||
Meta-
|
||
\family default
|
||
is the
|
||
\family sans
|
||
Alt-
|
||
\family default
|
||
key
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
issue, so you don't need to.)
|
||
\end_layout
|
||
|
||
\begin_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 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.)
|
||
\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.
|
||
\end_layout
|
||
|
||
\begin_layout Subsection
|
||
Tips for the English Version
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
\begin_inset LatexCommand \label{sec:english-only}
|
||
|
||
\end_inset
|
||
|
||
When contributing to the primary --- i.\InsetSpace ~
|
||
e.\InsetSpace ~
|
||
the English language version ---
|
||
of the LyX manuals, keep the following in mind.
|
||
\end_layout
|
||
|
||
\begin_layout Subsubsection
|
||
Write as if You're Talking with a Friend.
|
||
|
||
\end_layout
|
||
|
||
\begin_layout Enumerate
|
||
Think that way when you write.
|
||
Play the dialogue in your mind.
|
||
\end_layout
|
||
|
||
\begin_layout Enumerate
|
||
Be as informal as you please (without being rude).
|
||
\end_layout
|
||
|
||
\begin_layout Subsubsection
|
||
AVOID the Passive Voice
|
||
\end_layout
|
||
|
||
\begin_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
|
||
|
||
We 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
|
||
|
||
|
||
\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
|
||
|
||
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
|
||
|
||
|
||
\end_layout
|
||
|
||
\begin_deeper
|
||
\begin_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_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.
|
||
Some people think it makes speech better.
|
||
It doesn't.
|
||
It makes speech baroque, if not outright byzantine.
|
||
With a little effort, you can wean yourself off of it.
|
||
\end_layout
|
||
|
||
\begin_layout Enumerate
|
||
I
|
||
\emph on
|
||
will make you rewrite
|
||
\emph default
|
||
anything in the passive voice.
|
||
It's awkward and hard to read.
|
||
\end_layout
|
||
|
||
\begin_layout Enumerate
|
||
Note to non-Americans:
|
||
\end_layout
|
||
|
||
\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_layout
|
||
|
||
\end_deeper
|
||
\begin_layout Subsubsection
|
||
Short Sentences.
|
||
Short Paragraphs.
|
||
\end_layout
|
||
|
||
\begin_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
|
||
|
||
The classic example of a run-on sentence is 7 clauses strung 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.
|
||
\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
|
||
|
||
\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.
|
||
\end_layout
|
||
|
||
\begin_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, as well.
|
||
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.
|
||
Our goal is rapid information location and comprehension, not a literary
|
||
prize.
|
||
\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
|
||
|
||
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.
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
To reiterate, yet again, something I said before:
|
||
\end_layout
|
||
|
||
\begin_layout Quote
|
||
When in doubt, compromise.
|
||
\end_layout
|
||
|
||
\begin_layout Quote
|
||
When in doubt, use good judgement.
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
Hopefully, you've got the idea (grin).
|
||
\end_layout
|
||
|
||
\begin_layout Section
|
||
Translations
|
||
\end_layout
|
||
|
||
\begin_layout Subsection
|
||
Rules of the Translating Trade
|
||
\end_layout
|
||
|
||
\begin_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.
|
||
\end_layout
|
||
|
||
\begin_layout Subsubsection
|
||
Translate one paragraph at a time.
|
||
\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.
|
||
\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
|
||
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.
|
||
\end_layout
|
||
|
||
\begin_layout Subsubsection
|
||
You will not translate it correctly on the first try.
|
||
\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.
|
||
\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.
|
||
\end_layout
|
||
|
||
\begin_layout Subsubsection
|
||
When in doubt, write down all of the meanings for a word.
|
||
\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
|
||
one way.
|
||
Picking the most likely translations, summarize them in one to three words
|
||
in place of an
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
exact
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
translation.
|
||
|
||
\end_layout
|
||
|
||
\begin_layout Subsubsection
|
||
Using context, fix the meanings on the next pass.
|
||
\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.
|
||
\end_layout
|
||
|
||
\begin_layout Subsubsection
|
||
Fix the grammar only after you've finished translating the sentence.
|
||
\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
|
||
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.
|
||
\end_layout
|
||
|
||
\begin_layout Subsubsection
|
||
If you can't translate it, skip it and come back to it on the next pass.
|
||
\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.
|
||
\end_layout
|
||
|
||
\begin_layout Subsubsection
|
||
Translate the meaning first.
|
||
The rest can wait.
|
||
\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
|
||
is the only
|
||
\emph default
|
||
important part of the original document.
|
||
Lose that, and you lose the very point of performing the translation.
|
||
\end_layout
|
||
|
||
\begin_layout Subsection
|
||
Tips for the Translators
|
||
\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\InsetSpace ~
|
||
|
||
\begin_inset LatexCommand \ref{sec:english-only}
|
||
|
||
\end_inset
|
||
|
||
.
|
||
There are additional rules and regulations that follow those first few.
|
||
|
||
\end_layout
|
||
|
||
\begin_layout Subsubsection
|
||
Write as if you are explaining LyX to a colleague you know well.
|
||
\end_layout
|
||
|
||
\begin_layout Enumerate
|
||
Think that way when you write.
|
||
Play the dialogue in your mind.
|
||
\end_layout
|
||
|
||
\begin_layout Enumerate
|
||
Use a conversational style in your writing.
|
||
Pretend you are teaching LyX to a colleague you know well.
|
||
\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.
|
||
\end_layout
|
||
|
||
\begin_layout Subsubsection
|
||
AVOID Snobby, Academic, Specialized, or
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
Dead
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
Writing.
|
||
|
||
\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.
|
||
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.
|
||
\end_layout
|
||
|
||
\begin_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.
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
We who write the LyX manuals, original or translated, seek 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).
|
||
|
||
\end_layout
|
||
|
||
\begin_layout Subsubsection
|
||
Keep the Writing Simple.
|
||
\end_layout
|
||
|
||
\begin_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, in yet another language, short sentences
|
||
imply rudeness? Naturally, you would not want to use them in your translation.
|
||
\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.
|
||
\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:
|
||
\end_layout
|
||
|
||
\begin_layout Quote
|
||
When in doubt, compromise.
|
||
\end_layout
|
||
|
||
\begin_layout Quote
|
||
When in doubt, use good judgement.
|
||
\end_layout
|
||
|
||
\begin_layout Subsubsection
|
||
Translators must follow the Style Sheet, too!
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
Everything in this manual ---
|
||
\emph on
|
||
except section\InsetSpace ~
|
||
|
||
\begin_inset LatexCommand \ref{sec:english-only}
|
||
|
||
\end_inset
|
||
|
||
|
||
\emph default
|
||
--- applies to every LyX documenter, no matter what the language.
|
||
\end_layout
|
||
|
||
\begin_layout Subsubsection
|
||
Translators must read the Style Sheet Supplement for their language.
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
For every translation project, there is a Supplement to the Style Sheet.
|
||
It will be named:
|
||
\end_layout
|
||
|
||
\begin_layout Quote
|
||
|
||
\family typewriter
|
||
DocStyle_Supplement_<cn>.lyx
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
\SpecialChar \ldots{}
|
||
where
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
|
||
\family typewriter
|
||
<cn>
|
||
\family default
|
||
|
||
\begin_inset Quotes erd
|
||
\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
|
||
wink!
|
||
\emph default
|
||
>
|
||
\end_layout
|
||
|
||
\begin_layout Subsubsection
|
||
The English versions of the manuals are not Sacred Text.
|
||
\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
|
||
accurately
|
||
\emph default
|
||
and
|
||
\emph on
|
||
completely
|
||
\emph default
|
||
convey all of the information contained in the English versions.
|
||
\end_layout
|
||
|
||
\begin_layout Subsubsection
|
||
Any information in the LyX manuals must also be in the translations.
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
\begin_inset LatexCommand \label{sec:accuracy}
|
||
|
||
\end_inset
|
||
|
||
This falls under translating the orignals accurately and completely.
|
||
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
Omitting any feature description is
|
||
\emph on
|
||
stricly forbidden
|
||
\emph default
|
||
.
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
Misrepresenting or misdescribing any LyX feature or operation
|
||
\emph on
|
||
must be avoided
|
||
\emph default
|
||
.
|
||
\end_layout
|
||
|
||
\begin_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.\InsetSpace ~
|
||
e.\InsetSpace ~
|
||
the English versions), do not do so in the translations.
|
||
If you're really looking for something to do, either:
|
||
\end_layout
|
||
|
||
\begin_deeper
|
||
\begin_layout Itemize
|
||
\SpecialChar \ldots{}
|
||
focus on translating something you haven't yet,
|
||
\newline
|
||
OR
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
\SpecialChar \ldots{}
|
||
update or repair the primary manual.
|
||
\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_layout
|
||
|
||
\end_deeper
|
||
\begin_layout Subsubsection
|
||
What you cannot translate, you may omit (usually).
|
||
\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{}
|
||
|
||
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.
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
There may be special cases where omitting part of a sentence or paragraph
|
||
violates rule\InsetSpace ~
|
||
|
||
\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.
|
||
\end_layout
|
||
|
||
\begin_layout Subsubsection
|
||
Translators may add their own fluff to the information content.
|
||
\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
|
||
|
||
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.
|
||
\end_layout
|
||
|
||
\begin_layout Subsection
|
||
For Translation Project Chiefs
|
||
\end_layout
|
||
|
||
\begin_layout Subsubsection
|
||
The First Is In Charge
|
||
\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
|
||
only
|
||
\emph default
|
||
person translating the LyXDocs, that automatically makes you the Translation
|
||
Project Chief.
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
Amongst other things, that means that you must read this section and perform
|
||
the tasks described here.
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
If you are a member of a LyX Documentation Translation Team, but
|
||
\emph on
|
||
are not
|
||
\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.
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
If you have not read the Style Sheet Supplement for your language, you should
|
||
read it now.
|
||
|
||
\end_layout
|
||
|
||
\begin_layout Subsubsection
|
||
Read the Style Sheet
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
No documenter is excused from following the Style Sheet, not even a Translation
|
||
Project Chief.
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
Actually, it is
|
||
\emph on
|
||
especially
|
||
\emph default
|
||
important that the Translation Project Chiefs read the Style Sheet.
|
||
\end_layout
|
||
|
||
\begin_layout Subsubsection
|
||
Make your translators read the Style Sheet
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
No documenter is excused from following the Style Sheet.
|
||
\end_layout
|
||
|
||
\begin_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.
|
||
\end_layout
|
||
|
||
\begin_layout Subsubsection
|
||
Provide a
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
Supplement
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
to this Style Sheet
|
||
\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.
|
||
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
That's where you, as head of a LyXDoc Translation Team, come in.
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
Every Translation Team Chief is
|
||
\emph on
|
||
required
|
||
\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:
|
||
\end_layout
|
||
|
||
\begin_layout Enumerate
|
||
Name the file:
|
||
\newline
|
||
|
||
\family typewriter
|
||
DocStyle_Supplement_<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 is part of the filenames for 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.
|
||
\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.
|
||
\end_layout
|
||
|
||
\begin_layout Enumerate
|
||
Document Properties:
|
||
\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
|
||
status collapsed
|
||
|
||
\begin_layout Standard
|
||
Specifically, check the settings in the
|
||
\family sans
|
||
Document Layout
|
||
\family default
|
||
popup.
|
||
Use those in your Supplement.
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
Exceptions: Use margins, indentation/paragraph separation, language, and
|
||
encoding appropriate for your language.
|
||
\end_layout
|
||
|
||
\end_deeper
|
||
\begin_layout Enumerate
|
||
The title of the Supplement:
|
||
\end_layout
|
||
|
||
\begin_deeper
|
||
\begin_layout Itemize
|
||
The title will use the
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
|
||
\family sans
|
||
Title
|
||
\family default
|
||
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
paragraph environment.
|
||
In your native tongue, the title will read:
|
||
\end_layout
|
||
|
||
\begin_deeper
|
||
\begin_layout Standard
|
||
|
||
\family typewriter
|
||
Documentation Project Style Sheet:
|
||
\newline
|
||
Supplement for the <foo> Translation Project
|
||
\end_layout
|
||
|
||
\begin_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_layout
|
||
|
||
\end_deeper
|
||
\begin_layout Itemize
|
||
If, in your language,
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
supplement
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
translates into
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
appendix,
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
we have a problem.
|
||
In English,
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
Supplement
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
and
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
Appendix
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
have somewhat different meanings.
|
||
An appendix is an extra part of a document.
|
||
A supplement is an extra document.
|
||
|
||
\end_layout
|
||
|
||
\begin_deeper
|
||
\begin_layout Standard
|
||
Choose a replacement word accordingly.
|
||
Whatever you choose to replace
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
Supplement,
|
||
\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_layout
|
||
|
||
\end_deeper
|
||
\end_deeper
|
||
\begin_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.
|
||
\end_layout
|
||
|
||
\begin_deeper
|
||
\begin_layout Standard
|
||
There will be no abstract.
|
||
\end_layout
|
||
|
||
\end_deeper
|
||
\begin_layout Enumerate
|
||
The first
|
||
\family sans
|
||
Section
|
||
\family default
|
||
of the Supplement:
|
||
\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
|
||
|
||
Supplement
|
||
\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
|
||
|
||
Supplement
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
until he has read
|
||
\emph on
|
||
and
|
||
\emph default
|
||
understood the Style Sheet proper.
|
||
\end_layout
|
||
|
||
\end_deeper
|
||
\begin_layout Subsubsection
|
||
Keep the Supplement Succinct
|
||
\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.
|
||
\end_layout
|
||
|
||
\begin_layout Subsubsection
|
||
Font Issues
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
The second
|
||
\family sans
|
||
Section
|
||
\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:
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
|
||
\family typewriter
|
||
Typewriter
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
|
||
\family sans
|
||
Sans Serif
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
Roman
|
||
\newline
|
||
|
||
\emph on
|
||
Emphasized (actually Italics)
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
|
||
\bar under
|
||
Underlined
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
|
||
\series bold
|
||
Bold
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
|
||
\noun on
|
||
Noun (actually Small Caps)
|
||
\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.
|
||
|
||
\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.
|
||
\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
|
||
|
||
fonts.
|
||
\begin_inset Quotes erd
|
||
\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:
|
||
\end_layout
|
||
|
||
\begin_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 font doesn't exist:
|
||
\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.
|
||
\end_layout
|
||
|
||
\begin_layout List
|
||
\labelwidthstring MMMMMMMM
|
||
|
||
\noun on
|
||
Noun\InsetSpace ~
|
||
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.
|
||
\end_layout
|
||
|
||
\begin_layout List
|
||
\labelwidthstring MMMMMMMM
|
||
|
||
\emph on
|
||
Emphasized
|
||
\emph default
|
||
Use the font with which your language normally emphasizes text.
|
||
\end_layout
|
||
|
||
\begin_deeper
|
||
\begin_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_layout
|
||
|
||
\end_deeper
|
||
\begin_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
|
||
.
|
||
\end_layout
|
||
|
||
\begin_layout List
|
||
\labelwidthstring MMMMMMMM
|
||
|
||
\family sans
|
||
Sans\InsetSpace ~
|
||
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_layout
|
||
|
||
\begin_layout List
|
||
\labelwidthstring MMMMMMMM
|
||
|
||
\family sans
|
||
\bar under
|
||
U
|
||
\bar default
|
||
nderlined\InsetSpace ~
|
||
Sans\InsetSpace ~
|
||
Serif
|
||
\family default
|
||
Don't worry about this one.
|
||
\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_layout
|
||
|
||
\end_deeper
|
||
\end_deeper
|
||
\begin_layout Standard
|
||
Note that you may also want to describe fonts that your Translation Team
|
||
should
|
||
\emph on
|
||
never
|
||
\emph default
|
||
use.
|
||
For example, no contributer to the English/European versions may ever use
|
||
|
||
\series bold
|
||
Boldface
|
||
\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
|
||
Boldface
|
||
\series default
|
||
.
|
||
|
||
\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.
|
||
You may receive valuable feedback this way.
|
||
If not, that's okay.
|
||
If no one can read your writing system, and therefore cannot comment, that's
|
||
also okay.
|
||
Go ahead and describe the typographic standard you created in the Supplement.
|
||
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
Remember: stick to the font specifications in this Style Sheet as best you
|
||
can, whenever you can.
|
||
\end_layout
|
||
|
||
\begin_layout Subsubsection
|
||
Quoting Style and the
|
||
\family sans
|
||
Quote
|
||
\family default
|
||
vs.
|
||
|
||
\family sans
|
||
Quotation
|
||
\family default
|
||
Issue
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
The next section of the Supplement will cover the issue of quoting.
|
||
Give it an appropriate title.
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
One of the first things you should do in that section is resolve the following
|
||
issue:
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
Decide whether
|
||
\family sans
|
||
Quote
|
||
\family default
|
||
or
|
||
\family sans
|
||
Quotation
|
||
\family default
|
||
is the correct paragraph environment for your language.
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
In the Supplement, specify which one to use.
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
English has its own typography and style for quoting others.
|
||
The Style Sheet describes that typography in section\InsetSpace ~
|
||
|
||
\begin_inset LatexCommand \ref{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\InsetSpace ~
|
||
|
||
\begin_inset LatexCommand \ref{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.
|
||
The members of your Translation Team, however, will all likely be native
|
||
speakers of your language.
|
||
Therefore, discuss proper quoting style of your native tongue to an appropriate
|
||
level of detail.
|
||
\end_layout
|
||
|
||
\begin_layout Subsubsection
|
||
Translations of Style Sheet Terminology
|
||
\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.
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
In particular, standardize the translations of the phrases:
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
Note from
|
||
\noun on
|
||
<foo>:
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
|
||
\emph on
|
||
Author's Note:
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
Do
|
||
\emph on
|
||
not
|
||
\emph default
|
||
change the typography of the
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
Personal Note
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
and
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
Author's Note,
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
however.
|
||
Only provide a translation for the opening phrases.
|
||
Insist that the members of your Translation Team use these two tools correctly.
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
While we are discussing proper use of the
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
Personal Note
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
and
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
Author's Note
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
in translations, let's talk about a related problem.
|
||
The
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
Author's Note
|
||
\begin_inset Quotes erd
|
||
\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
|
||
not
|
||
\emph default
|
||
the author! How then should a translator translate an
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
Author's Note?
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
|
||
\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
|
||
|
||
Author's Notes,
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
omitting them entirely instead.
|
||
You could tell your translators to read any
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
Author's Note
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
they may encounter, understand it, then write their own
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
Author's Note
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
about the situation, not as a translation but as a personal opinion.
|
||
You may decide on some other policy.
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
Whatever you decide, codify your policy in its own
|
||
\family sans
|
||
Section
|
||
\family default
|
||
or
|
||
\family sans
|
||
Subsection
|
||
\family default
|
||
or whatever.
|
||
Place it near the section where you translated
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
Personal Note
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
and
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
Author's Note
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
.
|
||
\end_layout
|
||
|
||
\begin_layout Subsubsection
|
||
Lost in Translation
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
After describing all of the previous issues, create a new
|
||
\family sans
|
||
Section
|
||
\family default
|
||
.
|
||
Give it the name,
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
Lost in Translation,
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
or something similar.
|
||
\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
|
||
Subsection
|
||
\family default
|
||
--- or even
|
||
\family sans
|
||
Subsubsection
|
||
\family default
|
||
s --- to each specific issue.
|
||
\end_layout
|
||
|
||
\begin_layout Subsubsection
|
||
\SpecialChar \ldots{}
|
||
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
Yes, we mean now.
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
\SpecialChar \ldots{}
|
||
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
Throughout the manuals, the DocTeam has used the following sentences:
|
||
\end_layout
|
||
|
||
\begin_layout Quote
|
||
If you haven't read the <
|
||
\emph on
|
||
Foo
|
||
\emph default
|
||
> manual, go read it.
|
||
Yes, we mean now.
|
||
\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
|
||
for this issue in your
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
Lost in Translation
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
section.
|
||
Present the
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
\SpecialChar \ldots{}
|
||
Yes, we mean now\SpecialChar \ldots{}
|
||
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
sentences, then present a translation, along with any explanation you feel
|
||
necessary.
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
Here's what those two sentences, sitting alone in their own paragraph, mean:
|
||
\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
|
||
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
|
||
|
||
|
||
\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
|
||
|
||
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 fulfill 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
|
||
|
||
|
||
\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.
|
||
\end_layout
|
||
|
||
\begin_layout Subsubsection
|
||
Firm Convincing vs.
|
||
Rudeness
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
In the same part of the Supplement that you place the
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
\SpecialChar \ldots{}
|
||
Yes, we mean now\SpecialChar \ldots{}
|
||
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
translation, discuss the English version's use of
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
firm convincing.
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
|
||
\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
|
||
|
||
user-friendly.
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
This is where the use of
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
firm convincing
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
comes in.
|
||
|
||
\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.
|
||
\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.
|
||
Additionally, translating the firm-but-convincing bits may not work.
|
||
The translation may sound weird, or rude, or hostile.
|
||
Therefore, you and your translation team will face many sentences that
|
||
you cannot translate.
|
||
\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.\InsetSpace ~
|
||
e.\InsetSpace ~
|
||
how you want such sentences translated.)
|
||
If stumped, ask for help on the LyX Developer's List.
|
||
\end_layout
|
||
|
||
\begin_layout Subsubsection
|
||
Anything Else?
|
||
\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
|
||
short
|
||
\emph default
|
||
.
|
||
|
||
\end_layout
|
||
|
||
\end_body
|
||
\end_document
|