-#LyX 1.5.0svn created this file. For more info see http://www.lyx.org/
-\lyxformat 276
+#LyX 1.6.0svn created this file. For more info see http://www.lyx.org/
+\lyxformat 344
\begin_document
\begin_header
\textclass article
+\use_default_options false
\language english
\inputencoding latin1
\font_roman default
\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
\paperpagestyle plain
\tracking_changes false
\output_changes false
+\author ""
\end_header
\begin_body
\begin_layout Abstract
The Style Sheet for LyX documentation (hereafter known as the Style Sheet)
- applies to
-\emph default
-
+ 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 default
\emph on
Read the entire Style Sheet!
\end_layout
\begin_layout Quote
-If you have any questions about anything in the Style Sheet,
-\emph default
-
+If you have any questions about anything in the Style Sheet,
\emph on
ask first, write second!
\end_layout
\family typewriter
Typewriter
\family default
- program names, file names,
-\family default
-
+ program names, file names,
\family typewriter
man
\family default
\labelwidthstring MMMMMMMM
\family sans
-Sans\InsetSpace ~
+Sans
+\begin_inset space ~
+\end_inset
+
Serif
\family default
menu, button, or popup names, the names/lables of all widgets in a popup,
\labelwidthstring MMMMMMMM
\noun on
-Noun\InsetSpace ~
+Noun
+\begin_inset space ~
+\end_inset
+
Style
\noun default
people's names
\bar under
U
\bar default
-nderlined\InsetSpace ~
-Sans\InsetSpace ~
+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
\begin_deeper
\begin_layout Description
-WARNING! --- When you do this, make sure you
-\emph default
-
+WARNING! --- When you do this, make sure you
\emph on
only
\emph default
shut off the underlining.
Too many people send in things that look like:
-\newline
+\begin_inset Newline newline
+\end_inset
+
\family sans
\bar under
\family default
\bar default
his
-\newline
+\begin_inset Newline newline
+\end_inset
+
\SpecialChar \ldots{}
-i.\InsetSpace ~
-e.\InsetSpace ~
-they not only shut off underlining, they turned off
-\family default
-
+i.
+\begin_inset space ~
+\end_inset
+
+e.
+\begin_inset space ~
+\end_inset
+
+they not only shut off underlining, they turned off
\family sans
-Sans\InsetSpace ~
+Sans
+\begin_inset space ~
+\end_inset
+
Serif
\family default
-, too!
-\emph default
-
+, too!
\emph on
Don't do that!
\emph default
- Make sure the entire word is still in
-\family default
-
+ Make sure the entire word is still in
\family sans
-Sans\InsetSpace ~
+Sans
+\begin_inset space ~
+\end_inset
+
Serif
\family default
after you shut off the underlining.
\begin_deeper
\begin_layout Standard
-If you want to emphasize any text, use
-\emph default
-
+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 default
-
+ LaTeX will put many things boldface on its own, such as
\family sans
Section
\family default
\end_layout
\begin_layout Enumerate
-The function
-\family default
-
+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 default
-
+ in
\family typewriter
Typewriter
\family default
\end_layout
\begin_layout Enumerate
-However,
-\family default
-
+However,
\family sans
\bar under
M
\bar default
-ath\InsetSpace ~
+ath
+\begin_inset space ~
+\end_inset
+
mode
\family default
- is a menu item in the
-\family default
-
+ is a menu item in the
\family sans
\bar under
M
\bar default
ath
\family default
- menu, so it appears in
-\family default
-
+ menu, so it appears in
\family sans
-Sans\InsetSpace ~
+Sans
+\begin_inset space ~
+\end_inset
+
Serif
\family default
.
- Notice the use of
-\family default
-
+ Notice the use of
\family sans
\bar under
U
\bar default
-nderlined\InsetSpace ~
-Sans\InsetSpace ~
+nderlined
+\begin_inset space ~
+\end_inset
+
+Sans
+\begin_inset space ~
+\end_inset
+
Serif
\family default
for the accelerator keys.
\family sans
Return
\family default
- and
-\family default
-
+ and
\family sans
Enter
\family default
both refer to the same key.
- Some keyboards label the
-\family default
-
+ Some keyboards label the
\family sans
Return
\family default
\end_inset
still others have two keys.
- LyX treats all of them as the same key, so we'll use
-\family default
-
+ LyX treats all of them as the same key, so we'll use
\family sans
Return
\family default
- and
-\family default
-
+ and
\family sans
Enter
\family default
\end_layout
\begin_layout Standard
-Notice that the key name,
-\family default
-
+Notice that the key name,
\family sans
Return
\family default
-, is in
-\family default
-
+, is in
\family sans
-Sans\InsetSpace ~
+Sans
+\begin_inset space ~
+\end_inset
+
Serif
\family default
-, but
-\emph default
-
+, but
\emph on
only
\emph default
\end_layout
\begin_layout Standard
-Notice that the argument to the
-\family default
-
+Notice that the argument to the
\family typewriter
-P
\family default
- option is in
-\emph default
-
+ option is in
\emph on
Roman Italics
\emph default
(i.e.
emphasized).
- This is a case where you don't use
-\family default
-
+ This is a case where you don't use
\family typewriter
Typewriter
\family default
\begin_inset Quotes erd
\end_inset
-, you'd leave it in
-\family default
-
+, you'd leave it in
\family typewriter
Typewriter
\family default
\end_deeper
\begin_layout Enumerate
-Any LaTeX commands and code, and any
-\emph default
-
+Any LaTeX commands and code, and any
\emph on
unsupported
\emph default
- LaTeX package names get set in
-\family default
-
+ LaTeX package names get set in
\family typewriter
Typewriter
\family default
\family sans
C-
\family default
- or
-\family default
-
+ or
\family sans
Control-
\family default
\family sans
S-
\family default
- or
-\family default
-
+ or
\family sans
Shift-
\family default
\family sans
M-
\family default
- or
-\family default
-
+ or
\family sans
Meta-
\family default
\begin_deeper
\begin_layout Standard
Self-explanatory.
- Be lazy and
-\emph default
-
+ Be lazy and
\emph on
use the abbreviations
\emph default
\family sans
Insert
\family default
-
-\family default
\family sans
Delete
\family default
-
-\family default
\family sans
Home
\family default
-
-\family default
\family sans
End
\family default
-
-\family default
\family sans
PageUp
\family default
-
-\family default
\family sans
PageDown
\begin_inset Foot
status collapsed
-\begin_layout Standard
+\begin_layout Plain Layout
Same goes for
\begin_inset Quotes eld
\end_inset
\family sans
Return
\family default
- and
-\family default
-
+ and
\family sans
Enter
\family default
\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 default
-
+ I'd prefer if you used
\family sans
Return
\family default
- over
-\family default
-
+ over
\family sans
Enter
\family default
\end_deeper
\begin_layout Standard
-You do not need to explain everywhere what the
-\family default
-
+You do not need to explain everywhere what the
\family sans
Meta
\family default
- key is or where the
-\family default
-
+ key is or where the
\family sans
Left
\family default
key is, et cetera.
The user isn't stupid.
- Also, someone will document anything that isn't clear (e.\InsetSpace ~
-g.\InsetSpace ~
-the
-\family default
-
+ 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 default
\family sans
Alt
\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 default
-
+ LyX can support a keyboard missing
\family sans
F11
\family default
- and
-\family default
-
+ and
\family sans
F12
\family default
.
- There is a keyboard accelerator for
-\family default
-
+ There is a keyboard accelerator for
\family sans
F10
\family default
\begin_layout Standard
Exception: you're writing an Author's Note (see section
-\begin_inset LatexCommand ref
+\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 default
-
+ Since the rest of the note is in
\emph on
Emphasized
\emph default
\end_layout
\begin_layout Description
-Multi-word\InsetSpace ~
-names Use a
-\family default
-
+Multi-word
+\begin_inset space ~
+\end_inset
+
+names Use a
\family sans
-Protected\InsetSpace ~
+Protected
+\begin_inset space ~
+\end_inset
+
Blank
\family default
between the words for menu and widget names.
- E.\InsetSpace ~
-g.:
-\family default
-
+ E.
+\begin_inset space ~
+\end_inset
+
+g.:
\family sans
-Save\InsetSpace ~
+Save
+\begin_inset space ~
+\end_inset
+
As
\family default
-, not
-\family default
-
+, not
\family sans
Save As
\family default
\begin_deeper
\begin_layout Standard
-This holds for things in
-\family default
-
+This holds for things in
\family typewriter
Typewriter
\family default
- as well as
-\family default
-
+ as well as
\family sans
-Sans\InsetSpace ~
+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 default
-
+ in
\family typewriter
Typewriter
\family default
-, put that in a
-\family default
-
+, put that in a
\family sans
-LyX\InsetSpace ~
+LyX
+\begin_inset space ~
+\end_inset
+
Code
\family default
environment.
\end_layout
\begin_layout Standard
-I want the
-\family default
-
+I want the
\family sans
-Protected\InsetSpace ~
+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 default
-
+ If something with a
\family sans
-Protected\InsetSpace ~
+Protected
+\begin_inset space ~
+\end_inset
+
Blank
\family default
- is near the end of a line and overflows the margin, use a
-\family default
-
+ is near the end of a line and overflows the margin, use a
\family typewriter
\backslash
\end_deeper
\begin_layout Description
-Special\InsetSpace ~
+Special
+\begin_inset space ~
+\end_inset
+
Terms These are things like the following:
\end_layout
\begin_layout Itemize
\family sans
-Table\InsetSpace ~
+Table
+\begin_inset space ~
+\end_inset
+
Float
\end_layout
\begin_layout Itemize
\family sans
-Figure\InsetSpace ~
+Figure
+\begin_inset space ~
+\end_inset
+
Float
\end_layout
\begin_deeper
\begin_layout Standard
-Use
-\family default
-
+Use
\family sans
-Sans\InsetSpace ~
+Sans
+\begin_inset space ~
+\end_inset
+
Serif
\family default
- font and, in the case of
-\family default
-
+ font and, in the case of
\family sans
HFill
\family default
-
-and
-\family default
-
+ and
\family sans
VFill
\family default
\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 default
-
+ I want them to stand out from the rest of the text, hence the use of
\family sans
-Sans\InsetSpace ~
+Sans
+\begin_inset space ~
+\end_inset
+
Serif
\family default
for them.
\begin_layout Itemize
PostScript® is a registered trademark of Adobe Corp.
-
-\emph default
\emph on
You must put the ® after it or we'll get sued!
\begin_inset Quotes erd
\end_inset
- - both of them capitalized, in the default font (i.\InsetSpace ~
-.e.\InsetSpace ~
+ - both of them capitalized, in the default font (i.
+\begin_inset space ~
+\end_inset
+
+.e.
+\begin_inset space ~
+\end_inset
+
Roman).
If you must, cut and paste it from here.
\end_layout
\begin_layout Standard
I mean it! American companies like to sue anything that moves.
- We could get in
-\emph default
-
+ We could get in
\emph on
major trouble
\emph default
\end_layout
\begin_layout Description
-Menu\InsetSpace ~
+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
.
- Example:
-\family default
-
+ Example:
\family sans
File\SpecialChar \menuseparator
Save
\family default
.
- Notice that there are
-\emph default
-
+ Notice that there are
\emph on
no spaces
\emph default
\begin_inset Quotes erd
\end_inset
- and that it's in
-\family default
-
+ and that it's in
\family sans
-Sans\InsetSpace ~
+Sans
+\begin_inset space ~
+\end_inset
+
Serif
\family default
, just like the menu and item names.
\end_inset
is to prevent LyX from splitting terms across lines.
- The same goes for using
-\family default
-
+ The same goes for using
\family sans
-Protected\InsetSpace ~
+Protected
+\begin_inset space ~
+\end_inset
+
Blank
\family default
s between multi-word terms.
\begin_inset Quotes erd
\end_inset
- goes between menu names and item names
-\emph default
-
+ goes between menu names and item names
\emph on
only
\emph default
a
\bar default
per\SpecialChar \menuseparator
-Paper\InsetSpace ~
+Paper
+\begin_inset space ~
+\end_inset
+
Dialog
\family default
\begin_inset Quotes erd
\end_inset
-
-\emph default
\emph on
IS STRICTLY FORBIDDEN!
\family sans
-Paper\InsetSpace ~
+Paper
+\begin_inset space ~
+\end_inset
+
Dialog\SpecialChar \menuseparator
P
\bar under
\begin_inset Quotes erd
\end_inset
-
-\emph default
\emph on
IS STRICTLY FORBIDDEN!
\begin_inset Quotes erd
\end_inset
-
-\emph default
\emph on
IS STRICTLY FORBIDDEN!
\end_deeper
\end_deeper
\begin_layout Description
-Note\InsetSpace ~
-Boxes LyX has a feature for adding comments that appear only within
- the LyX GUI.
+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 Standard
+\begin_layout Plain Layout
These should NEVER appear in the manuals.
\end_layout
If you have a parenthetical comment you want to make, the reader should
see it too, even in the printed version.
Use an Author's Note (see section
-\begin_inset LatexCommand ref
+\begin_inset CommandInset ref
+LatexCommand ref
reference "sec:author-notes"
+
\end_inset
) in place of the Note-Boxes.
\begin_inset Quotes erd
\end_inset
-,\InsetSpace ~
+,
+\begin_inset space ~
+\end_inset
+
\begin_inset Quotes eld
\end_inset
\begin_inset Quotes erd
\end_inset
-\InsetSpace ~
-and\InsetSpace ~
+
+\begin_inset space ~
+\end_inset
+
+and
+\begin_inset space ~
+\end_inset
+
\begin_inset Quotes eld
\end_inset
\begin_inset Quotes erd
\end_inset
-, is used only within quotations (see section\InsetSpace ~
+, is used only within quotations (see section
+\begin_inset space ~
+\end_inset
+
-\begin_inset LatexCommand ref
+\begin_inset CommandInset ref
+LatexCommand ref
reference "sec:quote"
+
\end_inset
).
\begin_layout List
\labelwidthstring 00.00.0000
-sec:xxx Use this for
-\family default
-
+sec:xxx Use this for
\family sans
Section
\family default
-s as well as
-\family default
-
+s as well as
\family sans
Chapter
\family default
-s,
-\family default
-
+s,
\family sans
Subsection
\family default
-s,
-\family default
-
+s,
\family sans
Subsubsection
\family default
\end_layout
\begin_layout Enumerate
-The
-\emph default
-
+The
\emph on
beginning of the paragraph
\emph default
\end_layout
\begin_layout Enumerate
-If there is no paragraph after a section heading, put it at the
-\emph default
-
+If there is no paragraph after a section heading, put it at the
\emph on
end of the last line.
\begin_deeper
\begin_layout Standard
-Example: You have a
-\family default
-
+Example: You have a
\family sans
Section
\family default
- which is immediately followed by a
-\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 default
-
+ This is a case where you need to put the label at the end of the
\family sans
Section
\family default
\end_layout
\begin_layout Standard
-This is
-\emph default
-
+This is
\emph on
very
\emph default
\family typewriter
Intro.lyx
\family default
-
-Please, don't touch this file.
+ 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.
\family typewriter
UserGuide.lyx
\family default
-
-This file is complete.
- Any changes should be for updates
-\emph default
-
+ This file is complete.
+ Any changes should be for updates
\emph on
only
\emph default
\end_inset
from the author of the feature.
- Also, anyone who writes a
-\family default
-
+ Also, anyone who writes a
\family typewriter
.layout
\family default
\begin_deeper
\begin_layout Standard
-Note, however, that you are
-\emph default
-
+Note, however, that you are
\emph on
not
\emph default
- excused from following this Style Sheet just because the sections of
-\family default
-
+ excused from following this Style Sheet just because the sections of
\family typewriter
Extended.lyx
\family default
\begin_deeper
\begin_layout Standard
-If you are unsure whether or not something belongs in
-\family default
-
+If you are unsure whether or not something belongs in
\family typewriter
Customization.lyx
\family default
-, then, most-likely, it
-\emph default
-
+, then, most-likely, it
\emph on
really
\emph default
- belongs in
-\family 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 default
-
+ section should be migrated to
\family typewriter
Customization.lyx
\family default
\family default
I'd prefer to completely finish this one before doing anything else, but
that's unrealistic.
- LyX keeps changing so much that I think the
-\emph default
-
+ LyX keeps changing so much that I think the
\emph on
Reference Manual
\emph default
\begin_deeper
\begin_layout Standard
-Note that the
-\emph default
-
+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 default
-
+ At the top of this manual, there are examples of and a template for
\emph on
Reference Manual
\emph default
\end_layout
\begin_layout Standard
-All contributions to the
-\emph default
-
+All contributions to the
\emph on
primary
\emph default
\end_layout
\begin_layout Standard
-Nota Bene: by
-\emph default
-
+Nota Bene: by
\emph on
primary
\emph default
version of the LyX manuals.
The translation efforts require have their own set of guidelines.
See section
-\begin_inset LatexCommand ref
+\begin_inset CommandInset ref
+LatexCommand ref
reference "sec:translations"
+
\end_inset
for more info.
\begin_layout Subsection
Wearing Many Hats:
-\newline
-Commentary from the Author (i.\InsetSpace ~
+\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 LatexCommand label
+\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.
\end_layout
\begin_layout Subsubsection
-Personal\InsetSpace ~
+Personal
+\begin_inset space ~
+\end_inset
+
Notes: The
\begin_inset Quotes eld
\end_inset
\begin_inset Quotes eld
\end_inset
-me
-\begin_inset Quotes erd
+me
+\begin_inset Quotes erd
+\end_inset
+
+ hat, i.
+\begin_inset space ~
+\end_inset
+
+e.
+\begin_inset space ~
\end_inset
- hat, i.\InsetSpace ~
-e.\InsetSpace ~
to speak for yourself instead of for the LyX Team.
\end_layout
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 default
-
+ paragraph before or after the body of the
\family sans
Quotation
\family default
\end_layout
\begin_layout Subsubsection
-Author's\InsetSpace ~
+Author's
+\begin_inset space ~
+\end_inset
+
Notes: The
\begin_inset Quotes eld
\end_inset
\begin_layout Standard
The form of the Author's Note, by the way, isn't a suggestion or request.
- It is
-\emph default
-
+ It is
\emph on
mandatory
\emph default
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 default
-
+ Place quotes in a
\family sans
Quotation
\family default
\end_layout
\begin_layout Standard
-Author's Notes should
-\emph default
-
+Author's Notes should
\emph on
never
\emph default
\begin_layout Itemize
Personal Notes:
-\newline
-A
-\emph default
-
+\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\InsetSpace ~
+ If you have a long rant, however, quote yourself (see section
+\begin_inset space ~
+\end_inset
+
-\begin_inset LatexCommand ref
+\begin_inset CommandInset ref
+LatexCommand ref
reference "sec:quote"
+
\end_inset
).
\begin_layout Itemize
Author's Note:
-\newline
-Use this to describe things in LyX (or the manuals) that may
- change in the future or are somehow incomplete.
+\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:
-\newline
-Used for text fragments that almost fit into the flow of
- the text\SpecialChar \ldots{}
-but not quite.
+\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
\end_layout
\begin_layout Standard
-Everything in this section is
-\emph default
-
+Everything in this section is
\emph on
mandatory to all documenters
\emph default
\begin_deeper
\begin_layout Standard
-An example is in the
-\emph default
-
+An example is in the
\emph on
User's Guide
\emph default
.
- There is a footnote using the
-\family default
-
+ There is a footnote using the
\family typewriter
multcols
\family default
- command to divide a long
-\family default
-
+ command to divide a long
\family sans
Itemize
\family default
\end_deeper
\begin_layout Subsubsection
-\begin_inset LatexCommand label
+\begin_inset CommandInset label
+LatexCommand label
name "sec:quote"
+
\end_inset
Quoting Yourself and Others
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 default
-
+ in the following
\family sans
-Figure\InsetSpace ~
+Figure
+\begin_inset space ~
+\end_inset
+
Float
\family default
, for your convenience.
sideways false
status collapsed
-\begin_layout Standard
+\begin_layout Plain Layout
Quoting rules for English:
\end_layout
\begin_layout Itemize
-The body of the quote belongs in a
-\family default
-
+The body of the quote belongs in a
\family sans
Quotation
\family default
\end_layout
\begin_layout Itemize
-You must,
-\emph default
-
+You must,
\emph on
must
\emph default
\end_layout
\begin_layout Itemize
-For missing words (e.\InsetSpace ~
-g.\InsetSpace ~
+For missing words (e.
+\begin_inset space ~
+\end_inset
+
+g.
+\begin_inset space ~
+\end_inset
+
\begin_inset Quotes eld
\end_inset
\end_layout
\begin_layout Standard
-When describing a new feature or
-\family default
-
+When describing a new feature or
\family typewriter
*.layout
\family default
\end_layout
\begin_layout Enumerate
-Be
-\emph default
-
+Be
\emph on
clear, concise,
\emph default
-
-and
-\emph default
-
+ and
\emph on
to the point
\emph default
\begin_deeper
\begin_layout Itemize
-Do
-\emph default
-
+Do
\emph on
not
\emph default
\begin_layout Itemize
Take a look at the manual for a commercial word processor --- it's a fine
- example of how
-\series default
-
+ example of how
\series bold
NOT
\series default
to write documentation.
- It's all pithy, substanceless verbage, and its
-\emph default
-
+ It's all pithy, substanceless verbage, and its
\emph on
utterly useless!
\emph default
\begin_deeper
\begin_layout Enumerate
-You are documenting
-\emph default
-
+You are documenting
\emph on
features
\emph default
\end_layout
\begin_layout Enumerate
-Stay on topic --- one
-\family default
-
+Stay on topic --- one
\family sans
Section
\family default
- should cover
-\emph default
-
+ should cover
\emph on
one
\emph default
feature.
- Use
-\family default
-
+ Use
\family sans
Subsection
\family default
s and further subdivisions to group things if you're documenting several
- related features in a single
-\family default
-
+ related features in a single
\family sans
Section
\family default
\begin_layout Enumerate
Example: Paragraph Indenting.
Several popups control its behavior.
- You would document
-\emph default
-
+ You would document
\emph on
all
\emph default
John Weiss
\noun default
:
-\newline
+\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.
-\newline
-I got
-\emph default
-
+\begin_inset Newline newline
+\end_inset
+
+I got
\emph on
really
\emph default
- cranky when that happens, because it means
-\emph default
-
+ cranky when that happens, because it means
\emph on
I
\emph default
-
-ended up fixing it.
+ ended up fixing it.
Bad help is worse than no help at all.
\end_layout
\end_deeper
\end_deeper
\begin_layout Enumerate
-Remember, there are people who will reference
-\emph default
-
+Remember, there are people who will reference
\emph on
your
\emph default
\end_deeper
\begin_layout Subsubsection
-NEVER NEVER
-\emph default
-
+NEVER NEVER
\emph on
NEVER EVER
\emph default
\begin_layout Enumerate
The reader is smart enough to know how to use a keyboard, including the
-
-\family default
\family sans
Shift-
\family default
-,
-\family default
-
+,
\family sans
Control-
\family default
-, and
-\family default
-
+, and
\family sans
Meta-
\family default
\family sans
Meta-
\family default
- is the
-\family default
-
+ is the
\family sans
Alt-
\family default
\end_layout
\begin_layout Standard
-\begin_inset LatexCommand label
+\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
-When contributing to the primary --- i.\InsetSpace ~
-e.\InsetSpace ~
-the English language version ---
- of the LyX manuals, keep the following in mind.
+the English language version --- of the LyX manuals, keep the following
+ in mind.
\end_layout
\begin_layout Subsubsection
\begin_inset Quotes erd
\end_inset
- If
-\family default
-
+ If
\family typewriter
ispell
\family default
\end_layout
\begin_layout Enumerate
-I
-\emph default
-
+I
\emph on
will make you rewrite
\emph default
\begin_deeper
\begin_layout Standard
-Using passive voice is generally considered bad style in the U.\InsetSpace ~
-S.\InsetSpace ~
-as it is
- too easy to obfuscate your words with it.
+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
\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 default
-
+ All those words mean
\emph on
roughly
\emph default
\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 default
-
+ This is especially important for a manual, where the information
\emph on
is the only
\emph default
\begin_layout Standard
Those of you contributing to a translation of the LyX manuals must follow
a modified set of rules.
- The first few rules are analogous to those in section\InsetSpace ~
+ The first few rules are analogous to those in section
+\begin_inset space ~
+\end_inset
+
-\begin_inset LatexCommand ref
+\begin_inset CommandInset ref
+LatexCommand ref
reference "sec:english-only"
+
\end_inset
.
\end_layout
\begin_layout Standard
-We who write the LyX manuals, original or translated, seek to
-\emph default
-
+We who write the LyX manuals, original or translated, seek to
\emph on
inform
\emph default
\end_layout
\begin_layout Standard
-Everything in this manual ---
-\emph default
-
+Everything in this manual ---
\emph on
-except section\InsetSpace ~
+except section
+\begin_inset space ~
+\end_inset
-\begin_inset LatexCommand ref
+
+\begin_inset CommandInset ref
+LatexCommand ref
reference "sec:english-only"
+
\end_inset
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 default
-
+ Be as creative as you want, as long as you
\emph on
accurately
\emph default
- and
-\emph default
-
+ and
\emph on
completely
\emph default
\end_layout
\begin_layout Standard
-\begin_inset LatexCommand label
+\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 default
-
+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 default
-
+Misrepresenting or misdescribing any LyX feature or operation
\emph on
must be avoided
\emph default
\end_layout
\begin_layout Itemize
-The translation
-\emph default
-
+The translation
\emph on
cannot
\emph default
outpace the original.
-\newline
-If no one has documented new feature in the primary
- LyX manuals (i.\InsetSpace ~
-e.\InsetSpace ~
+\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_layout Itemize
\SpecialChar \ldots{}
focus on translating something you haven't yet,
-\newline
+\begin_inset Newline newline
+\end_inset
+
OR
\end_layout
\begin_layout Standard
There may be special cases where omitting part of a sentence or paragraph
- violates rule\InsetSpace ~
+ violates rule
+\begin_inset space ~
+\end_inset
+
-\begin_inset LatexCommand ref
+\begin_inset CommandInset ref
+LatexCommand ref
reference "sec:accuracy"
+
\end_inset
.
- In those cases,
-\emph default
-
+ In those cases,
\emph on
do not omit!
\emph default
\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 default
-
+ If you are the
\emph on
only
\emph default
\end_layout
\begin_layout Standard
-If you are a member of a LyX Documentation Translation Team, but
-\emph default
-
+If you are a member of a LyX Documentation Translation Team, but
\emph on
are not
\emph default
\end_layout
\begin_layout Standard
-Actually, it is
-\emph default
-
+Actually, it is
\emph on
especially
\emph default
\end_layout
\begin_layout Standard
-Since your translation team is translating, they know
-\emph default
-
+Since your translation team is translating, they know
\emph on
some
\emph default
\end_layout
\begin_layout Standard
-Every Translation Team Chief is
-\emph default
-
+Every Translation Team Chief is
\emph on
required
\emph default
\begin_layout Enumerate
Name the file:
-\newline
+\begin_inset Newline newline
+\end_inset
+
\family typewriter
DocStyle_Supplement_<cn>.lyx
\family default
-\newline
+\begin_inset Newline newline
+\end_inset
+
\SpecialChar \ldots{}
where
\begin_inset Quotes eld
\begin_inset Foot
status collapsed
-\begin_layout Standard
-Specifically, check the settings in the
-\family default
-
+\begin_layout Plain Layout
+Specifically, check the settings in the
\family sans
Document Layout
\family default
\family typewriter
Documentation Project Style Sheet:
-\newline
+\begin_inset Newline newline
+\end_inset
+
Supplement for the <foo> Translation Project
\end_layout
\end_deeper
\begin_layout Enumerate
-The first
-\family default
-
+The first
\family sans
Section
\family default
\begin_inset Quotes erd
\end_inset
- until he has read
-\emph default
-
+ until he has read
\emph on
and
\emph default
\end_layout
\begin_layout Standard
-The second
-\family default
-
+The second
\family sans
Section
\family default
\begin_layout Itemize
Roman
-\newline
+\begin_inset Newline newline
+\end_inset
+
\emph on
Emphasized (actually Italics)
\end_inset
fonts,
-\newline
+\begin_inset Newline newline
+\end_inset
+
or
-\newline
+\begin_inset Newline newline
+\end_inset
+
What to do when a font doesn't exist:
\end_layout
\labelwidthstring MMMMMMMM
\noun on
-Noun\InsetSpace ~
+Noun
+\begin_inset space ~
+\end_inset
+
Style
\noun default
This is for people's names.
\begin_deeper
\begin_layout Standard
-Use a font that is different from your language's equivalent of
-\series default
-
+Use a font that is different from your language's equivalent of
\series bold
Boldface
\series default
.
- In other words, your
-\family default
-
+ In other words, your
\family sans
Section
\family default
-,
-\family default
-
+,
\family sans
Subsection
\family default
- and similar headers will be in one typeface, perhaps
-\series 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 default
-
+ Whatever that font is, avoid using it for
\emph on
Emphasized
\emph 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 default
-
+ Use that same font in place of
\family typewriter
Typewriter
\family default
\labelwidthstring MMMMMMMM
\family sans
-Sans\InsetSpace ~
+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 default
-
+ of
\emph on
Emphasized
\emph default
-,
-\series default
-
+,
\series bold
Boldface
\series default
-, and
-\family 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 default
-
+ fonts, use the same font you picked to replace
\family typewriter
Typewriter
\family default
\bar under
U
\bar default
-nderlined\InsetSpace ~
-Sans\InsetSpace ~
+nderlined
+\begin_inset space ~
+\end_inset
+
+Sans
+\begin_inset space ~
+\end_inset
+
Serif
\family default
Don't worry about this one.
\end_deeper
\begin_layout Standard
Note that you may also want to describe fonts that your Translation Team
- should
-\emph default
-
+ should
\emph on
never
\emph default
use.
For example, no contributer to the English/European versions may ever use
-
-\series default
\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 default
-
+ variants can afford to omit
\series bold
Boldface
\series default
\end_layout
\begin_layout Subsubsection
-Quoting Style and the
-\family default
-
+Quoting Style and the
\family sans
Quote
\family default
vs.
-
-\family default
\family sans
Quotation
\end_layout
\begin_layout Itemize
-Decide whether
-\family default
-
+Decide whether
\family sans
Quote
\family default
- or
-\family default
-
+ or
\family sans
Quotation
\family default
\begin_layout Standard
English has its own typography and style for quoting others.
- The Style Sheet describes that typography in section\InsetSpace ~
+ The Style Sheet describes that typography in section
+\begin_inset space ~
+\end_inset
-\begin_inset LatexCommand ref
+
+\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\InsetSpace ~
+ Section
+\begin_inset space ~
+\end_inset
+
-\begin_inset LatexCommand ref
+\begin_inset CommandInset ref
+LatexCommand ref
reference "sec:quote"
+
\end_inset
of this Style Sheet is overly detailed for a good reason.
\end_layout
\begin_layout Standard
-Do
-\emph default
-
+Do
\emph on
not
\emph default
\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 default
-
+ In the case of a translation, however, the translator is
\emph on
not
\emph default
\end_layout
\begin_layout Standard
-Whatever you decide, codify your policy in its own
-\family default
-
+Whatever you decide, codify your policy in its own
\family sans
Section
\family default
- or
-\family default
-
+ or
\family sans
Subsection
\family default
\end_layout
\begin_layout Standard
-After describing all of the previous issues, create a new
-\family default
-
+After describing all of the previous issues, create a new
\family sans
Section
\family default
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 default
-
+ Devote a
\family sans
Subsection
\family default
- --- or even
-\family default
-
+ --- or even
\family sans
Subsubsection
\family default
\begin_layout Standard
This sentence will be tricky to translate, since it contains non-translatable
connotations.
- Therefore, create a
-\family default
-
+ Therefore, create a
\family sans
Subsection
\family default
\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 default
-
+ For example, the
\emph on
Intro
\emph default
Try and find parts of the original manuals where some friendly but firm
convincing does not translate properly.
Use these cases as the basis for examples of the problem.
- Be sure to then offer a solution (i.\InsetSpace ~
-e.\InsetSpace ~
-how you want such sentences translated.)
- If stumped, ask for help on the LyX Developer's List.
+ 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
issues.
There may be policies or guidelines that you want to set for your Translation
Team.
- Be careful, however! Keep the Supplement
-\emph default
-
+ Be careful, however! Keep the Supplement
\emph on
short
\emph default