_

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 LatexCommand

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 LatexCommand

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 LatexCommand

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 LatexCommand

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 LatexCommand

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 LatexCommand

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 LatexCommand

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 LatexCommand

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 LatexCommand

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 LatexCommand

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 LatexCommand

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