mirror of
https://git.lyx.org/repos/lyx.git
synced 2024-09-20 06:49:56 +00:00
8a765440cb
git-svn-id: svn://svn.lyx.org/lyx/lyx-devel/trunk@30237 a592a061-630c-0410-9148-cb99ea01b6c8
5079 lines
92 KiB
Plaintext
5079 lines
92 KiB
Plaintext
#LyX 1.6.0 created this file. For more info see http://www.lyx.org/
|
|
\lyxformat 345
|
|
\begin_document
|
|
\begin_header
|
|
\textclass article
|
|
\use_default_options false
|
|
\language english
|
|
\inputencoding latin1
|
|
\font_roman default
|
|
\font_sans default
|
|
\font_typewriter default
|
|
\font_default_family default
|
|
\font_sc false
|
|
\font_osf false
|
|
\font_sf_scale 100
|
|
\font_tt_scale 100
|
|
\graphics dvips
|
|
\paperfontsize 12
|
|
\spacing single
|
|
\use_hyperref false
|
|
\papersize default
|
|
\use_geometry false
|
|
\use_amsmath 0
|
|
\use_esint 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 false
|
|
\author ""
|
|
\author ""
|
|
\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
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
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
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
Style
|
|
\noun default
|
|
people's names
|
|
\end_layout
|
|
|
|
\begin_layout List
|
|
\labelwidthstring MMMMMMMM
|
|
|
|
\family sans
|
|
\bar under
|
|
U
|
|
\bar default
|
|
nderlined
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
Sans
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
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:
|
|
\begin_inset Newline newline
|
|
\end_inset
|
|
|
|
|
|
\family sans
|
|
\bar under
|
|
T
|
|
\family default
|
|
\bar default
|
|
his
|
|
\begin_inset Newline newline
|
|
\end_inset
|
|
|
|
\SpecialChar \ldots{}
|
|
i.
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
e.
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
they not only shut off underlining, they turned off
|
|
\family sans
|
|
Sans
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
Serif
|
|
\family default
|
|
, too!
|
|
\emph on
|
|
Don't do that!
|
|
\emph default
|
|
Make sure the entire word is still in
|
|
\family sans
|
|
Sans
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
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
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
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
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
Serif
|
|
\family default
|
|
.
|
|
Notice the use of
|
|
\family sans
|
|
\bar under
|
|
U
|
|
\bar default
|
|
nderlined
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
Sans
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
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
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
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.
|
|
\begin_inset space \thinspace{}
|
|
\end_inset
|
|
|
|
g.
|
|
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 Plain Layout
|
|
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.
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
g.
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
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 CommandInset ref
|
|
LatexCommand ref
|
|
reference "sec:author-notes"
|
|
|
|
\end_inset
|
|
|
|
) and you need to mention something about the mouse.
|
|
Since the rest of the note is in
|
|
\emph on
|
|
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
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
names Use a
|
|
\family sans
|
|
Protected
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
Blank
|
|
\family default
|
|
between the words for menu and widget names.
|
|
E.
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
g.:
|
|
\family sans
|
|
Save
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
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
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
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
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
Code
|
|
\family default
|
|
environment.
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
I want the
|
|
\family sans
|
|
Protected
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
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
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
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
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
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
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
Float
|
|
\end_layout
|
|
|
|
\begin_layout Itemize
|
|
|
|
\family sans
|
|
Figure
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
Float
|
|
\end_layout
|
|
|
|
\begin_deeper
|
|
\begin_layout Standard
|
|
Use
|
|
\family sans
|
|
Sans
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
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
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
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® is a registered trademark of Adobe Corp.
|
|
|
|
\emph on
|
|
You must put the ® after it or we'll get sued!
|
|
\emph default
|
|
I also want it written as seen here, always capitalized.
|
|
Not
|
|
\begin_inset Quotes eld
|
|
\end_inset
|
|
|
|
postscript®,
|
|
\begin_inset Quotes erd
|
|
\end_inset
|
|
|
|
or
|
|
\begin_inset Quotes eld
|
|
\end_inset
|
|
|
|
Postscript®
|
|
\begin_inset Quotes erd
|
|
\end_inset
|
|
|
|
but
|
|
\begin_inset Quotes eld
|
|
\end_inset
|
|
|
|
PostScript®
|
|
\begin_inset Quotes erd
|
|
\end_inset
|
|
|
|
- both of them capitalized, in the default font (i.
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
.
|
|
\begin_inset space \thinspace{}
|
|
\end_inset
|
|
|
|
g.
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
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 ® after PostScript® 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 ®.
|
|
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 ® after it, too.
|
|
\end_layout
|
|
|
|
\begin_layout Description
|
|
Menu
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
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
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
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
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
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
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
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
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
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
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
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 Plain Layout
|
|
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 CommandInset ref
|
|
LatexCommand ref
|
|
reference "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
|
|
|
|
,
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
|
|
\begin_inset Quotes eld
|
|
\end_inset
|
|
|
|
[\SpecialChar \ldots{}
|
|
]
|
|
\begin_inset Quotes erd
|
|
\end_inset
|
|
|
|
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
and
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
|
|
\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
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
|
|
\begin_inset CommandInset ref
|
|
LatexCommand ref
|
|
reference "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 CommandInset ref
|
|
LatexCommand ref
|
|
reference "sec:translations"
|
|
|
|
\end_inset
|
|
|
|
for more info.
|
|
\end_layout
|
|
|
|
\begin_layout Subsection
|
|
Wearing Many Hats:
|
|
\begin_inset Newline newline
|
|
\end_inset
|
|
|
|
Commentary from the Author (i.
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
e.: You)
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
\begin_inset CommandInset label
|
|
LatexCommand label
|
|
name "sec:author-notes"
|
|
|
|
\end_inset
|
|
|
|
I want to make it easy for everyone when it comes to documenting things.
|
|
Some features are incomplete.
|
|
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
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
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.
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
e.
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
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
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
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:
|
|
\begin_inset Newline newline
|
|
\end_inset
|
|
|
|
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
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
|
|
\begin_inset CommandInset ref
|
|
LatexCommand ref
|
|
reference "sec:quote"
|
|
|
|
\end_inset
|
|
|
|
).
|
|
\end_layout
|
|
|
|
\begin_layout Itemize
|
|
Author's Note:
|
|
\begin_inset Newline newline
|
|
\end_inset
|
|
|
|
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:
|
|
\begin_inset Newline newline
|
|
\end_inset
|
|
|
|
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 CommandInset label
|
|
LatexCommand label
|
|
name "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
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
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 Plain Layout
|
|
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.
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
g.
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
|
|
\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
|
|
:
|
|
\begin_inset Newline newline
|
|
\end_inset
|
|
|
|
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.
|
|
\begin_inset Newline newline
|
|
\end_inset
|
|
|
|
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 CommandInset label
|
|
LatexCommand label
|
|
name "sec:english-only"
|
|
|
|
\end_inset
|
|
|
|
When contributing to the primary --- i.
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
e.
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
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.
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
S.
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
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
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
|
|
\begin_inset CommandInset ref
|
|
LatexCommand ref
|
|
reference "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
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
|
|
\begin_inset CommandInset ref
|
|
LatexCommand ref
|
|
reference "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 CommandInset label
|
|
LatexCommand label
|
|
name "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.
|
|
\begin_inset Newline newline
|
|
\end_inset
|
|
|
|
If no one has documented new feature in the primary LyX manuals (i.
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
e.
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
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,
|
|
\begin_inset Newline newline
|
|
\end_inset
|
|
|
|
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
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
|
|
\begin_inset CommandInset ref
|
|
LatexCommand ref
|
|
reference "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:
|
|
\begin_inset Newline newline
|
|
\end_inset
|
|
|
|
|
|
\family typewriter
|
|
DocStyle_Supplement_<cn>.lyx
|
|
\family default
|
|
|
|
\begin_inset Newline newline
|
|
\end_inset
|
|
|
|
\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 Plain Layout
|
|
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:
|
|
\begin_inset Newline newline
|
|
\end_inset
|
|
|
|
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
|
|
\begin_inset Newline newline
|
|
\end_inset
|
|
|
|
|
|
\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,
|
|
\begin_inset Newline newline
|
|
\end_inset
|
|
|
|
or
|
|
\begin_inset Newline newline
|
|
\end_inset
|
|
|
|
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
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
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
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
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
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
Sans
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
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
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
|
|
\begin_inset CommandInset ref
|
|
LatexCommand ref
|
|
reference "sec:quote"
|
|
|
|
\end_inset
|
|
|
|
.
|
|
Your language also has a specific typography and style for quotations.
|
|
Describe that style in this section of the Supplement, too.
|
|
Naturally, you do not need to go overboard.
|
|
Section
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
|
|
\begin_inset CommandInset ref
|
|
LatexCommand ref
|
|
reference "sec:quote"
|
|
|
|
\end_inset
|
|
|
|
of this Style Sheet is overly detailed for a good reason.
|
|
Authors of the primary LyX manuals are not necessarily native English speakers.
|
|
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.
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
e.
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
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
|