Title
Documentation Project Style Sheet Author
by John Weiss Abstract
This article is a style sheet. It describes, with examples, how the documentation should look and sound. It also explains the purpose of each of the different manuals. Section
Fonts Standard
Since this is the easiest section, I'll start here. Standard
This is how you should fontify text in the manuals: List MMMMMMMM
on Emphasized default general emphasis, generic arguments, titles of books, names the other manuals and of their sections, and notes from the authors List MMMMMMMM
typewriter Typewriter default program and file names, LaTeX code, LaTeX commands, LaTeX package names, and LyX code and functions List MMMMMMMM
sans Sans _separator Serif default menu, button, or popup names, the names/lables of all widgets in a popup, the names of keyboard keys, and certain _inset Quotes eld inset
special terms _inset Quotes erd inset
List MMMMMMMM
on Noun _separator Style default people's names List MMMMMMMM
sans ūnder U d̄efault nderlined _separator Sans _separator Serif 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. _deeper Description
ūnder
WARNING!
d̄efault
— When you do this, make sure you
on
only
default
shut off the underlining.
Too many people send in things that look like:
sans
ūnder
T
default
d̄efault
his
...
i.
_separator
e.
_separator
they not only shut off underlining, they turned off sans-serif, too!
on
Don't do that!
default
Make sure the entire word is still in
sans
Sans-Serif
default
after you shut off the underlining.
deeper
Standard
Here are some examples: Enumerate
The function typewriter math-mode 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 typewriter Typewriter default . Enumerate
However, sans ūnder M d̄efault ath _separator mode default is a menu item in the sans ūnder M d̄efault ath default menu, so it appears in sans Sans _separator Serif default . Notice the use of sans ūnder U d̄efault nderlined _separator Sans _separator Serif default for the accelerator keys. Enumerate
Consider the following excerpt from the introduction of one of the manuals: _deeper Quotation
sans Return default and sans Enter default both refer to the same key. Some keyboards label the sans Return default key as _inset Quotes eld inset
Return, _inset Quotes erd inset
others as _inset Quotes eld inset
Enter, _inset Quotes erd inset
still others have two keys. LyX treats all of them as the same key, so we'll use sans Return default and sans Enter default interchangeably. Standard
Notice that the key name, sans Return default , is in sans Sans _separator Serif default , but on only 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. deeper Enumerate
Take the following command: _deeper Standard
typewriter lpr -P default on printername Standard
Notice that the argument to the typewriter -P default option is in on Roman Italics default [i.e. emphasized]. This is a case where you don't use typewriter Typewriter 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, _inset Quotes eld inset
typewriter lpr -Pduaneps default
_inset Quotes erd inset
, you'd leave it in typewriter Typewriter default .
deeper Enumerate
Any LaTeX commands and code, and any on unsupported default LaTeX package names get set in typewriter Typewriter default . For example, _inset Quotes eld inset
typewriter multicol default
_inset Quotes erd inset
is the name of an unsupported LaTeX package, but _inset Quotes eld inset
sans book default
_inset Quotes erd inset
is a supported LaTeX class. Standard
I also have some pointers for you: Description
Multi-word
_separator
names Use a
sans
Protected
_separator
Blank
default
between the words.
E.
_separator
g.:
sans
Save
_separator
As
default
, not
sans
Save As
default
.
I want the
sans
Protected
_separator
Blank
default
so that the name doesn't get split between two lines, which is visually
disruptive.
Description
Special _separator Terms These are things like the following: _deeper Itemize
sans HFill default
Itemize
sans VFill default
Itemize
sans Table _separator Float Itemize
sans Figure _separator Float _deeper Standard
Use sans Sans _separator Serif default font and, in the case of sans HFill default and sans VFill default , capitalize the first two letters. 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 sans Sans _separator Serif default for them. deeper deeper Description
Terminology sans
Itemize
PostScript� is a registered trademark of Adobe Corp.
on You must put the � after it or we'll get sued! default I also want it written as seen here, always capitalized. Not _inset Quotes eld inset
postscript�, _inset Quotes erd inset
or _inset Quotes eld inset
Postscript� _inset Quotes erd inset
but _inset Quotes eld inset
PostScript� _inset Quotes erd inset
- both of them capitalized, in the default font [i. _separator .e. _separator Roman]. If you must, cut and paste it from here. _deeper Standard
I am going to say this again: Standard _space_top 0.37cm _space_bottom 0.51cm center
larger on You must put the � after PostScript� or we'll get sued! Standard
I mean it! American companies like to sue anything that moves. If LyX gets in trouble because on you default forgot the �, I will come after you with a running chainsaw. Got it? deeper Itemize
It's a ūnder popup d̄efault ; _inset Quotes eld inset
widget _inset Quotes erd inset
and _inset Quotes eld inset
dialog box _inset Quotes erd inset
are programmer terms, so don't use them. Itemize
The thing below the menu and above the editing window is the ūnder toolbar d̄efault . Itemize
Use the text _inset Quotes eld inset
-> _inset Quotes erd inset
to quick-reference menu items. Example: sans File->Save default . Notice that there are on no spaces default around the _inset Quotes eld inset
-> _inset Quotes erd inset
. See Below. Standard
The reason why I want no spaces around the _inset Quotes eld inset
-> _inset Quotes erd inset
is to prevent LyX from splitting terms across lines. The same goes for using sans Protected _separator Blank default s between multi-word terms. The split would be visually disruptive. Standard
As for the terms _inset Quotes eld inset
popup _inset Quotes erd inset
and _inset Quotes eld inset
toolbar _inset Quotes erd inset
, if at some point I [or a future editor] need to change those, on I'll default take care of that. That's my job, after all. I want all of you, however, to use those terms. It will make any future switch much, much easier for either me or my successor( s). Section
Keys Standard
The canonical keyboard contains these keys: Itemize
sans C- default or sans Control- default
Itemize
sans S- default or sans Shift- default
Itemize
sans M- default or sans Meta- default
_deeper Standard
Self-explanatory. Be lazy and on use the abbreviations default whenever possible. deeper Itemize
sans F1 F2 F3 F4 F5 F6 F7 F8 F9 F10 F11 F12 _deeper Standard
The function keys. Most modern keyboards have all 12. deeper Itemize
sans Esc default
_deeper Standard
The _inset Quotes eld inset
Escape key. _inset Quotes erd inset
deeper Itemize
sans Insert default
sans Delete default
sans Home default
sans End default
sans PageUp default
sans PageDown _deeper 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. deeper Itemize
sans Left Right Up Down _deeper Standard
The four standard motion keys. There is no need to put the word _inset Quotes eld inset
arrow _inset Quotes erd inset
anywhere, since that's obvious. _float footnote deeper Standard
Same goes for _inset Quotes eld inset
cursor key _inset Quotes erd inset
. Even the word _inset Quotes eld inset
key _inset Quotes erd inset
after one of these may be redundant in certain situations. float
Itemize
sans Return default and sans Enter default
_deeper Standard
I won't throw a hissy fit if you use one instead of the other. I'd prefer if you used sans Return default over sans Enter 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. deeper Standard
You do not need to explain everywhere what the sans Meta default key is or where the sans Left default key is, et cetera. The user isn't stupid. Also, someone will document anything that isn't clear [e. _separator g. _separator the sans Meta default vs.
sans Alt default problem] someplace in the introduction. No need for you to repeat someone else's work. Section
Cross-References and Labels Standard
Use the following labelling conventions: List 00.00.0000
sec:xxx Use this for sans Section default s as well as sans Chapter default s, sans Subsection default s, sans Subsubsection default s, etc. List 00.00.0000
eqn:xxx Use this for Equations. Right now, only on David Johnson default should have to worry about this. List 00.00.0000
tbl:xxxx Use this for tables inside of a table float. List 00.00.0000
fig:xxx Use this for figures inside of figure floats. Standard
Additionally, you should put the label at one of two locations: Enumerate
The on beginning of the paragraph 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. Enumerate
If there is no paragraph after a section heading, put it at the on end of the last line.
default
_deeper Standard
Example: You have a sans Section default which is immediately followed by a sans Subsection default heading. This is a case where you need to put the label at the end of the sans Section default heading. I know it looks ugly; not much we can do about that, though. deeper Section
Language Standard
All contributions to the documentation must be in English. I don't care if it's British or American English. I will proofread for glaring mistakes and fix them. 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, I can fix it. Section
Consistent Grammar Style Enumerate
You are _inset Quotes eld inset
we _inset Quotes erd inset
. _deeper Standard
When you speak, you speak for the LyX Team, so use _inset Quotes eld inset
we _inset Quotes erd inset
instead of _inset Quotes eld inset
I _inset Quotes erd inset
. deeper Enumerate
The reader is _inset Quotes eld inset
you _inset Quotes erd inset
. _deeper Standard
Whenever you want to say something to the reader, use _inset Quotes eld inset
you, _inset Quotes erd inset
not some contorted construction to avoid being too informal.
deeper Enumerate
Write as if you're talking with a friend.
_deeper Enumerate
Think that way when you write. Play the dialogue in your mind. Enumerate
Be as informal as you please [without being rude]. deeper Enumerate
AVOID the passive voice: _deeper Enumerate
No: _inset Quotes eld inset
It is felt that this name best explains the command's purpose. _inset Quotes erd inset
You know full well who wrote the command: _inset Quotes eld inset
The LyX Team felt ... _inset Quotes erd inset
Or, better yet, _inset Quotes eld inset
We felt that ... _inset Quotes erd inset
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, _inset Quotes eld inset
LyX reformatted the paragraph. _inset Quotes erd inset
If typewriter ispell default makes changes, write, _inset Quotes eld inset
typewriter ispell default changes the document. _inset Quotes erd inset
_deeper Standard
Rule of thumb: any sentence you can express as, _inset Quotes eld inset
It was done by foo, _inset Quotes erd inset
you can express as, _inset Quotes eld inset
Foo did it. _inset Quotes erd inset
Much nicer. deeper 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. Enumerate
I on will make you rewrite default anything in the passive voice. It's awkward and hard to read. deeper Enumerate
Use the term _inset Quotes eld inset
mouse _inset Quotes erd 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. Enumerate
Use the term _inset Quotes eld inset
cursor _inset Quotes erd inset
for the little blinking vertical bar that indicates where text can/will appear next. Enumerate
Be on clear, concise, default and on to the point default . KISS = _inset Quotes eld inset
Keep It Short and Sweet _inset Quotes erd inset
[or, _inset Quotes eld inset
Keep It Simple, Stupid! _inset Quotes erd inset
] _deeper Itemize
Do on not default write paragraph after paragraph of verbage.
Itemize
Get to the point. Itemize
Take a look at the manual for a commercial word processor — it's a fine example of how bold NOT default to write documentation. It's all pithy, substanceless verbage, and its on utterly useless! default
deeper Enumerate
Avoid being pedantic like The Plauge! 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 _inset Quotes eld inset
other part of the manual _inset Quotes erd inset
is incomplete or empty, refer to it. Someone will fill it in. Enumerate
On the other hand, BE THOROUGH! _deeper Enumerate
You are documenting on features default , not widgets, not how the source code is organized.
Enumerate
Stay on topic — one sans Section default should cover on one default feature. Use sans Subsection default s and further subdivisions to group things if you're documenting several related features in a single sans Section default . Enumerate
Describe EVERYTHING related to that feature, no matter where it is. _deeper Enumerate
Example: Paragraph Indenting. Several popups control its behavior. You would document on all 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. Enumerate
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.
I get
on
really
default
cranky when that happens, because it means
on
I
default
end up fixing it.
Bad help is worse than no help at all.
deeper
Enumerate
Remember, there are people who will reference on your default section, just as you're referencing someone else's. You do want what you write to be useful, don't you? deeper Enumerate
NEVER NEVER bold NEVER on EVER default default treat the reader as if she is stupid: _deeper Enumerate
No dumbing-down! Enumerate
No talking down to the reader! Enumerate
The reader is smart enough to know what a mouse is. Enumerate
The reader is smart enough to know how to use a keyboard, including the
sans Shift- default , sans Control- default , and sans Meta- default keys. [ on I default explain that sans Meta- default is the sans Alt- default key on many keyboards in the introductions of every one of the manuals, so you don't need to.] Enumerate
The reader is smart enough to know that _inset Quotes eld inset
at the cursor _inset Quotes erd inset
means _inset Quotes eld inset
where the text cursor is sitting right now, in the buffer currently visible. _inset Quotes erd inset
small [Anything more than the word _inset Quotes eld inset
cursor _inset Quotes erd 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.] 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. deeper Section
Tools Standard
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 _inset Quotes eld inset
speak for yourself; _inset Quotes erd inset
you want to say something that is your personal opinion and using _inset Quotes eld inset
we _inset Quotes erd inset
would be inappropriate. Standard
For occasions like those, I've designed two mechanisms: Description
Personal _separator Notes: These are footnotes. They begin with the following: _deeper Standard
Note from on Name of Person default : Standard
using the on Noun Style default for the person's name. The rest of the footnote is the actual comment. If the comment is too large to put in a footnote, put it in a sans Quotation default paragraph environment instead. Standard
Use these when you need to quote a comment by someone, and want to identify that person. deeper Description
Author's _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, _inset Quotes eld inset
on Author's Note: default
_inset Quotes eld inset
and end with _inset Quotes eld inset
— _inset Quotes eld inset
followed by your initials. Here's an example: [ on Author's Note: This is an example note. —jw default ]. _deeper Standard
You should use these for the following purposes: 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. Itemize
You need to leave a note for yourself. Itemize
You need to leave a note for the editor or the other DocTeam members. Itemize
You need to point something out to the reader that doesn't fit into the context of the current paragraph. deeper 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 ... well, to comment on parts of a section without putting the commentary into the body of the text. Section
Content - What Goes Where Standard
This is on very default important, so PAY ATTENTION! Standard
I do not want typewriter Tutorial.lyx default , typewriter Reference.lyx default , and typewriter UserGuide.lyx 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 typewriter Reference.lyx default as a base and build the others on it.
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 typewriter Main.lyx 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, Quote
...and on Quote
...and on Quote
...and on. Standard
The result was a totally bloated, totally unnavigable typewriter Main.lyx 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
typewriter UserGuide.lyx 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. Standard
With that in mind, I have some instructions for how to keep things organized: List 00.00.0000
typewriter Intro.lyx default Please, don't touch this file. It's essentially complete, anyhow. Only the editor(s) and/or maintainer 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. List 00.00.0000
typewriter HowDoI-.lyx default is the FAQ. There are some people working on this, so contact them if you want to contribut e. List 00.00.0000
typewriter UserGuide.lyx default This file is complete. Any changes should be for updates on only default . DO NOT ADD new features to here willy-nilly. Let the editor/maintainer decide if — and when — new sections go in here. Place any new features in...
List 00.00.0000
typewriter SpecialTools.lyx default This is where all new features go from now on. It's in the style of a bound journal — each section is an _inset Quotes eld inset
article _inset Quotes erd inset
from the author of the feature. Also, anyone who writes a typewriter .layout default file for a new document class should write a section describing that new class and how to use it. That also goes here. List 00.00.0000
typewriter Tutorial.lyx default It ain't complete — yet. But, someone's working on it, and when he finishes, there won't be much else to add.
The purpose of the
on
Tutorial
default
is to get the users on their feet, especially and specifically if they've
never used LaTeX or an environment-based word-processor before.
Once it's done, the only new things that should go into the
on
Tutorial
default
are excersizes for how to use new document classes, [if even that].
List
00.00.0000
typewriter
Customization.lyx
default
It's a mess.
Complete disaster! [
on
sob
default
!]
Someday, a complete description of how to write new
typewriter
.layout
default
files will be in here.
And a description of the new
typewriter
.lyxrc
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.
Right now, there's a mini-tutorial about how to set up your Linux print
daemon.
That's the only thing which is truly complete.
Anything else, you can change.
List
00.00.0000
typewriter Reference.lyx 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 on Reference Manual 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