I've just modified the Style Sheet to take the new menu-separator into
account. For v1.0.2, the new Style Sheet applies to all docs. That
means that the old "->" character sequence shall be replaced with the
menu separator for v1.0.2 [or v1.0.3, which would be a doc-update
only].
BTW: I *like* the way footnotes look now. Verrrry spiffy!
--
John Weiss
On a train, someplace between Pawling and White Plains...
#This file was created by <candide> Fri Mar 26 08:33:41 1999
#LyX 1.0 (C) 1995-1999 Matthias Ettrich and the LyX Team
\lyxformat 2.15
\textclass article
\language default
\inputencoding latin1
\fontscheme default
\graphics dvips
\paperfontsize 12
\spacing single
\papersize letterpaper
\paperpackage a4
\use_geometry 0
\use_amsmath 0
\paperorientation portrait
\secnumdepth 3
\tocdepth 3
\paragraph_separation indent
\defskip medskip
\quotes_language english
\quotes_times 2
\papercolumns 1
\papersides 1
\paperpagestyle plain
\layout Title
Documentation Project Style Sheet
\layout Author
by John Weiss
\layout Abstract
This article is a style sheet.
It describes, with examples, how the documentation should look and sound.
The first few sections explain the font conventions and typography conventions
all documentation writers should follow.
Those sections also contain examples.
It also explains the purpose of each of the different manuals.
Follow it not merely to the letter, but also in spirit.
\layout Abstract
The Style Sheet for LyX documentation [hereafter known as the Style Sheet]
applies to
\emph on
all
\emph default
forms of LyX documenation, regardless of language.
There is a section for translators in the Style Sheet, towards the end.
\emph on
Read the entire Style Sheet!
\emph default
Even if you are a translator, I assume you know enough English to comprehend
this document.
\layout Section
Version
\layout Standard
All documenters and translators should be using version 1.0.1 or later as
of April 1, 1999.
\layout Section
Fonts
\layout Standard
Since this is the easiest section, I'll start here.
\layout Standard
This is how you should fontify text in the manuals:
\layout List
\labelwidthstring MMMMMMMM
\emph on
Emphasized
\emph default
general emphasis, generic arguments, titles of books, names the other manuals
and of their sections, and notes from the authors
\begin_deeper
\layout Standard
Do not overemphasize your text.
\end_deeper
\layout List
\labelwidthstring MMMMMMMM
\family typewriter
Typewriter
\family default
program names, file names,
\family typewriter
man
\family default
-page names, LaTeX code, LaTeX commands, LaTeX package names, and LyX code
and functions
\layout List
\labelwidthstring MMMMMMMM
\family sans
Sans
\protected_separator
Serif
\family default
menu, button, or popup names, the names/lables of all widgets in a popup,
the names of keyboard keys, and certain
\begin_inset Quotes eld
\end_inset
special terms
\begin_inset Quotes erd
\end_inset
\layout List
\labelwidthstring MMMMMMMM
\noun on
Noun
\protected_separator
Style
\noun default
people's names
\layout List
\labelwidthstring MMMMMMMM
\family sans
\bar under
U
\bar default
nderlined
\protected_separator
Sans
\protected_separator
Serif
\family default
Rich Fields added this to mimick the underlining of letters in the menus
and on buttons.
It helps to highlight the accelerator keys, and human brains store information
best when they see it frequently.
\begin_deeper
\layout Description
\bar under
WARNING!
\bar default
--- When you do this, make sure you
\emph on
only
\emph default
shut off the underlining.
Too many people send in things that look like:
\newline
\family sans
\bar under
T
\family default
\bar default
his
\newline
\SpecialChar \ldots{}
i.
\protected_separator
e.
\protected_separator
they not only shut off underlining, they turned off sans-serif, too!
\emph on
Don't do that!
\emph default
Make sure the entire word is still in
\family sans
Sans-Serif
\family default
after you shut off the underlining.
\end_deeper
\layout List
\labelwidthstring MMMMMMMM
\series bold
Bold
\series default
Unused.
\begin_deeper
\layout Standard
If you want to emphasize any text, use
\emph on
Emphasized
\emph default
.
LaTeX will put many things boldface on its own, such as
\family sans
Section
\family default
s, certain parts of equations, et cetera.
\layout Standard
Repeat: do not use boldface.
\end_deeper
\layout Standard
Here are some examples:
\layout Enumerate
The function
\family typewriter
math-mode
\family default
appears in configuration files and in the LyX source.
Therefore, it [and all other LyX function names] count as code and is set
in
\family typewriter
Typewriter
\family default
.
\layout Enumerate
However,
\family sans
\bar under
M
\bar default
ath
\protected_separator
mode
\family default
is a menu item in the
\family sans
\bar under
M
\bar default
ath
\family default
menu, so it appears in
\family sans
Sans
\protected_separator
Serif
\family default
.
Notice the use of
\family sans
\bar under
U
\bar default
nderlined
\protected_separator
Sans
\protected_separator
Serif
\family default
for the accelerator keys.
\layout Enumerate
Consider the following excerpt from the introduction of one of the manuals:
\begin_deeper
\layout Quotation
\family sans
Return
\family default
and
\family sans
Enter
\family default
both refer to the same key.
Some keyboards label the
\family sans
Return
\family default
key as
\begin_inset Quotes eld
\end_inset
Return,
\begin_inset Quotes erd
\end_inset
others as
\begin_inset Quotes eld
\end_inset
Enter,
\begin_inset Quotes erd
\end_inset
still others have two keys.
LyX treats all of them as the same key, so we'll use
\family sans
Return
\family default
and
\family sans
Enter
\family default
interchangeably.
\layout Standard
Notice that the key name,
\family sans
Return
\family default
, is in
\family sans
Sans
\protected_separator
Serif
\family default
, but
\emph on
only
\emph default
when it references the key itself! When I described how the manufacturer
chose to label its keyboard, I used Roman and put the word in quotes.
There is a semantic difference.
\end_deeper
\layout Enumerate
Take the following command:
\begin_deeper
\layout Standard
\family typewriter
lpr -P
\family default
\emph on
printername
\layout Standard
Notice that the argument to the
\family typewriter
-P
\family default
option is in
\emph on
Roman Italics
\emph default
[i.e.
emphasized].
This is a case where you don't use
\family typewriter
Typewriter
\family default
for code, because you want the generic argument label to stand out.
On the other hand, if you were specifying an argument, for example,
\begin_inset Quotes eld
\end_inset
\family typewriter
lpr -Pduaneps
\family default
\begin_inset Quotes erd
\end_inset
, you'd leave it in
\family typewriter
Typewriter
\family default
.
\end_deeper
\layout Enumerate
Any LaTeX commands and code, and any
\emph on
unsupported
\emph default
LaTeX package names get set in
\family typewriter
Typewriter
\family default
.
For example,
\begin_inset Quotes eld
\end_inset
\family typewriter
multicol
\family default
\begin_inset Quotes erd
\end_inset
is the name of an unsupported LaTeX package, but
\begin_inset Quotes eld
\end_inset
\family sans
book
\family default
\begin_inset Quotes erd
\end_inset
is a supported LaTeX class.
\layout Section
Special Typography
\layout Standard
Do the following:
\layout Description
Multi-word
\protected_separator
names Use a
\family sans
Protected
\protected_separator
Blank
\family default
between the words for menu and widget names.
E.
\protected_separator
g.:
\family sans
Save
\protected_separator
As
\family default
, not
\family sans
Save As
\family default
.
\begin_deeper
\layout Standard
This holds for things in
\family typewriter
Typewriter
\family default
as well as
\family sans
Sans
\protected_separator
Serif
\family default
, with one caveat.
If you have a long code example, one that can't simply be inlined and put
in
\family typewriter
Typewriter
\family default
, put that in a
\family sans
LyX
\protected_separator
Code
\family default
environment.
\layout Standard
I want the
\family sans
Protected
\protected_separator
Blank
\family default
so that the name doesn't get split between two lines, which is visually
disruptive.
If something with a
\family sans
Protected
\protected_separator
Blank
\family default
is near the end of a line and overflows the margin, use a
\family typewriter
\backslash
sloppypar
\family default
in that parargraph [consult a LaTeX book for more about
\begin_inset Quotes eld
\end_inset
\family typewriter
\backslash
sloppypar
\family default
\begin_inset Quotes erd
\end_inset
] or manually add a hypenation point.
\end_deeper
\layout Description
Special
\protected_separator
Terms These are things like the following:
\begin_deeper
\layout Itemize
\family sans
HFill
\family default
\layout Itemize
\family sans
VFill
\family default
\layout Itemize
\family sans
Table
\protected_separator
Float
\layout Itemize
\family sans
Figure
\protected_separator
Float
\begin_deeper
\layout Standard
Use
\family sans
Sans
\protected_separator
Serif
\family default
font and, in the case of
\family sans
HFill
\family default
and
\family sans
VFill
\family default
, capitalize the first two letters.
\layout Standard
Why are these terms special? They are concepts which the seasoned LaTeX-pert
is familiar with, but which the new LyX user is not.
I want them to stand out from the rest of the text, hence the use of
\family sans
Sans
\protected_separator
Serif
\family default
for them.
\end_deeper
\end_deeper
\layout Description
Terminology Note the following:
\layout Itemize
PostScript� is a registered trademark of Adobe Corp.
\emph on
You must put the � after it or we'll get sued!
\emph default
I also want it written as seen here, always capitalized.
Not
\begin_inset Quotes eld
\end_inset
postscript�,
\begin_inset Quotes erd
\end_inset
or
\begin_inset Quotes eld
\end_inset
Postscript�
\begin_inset Quotes erd
\end_inset
but
\begin_inset Quotes eld
\end_inset
PostScript�
\begin_inset Quotes erd
\end_inset
- both of them capitalized, in the default font [i.
\protected_separator
.e.
\protected_separator
Roman].
If you must, cut and paste it from here.
\begin_deeper
\layout Standard
I am going to say this again:
\layout Standard
\added_space_top 0.37cm \added_space_bottom 0.51cm \align center
\size larger
\emph on
You must put the � after PostScript� or we'll get sued!
\layout Standard
I mean it! American companies like to sue anything that moves.
If LyX gets in trouble because
\emph on
you
\emph default
forgot the �, I will come after you with a running chainsaw.
Got it?
\end_deeper
\layout Itemize
It's a
\bar under
popup
\bar default
;
\begin_inset Quotes eld
\end_inset
widget
\begin_inset Quotes erd
\end_inset
and
\begin_inset Quotes eld
\end_inset
dialog box
\begin_inset Quotes erd
\end_inset
are programmer terms, so don't use them.
\layout Itemize
The word
\begin_inset Quotes eld
\end_inset
popup
\begin_inset Quotes erd
\end_inset
should be in Roman.
There should be no
\family sans
Protected
\protected_separator
Blank
\family default
between the popup's name and the word
\begin_inset Quotes eld
\end_inset
popup.
\begin_inset Quotes erd
\end_inset
Example:
\begin_inset Quotes eld
\end_inset
\SpecialChar \ldots{}
\family sans
Paragraph
\protected_separator
Layout
\family default
popup\SpecialChar \ldots{}
\begin_inset Quotes erd
\end_inset
.
Anything else is
\emph on
wrong.
\layout Itemize
The thing below the menu and above the editing window is the
\bar under
toolbar
\bar default
.
\begin_deeper
\layout Standard
As for the terms
\begin_inset Quotes eld
\end_inset
popup
\begin_inset Quotes erd
\end_inset
and
\begin_inset Quotes eld
\end_inset
toolbar
\begin_inset Quotes erd
\end_inset
, if at some point I [or a future editor] need to change those,
\emph on
I'll
\emph default
take care of that.
That's the editor's job, after all.
I want all of you, however, to use those terms.
It will make any future switch much, much easier for the either me or my
successor(s).
\end_deeper
\layout Description
Menu
\protected_separator
Items When quick-referencing an item in a menu, use the menu separator:
\begin_inset Quotes eld
\end_inset
\SpecialChar \menuseparator
\begin_inset Quotes erd
\end_inset
.
Example:
\family sans
File\SpecialChar \menuseparator
Save
\family default
.
Notice that there are
\emph on
no spaces
\emph default
around the
\begin_inset Quotes eld
\end_inset
\SpecialChar \menuseparator
\begin_inset Quotes erd
\end_inset
and that it's in
\family sans
Sans
\protected_separator
Serif
\family default
, just like the menu and item names.
\begin_deeper
\layout Enumerate
The reason why I want no spaces around the
\begin_inset Quotes eld
\end_inset
\SpecialChar \menuseparator
\begin_inset Quotes erd
\end_inset
is to prevent LyX from splitting terms across lines.
The same goes for using
\family sans
Protected
\protected_separator
Blank
\family default
s between multi-word terms.
The split would be visually disruptive.
\layout Enumerate
A
\begin_inset Quotes eld
\end_inset
\SpecialChar \menuseparator
\begin_inset Quotes erd
\end_inset
goes between menu names and item names
\emph on
only
\emph default
.
[Yes, submenus are okay, too].
\layout Enumerate
\emph on
NEVER
\emph default
put
\begin_inset Quotes eld
\end_inset
\SpecialChar \menuseparator
\begin_inset Quotes erd
\end_inset
between menu items and popup names.
Example:
\begin_inset Quotes eld
\end_inset
\family sans
\bar under
L
\bar default
ayout\SpecialChar \menuseparator
P
\bar under
a
\bar default
per\SpecialChar \menuseparator
Paper
\protected_separator
Popup
\family default
\begin_inset Quotes erd
\end_inset
\emph on
IS STRICTLY FORBIDDEN!
\emph default
\begin_deeper
\layout Standard
Use
\begin_inset Quotes eld
\end_inset
\SpecialChar \ldots{}
the
\family sans
Paper
\family default
popup [opened via
\family sans
\bar under
L
\bar default
ayout\SpecialChar \menuseparator
P
\bar under
a
\bar default
per
\family default
]\SpecialChar \ldots{}
\begin_inset Quotes erd
\end_inset
or something similar.
If you mentioned how to open the popup in an earlier sentence, someplace
else in the paragraph, you needn't do it repeatedly.
\end_deeper
\layout Enumerate
\emph on
NEVER
\emph default
put
\begin_inset Quotes eld
\end_inset
\SpecialChar \menuseparator
\begin_inset Quotes erd
\end_inset
between popup names and any popup widget.
Example:
\begin_inset Quotes eld
\end_inset
\family sans
Paper
\protected_separator
Popup\SpecialChar \menuseparator
P
\bar under
o
\bar default
rtrait
\family default
\begin_inset Quotes erd
\end_inset
\emph on
IS STRICTLY FORBIDDEN!
\begin_deeper
\layout Standard
Use
\begin_inset Quotes eld
\end_inset
\SpecialChar \ldots{}
the
\family sans
P
\bar under
o
\bar default
rtrait
\family default
button on the
\family sans
Paper
\family default
popup\SpecialChar \ldots{}
\begin_inset Quotes erd
\end_inset
or something similar.
If it's clear where the button is, you don't need to keep repeating the
popup's name.
\end_deeper
\layout Enumerate
\emph on
NEVER
\emph default
put
\begin_inset Quotes eld
\end_inset
\SpecialChar \menuseparator
\begin_inset Quotes erd
\end_inset
between menu items and any popup widget.
Example:
\begin_inset Quotes eld
\end_inset
\family sans
\bar under
L
\bar default
ayout\SpecialChar \menuseparator
P
\bar under
a
\bar default
per\SpecialChar \menuseparator
P
\bar under
o
\bar default
rtrait
\family default
\begin_inset Quotes erd
\end_inset
\emph on
IS STRICTLY FORBIDDEN!
\begin_deeper
\layout Standard
If you really, really need to name a widget, the popup its on, and the menu
item used to open the popup, then write it out:
\begin_inset Quotes eld
\end_inset
\SpecialChar \ldots{}
the
\family sans
P
\bar under
o
\bar default
rtrait
\family default
button [on the
\family sans
Paper
\family default
popup, opened using
\family sans
\bar under
L
\bar default
ayout\SpecialChar \menuseparator
P
\bar under
a
\bar default
per
\family default
]\SpecialChar \ldots{}
\begin_inset Quotes erd
\end_inset
\end_deeper
\end_deeper
\layout Description
Note
\protected_separator
Boxes LyX has a feature for adding comments to a popup that appear only
within the LyX GUI.
Here's one:
\begin_inset Info These should NEVER appear in the manuals.
\end_inset
.
You will see nothing in a printout of the Style Sheet.
Therefore, they have no place in the manuals.
Period.
If you have a parenthetical comment you want to make, the reader should
see it too.
Use an Author's Note [see section
\begin_inset LatexCommand \ref{sec:author-notes}
\end_inset
] in place of the Note-Boxes [or whatever they're called].
\layout Section
Keys
\layout Standard
The canonical keyboard contains these keys:
\layout Itemize
\family sans
C-
\family default
or
\family sans
Control-
\family default
\layout Itemize
\family sans
S-
\family default
or
\family sans
Shift-
\family default
\layout Itemize
\family sans
M-
\family default
or
\family sans
Meta-
\family default
\begin_deeper
\layout Standard
Self-explanatory.
Be lazy and
\emph on
use the abbreviations
\emph default
whenever possible.
\end_deeper
\layout Itemize
\family sans
F1 F2 F3 F4 F5 F6 F7 F8 F9 F10 F11 F12
\begin_deeper
\layout Standard
The function keys.
Most modern keyboards have all 12.
\end_deeper
\layout Itemize
\family sans
Esc
\family default
\begin_deeper
\layout Standard
The
\begin_inset Quotes eld
\end_inset
Escape key.
\begin_inset Quotes erd
\end_inset
\end_deeper
\layout Itemize
\family sans
Insert
\family default
\family sans
Delete
\family default
\family sans
Home
\family default
\family sans
End
\family default
\family sans
PageUp
\family default
\family sans
PageDown
\begin_deeper
\layout Standard
These are the 6 keys that appear above the cursor keys on many PC keyboards.
Consider them as part of the standard motion keys.
\end_deeper
\layout Itemize
\family sans
Left Right Up Down
\begin_deeper
\layout Standard
The four standard motion keys.
There is no need to put the word
\begin_inset Quotes eld
\end_inset
arrow
\begin_inset Quotes erd
\end_inset
anywhere, since that's obvious.
\begin_float footnote
\end_deeper
\layout Standard
Same goes for
\begin_inset Quotes eld
\end_inset
cursor key
\begin_inset Quotes erd
\end_inset
.
Even the word
\begin_inset Quotes eld
\end_inset
key
\begin_inset Quotes erd
\end_inset
after one of these may be redundant in certain situations.
\end_float
\layout Itemize
\family sans
Return
\family default
and
\family sans
Enter
\family default
\begin_deeper
\layout Standard
I won't throw a hissy fit if you use one instead of the other.
I'd prefer if you used
\family sans
Return
\family default
over
\family sans
Enter
\family default
, but it's okay if you slip up and forget.
Since these two keys are bound to the same function in LyX, it doesn't
really matter.
\end_deeper
\layout Standard
You do not need to explain everywhere what the
\family sans
Meta
\family default
key is or where the
\family sans
Left
\family default
key is, et cetera.
The user isn't stupid.
Also, someone will document anything that isn't clear [e.
\protected_separator
g.
\protected_separator
the
\family sans
Meta
\family default
vs.
\family sans
Alt
\family default
problem] someplace in the introduction.
No need for you to repeat someone else's work.
\layout Standard
LyX does not support kyboards missing any of the keys described above, with
one exception.
LyX can support a keyboard missing
\family sans
F11
\family default
and
\family sans
F12
\family default
.
There is a keyboard accelerator for
\family sans
F10
\family default
, but this is the only function key LyX assumes exists.
Nevertheless, these details are of minor, if any, concern for the documentation.
Assume the aforementioned keys exist.
\layout Section
Mice
\layout Standard
The word
\begin_inset Quotes eld
\end_inset
mouse
\begin_inset Quotes erd
\end_inset
and any description of the 3 mice buttons have no special handling.
Don't typeset them in any other font than the default, which is Roman.
Exception: you're writing an Author's Note [see section
\begin_inset LatexCommand \ref{sec:author-notes}
\end_inset
] and you need to mention something about the mouse.
Since the rest of the note is in
\emph on
Emphasized
\emph default
, your description of
\begin_inset Quotes eld
\end_inset
middle mouse button
\begin_inset Quotes erd
\end_inset
should be emphasized, as well.
There are a couple of other cases like this one; use your judgement.
\layout Standard
There are only 3 mouse buttons.
The use of them and of the mouse itself is obvious.
There are few nonstandard things we do with the mouse.
Therefore, there's no need to make the word
\begin_inset Quotes eld
\end_inset
mouse
\begin_inset Quotes erd
\end_inset
or
\begin_inset Quotes eld
\end_inset
mouse button
\begin_inset Quotes erd
\end_inset
stand out.
\layout Section
Cross-References and Labels
\layout Standard
Use the following labelling conventions:
\layout List
\labelwidthstring 00.00.0000
sec:xxx Use this for
\family sans
Section
\family default
s as well as
\family sans
Chapter
\family default
s,
\family sans
Subsection
\family default
s,
\family sans
Subsubsection
\family default
s, etc.
\layout List
\labelwidthstring 00.00.0000
eqn:xxx Use this for Equations, should you need to create any.
\layout List
\labelwidthstring 00.00.0000
tbl:xxxx Use this for tables inside of a table float.
\layout List
\labelwidthstring 00.00.0000
fig:xxx Use this for figures inside of figure floats.
\layout Standard
Additionally, you should put the label at one of two locations:
\layout Enumerate
The
\emph on
beginning of the paragraph
\emph default
, after a section heading, or at the beginning of captions, etc.
It should be the first thing on the first line.
Don't put a space betweeen it and the first word.
\layout Enumerate
If there is no paragraph after a section heading, put it at the
\emph on
end of the last line.
\emph default
\begin_deeper
\layout Standard
Example: You have a
\family sans
Section
\family default
which is immediately followed by a
\family sans
Subsection
\family default
heading.
This is a case where you need to put the label at the end of the
\family sans
Section
\family default
heading.
I know it looks ugly; not much we can do about that, though.
\end_deeper
\layout Section
Content - What Goes Where
\layout Standard
This is
\emph on
very
\emph default
important, so PAY ATTENTION!
\layout Standard
I do not want
\family typewriter
Tutorial.lyx
\family default
,
\family typewriter
Reference.lyx
\family default
, and
\family typewriter
UserGuide.lyx
\family default
to all repeat the same dumbed-down drivel, like the manuals for certain
commercial wordprocessors do.
That's useless.
It's a waste of our time, too.
I want the manuals to dovetail together, to interface with one another.
In principle, we use
\family typewriter
Reference.lyx
\family default
as a base and build the others on it.
\layout Standard
You see, in the past, whenever someone wanted to document a new feature
they added, they either wrote a mini-doc and stuck it into the documentation
directory, or they added a new section to
\family typewriter
Main.lyx
\family default
.
They tried to explain what their new feature did, but then needed to explain
how to bind keys to it, how to use it, provide examples,
\layout Quote
...and on
\layout Quote
...and on
\layout Quote
...and on.
\layout Standard
The result was a totally bloated, totally unnavigable
\family typewriter
Main.lyx
\family default
.
I wanted to change, which is why I ended up as editor of the DocTeam.
In that time, I started a major reworking, which included the writing of
\family typewriter
UserGuide.lyx
\family default
, over half of which is my own work.
I don't want all that work to be for nothing.
I don't want the docs to fall back into a mess.
\layout Standard
With that in mind, I have some instructions for how to keep things organized:
\layout List
\labelwidthstring 00.00.0000
\family typewriter
Intro.lyx
\family default
Please, don't touch this file.
It's essentially complete, anyhow.
Only the editor(s) should make changes to this, as this file contains info
about how to contribute to the doc project.
That's really the only stuff that should need to change, and even then,
only when a new maintainer comes along.
\layout List
\labelwidthstring 00.00.0000
\family typewriter
UserGuide.lyx
\family default
This file is complete.
Any changes should be for updates
\emph on
only
\emph default
.
DO NOT ADD new features to here willy-nilly.
Let the editor decide if --- and when --- new sections go in here.
Place any new features in\SpecialChar \ldots{}
\layout List
\labelwidthstring 00.00.0000
\family typewriter
Extended.lyx
\family default
This is where all new features go from now on.
It's in the style of a bound journal --- each section is an
\begin_inset Quotes eld
\end_inset
article
\begin_inset Quotes erd
\end_inset
from the author of the feature.
Also, anyone who writes a
\family typewriter
.layout
\family default
file for a new document class should write a section describing that new
class and how to use it.
That also goes here.
\begin_deeper
\layout Standard
Note, however, that you are
\emph on
not
\emph default
excused from following this Style Sheet just because the sections of
\family typewriter
Extended.lyx
\family default
are in the form of a journal article.
\end_deeper
\layout List
\labelwidthstring 00.00.0000
\family typewriter
Tutorial.lyx
\family default
This file is complete.
Do not change or add to without permission of the Documenation Project
editor.
\layout List
\labelwidthstring 00.00.0000
\family typewriter
Customization.lyx
\family default
It's a mess.
Complete disaster! [
\emph on
sob
\emph default
!]
\newline
Someday, a complete description of how to write new
\family typewriter
.layout
\family default
files will be in here.
And a description of the new
\family typewriter
.lyxrc
\family default
format.
And a description of how to tailor LyX for use with languages other than
English, or how to use LyX in a multi-lingual setting.
And how to customize your keyboard bindings.
Plenty of stuff to do!
\layout List
\labelwidthstring 00.00.0000
\family typewriter
Reference.lyx
\family default
I'd prefer to completely finish this one before doing anything else, but
that's unrealistic.
LyX keeps changing so much that I think the
\emph on
Reference Manual
\emph default
will be the last one completed.
However, I'd like it if the developer's would add entries anytime they
create a new function or popup.
That would help things immensely!
\layout Section
Writing Style: The Primary Manuals
\layout Standard
While I want to make contributing to the Documentation Project as painless
as possible for newcomers, I also want the newcomers to be painless on
the existing Documentation Team! Ergo, I've written this section to give
some flavor to guide everyone's individual style.
\layout Subsection
Language
\layout Standard
All contributions to the
\emph on
primary
\emph default
LyX documentation must be in English.
I don't care if it's British, Australian, or American English.
The DocTeam editor will proofread for glaring mistakes and fix them.
\layout Standard
Don't get hung up on semantics.
English is a flexible language, and just because your Mothertongue-to-English
dictionary gives only one translation for a word doesn't necessarily mean
it's so.
We've had some discussions and misunderstandings on the Developers' List
because of this very problem.
If something is unclear [or just plain weird] due to a translation problem,
one of the American/British/Australian developers can fix it.
\layout Standard
Nota Bene: by
\emph on
primary
\emph default
documentation, I exclude the translations.
Right now, we don't have enough people to cover the manuals in one language,
let alone more than one.
Subsequently, the tranlsations tend to be just that --- translations of
the English version of the LyX manuals.
The translation efforts require have their own set of guidelines.
See section
\begin_inset LatexCommand \ref{sec:translations}
\end_inset
for more info.
\layout Subsection
General Stylistic Guidelines
\layout Standard
Everything in this section is
\emph on
mandatory to all documenters
\emph default
, regardless the language you're writing in.
\layout Subsubsection
Typography
\layout Enumerate
Use the typography rules outlined in the beginning sections of this document.
\layout Enumerate
Don't, however, mimic the typography of this file.
Yes, the Style Sheet doesn't follow the Style Sheet [grin].
\layout Enumerate
There is some typographic freedom in those rules in earlier sections.
Use that freedom wisely.
Most importanly, never sacrifice the online appearance for the printed
appearance and vice versa.
\begin_deeper
\layout Standard
An example is in the
\emph on
User's Guide
\emph default
.
There is a footnote using the
\family typewriter
multcols
\family default
command to divide a long
\family sans
Itemize
\family default
environment into 3 columns.
It adds some LaTeX commands to the online version, the so-called
\begin_inset Quotes eld
\end_inset
Evil Red Text
\begin_inset Quotes erd
\end_inset
that some so vehemently oppose.
Without it, however, that footnote takes up over two pages, most of which
is empty space.
This is an example of permitting a little ugliness in the online version
to get the printed version to look right.
\layout Standard
The old menu separator,
\begin_inset Quotes eld
\end_inset
->
\begin_inset Quotes erd
\end_inset
, was another example.
The characters
\begin_inset Quotes eld
\end_inset
->
\begin_inset Quotes erd
\end_inset
didn't look all that great in printed versions.
Online, however, it was a reasonable approximation of an arrow regardless
of screen font.
This is a case where the printed version took a slight appearance hit for
the benefit of the online version.
\begin_float footnote
\end_deeper
\layout Standard
Note that we have simce replaced the
\begin_inset Quotes eld
\end_inset
->
\begin_inset Quotes erd
\end_inset
characters with the true menu separator,
\begin_inset Quotes eld
\end_inset
\SpecialChar \menuseparator
\begin_inset Quotes erd
\end_inset
.
\end_float
\layout Enumerate
When in doubt, compromise.
\begin_deeper
\layout Standard
When in doubt, use good judgement.
\end_deeper
\layout Subsubsection
Semantics
\layout Enumerate
You are
\begin_inset Quotes eld
\end_inset
we
\begin_inset Quotes erd
\end_inset
.
\begin_deeper
\layout Standard
When you speak, you speak for the entire LyX Team, so use
\begin_inset Quotes eld
\end_inset
we
\begin_inset Quotes erd
\end_inset
instead of
\begin_inset Quotes eld
\end_inset
I
\begin_inset Quotes erd
\end_inset
.
\end_deeper
\layout Enumerate
The reader is
\begin_inset Quotes eld
\end_inset
you
\begin_inset Quotes erd
\end_inset
.
\begin_deeper
\layout Standard
Whenever you want to say something to the reader, use
\begin_inset Quotes eld
\end_inset
you,
\begin_inset Quotes erd
\end_inset
not some contorted construction to avoid being too informal.
\end_deeper
\layout Enumerate
Use the term
\begin_inset Quotes eld
\end_inset
mouse
\begin_inset Quotes erd
\end_inset
for both the physical pointing object [mouse, joystick, touch pad, track
ball, etc.] and the mouse cursor which the physical object moves about the
screen.
\layout Enumerate
Use the term
\begin_inset Quotes eld
\end_inset
cursor
\begin_inset Quotes erd
\end_inset
for the little blinking vertical bar that indicates where text can/will
appear next.
\layout Enumerate
When in doubt, compromise.
\begin_deeper
\layout Standard
When in doubt, use good judgement.
\end_deeper
\layout Subsubsection
Commentary from the Author [i.
\protected_separator
e.: You]
\layout Standard
\begin_inset LatexCommand \label{sec:author-notes}
\end_inset
I want to make it easy for everyone when it comes to documenting things.
Some features are incomplete.
Some you might not know everything about.
Sometimes, you may want to comminucate something to me or the reader or
other DocTeam members.
Sometimes, you may want to
\begin_inset Quotes eld
\end_inset
speak for yourself;
\begin_inset Quotes erd
\end_inset
you want to say something that is your personal opinion and using
\begin_inset Quotes eld
\end_inset
we
\begin_inset Quotes erd
\end_inset
would be inappropriate.
\layout Standard
For occasions like those, I've designed two mechanisms:
\layout Description
Personal
\protected_separator
Notes: These are footnotes.
They begin with the following:
\begin_deeper
\layout Standard
\begin_inset Quotes eld
\end_inset
Note from
\noun on
Name of Person
\noun default
:
\begin_inset Quotes erd
\end_inset
\layout Standard
\SpecialChar \ldots{}
using the
\noun on
Noun Style
\noun default
for the person's name and without the quotes.
The rest of the footnote is the actual comment.
If the comment is too large to put in a footnote, put it in a
\family sans
Quotation
\family default
paragraph environment instead.
\layout Standard
Use these when you need to quote a comment by someone, and want to identify
that person.
\end_deeper
\layout Description
Author's
\protected_separator
Notes: These go in the body of the text, in brackets.
The bracket are in the defaul character style, but the note itself is emphasize
d.
Begin with the words,
\begin_inset Quotes eld
\end_inset
\emph on
Author's Note:
\emph default
\begin_inset Quotes erd
\end_inset
and end with
\begin_inset Quotes eld
\end_inset
---
\begin_inset Quotes eld
\end_inset
followed by your initials.
Here's an example: [
\emph on
Author's Note: This is an example note.
---jw
\emph default
].
\begin_deeper
\layout Standard
You should use these for the following purposes:
\layout Itemize
You need to contradict something you just wrote because the feature isn't
quite ready yet, but you want to document what it will do.
\layout Itemize
You need to leave a note for yourself.
\layout Itemize
You need to leave a note for the editor or the other DocTeam members.
\layout Itemize
You need to point something out to the reader that doesn't fit into the
context of the current paragraph.
\end_deeper
\layout Standard
You are also free to use footnotes on their own in addition to the personal
notes and/or author's notes.
I've frequently used footnotes to \SpecialChar \ldots{}
well, to comment on parts of a section
without putting the commentary into the body of the text.
\layout Subsubsection
Coverage
\layout Standard
When describing a new feature or
\family typewriter
*.layout
\family default
file, be sure to:
\layout Enumerate
Be
\emph on
clear, concise,
\emph default
and
\emph on
to the point
\emph default
.
KISS =
\begin_inset Quotes eld
\end_inset
Keep It Short and Sweet
\begin_inset Quotes erd
\end_inset
[or,
\begin_inset Quotes eld
\end_inset
Keep It Simple, Stupid!
\begin_inset Quotes erd
\end_inset
]
\begin_deeper
\layout Itemize
Do
\emph on
not
\emph default
write paragraph after paragraph of verbage.
\layout Itemize
Get to the point.
\layout Itemize
Take a look at the manual for a commercial word processor --- it's a fine
example of how
\series bold
NOT
\series default
to write documentation.
It's all pithy, substanceless verbage, and its
\emph on
utterly useless!
\emph default
\end_deeper
\layout Enumerate
Avoid being pedantic like The Plauge!
\layout Enumerate
In the same vein, don't write more than you have to.
You're not working in a vacuum --- refer freely to other parts of the manual
[and other parts of other manuals].
Even if that
\begin_inset Quotes eld
\end_inset
other part of the manual
\begin_inset Quotes erd
\end_inset
is incomplete or empty, refer to it.
Someone will fill it in.
\layout Enumerate
On the other hand, BE THOROUGH!
\begin_deeper
\layout Enumerate
You are documenting
\emph on
features
\emph default
, not widgets, not how the source code is organized.
\layout Enumerate
Stay on topic --- one
\family sans
Section
\family default
should cover
\emph on
one
\emph default
feature.
Use
\family sans
Subsection
\family default
s and further subdivisions to group things if you're documenting several
related features in a single
\family sans
Section
\family default
.
\layout Enumerate
Describe EVERYTHING related to that feature, no matter where it is.
\begin_deeper
\layout Enumerate
Example: Paragraph Indenting.
Several popups control its behavior.
You would document
\emph on
all
\emph default
of this: which popups control it, when you use which setting on which popup
to do which operation, et cetera, et cetera, et cetera.
\layout Enumerate
Note from
\noun on
John Weiss
\noun default
:
\newline
I've had people only document one popup --- literally.
This added off-topic information and only described half of the feature,
since other menus, popups, and even unbound functions contained additional
stuff.
\newline
I get
\emph on
really
\emph default
cranky when that happens, because it means
\emph on
I
\emph default
end up fixing it.
Bad help is worse than no help at all.
\begin_deeper
\layout Standard
These remarks still hold true: you'll piss of the DocTeam editor if you
do things wrong, because he'll have to fix your mistakes.
\end_deeper
\end_deeper
\layout Enumerate
Remember, there are people who will reference
\emph on
your
\emph default
section, just as you're referencing someone else's.
You do want what you write to be useful, don't you?
\end_deeper
\layout Enumerate
When in doubt, compromise.
\begin_deeper
\layout Standard
When in doubt, use good judgement.
\end_deeper
\layout Subsubsection
NEVER NEVER
\emph on
NEVER EVER
\emph default
Treat the Reader as if She is Stupid
\layout Enumerate
No dumbing-down!
\layout Enumerate
No talking down to the reader!
\layout Enumerate
The reader is smart enough to know what a mouse is.
\layout Enumerate
The reader is smart enough to know how to use a keyboard, including the
\family sans
Shift-
\family default
,
\family sans
Control-
\family default
, and
\family sans
Meta-
\family default
keys.
[
\emph on
I
\emph default
explain that
\family sans
Meta-
\family default
is the
\family sans
Alt-
\family default
key on many keyboards in the introductions of every one of the manuals,
so you don't need to.]
\layout Enumerate
The reader is smart enough to know that
\begin_inset Quotes eld
\end_inset
at the cursor
\begin_inset Quotes erd
\end_inset
means
\begin_inset Quotes eld
\end_inset
where the text cursor is sitting right now, in the buffer currently visible.
\begin_inset Quotes erd
\end_inset
\size small
[Anything more than the word
\begin_inset Quotes eld
\end_inset
cursor
\begin_inset Quotes erd
\end_inset
is, IMO, superfluous and I will delete it.
So, save yourself the typing, save me the editing, and save the reader
the strain of sifting through extra verbage that adds no content.]
\layout Enumerate
Rule of thumb: the reader is not an imbecile.
The reader is merely lost; point them in the right direction, and they
can take it from there.
\layout Subsection
Tips for the English Version
\layout Standard
When contributing to the primary --- i.
\protected_separator
e.
\protected_separator
the English language version --- of the LyX manuals, keep the following
in mind.
\layout Subsubsection
Write as if You're Talking with a Friend.
\layout Enumerate
Think that way when you write.
Play the dialogue in your mind.
\layout Enumerate
Be as informal as you please [without being rude].
\layout Subsubsection
AVOID the Passive Voice
\layout Enumerate
No:
\begin_inset Quotes eld
\end_inset
It is felt that this name best explains the command's purpose.
\begin_inset Quotes erd
\end_inset
You know full well who wrote the command:
\begin_inset Quotes eld
\end_inset
The LyX Team felt ...
\begin_inset Quotes erd
\end_inset
Or, better yet,
\begin_inset Quotes eld
\end_inset
We felt that ...
\begin_inset Quotes erd
\end_inset
\layout Enumerate
Things don't happen by magic - somebody or something did it.
Only politicians use the passive voice to cover up actions.
If LyX reformats a paragraph, write,
\begin_inset Quotes eld
\end_inset
LyX reformatted the paragraph.
\begin_inset Quotes erd
\end_inset
If
\family typewriter
ispell
\family default
makes changes, write,
\begin_inset Quotes eld
\end_inset
\family typewriter
ispell
\family default
changes the document.
\begin_inset Quotes erd
\end_inset
\begin_deeper
\layout Standard
Rule of thumb: any sentence you can express as,
\begin_inset Quotes eld
\end_inset
It was done by foo,
\begin_inset Quotes erd
\end_inset
you can express as,
\begin_inset Quotes eld
\end_inset
Foo did it.
\begin_inset Quotes erd
\end_inset
Much nicer.
\end_deeper
\layout Enumerate
I know it's tough.
We all hear way, way too much garbage English on the TV every day in the
passive voice.
Some people think it makes speech better.
It doesn't.
It makes speech byzantine.
With a little effort, you can wean yourself off of it.
\layout Enumerate
I
\emph on
will make you rewrite
\emph default
anything in the passive voice.
It's awkward and hard to read.
\layout Enumerate
Note to non-Americans:
\begin_deeper
\layout Standard
Using passive voice is generally considered bad style in the U.
\protected_separator
S.
\protected_separator
as it is too easy to obfuscate your words with it.
It also bloats sentences, often unnecessarily.
\end_deeper
\layout Subsubsection
Short Sentences.
Short Paragraphs.
\layout Standard
In English, there is a grammatical error known as the
\begin_inset Quotes eld
\end_inset
run-on sentence.
\begin_inset Quotes erd
\end_inset
Those of us who grew up with English learned in school to avoid stringing
7 clauses together with the word
\begin_inset Quotes eld
\end_inset
and.
\begin_inset Quotes erd
\end_inset
There are, however, less obvious run-on sentences, ones using too many
subordinate clauses.
Such sentences may look elegant because they are complex.
However, they are also extremely difficult to read because they are so
complex.
\layout Standard
In general, stick to short sentences in written English.
Getting rid of passive void [
\begin_inset Quotes eld
\end_inset
\SpecialChar \ldots{}
was done by\SpecialChar \ldots{}
\begin_inset Quotes erd
\end_inset
] shortens and simplifies them.
Hacking apart sentences with many dependent clauses is another way to shorten
sentences.
There are ways to do this yet still have a smooth-flowing paragraph.
\layout Standard
While I'm talking about paragraphs, I'll apply the
\begin_inset Quotes eld
\end_inset
shorter is better
\begin_inset Quotes erd
\end_inset
motto to them.
At the time I started with the manuals [and this Style Sheet], I didn't
pay too much attention to paragraph size.
I've since become a big proponent of short paragraphs, with one idea per
paragraph.
While long, flowing, multi-concept paragraphs can be nice in novels, we're
writing manuals here, folks.
Our goal is rapid information location and comprehension, not a literary
prize.
\layout Standard
There is a single exception to the short sentence, short paragraph rule.
Particularly complex ideas may need more
\begin_inset Quotes eld
\end_inset
breathing room.
\begin_inset Quotes erd
\end_inset
However, you shouldn't encounter such complex ideas often when documenting
LyX.
Try to keep things short, and use your judgement as needed.
\layout Standard
To reiterate, yet again, something I said before:
\layout Quote
When in doubt, compromise.
\layout Quote
When in doubt, use good judgement.
\layout Standard
Hopefully, you've got the idea.
\layout Section
Translations
\layout Standard
\begin_inset LatexCommand \label{sec:translations}
\end_inset
As of version 1.0.*, LyX now has translations of the manuals into several
languages.
These translations are in varying stages of completion.
Since I can speak German fluently [on most days], I decided to give das
deutsche �bersetzung a look.
\layout Standard
\emph on
More to come soon...
\the_end
