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. 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. Abstract
The Style Sheet for LyX documentation (hereafter known as the Style Sheet) applies to on all default forms of LyX documenation, regardless of language. There is a section for translators in the Style Sheet, towards the end.
on Read the entire Style Sheet! default Even if you are a translator, I assume you know enough English to comprehend this document. Section
Version Standard
All documenters and translators should be using version 1.0.1 or later as of April 1, 1999. Section
Questions and Clarifications Standard
After the second version of this Style Sheet grew uncomfortably large, the LyX DocTeam decided it needed to lose some excess weight. It seems the Style Sheet began to specify too many special cases, too many points of clarification. On the other hand, contributors to the documents were discovering many creative ways of misinterpreting the Style Sheet specifications. Therefore: Quote
If you have any questions about anything in the Style Sheet, on ask first, write second! Standard
Field all questions to the LyX Developer's Mailing List. There are seasoned DocTeam members who can answer your questions. If you have any problems with the Style Sheet itself, also contact the mailing list. Section
Fonts Standard
We'll start with the easiest section, yet also the most important. 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 _deeper Standard
Do not overemphasize your text. deeper List MMMMMMMM
typewriter Typewriter default program names, file names, typewriter man default -page 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
WARNING! — 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
Sans
_separator
Serif
default
, too!
on
Don't do that!
default
Make sure the entire word is still in
sans
Sans
_separator
Serif
default
after you shut off the underlining.
deeper
List
MMMMMMMM
bold Bold default Unused. _deeper Standard
If you want to emphasize any text, use on Emphasized default . LaTeX will put many things boldface on its own, such as sans Section default s, certain parts of equations, et cetera. Standard
Repeat: do not use boldface. 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. 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. Standard
LyX does not support kyboards missing any of the keys described above, with one exception. LyX can support a keyboard missing sans F11 default and sans F12 default . There is a keyboard accelerator for sans F10 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. Section
Mice Standard
The word _inset Quotes eld inset
mouse _inset Quotes erd inset
and any description of the 3 mouse buttons have no special handling. Don't typeset them in any other font than the default, which is Roman.
Standard
Exception: you're writing an Author's Note (see section
_inset LatexCommand
inset
) and you need to mention something about the mouse. Since the rest of the note is in on Emphasized default , your description of _inset Quotes eld inset
middle mouse button _inset Quotes erd inset
should be emphasized, as well. There are a couple of other cases like this one; use your judgement. Standard
There are only 3 mouse buttons. The use of them and of the mouse itself is obvious. There are few — if any — nonstandard things we do with the mouse. Therefore, there's no need to make the word _inset Quotes eld inset
mouse _inset Quotes erd inset
or _inset Quotes eld inset
mouse button _inset Quotes erd inset
stand out. Section
Special Typography Standard
Do the following: Description
Multi-word _separator names Use a sans Protected _separator Blank default between the words for menu and widget names. E. _separator g.: sans Save _separator As default , not sans Save As default .
_deeper Standard
This holds for things in typewriter Typewriter default as well as sans Sans _separator Serif default , with one caveat. If you have a long code example, one that can't simply be inlined and put in typewriter Typewriter default , put that in a sans LyX _separator Code default environment. Standard
I want the sans Protected _separator Blank default so that the name doesn't get split between two lines, which is visually disruptive. If something with a sans Protected _separator Blank default is near the end of a line and overflows the margin, use a typewriter
sloppypar default in that parargraph (consult a LaTeX book for more about _inset Quotes eld inset
typewriter
sloppypar default
_inset Quotes erd inset
) or manually add a hypenation point. deeper 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 Standard
Seasoned LyX Team Members: Are there other terms that require this special status? On the other hand, should we eliminate this style completely? Description
Terminology Note the following: 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. We could get in on major trouble default by forgetting that «. So, don't. 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 word _inset Quotes eld inset
popup _inset Quotes erd inset
should be in Roman. There should be no sans Protected _separator Blank default between the popup's name and the word _inset Quotes eld inset
popup. _inset Quotes erd inset
Example: _inset Quotes eld inset
...
sans Paragraph _separator Layout default popup...
_inset Quotes erd inset
. Anything else is on wrong. Itemize
The thing below the menu and above the editing window is the ūnder toolbar d̄efault . _deeper 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 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). deeper Description
Menu _separator Items When quick-referencing an item in a menu, use the menu separator:
_inset Quotes eld inset
_inset Quotes erd inset
. Example: sans File Save default . Notice that there are on no spaces default around the _inset Quotes eld inset
_inset Quotes erd inset
and that it's in sans Sans _separator Serif default , just like the menu and item names. _deeper Enumerate
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. Enumerate
A _inset Quotes eld inset
_inset Quotes erd inset
goes between menu names and item names on only default . (Yes, submenus are okay, too). Enumerate
on NEVER default put _inset Quotes eld inset
_inset Quotes erd inset
between menu items and popup names. Example: _inset Quotes eld inset
sans ūnder L d̄efault ayout P ūnder a d̄efault per Paper _separator Popup default
_inset Quotes erd inset
on IS STRICTLY FORBIDDEN! default
_deeper Standard
on NEVER default put _inset Quotes eld inset
_inset Quotes erd inset
between popup names and any popup widget. Example: _inset Quotes eld inset
sans Paper _separator Popup P ūnder o d̄efault rtrait default
_inset Quotes erd inset
on IS STRICTLY FORBIDDEN! Standard
on NEVER default put _inset Quotes eld inset
_inset Quotes erd inset
between menu items and any popup widget. Example: _inset Quotes eld inset
sans ūnder L d̄efault ayout P ūnder a d̄efault per P ūnder o d̄efault rtrait default
_inset Quotes erd inset
on IS STRICTLY FORBIDDEN! Standard
Either write out the description, or use context to eliminate any need to repeat menu items, popup names, etc. deeper deeper Description
Note _separator Boxes LyX has a feature for adding comments to a popup that appear only within the LyX GUI. Here's one: _inset Info These should NEVER appear in the manuals. inset
. You will see nothing in a printout of the Style Sheet. Therefore, they have no place in the manuals. Period.
_deeper Standard
If you have a parenthetical comment you want to make, the reader should
see it too.
Use an Author's Note (see section
_inset LatexCommand
inset
) in place of the Note-Boxes (or whatever they're called). deeper Description
_inset Quotes eld inset
(... ) _inset Quotes erd inset
, _separator
_inset Quotes eld inset
[... ] _inset Quotes erd inset
_separator and _separator
_inset Quotes eld inset
... _inset Quotes erd inset
I have recently been corrected about the use of parentheses. Standard English typesetting uses the normal parentheses, _inset Quotes eld inset
(... ) _inset Quotes erd inset
, around any aside, remark, or parenthetical expression. The bracket, _inset Quotes eld inset
[... ] _inset Quotes erd inset
, is used only within quotations (see section _separator
inset
). The brace, _inset Quotes eld inset
... _inset Quotes erd inset
, is never used. Therefore, never use _inset Quotes eld inset
[... ] _inset Quotes erd inset
or _inset Quotes eld inset
... _inset Quotes erd inset
unless otherwise specified by this Style Sheet. Description
Dashes: Be sure to use the correct one. A single _inset Quotes eld inset
typewriter - default
_inset Quotes erd inset
character is not a dash, it's a hyphen. Use it only as a hyphen.
_deeper Standard
Instead, use an _inset Quotes eld inset
en-dash _inset Quotes erd inset
or an _inset Quotes eld inset
em- dash. _inset Quotes erd inset
Two back-to-back _inset Quotes eld inset
typewriter - default
_inset Quotes erd inset
characters form the en-dash. Three _inset Quotes eld inset
typewriter - default
_inset Quotes erd inset
characters create an em-dash, which is slightly longer than the en-dash. In the printed version of any document, LyX will combine the two or three
_inset Quotes eld inset
typewriter - default
_inset Quotes erd inset
characters into a single, unbroken line. deeper 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, should you need to create any. 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
Content — What Goes Where Standard
This is on very default important to anyone documenting a new feature. If you need to add new documentation, pay attention.
Standard
In the dim and distant past, whenever someone wanted to document a new feature they added, they either wrote a mini-doc and stuck it into the documentation directory, or they added a new section to the lone manual. No one paid much attention to organization in those days, either. The result was a totally bloated, totally unnavigable, and incomplete manual orbitted by a swarm of tiny, incomplete mini-docs. I don't want the docs to fall back into 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) 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 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 decide if — and when — new sections go in here. Place any new features in...
List 00.00.0000
typewriter Extended.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. _deeper Standard
Note, however, that you are on not default excused from following this Style Sheet just because the sections of typewriter Extended.lyx default are in the form of a journal article. deeper List 00.00.0000
typewriter Tutorial.lyx default This file is complete. Do not change or add to without permission of the Documenation Project Editor. 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.
Plenty of stuff to do!
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! Section
Writing Style: The Primary Manuals 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.
Subsection
Language Standard
All contributions to the on primary 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. 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. Standard
Nota Bene: by
on
primary
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
_inset LatexCommand
inset
for more info. Subsection
Wearing Many Hats:
Commentary from the Author (i.
_separator
e.: You)
Standard
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 _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
In short, when you contribute to the LyX Docs, you wear many hats. Standard
For occasions when you need to switch hats, I've designed some special mechanism s. Subsubsection
Personal _separator Notes: The _inset Quotes eld inset
Me _inset Quotes erd inset
Hat Standard
These are footnotes. They begin with the following: Quote
Note from on Name of Person default : Standard
... using the on Noun Style default for the person's name and without the quotes. The rest of the footnote is the actual comment.
Standard
Use these when you need to quote a comment by someone (usually yourself), and need to identify that person. This includes occasions when you need wear the _inset Quotes eld inset
me _inset Quotes erd inset
hat, i. _separator e. _separator to speak for yourself instead of for the LyX Team. Standard
If the comment is too large to put in a footnote, don't use a Personal Note. When quoting more than about 3 sentences or 5 lines of text, use a bona fide quote. Don't use any leading _inset Quotes eld inset
Note from on Name of Person default : _inset Quotes erd inset
in that case. In a real quote, you'll give credit to the original speaker in either the paragraph before or after the body of the sans Quotation default . Subsubsection
Author's _separator Notes: The _inset Quotes eld inset
Author _inset Quotes erd inset
Hat Standard
There will be times when you are not speaking for the LyX Team, yet you are not entirely speaking for yourself. Instead, you are speaking on behalf of the manual itself, as the author of the manual. Some examples of when you might need to do this are: Itemize
You need to contradict something you just wrote because the feature isn't quite ready yet, but you wanted to document what it will do. 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 out something about the manuals to the reader, something that doesn't fit into the context of the current paragraph. Standard
At such times, you are wearing your _inset Quotes eld inset
I am the Author _inset Quotes erd inset
hat, if you will. Standard
The typography for an _inset Quotes eld inset
Author's Note _inset Quotes erd inset
is as follows: Itemize
They go in the body of the text, in brackets, _inset Quotes eld inset
[] _inset Quotes erd inset
, not any other form of parentheses. The bracket are in the default character style. Itemize
The text of the note itself, however, is emphasized.
Itemize
Begin with the words, _inset Quotes eld inset
on Author's Note: default
_inset Quotes erd inset
and end with an em-dash, _inset Quotes eld inset
— _inset Quotes erd inset
, followed by your initials.
Standard
Here's an example: [ on Author's Note: This is an example note. —jw default ]. Standard
The form of the Author's Note, by the way, isn't a suggestion or request. It is on mandatory default . All Author's Notes must begin with this text, verbatim: _inset Quotes eld inset
[ on Author's Note: default
_inset Quotes erd inset
. Abbreviations to _inset Quotes eld inset
AN _inset Quotes erd inset
are or any other variant are forbidden. The Author's Note must end with an em-dash, which is 3 _inset Quotes eld inset
- _inset Quotes erd inset
characters: _inset Quotes eld inset
— _inset Quotes erd inset
. Do not use 2 or 1 _inset Quotes eld inset
- _inset Quotes erd inset
; you must use 3. Standard
_inset Quotes eld inset
Author's Notes _inset Quotes erd inset
are inherently transient, and should disapear as a manual matures. Subsubsection
Footnotes: 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. Paragraph*
Mixing Footnotes and Personal Notes Standard
Personal Notes always go in footnotes, and should be 5 lines or fewer. Any larger quotation should be quoted properly, using the rules of standard English. Place quotes in a sans Quotation default paragraph environment. Paragraph*
Mixing Footnotes and Author's Notes Standard
Author's Notes should never go in footnotes. Or, I'd like that to be the case. I need to look at the docs yet and come to a decision on this. Paragraph*
Mixing Personal Notes and Author's Notes Standard
Forbidden; these two are mutually exclusive. Subsubsection
Summary of Use Itemize
Personal Notes:
A
on
short
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
_separator
inset
]. Itemize
Author's Note:
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.
Itemize
Plain Footnotes:
Used for text fragments that almost fit into the flow of the text...
but not
quite.
Standard
When using these three mechanisms, in addition to rigorously following their descriptions, please use them properly. I have listed some additional restrictions previously. Some of you may balk at these restrictions. Nevertheless, there is a reason for them: if you have an overwhemling desire to mix or modify footnotes, Personal Notes, and Author's Notes, you shouldn't be using any of them. More specifically, you're trying to use a hammer to drive in a screw. What you want to say probably needs to go into the main body of the text. Subsection
General Stylistic Guidelines Standard
Everything in this section is on mandatory to all documenters default , regardless the language you're writing in.
Subsubsection
Typography Enumerate
Use the typography rules outlined in the beginning sections of this document. Enumerate
Don't, however, mimic the typography of this file. Yes, the Style Sheet doesn't follow the Style Sheet (grin). 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. _deeper Standard
An example is in the on User's Guide default . There is a footnote using the typewriter multcols default command to divide a long sans Itemize default environment into 3 columns. It adds some LaTeX commands to the online version, the so-called _inset Quotes eld inset
Evil Red Text _inset Quotes erd 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. deeper Enumerate
When in doubt, compromise. _deeper Standard
When in doubt, use good judgement. deeper Subsubsection
Semantics Enumerate
You are _inset Quotes eld inset
we _inset Quotes erd inset
. _deeper Standard
When you speak, you speak for the entire 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
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
When in doubt, compromise. _deeper Standard
When in doubt, use good judgement. deeper Subsubsection
inset
Quoting Yourself and Others Standard
In some cases, you'll have something to say, an opinion of yours. Since this is your opinion, you're not speaking for the LyX Team. You have so much to say, in fact, that it won't fit into a Personal Note or an Author's Note. In these cases you want to quote yourself. Standard
Any time you wish to quote someone, be it yourself or someone else, there are standard rules one follows. Every language has its own rules. You should follow the rules that apply to the language of the document to which you are contributing.
Standard
This creates a problem for the primary documentation. The primary documentation is written in English, yet the contributors come from many countries. The quoting rules for English (well, American English, at least) are outlined in the following sans Figure _separator Float default , for your convenience. Read them if you need to. Standard
_float fig Standard
Quoting rules for English: Itemize
The body of the quote belongs in a sans Quotation default environment. Itemize
The sentences prior to the quote should flow logically and smoothly into the quote. Itemize
The sentences immediately following the quote should continue the flow of the text. Itemize
You must, on must default credit the original author of the quote in the sentences immediately before or after the quote. Itemize
Crediting the original author of the quote should not, however, disrupt the flow of the text. Itemize
If you omit text from the beginning of the first sentence in the quote, the quote must start with the text _inset Quotes eld inset
[... ] _inset Quotes erd inset
. This is an ellipsis in square brackets. Itemize
If you omit text from the end of the last sentence in the quote, the quote must end with the text _inset Quotes eld inset
[... ] _inset Quotes erd inset
followed by the sentence's punctuation mark. Itemize
If you omit any text from the middle of the quote, be it whole sentences or parts of sentences, replace it with the text _inset Quotes eld inset
[... ] _inset Quotes erd inset
. Itemize
The quote must be grammatically correct.
_deeper Itemize
If the original is wrong, you must correct it. Itemize
If omitting part of the quote _inset Quotes eld inset
breaks _inset Quotes erd inset
it, you must correct the problem. Itemize
For missing words (e. _separator g. _separator
_inset Quotes eld inset
the _inset Quotes erd inset
goes missing), place the word in square brackets, _inset Quotes eld inset
[... ] _inset Quotes erd inset
and insert in the quote where needed. Itemize
For mangled word order, correct the mangled text, following it with the text _inset Quotes eld inset
[sic] _inset Quotes erd inset
. deeper Itemize
Spelling in the quote must be correct. Correct any misspelled words and place the text _inset Quotes eld inset
[sic] _inset Quotes erd inset
after the corrected word. Itemize
Back-to-back bracket blocks merge together. Example: _inset Quotes eld inset
[... ][the] _inset Quotes erd inset
is wrong. It should be _inset Quotes eld inset
[... the] _inset Quotes erd inset
. Itemize
If you correct the spelling in 2 or more consecutive words, you can get away with one _inset Quotes eld inset
[sic] _inset Quotes erd inset
after the last mistake. dummy
float Subsubsection
Coverage Standard
When describing a new feature or typewriter *.layout default file, be sure to: 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 Plague! 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
Group by feature, not by widget. 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
Note from
on
John Weiss
default
:
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 got
on
really
default
cranky when that happens, because it means
on
I
default
ended up fixing it.
Bad help is worse than no help at all.
_deeper
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. deeper 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
When in doubt, compromise. _deeper Standard
When in doubt, use good judgement. deeper Subsubsection
NEVER NEVER on NEVER EVER default Treat the Reader as if She is Stupid 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. Subsection
Tips for the English Version Standard
inset
When contributing to the primary — i. _separator e. _separator the English language version — of the LyX manuals, keep the following in mind. Subsubsection
Write as if You're Talking with a Friend.
Enumerate
Think that way when you write. Play the dialogue in your mind. Enumerate
Be as informal as you please (without being rude). Subsubsection
AVOID the Passive Voice Enumerate
No: _inset Quotes eld inset
It is felt that this name best explains the command's purpose. _inset Quotes erd inset
We 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. Enumerate
Note to non-Americans: _deeper Standard
Using passive voice is generally considered bad style in the U. _separator S. _separator as it is too easy to obfuscate your words with it. It also bloats sentences, often unnecessarily. deeper Subsubsection
Short Sentences. Short Paragraphs. Standard
In English, there is a grammatical error known as the _inset Quotes eld inset
run-on sentence. _inset Quotes erd inset
The classic example of a run-on sentence is 7 clauses strung together with the word _inset Quotes eld inset
and. _inset Quotes erd 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. Standard
In general, stick to short sentences in written English. Getting rid of passive voice ( _inset Quotes eld inset
... was done by...
_inset Quotes erd 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. Standard
While I'm talking about paragraphs, I'll apply the _inset Quotes eld inset
shorter is better _inset Quotes erd inset
motto to them, as well. At the time I started with the manuals (and this Style Sheet), I didn't pay too much attention to paragraph size. I've since become a big proponent of short paragraphs, with one idea per paragraph. While long, flowing, multi-concept paragraphs can be nice in novels, we're writing manuals. Our goal is rapid information location and comprehension, not a literary prize. Standard
There is a single exception to the short sentence, short paragraph rule. Particularly complex ideas may need more _inset Quotes eld inset
breathing room. _inset Quotes erd inset
However, you shouldn't encounter such complex ideas often when documenting LyX. Try to keep things short, and use your judgement as needed. Standard
To reiterate, yet again, something I said before: Quote
When in doubt, compromise. Quote
When in doubt, use good judgement. Standard
Hopefully, you've got the idea. Section
Translations Subsection
Rules of the Translating Trade Standard
While translating anything, there are certain _inset Quotes eld inset
tools of the trade _inset Quotes erd inset
you should use. They will help you greatly. Subsubsection
Translate one paragraph at a time. Standard
Most people translate word by word. Clearly, you lose all context if you do that. A word may have multiple meanings. You can't tell which unless you look at the rest of the sentence. Standard
There is another level to the context issue, however. Your dictionary may translate multiple English words the same way. All those words mean on roughly default the same thing. Each one, however, covers a different shade of meaning, a different mood or intent. It is often difficult to resolve those shades of meaning in the context of even one sentence. A paragraph, however, will provide that context. Subsubsection
You will not translate it correctly on the first try. Standard
Alright, I admit that you may be able to translate some of the sentences at first glance. If you know a language well, you may even understand over half of the text. Nevertheless, overconfidence can lead you astray. There will be some sentences, no matter how few, that will simply confound you. Standard
It is generally a good idea to make multiple passes over a paragraph you're translating. Even if you translate the entire paragraph on the first pass, make a second one. You'll often improve upon your first attempt. Subsubsection
When in doubt, write down all of the meanings for a word. Standard
You can often translate tricky parts of a text using the context of the surrounding sentences. So, if you hit a word or phrase you don't know, translate it more than one way. Picking the most likely translations, summarize them in one to three words.
Subsubsection
Using context, fix the meanings on the next pass. Standard
This is where your multiple translations of a single word become useful. Using the other sentences you translated, you can now translate that mystery–s entence without reconsulting your dictionary. Subsubsection
Fix the grammar only after you've finished translating the sentence. Standard
If there's a mystery phrase in the middle of a sentence, you can't translate the entire sentence. Why grammatically rearrange the words you translated already? You may need to restructure the sentence a second time once you figure out how to translate that mystery phrase. Better to wait until you've completely translated the sentence to clean up its grammar. That way, you do so only once. Subsubsection
If you can't translate it, skip it and come back to it on the next pass. Standard
Remember the earlier discussion of context and its immense usefulness? There is no sin in making multiple passes over a tricky passage. Subsubsection
Translate the meaning first. The rest can wait. Standard
The information content of the text under translation is the most important part. This is especially important for a manual, where the information on is the only default important part of the original document. Lose that, and you lose the very point of performing the translation. Subsection
Tips for the Translators 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 _separator
inset
. There are additional rules and regulations that follow those first few.
Subsubsection
Write as if you are explaining LyX to a colleague you know well. Enumerate
Think that way when you write. Play the dialogue in your mind. Enumerate
Use a conversational style in your writing. Pretend you are teaching LyX to a colleague you know well. Enumerate
Use a style that is polite without being too formal. If, in your culture, informal language is appropriate to use with a colleague, use informal speech in the translation of the manual. Subsubsection
AVOID Snobby, Academic, Specialized, or _inset Quotes eld inset
Dead _inset Quotes erd inset
Writing.
Standard
In English, the passive voice appears formal, dry, barren. It also often adds unnecessary complexity. In other langauges, however, this is not the case. There is nothing wrong with passive voice, and people use it frequently in everyday conversation. Nevertheless, your translation of the LyX manuals must avoid _inset Quotes eld inset
dead _inset Quotes erd inset
writing. Standard
In Germany, there is a magazine known as _inset Quotes gld inset
Der Spiegel. _inset Quotes grd inset
The writing in it is so complex, it is extremely difficult for non-native German speakers to understand. While sophisticated, the writing style of _inset Quotes gld inset
Der Spiegel _inset Quotes grd inset
is not what a German uses in everyday conversation. Nor is the writing style for a Russian mathematics journal. Such specialized or overly-sophisticated styles are _inset Quotes eld inset
dead _inset Quotes erd inset
in the sense that they are seldom used by normal people in everyday speech. Standard
We who write the LyX manuals, original or translated, seek to on inform default . If we write in a style only a few people use, and use seldomly, we will fail to inform. Use a writing style that mirrors everyday speech (without being vulgar, of course).
Subsubsection
Keep the Writing Simple. Standard
For the English version, I wrote, _inset Quotes eld inset
Use short sentences and short paragraphs. _inset Quotes erd inset
What if, however, short sentences and paragraphs are something only children use in your language? What if short sentences imply rudeness in yet another language? Naturally, you would not want to use them in your translation. Standard
Nevertheless, the translations of the LyX manuals should be as clear as the originals. So, for our international colleagues, we apply this rule: Keep your sentences and paragraphs as short as makes sense. Standard
Remember: we're translating manuals here, folks. Our goal is rapid information location and comprehension, not a literary prize. Try to keep your writing concise yet smooth-flowing. And use your judgement as needed: Quote
When in doubt, compromise. Quote
When in doubt, use good judgement. Subsubsection
Translators must follow the Style Sheet, too! Standard
Everything in this manual — on except section _separator
inset
default — applies to every LyX documenter, no matter what the language. Subsubsection
Translators must read the Style Sheet Supplement for their language. Standard
For every translation project, there is a Supplement to the Style Sheet. It will be named: Quote
typewriter DocStyle_Supplement_<cn>.lyx Standard
... where _inset Quotes eld inset
typewriter <cn> default
_inset Quotes erd inset
is your language's two-letter locale code. The Translation Project Chief for your language wrote this. If he hasn't, pester him to do so! < on wink! default > Subsubsection
The English versions of the manuals are not Sacred Text. Standard
You do not need to translate everything word for word. In fact, you shouldn't. Keep to the spirit of the originals, not the letter. Be as creative as you want, as long as you on accurately default and on completely default convey all of the information contained in the English versions. Subsubsection
Any information in the LyX manuals must also be in the translations. Standard
inset
This falls under translating the orignals accurately and completely.
Itemize
Omitting any feature description is on stricly forbidden default . Itemize
Misrepresenting or misdescribing any LyX feature or operation on must be avoided default . Itemize
The translation
on
cannot
default
outpace the original.
If no one has documented new feature in the primary LyX manuals (i.
_separator
e.
_separator
the English versions), do not do so in the translations.
If you're really looking for something to do, either:
_deeper
Itemize
...
focus on translating something you haven't yet,
OR
Itemize
... update or repair the primary manual. Standard
If you cannot or do not want to do one of the above, then take a break. Wait for the main manuals to catch up before translating anything else. deeper Subsubsection
What you cannot translate, you may omit (usually). Standard
Prepositions, idioms, metaphors, slang, Oh My! There's a jungle of potentially untranslatable text you may face. Happily, none of these untranslatables are essential to the original text...
usually. If you can't translate a phrase or two, try omitting them. If the rest of the paragraph still makes sense, then don't worry about the omission. Standard
There may be special cases where omitting part of a sentence or paragraph violates rule _separator
inset
. In those cases, on do not omit! default You must try and translate those tricky spots. Subsubsection
Translators may add their own fluff to the information content. Standard
After you do strip away all of the idioms, metaphors, slang, humor, and other _inset Quotes eld inset
expendable text, _inset Quotes erd inset
you may find that your translated manual is dull and dry. Why not add your own fluff? Add text that makes the manual a pleasure to read, that engages the reader. It may take the form of humor, or metaphors, or sayings. Whatever you add, it should be _inset Quotes eld inset
in context. _inset Quotes erd inset
It should not clash with the explanation of LyX features and functions. Subsection
For Translation Project Chiefs Subsubsection
The First Is In Charge 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 on only default person translating the LyXDocs, that automatically makes you the Translation Project Chief. Standard
Amongst other things, that means that you must read this section and perform the tasks described here. Standard
If you are a member of a LyX Documentation Translation Team, but on are not default its Chief, you may stop reading. The remainder of this section will be of no interest to you. If you came to the Style Sheet from the Supplement for your language, you may return to it. Standard
If you have not read the Style Sheet Supplement for your language, you should read it now.
Subsubsection
Read the Style Sheet Standard
No documenter is excused from following the Style Sheet, not even a Translation Project Chief. Standard
Actually, it is on especially default important that the Translation Project Chiefs read the Style Sheet. Subsubsection
Make your translators read the Style Sheet Standard
No documenter is excused from following the Style Sheet. Standard
Since your translation team is translating, they know on some default English, at least. Therefore, they should be able to read the Style Sheet. Subsubsection
Provide a _inset Quotes eld inset
Supplement _inset Quotes erd inset
to this Style Sheet Standard
There are parts of this Style Sheet that are English-specific. I have tried to provide a general, language-independent description of certain details in this section. Unfortunately, that general description doesn't cover the specifics of each language.
Standard
That's where you, as head of a LyXDoc Translation Team, come in. Standard
Every Translation Team Chief is on required default to write a Supplement to the official Documentation Style Sheet, with specifics issues affecting your language. (You are, after all, the LyX Team expert on your native tongue.) Follow these guidelines when writing the Supplement: Enumerate
Name the file:
typewriter DocStyle_Supplement_<cn>.lyx default
...
where
_inset Quotes eld
inset
typewriter <cn> default
_inset Quotes erd inset
is the two-letter code for your language. This is the same two-letter code that is part of the filenames for the translated manuals. Example: _inset Quotes eld inset
typewriter _de default
_inset Quotes erd inset
for German, _inset Quotes eld inset
typewriter _sv default
_inset Quotes erd inset
for Swedish, and _inset Quotes eld inset
typewriter _ru default
_inset Quotes erd inset
for Russian. Enumerate
Do not worry about where the file goes. The CVS maintainers will locate all documentation and Style Sheet Supplements in an appropriate place. Enumerate
Document Properties: _deeper Itemize
For consistency, use the same document class and other document properties as the Style Sheet. _float footnote deeper Standard
Specifically, check the settings in the sans Document Layout default popup. Use those in your Supplement. float _deeper Itemize
Exceptions: Use margins, indentation/paragraph separation, language, and encoding appropriate for your language. deeper Enumerate
The title of the Supplement: _deeper Itemize
The title will use the _inset Quotes eld inset
sans Title default
_inset Quotes erd inset
paragraph environment. In your native tongue, the title will read: _deeper Standard
typewriter
Documentation Project Style Sheet:
Supplement for the <foo> Translation Project
Standard
(Replace _inset Quotes eld inset
typewriter <foo> default
_inset Quotes erd inset
with the name of your language.) deeper Itemize
If, in your language, _inset Quotes eld inset
supplement _inset Quotes erd inset
translates into _inset Quotes eld inset
appendix, _inset Quotes erd inset
we have a problem. In English, _inset Quotes eld inset
Supplement _inset Quotes erd inset
and _inset Quotes eld inset
Appendix _inset Quotes erd inset
have somewhat different meanings. An appendix is an extra part of a document. A supplement is an extra document.
_deeper Standard
Choose a replacement word accordingly. Whatever you choose to replace _inset Quotes eld inset
Supplement, _inset Quotes erd inset
it must not have the same translation as the word _inset Quotes eld inset
appendix. _inset Quotes erd inset
deeper deeper Enumerate
Below the title, in the _inset Quotes eld inset
sans Author default
_inset Quotes erd inset
paragraph environment, place your name. _deeper Standard
There will be no abstract. deeper Enumerate
The first sans Section default of the Supplement: _deeper Standard
The first thing you will do is strongly yet politely encourage the reader to stop reading the _inset Quotes eld inset
Supplement _inset Quotes erd inset
and go read the Style Sheet. The reader should not return to the _inset Quotes eld inset
Supplement _inset Quotes erd inset
until he has read on and default understood the Style Sheet proper. deeper Subsubsection
Keep the Supplement Succinct Standard
This Style Sheet is already very detailed. DocTeam members all have a lot to read. We don't want to place an extra burden on translators. Therefore, keep the Supplement as short as you can without losing information. Subsubsection
Font Issues Standard
The second sans Section default will be about font issues... if you have any. Not all Translation Project Chiefs will need to deal with this issue. The fonts: Itemize
typewriter Typewriter Itemize
sans Sans Serif Itemize
Roman
on Emphasized (actually Italics) Itemize
ūnder Underlined Itemize
bold Bold Itemize
on Noun (actually Small Caps) Standard
... certainly exist for all languages that use the Roman alphabet. Do they exist, however, for Greek? How about Cyrillic? These different fonts almost certainly do not exist for Devanagri, Chinese, Korean, Japanese, Hebrew, Arabic, and other scripts.
Standard
There will be some languages in which following the font-scheme specified in this Style Sheet may not be possible. If you are the Translation Project Chief for such a language, you have extra work. The rest of you can safely ignore the remainder of this section. Standard
In the font section of the Supplement, you will provide a new typographic style, designed specifically for your writing system. For consistency, the title of this section in every Supplement should translate into English as _inset Quotes eld inset
fonts. _inset Quotes erd inset
Before adding anything to this section, however, determine what this new typographic style will look like. Stick to the font specifications in this Style Sheet as best you can, whenever you can. When you cannot, use the following suggestions: Itemize
Guidelines for _inset Quotes eld inset
translating _inset Quotes erd inset
fonts,
or
What to do when a font doesn't exist:
_deeper
List
MMMMMMMM
Roman Use the font that typesetters in your language use for printing books, manuals, etc. This will also be the default font. List MMMMMMMM
on Noun _separator Style default This is for people's names. If there is special font for names in your alphabet/writing system, use it in place of this. Otherwise, write names in the default font, typeset according to the rules of your language. List MMMMMMMM
on Emphasized default Use the font with which your language normally emphasizes text. _deeper Standard
Use a font that is different from your language's equivalent of bold Boldface default . In other words, your sans Section default , sans Subsection default and similar headers will be in one typeface, perhaps bold Boldface default , perhaps not. Whatever that font is, avoid using it for on Emphasized default if at all possible! deeper List MMMMMMMM
typewriter Typewriter 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 typewriter Typewriter default . List MMMMMMMM
sans Sans _separator Serif default Pick any other font that is different from the ones you're using in place of on Emphasized default , bold Boldface default , and typewriter Typewriter default . If you're unlucky, and your language's writing system doesn't have enough fonts, use the same font you picked to replace typewriter Typewriter default . Only do this, however, if your alphabet/writing system has very few fonts to pick from. List MMMMMMMM
sans ūnder U d̄efault nderlined _separator Sans _separator Serif default Don't worry about this one. _deeper Standard
If you use some special font on-screen to highlight the accelerator keys for menus, buttons, and other widgets, you might want to mimic that in the translations. It is not required, however. Therefore, if you can't mimic this typographic convention in your native writing system, don't. deeper deeper Standard
Note that you may also want to describe fonts that your Translation Team should on never default use. For example, no contributer to the English/European versions may ever use
bold Boldface 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 bold Boldface default .
Standard
Once you have determined which fonts in your native writing system will replace one or more of the above, propose it to the LyX Developer's Mailing List. You may receive valuable feedback this way. If not, that's okay. If no one can read your writing system, and therefore cannot comment, that's also okay. Go ahead and describe the typographic standard you created in the Supplement.
Standard
Remember: stick to the font specifications in this Style Sheet as best you can, whenever you can. Subsubsection
Quoting Style and the sans Quote default vs.
sans Quotation default Issue Standard
The next section of the Supplement will cover the issue of quoting. Give it an appropriate title. Standard
One of the first things you should do in that section is resolve the following issue: Itemize
Decide whether sans Quote default or sans Quotation default is the correct paragraph environment for your language. Itemize
In the Supplement, specify which one to use. Standard
English has its own typography and style for quoting others. The Style Sheet describes that typography in section _separator
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 _separator
inset
of this Style Sheet is overly detailed for a good reason. Authors of the primary LyX manuals are not necessarily native English speakers. The members of your Translation Team, however, will all likely be native speakers of your language. Therefore, discuss proper quoting style of your native tongue to an appropriate level of detail. Subsubsection
Translations of Style Sheet Terminology Standard
In the Supplement, you must provide a standard translation of certain key phrases for the members of your Translation Team. Place this in a section following the one about quotations. Standard
In particular, standardize the translations of the phrases: Itemize
Note from on <foo>: Itemize
on Author's Note: Standard
Do not change the typography of the _inset Quotes eld inset
Personal Note _inset Quotes erd inset
and _inset Quotes eld inset
Author's Note, _inset Quotes erd inset
however. Only provide a translation for the opening phrases. Insist that the members of your Translation Team use these two tools correctly. Standard
While we are discussing proper use of the _inset Quotes eld inset
Personal Note _inset Quotes erd inset
and _inset Quotes eld inset
Author's Note _inset Quotes erd inset
in translations, let's talk about a related problem. The _inset Quotes eld inset
Author's Note _inset Quotes erd 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 on not default the author! How then should a translator translate an _inset Quotes eld inset
Author's Note? _inset Quotes erd inset
Standard
You, as Translation Project Chief, must decide. You can forbid translation of pre-existing _inset Quotes eld inset
Author's Notes, _inset Quotes erd inset
omitting them entirely instead. You could tell your translators to read any _inset Quotes eld inset
Author's Note _inset Quotes erd inset
they may encounter, understand it, then write their own _inset Quotes eld inset
Author's Note _inset Quotes erd inset
about the situation, not as a translation but as a personal opinion. You may decide on some other policy. Standard
Whatever you decide, codify your policy in its own sans Section default or sans Subsection default or whatever. Place it near the section where you translated _inset Quotes eld inset
Personal Note _inset Quotes erd inset
and _inset Quotes eld inset
Author's Note _inset Quotes erd inset
. Subsubsection
Lost in Translation Standard
After describing all of the previous issues, create a new sans Section default . Give it the name, _inset Quotes eld inset
Lost in Translation, _inset Quotes erd inset
or something similar. Standard
In this section you will discuss any common English metaphors, humor, connotatio n, or other difficult to translate text. Try to balance brevity and completeness. Devote a sans Subsection default — or even sans Subsubsection default s — to each specific issue. Subsubsection
...
_inset Quotes eld inset
Yes, we mean now. _inset Quotes erd inset
...
Standard
Throughout the manuals, the DocTeam has used the following sentences: Quote
If you haven't read the < on Foo default > manual, go read it. Yes, we mean now. Standard
This sentence will be tricky to translate, since it contains non-translatable connotations. Therefore, create a sans Subsection default for this issue in your _inset Quotes eld inset
Lost in Translation _inset Quotes erd inset
section. Present the _inset Quotes eld inset
... Yes, we mean now...
_inset Quotes erd inset
sentences, then present a translation, along with any explanation you feel necessary. Standard
Here's what those two sentences, sitting alone in their own paragraph, mean: 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 on Intro default manual is a prerequisite for all of the other manuals. The conditional clause preceeding the command means, _inset Quotes eld inset
You do not need to perform this command twice. _inset Quotes erd inset
Standard
The second sentence adds force to the command. Culturally, the imperative tense of a verb in english is not necessarily forceful. The way we wrote that command, _inset Quotes eld inset
go read it, _inset Quotes erd inset
is firm, yet polite. The reader may choose to ignore it. By following with, _inset Quotes eld inset
Yes, we mean now, _inset Quotes erd inset
we imply two things. First, we add some _inset Quotes eld inset
resistive force _inset Quotes erd inset
to the command. That second sentence reinforces the command, making it a bit harder to ignore. Second, the sentence itself implies a certain sense of urgency. You cannot merely wait until later to fulfil that command. The brief pragraph, and its sudden end, add still further subtle reinforcement to the command, _inset Quotes eld inset
go do the required reading before using this manual. _inset Quotes erd inset
Standard
Note that all of this commanding and reinforcing is nevertheless in a polite format. Furthermore, it is in a subtle form. We are commanding the reader to do something, but in an indirect fashion. This way, the reader does not feel like we are bullying him. Subsubsection
Firm Convincing vs. Rudeness Standard
In the same part of the Supplement that you place the _inset Quotes eld inset
... Yes, we mean now...
_inset Quotes erd inset
translation, discuss the English version's use of _inset Quotes eld inset
firm convincing. _inset Quotes erd inset
Standard
You see, here in America, it is said that everything is permitted unless explicitly banned by law. As a result, manuals for computer software are frequently ignored and the software subsequently blamed for not being _inset Quotes eld inset
user-friendly. _inset Quotes erd inset
This is where the use of _inset Quotes eld inset
firm convincing _inset Quotes erd inset
comes in.
Standard
We who wrote the manuals added sentences insisting that the reader not ignore certain parts of the documentation. We wrote in a manner that was polite, yet firmly asserted that the user was misusing the software if he did not read the manual correctly. We did not, however, want to sound threatening, coercive, or bullying. Standard
In your culture, cajoling the reader into using the manuals correctly may not be necessary. It may, in fact, be outright rude. Additionally, translating the firm-but-convincing bits may not work. The translation may sound weird, or rude, or hostile. Therefore, you and your translation team will face many sentences that you cannot translate. Standard
You, the Translation Project Chief, must discuss this issue. Try and find parts of the original manuals where some friendly but firm convincing does not translate properly. Use these cases as the basis for examples of the problem. Be sure to then offer a solution (i. _separator e. _separator how you want such sentences translated.) If stumped, ask for help on the LyX Developer's List. Subsubsection
Anything Else? Standard
You can add more sections to the Supplement if you need to discuss other issues. There may be policies or guidelines that you want to set for your Translation Team. Be careful, however! Keep the Supplement on short default .
_end