+++ /dev/null
-#LyX 1.6.0 created this file. For more info see http://www.lyx.org/
-\lyxformat 345
-\begin_document
-\begin_header
-\textclass article
-\use_default_options false
-\language english
-\inputencoding latin1
-\font_roman default
-\font_sans default
-\font_typewriter default
-\font_default_family default
-\font_sc false
-\font_osf false
-\font_sf_scale 100
-\font_tt_scale 100
-\graphics dvips
-\paperfontsize 12
-\spacing single
-\use_hyperref false
-\papersize default
-\use_geometry false
-\use_amsmath 0
-\use_esint 0
-\cite_engine basic
-\use_bibtopic false
-\paperorientation portrait
-\secnumdepth 3
-\tocdepth 3
-\paragraph_separation indent
-\defskip medskip
-\quotes_language english
-\papercolumns 1
-\papersides 1
-\paperpagestyle plain
-\tracking_changes false
-\output_changes false
-\author ""
-\author ""
-\end_header
-
-\begin_body
-
-\begin_layout Title
-Documentation Project Style Sheet
-\end_layout
-
-\begin_layout Author
-by John Weiss
-\end_layout
-
-\begin_layout Abstract
-This article is a style sheet.
- It describes, with examples, how the documentation should look and sound.
- The first few sections explain the font conventions and typography conventions
- all documentation writers should follow.
- Those sections also contain examples.
- It also explains the purpose of each of the different manuals.
- Follow it not merely to the letter, but also in spirit.
-\end_layout
-
-\begin_layout Abstract
-The Style Sheet for LyX documentation (hereafter known as the Style Sheet)
- applies to
-\emph on
-all
-\emph default
- forms of LyX documenation, regardless of language.
- There is a section for translators in the Style Sheet, towards the end.
-
-\emph on
-Read the entire Style Sheet!
-\emph default
- Even if you are a translator, I assume you know enough English to comprehend
- this document.
-\end_layout
-
-\begin_layout Section
-Questions and Clarifications
-\end_layout
-
-\begin_layout 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:
-\end_layout
-
-\begin_layout Quote
-If you have any questions about anything in the Style Sheet,
-\emph on
-ask first, write second!
-\end_layout
-
-\begin_layout 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.
-\end_layout
-
-\begin_layout Section
-Fonts
-\end_layout
-
-\begin_layout Standard
-We'll start with the easiest section, yet also the most important.
-\end_layout
-
-\begin_layout Standard
-This is how you should fontify text in the manuals:
-\end_layout
-
-\begin_layout List
-\labelwidthstring MMMMMMMM
-
-\emph on
-Emphasized
-\emph default
- general emphasis, generic arguments, titles of books, names the other manuals
- and of their sections, and notes from the authors
-\end_layout
-
-\begin_deeper
-\begin_layout Standard
-Do not overemphasize your text.
-\end_layout
-
-\end_deeper
-\begin_layout List
-\labelwidthstring MMMMMMMM
-
-\family typewriter
-Typewriter
-\family default
- program names, file names,
-\family typewriter
-man
-\family default
--page names, LaTeX code, LaTeX commands, LaTeX package names, and LyX code
- and functions
-\end_layout
-
-\begin_layout List
-\labelwidthstring MMMMMMMM
-
-\family sans
-Sans
-\begin_inset space ~
-\end_inset
-
-Serif
-\family default
- menu, button, or popup names, the names/lables of all widgets in a popup,
- the names of keyboard keys, and certain
-\begin_inset Quotes eld
-\end_inset
-
-special terms
-\begin_inset Quotes erd
-\end_inset
-
-
-\end_layout
-
-\begin_layout List
-\labelwidthstring MMMMMMMM
-
-\noun on
-Noun
-\begin_inset space ~
-\end_inset
-
-Style
-\noun default
- people's names
-\end_layout
-
-\begin_layout List
-\labelwidthstring MMMMMMMM
-
-\family sans
-\bar under
-U
-\bar default
-nderlined
-\begin_inset space ~
-\end_inset
-
-Sans
-\begin_inset space ~
-\end_inset
-
-Serif
-\family default
- Rich Fields added this to mimick the underlining of letters in the menus
- and on buttons.
- It helps to highlight the accelerator keys, and human brains store information
- best when they see it frequently.
-\end_layout
-
-\begin_deeper
-\begin_layout Description
-WARNING! --- When you do this, make sure you
-\emph on
-only
-\emph default
- shut off the underlining.
- Too many people send in things that look like:
-\begin_inset Newline newline
-\end_inset
-
-
-\family sans
-\bar under
-T
-\family default
-\bar default
-his
-\begin_inset Newline newline
-\end_inset
-
-\SpecialChar \ldots{}
-i.
-\begin_inset space ~
-\end_inset
-
-e.
-\begin_inset space ~
-\end_inset
-
-they not only shut off underlining, they turned off
-\family sans
-Sans
-\begin_inset space ~
-\end_inset
-
-Serif
-\family default
-, too!
-\emph on
-Don't do that!
-\emph default
- Make sure the entire word is still in
-\family sans
-Sans
-\begin_inset space ~
-\end_inset
-
-Serif
-\family default
- after you shut off the underlining.
-\end_layout
-
-\end_deeper
-\begin_layout List
-\labelwidthstring MMMMMMMM
-
-\series bold
-Bold
-\series default
- Unused.
-\end_layout
-
-\begin_deeper
-\begin_layout Standard
-If you want to emphasize any text, use
-\emph on
-Emphasized
-\emph default
-.
- LaTeX will put many things boldface on its own, such as
-\family sans
-Section
-\family default
-s, certain parts of equations, et cetera.
-\end_layout
-
-\begin_layout Standard
-Repeat: do not use boldface.
-\end_layout
-
-\end_deeper
-\begin_layout Standard
-Here are some examples:
-\end_layout
-
-\begin_layout Enumerate
-The function
-\family typewriter
-math-mode
-\family default
- appears in configuration files and in the LyX source.
- Therefore, it (and all other LyX function names) count as code and is set
- in
-\family typewriter
-Typewriter
-\family default
-.
-\end_layout
-
-\begin_layout Enumerate
-However,
-\family sans
-\bar under
-M
-\bar default
-ath
-\begin_inset space ~
-\end_inset
-
-mode
-\family default
- is a menu item in the
-\family sans
-\bar under
-M
-\bar default
-ath
-\family default
- menu, so it appears in
-\family sans
-Sans
-\begin_inset space ~
-\end_inset
-
-Serif
-\family default
-.
- Notice the use of
-\family sans
-\bar under
-U
-\bar default
-nderlined
-\begin_inset space ~
-\end_inset
-
-Sans
-\begin_inset space ~
-\end_inset
-
-Serif
-\family default
- for the accelerator keys.
-\end_layout
-
-\begin_layout Enumerate
-Consider the following excerpt from the introduction of one of the manuals:
-\end_layout
-
-\begin_deeper
-\begin_layout Quotation
-
-\family sans
-Return
-\family default
- and
-\family sans
-Enter
-\family default
- both refer to the same key.
- Some keyboards label the
-\family sans
-Return
-\family default
- key as
-\begin_inset Quotes eld
-\end_inset
-
-Return,
-\begin_inset Quotes erd
-\end_inset
-
- others as
-\begin_inset Quotes eld
-\end_inset
-
-Enter,
-\begin_inset Quotes erd
-\end_inset
-
- still others have two keys.
- LyX treats all of them as the same key, so we'll use
-\family sans
-Return
-\family default
- and
-\family sans
-Enter
-\family default
- interchangeably.
-\end_layout
-
-\begin_layout Standard
-Notice that the key name,
-\family sans
-Return
-\family default
-, is in
-\family sans
-Sans
-\begin_inset space ~
-\end_inset
-
-Serif
-\family default
-, but
-\emph on
-only
-\emph default
- when it references the key itself! When I described how the manufacturer
- chose to label its keyboard, I used Roman and put the word in quotes.
- There is a semantic difference.
-\end_layout
-
-\end_deeper
-\begin_layout Enumerate
-Take the following command:
-\end_layout
-
-\begin_deeper
-\begin_layout Standard
-
-\family typewriter
-lpr -P
-\family default
-\emph on
-printername
-\end_layout
-
-\begin_layout Standard
-Notice that the argument to the
-\family typewriter
--P
-\family default
- option is in
-\emph on
-Roman Italics
-\emph default
- (i.
-\begin_inset space \thinspace{}
-\end_inset
-
-g.
- emphasized).
- This is a case where you don't use
-\family typewriter
-Typewriter
-\family default
- for code, because you want the generic argument label to stand out.
- On the other hand, if you were specifying an argument, for example,
-\begin_inset Quotes eld
-\end_inset
-
-
-\family typewriter
-lpr -Pduaneps
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
-, you'd leave it in
-\family typewriter
-Typewriter
-\family default
-.
-
-\end_layout
-
-\end_deeper
-\begin_layout Enumerate
-Any LaTeX commands and code, and any
-\emph on
-unsupported
-\emph default
- LaTeX package names get set in
-\family typewriter
-Typewriter
-\family default
-.
- For example,
-\begin_inset Quotes eld
-\end_inset
-
-
-\family typewriter
-multicol
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
- is the name of an unsupported LaTeX package, but
-\begin_inset Quotes eld
-\end_inset
-
-
-\family sans
-book
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
- is a supported LaTeX class.
-\end_layout
-
-\begin_layout Section
-Keys
-\end_layout
-
-\begin_layout Standard
-The canonical keyboard contains these keys:
-\end_layout
-
-\begin_layout Itemize
-
-\family sans
-C-
-\family default
- or
-\family sans
-Control-
-\family default
-
-\end_layout
-
-\begin_layout Itemize
-
-\family sans
-S-
-\family default
- or
-\family sans
-Shift-
-\family default
-
-\end_layout
-
-\begin_layout Itemize
-
-\family sans
-M-
-\family default
- or
-\family sans
-Meta-
-\family default
-
-\end_layout
-
-\begin_deeper
-\begin_layout Standard
-Self-explanatory.
- Be lazy and
-\emph on
-use the abbreviations
-\emph default
- whenever possible.
-\end_layout
-
-\end_deeper
-\begin_layout Itemize
-
-\family sans
-F1 F2 F3 F4 F5 F6 F7 F8 F9 F10 F11 F12
-\end_layout
-
-\begin_deeper
-\begin_layout Standard
-The function keys.
- Most modern keyboards have all 12.
-\end_layout
-
-\end_deeper
-\begin_layout Itemize
-
-\family sans
-Esc
-\family default
-
-\end_layout
-
-\begin_deeper
-\begin_layout Standard
-The
-\begin_inset Quotes eld
-\end_inset
-
-Escape key.
-\begin_inset Quotes erd
-\end_inset
-
-
-\end_layout
-
-\end_deeper
-\begin_layout Itemize
-
-\family sans
-Insert
-\family default
-
-\family sans
-Delete
-\family default
-
-\family sans
-Home
-\family default
-
-\family sans
-End
-\family default
-
-\family sans
-PageUp
-\family default
-
-\family sans
-PageDown
-\end_layout
-
-\begin_deeper
-\begin_layout Standard
-These are the 6 keys that appear above the cursor keys on many PC keyboards.
- Consider them as part of the standard motion keys.
-\end_layout
-
-\end_deeper
-\begin_layout Itemize
-
-\family sans
-Left Right Up Down
-\end_layout
-
-\begin_deeper
-\begin_layout Standard
-The four standard motion keys.
- There is no need to put the word
-\begin_inset Quotes eld
-\end_inset
-
-arrow
-\begin_inset Quotes erd
-\end_inset
-
- anywhere, since that's obvious.
-\begin_inset Foot
-status collapsed
-
-\begin_layout Plain Layout
-Same goes for
-\begin_inset Quotes eld
-\end_inset
-
-cursor key
-\begin_inset Quotes erd
-\end_inset
-
-.
- Even the word
-\begin_inset Quotes eld
-\end_inset
-
-key
-\begin_inset Quotes erd
-\end_inset
-
- after one of these may be redundant in certain situations.
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_deeper
-\begin_layout Itemize
-
-\family sans
-Return
-\family default
- and
-\family sans
-Enter
-\family default
-
-\end_layout
-
-\begin_deeper
-\begin_layout Standard
-I won't throw a hissy fit if you use one instead of the other.
- I'd prefer if you used
-\family sans
-Return
-\family default
- over
-\family sans
-Enter
-\family default
-, but it's okay if you slip up and forget.
- Since these two keys are bound to the same function in LyX, it doesn't
- really matter.
-\end_layout
-
-\end_deeper
-\begin_layout Standard
-You do not need to explain everywhere what the
-\family sans
-Meta
-\family default
- key is or where the
-\family sans
-Left
-\family default
- key is, et cetera.
- The user isn't stupid.
- Also, someone will document anything that isn't clear (e.
-\begin_inset space ~
-\end_inset
-
-g.
-\begin_inset space ~
-\end_inset
-
-the
-\family sans
-Meta
-\family default
- vs.
-
-\family sans
-Alt
-\family default
- problem) someplace in the introduction.
- No need for you to repeat someone else's work.
-\end_layout
-
-\begin_layout Standard
-LyX does not support keyboards missing any of the keys described above,
- with one exception.
- LyX can support a keyboard missing
-\family sans
-F11
-\family default
- and
-\family sans
-F12
-\family default
-.
- There is a keyboard accelerator for
-\family sans
-F10
-\family default
-, but this is the only function key LyX assumes exists.
- Nevertheless, these details are of minor, if any, concern for the documentation.
- Assume the aforementioned keys exist.
-\end_layout
-
-\begin_layout Section
-Mice
-\end_layout
-
-\begin_layout Standard
-The word
-\begin_inset Quotes eld
-\end_inset
-
-mouse
-\begin_inset Quotes erd
-\end_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.
-
-\end_layout
-
-\begin_layout Standard
-Exception: you're writing an Author's Note (see section
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sec:author-notes"
-
-\end_inset
-
-) and you need to mention something about the mouse.
- Since the rest of the note is in
-\emph on
-Emphasized
-\emph default
-, your description of
-\begin_inset Quotes eld
-\end_inset
-
-middle mouse button
-\begin_inset Quotes erd
-\end_inset
-
- should be emphasized, as well.
- There are a couple of other cases like this one; use your judgement.
-\end_layout
-
-\begin_layout 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
-\begin_inset Quotes eld
-\end_inset
-
-mouse
-\begin_inset Quotes erd
-\end_inset
-
- or
-\begin_inset Quotes eld
-\end_inset
-
-mouse button
-\begin_inset Quotes erd
-\end_inset
-
- stand out.
-\end_layout
-
-\begin_layout Section
-Special Typography
-\end_layout
-
-\begin_layout Standard
-Do the following:
-\end_layout
-
-\begin_layout Description
-Multi-word
-\begin_inset space ~
-\end_inset
-
-names Use a
-\family sans
-Protected
-\begin_inset space ~
-\end_inset
-
-Blank
-\family default
- between the words for menu and widget names.
- E.
-\begin_inset space ~
-\end_inset
-
-g.:
-\family sans
-Save
-\begin_inset space ~
-\end_inset
-
-As
-\family default
-, not
-\family sans
-Save As
-\family default
-.
-
-\end_layout
-
-\begin_deeper
-\begin_layout Standard
-This holds for things in
-\family typewriter
-Typewriter
-\family default
- as well as
-\family sans
-Sans
-\begin_inset space ~
-\end_inset
-
-Serif
-\family default
-, with one caveat.
- If you have a long code example, one that can't simply be inlined and put
- in
-\family typewriter
-Typewriter
-\family default
-, put that in a
-\family sans
-LyX
-\begin_inset space ~
-\end_inset
-
-Code
-\family default
- environment.
-\end_layout
-
-\begin_layout Standard
-I want the
-\family sans
-Protected
-\begin_inset space ~
-\end_inset
-
-Blank
-\family default
- so that the name doesn't get split between two lines, which is visually
- disruptive.
- If something with a
-\family sans
-Protected
-\begin_inset space ~
-\end_inset
-
-Blank
-\family default
- is near the end of a line and overflows the margin, use a
-\family typewriter
-
-\backslash
-sloppypar
-\family default
- in that parargraph (consult a LaTeX book for more about
-\begin_inset Quotes eld
-\end_inset
-
-
-\family typewriter
-
-\backslash
-sloppypar
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
-) or manually add a hypenation point.
-\end_layout
-
-\end_deeper
-\begin_layout Description
-Special
-\begin_inset space ~
-\end_inset
-
-Terms These are things like the following:
-\end_layout
-
-\begin_deeper
-\begin_layout Itemize
-
-\family sans
-HFill
-\family default
-
-\end_layout
-
-\begin_layout Itemize
-
-\family sans
-VFill
-\family default
-
-\end_layout
-
-\begin_layout Itemize
-
-\family sans
-Table
-\begin_inset space ~
-\end_inset
-
-Float
-\end_layout
-
-\begin_layout Itemize
-
-\family sans
-Figure
-\begin_inset space ~
-\end_inset
-
-Float
-\end_layout
-
-\begin_deeper
-\begin_layout Standard
-Use
-\family sans
-Sans
-\begin_inset space ~
-\end_inset
-
-Serif
-\family default
- font and, in the case of
-\family sans
-HFill
-\family default
- and
-\family sans
-VFill
-\family default
-, capitalize the first two letters.
-\end_layout
-
-\begin_layout Standard
-Why are these terms special? They are concepts which the seasoned LaTeX-pert
- is familiar with, but which the new LyX user is not.
- I want them to stand out from the rest of the text, hence the use of
-\family sans
-Sans
-\begin_inset space ~
-\end_inset
-
-Serif
-\family default
- for them.
-\end_layout
-
-\end_deeper
-\end_deeper
-\begin_layout Standard
-Seasoned LyX Team Members: Are there other terms that require this special
- status? On the other hand, should we eliminate this style completely?
-\end_layout
-
-\begin_layout Description
-Terminology Note the following:
-\end_layout
-
-\begin_layout Itemize
-\begin_inset Quotes eld
-\end_inset
-
-dialog
-\begin_inset Quotes erd
-\end_inset
-
- not
-\begin_inset Quotes eld
-\end_inset
-
-popup
-\begin_inset Quotes erd
-\end_inset
-
- or
-\begin_inset Quotes eld
-\end_inset
-
-window
-\begin_inset Quotes erd
-\end_inset
-
-.
-
-\begin_inset Quotes eld
-\end_inset
-
-Confirmation alert
-\begin_inset Quotes erd
-\end_inset
-
- not
-\begin_inset Quotes eld
-\end_inset
-
-dialog
-\begin_inset Quotes erd
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Itemize
-PostScript® is a registered trademark of Adobe Corp.
-
-\emph on
-You must put the ® after it or we'll get sued!
-\emph default
- I also want it written as seen here, always capitalized.
- Not
-\begin_inset Quotes eld
-\end_inset
-
-postscript®,
-\begin_inset Quotes erd
-\end_inset
-
- or
-\begin_inset Quotes eld
-\end_inset
-
-Postscript®
-\begin_inset Quotes erd
-\end_inset
-
- but
-\begin_inset Quotes eld
-\end_inset
-
-PostScript®
-\begin_inset Quotes erd
-\end_inset
-
- - both of them capitalized, in the default font (i.
-\begin_inset space ~
-\end_inset
-
-.
-\begin_inset space \thinspace{}
-\end_inset
-
-g.
-\begin_inset space ~
-\end_inset
-
-Roman).
- If you must, cut and paste it from here.
-\end_layout
-
-\begin_deeper
-\begin_layout Standard
-I am going to say this again:
-\end_layout
-
-\begin_layout Standard
-\begin_inset VSpace 0.37cm
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-\align center
-
-\size larger
-\emph on
-You must put the ® after PostScript® or we'll get sued!
-\end_layout
-
-\begin_layout Standard
-\begin_inset VSpace 0.51cm
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-I mean it! American companies like to sue anything that moves.
- We could get in
-\emph on
-major trouble
-\emph default
- by forgetting that ®.
- So, don't.
- Got it?
-\end_layout
-
-\end_deeper
-\begin_layout Itemize
-Similarly, if you use any other registered trademark in any documentation,
- put the ® after it, too.
-\end_layout
-
-\begin_layout Description
-Menu
-\begin_inset space ~
-\end_inset
-
-Items When quick-referencing an item in a menu, use the menu separator:
-
-\begin_inset Quotes eld
-\end_inset
-
-\SpecialChar \menuseparator
-
-\begin_inset Quotes erd
-\end_inset
-
-.
- Example:
-\family sans
-File\SpecialChar \menuseparator
-Save
-\family default
-.
- Notice that there are
-\emph on
-no spaces
-\emph default
- around the
-\begin_inset Quotes eld
-\end_inset
-
-\SpecialChar \menuseparator
-
-\begin_inset Quotes erd
-\end_inset
-
- and that it's in
-\family sans
-Sans
-\begin_inset space ~
-\end_inset
-
-Serif
-\family default
-, just like the menu and item names.
-\end_layout
-
-\begin_deeper
-\begin_layout Enumerate
-The reason why I want no spaces around the
-\begin_inset Quotes eld
-\end_inset
-
-\SpecialChar \menuseparator
-
-\begin_inset Quotes erd
-\end_inset
-
- is to prevent LyX from splitting terms across lines.
- The same goes for using
-\family sans
-Protected
-\begin_inset space ~
-\end_inset
-
-Blank
-\family default
-s between multi-word terms.
- The split would be visually disruptive.
-\end_layout
-
-\begin_layout Enumerate
-A
-\begin_inset Quotes eld
-\end_inset
-
-\SpecialChar \menuseparator
-
-\begin_inset Quotes erd
-\end_inset
-
- goes between menu names and item names
-\emph on
-only
-\emph default
-.
- (Yes, submenus are okay, too).
-\end_layout
-
-\begin_layout Enumerate
-
-\emph on
-NEVER
-\emph default
- put
-\begin_inset Quotes eld
-\end_inset
-
-\SpecialChar \menuseparator
-
-\begin_inset Quotes erd
-\end_inset
-
- between menu items and dialog names.
- Example:
-\begin_inset Quotes eld
-\end_inset
-
-
-\family sans
-\bar under
-L
-\bar default
-ayout\SpecialChar \menuseparator
-P
-\bar under
-a
-\bar default
-per\SpecialChar \menuseparator
-Paper
-\begin_inset space ~
-\end_inset
-
-Dialog
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
-
-\emph on
-IS STRICTLY FORBIDDEN!
-\emph default
-
-\end_layout
-
-\begin_deeper
-\begin_layout Standard
-
-\emph on
-NEVER
-\emph default
- put
-\begin_inset Quotes eld
-\end_inset
-
-\SpecialChar \menuseparator
-
-\begin_inset Quotes erd
-\end_inset
-
- between popup names and any dialog.
- Example:
-\begin_inset Quotes eld
-\end_inset
-
-
-\family sans
-Paper
-\begin_inset space ~
-\end_inset
-
-Dialog\SpecialChar \menuseparator
-P
-\bar under
-o
-\bar default
-rtrait
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
-
-\emph on
-IS STRICTLY FORBIDDEN!
-\end_layout
-
-\begin_layout Standard
-
-\emph on
-NEVER
-\emph default
- put
-\begin_inset Quotes eld
-\end_inset
-
-\SpecialChar \menuseparator
-
-\begin_inset Quotes erd
-\end_inset
-
- between menu items and any dialog.
- Example:
-\begin_inset Quotes eld
-\end_inset
-
-
-\family sans
-\bar under
-L
-\bar default
-ayout\SpecialChar \menuseparator
-P
-\bar under
-a
-\bar default
-per\SpecialChar \menuseparator
-P
-\bar under
-o
-\bar default
-rtrait
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
-
-\emph on
-IS STRICTLY FORBIDDEN!
-\end_layout
-
-\begin_layout Standard
-Either write out the description, or use context to eliminate any need to
- repeat menu items, dialog names, etc.
-\end_layout
-
-\end_deeper
-\end_deeper
-\begin_layout Description
-Note
-\begin_inset space ~
-\end_inset
-
-Boxes LyX has a feature for adding comments that appear only within the
- LyX GUI.
- Here's one:
-\begin_inset Note Note
-status collapsed
-
-\begin_layout Plain Layout
-These should NEVER appear in the manuals.
-\end_layout
-
-\end_inset
-
-.
- You will see nothing in a printout of the Style Sheet.
- Therefore, they have no place in the manuals.
- Period.
-
-\end_layout
-
-\begin_deeper
-\begin_layout Standard
-If you have a parenthetical comment you want to make, the reader should
- see it too, even in the printed version.
- Use an Author's Note (see section
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sec:author-notes"
-
-\end_inset
-
-) in place of the Note-Boxes.
-\end_layout
-
-\end_deeper
-\begin_layout Description
-\begin_inset Quotes eld
-\end_inset
-
-(\SpecialChar \ldots{}
-)
-\begin_inset Quotes erd
-\end_inset
-
-,
-\begin_inset space ~
-\end_inset
-
-
-\begin_inset Quotes eld
-\end_inset
-
-[\SpecialChar \ldots{}
-]
-\begin_inset Quotes erd
-\end_inset
-
-
-\begin_inset space ~
-\end_inset
-
-and
-\begin_inset space ~
-\end_inset
-
-
-\begin_inset Quotes eld
-\end_inset
-
-{\SpecialChar \ldots{}
-}
-\begin_inset Quotes erd
-\end_inset
-
- I have recently been corrected about the use of parentheses.
- Standard English typesetting uses the normal parentheses,
-\begin_inset Quotes eld
-\end_inset
-
-(\SpecialChar \ldots{}
-)
-\begin_inset Quotes erd
-\end_inset
-
-, around any aside, remark, or parenthetical expression.
- The bracket,
-\begin_inset Quotes eld
-\end_inset
-
-[\SpecialChar \ldots{}
-]
-\begin_inset Quotes erd
-\end_inset
-
-, is used only within quotations (see section
-\begin_inset space ~
-\end_inset
-
-
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sec:quote"
-
-\end_inset
-
-).
- The brace,
-\begin_inset Quotes eld
-\end_inset
-
-{\SpecialChar \ldots{}
-}
-\begin_inset Quotes erd
-\end_inset
-
-, is never used.
- Therefore, never use
-\begin_inset Quotes eld
-\end_inset
-
-[\SpecialChar \ldots{}
-]
-\begin_inset Quotes erd
-\end_inset
-
- or
-\begin_inset Quotes eld
-\end_inset
-
-{\SpecialChar \ldots{}
-}
-\begin_inset Quotes erd
-\end_inset
-
- unless otherwise specified by this Style Sheet.
-\end_layout
-
-\begin_layout Description
-Dashes: Be sure to use the correct one.
- A single
-\begin_inset Quotes eld
-\end_inset
-
-
-\family typewriter
--
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
- character is not a dash, it's a hyphen.
- Use it only as a hyphen.
-
-\end_layout
-
-\begin_deeper
-\begin_layout Standard
-Instead, use an
-\begin_inset Quotes eld
-\end_inset
-
-en-dash
-\begin_inset Quotes erd
-\end_inset
-
- or an
-\begin_inset Quotes eld
-\end_inset
-
-em- dash.
-\begin_inset Quotes erd
-\end_inset
-
- Two back-to-back
-\begin_inset Quotes eld
-\end_inset
-
-
-\family typewriter
--
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
- characters form the en-dash.
- Three
-\begin_inset Quotes eld
-\end_inset
-
-
-\family typewriter
--
-\family default
-
-\begin_inset Quotes erd
-\end_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
-
-\begin_inset Quotes eld
-\end_inset
-
-
-\family typewriter
--
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
- characters into a single, unbroken line.
-\end_layout
-
-\end_deeper
-\begin_layout Section
-Cross-References and Labels
-\end_layout
-
-\begin_layout Standard
-Use the following labelling conventions:
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-sec:xxx Use this for
-\family sans
-Section
-\family default
-s as well as
-\family sans
-Chapter
-\family default
-s,
-\family sans
-Subsection
-\family default
-s,
-\family sans
-Subsubsection
-\family default
-s, etc.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-eqn:xxx Use this for Equations, should you need to create any.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-tbl:xxxx Use this for tables inside of a table float.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-fig:xxx Use this for figures inside of figure floats.
-\end_layout
-
-\begin_layout Standard
-Additionally, you should put the label at one of two locations:
-\end_layout
-
-\begin_layout Enumerate
-The
-\emph on
-beginning of the paragraph
-\emph default
-, after a section heading, or at the beginning of captions, etc.
- It should be the first thing on the first line.
- Don't put a space betweeen it and the first word.
-\end_layout
-
-\begin_layout Enumerate
-If there is no paragraph after a section heading, put it at the
-\emph on
-end of the last line.
-
-\emph default
-
-\end_layout
-
-\begin_deeper
-\begin_layout Standard
-Example: You have a
-\family sans
-Section
-\family default
- which is immediately followed by a
-\family sans
-Subsection
-\family default
- heading.
- This is a case where you need to put the label at the end of the
-\family sans
-Section
-\family default
- heading.
- I know it looks ugly; not much we can do about that, though.
-\end_layout
-
-\end_deeper
-\begin_layout Section
-Content --- What Goes Where
-\end_layout
-
-\begin_layout Standard
-This is
-\emph on
-very
-\emph default
- important to anyone documenting a new feature.
- If you need to add new documentation, pay attention.
-
-\end_layout
-
-\begin_layout 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 that mess.
-\end_layout
-
-\begin_layout Standard
-With that in mind, I have some instructions for how to keep things organized:
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-Intro.lyx
-\family default
- Please, don't touch this file.
- It's essentially complete, anyhow.
- Only the editor(s) should make changes to this, as this file contains info
- about how to contribute to the doc project.
- That's really the only stuff that should need to change, and even then,
- only when a new maintainer comes along.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-UserGuide.lyx
-\family default
- This file is complete.
- Any changes should be for updates
-\emph on
-only
-\emph default
-.
- DO NOT ADD new features to here willy-nilly.
- Let the editor decide if --- and when --- new sections go in here.
- Place any new features in\SpecialChar \ldots{}
-
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-Extended.lyx
-\family default
- This is where all new features go from now on.
- It's in the style of a bound journal --- each section is an
-\begin_inset Quotes eld
-\end_inset
-
-article
-\begin_inset Quotes erd
-\end_inset
-
- from the author of the feature.
- Also, anyone who writes a
-\family typewriter
-.layout
-\family default
- file for a new document class should write a section describing that new
- class and how to use it.
- That also goes here.
-\end_layout
-
-\begin_deeper
-\begin_layout Standard
-Note, however, that you are
-\emph on
-not
-\emph default
- excused from following this Style Sheet just because the sections of
-\family typewriter
-Extended.lyx
-\family default
- are in the form of a journal article.
-\end_layout
-
-\end_deeper
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-Tutorial.lyx
-\family default
- This file is complete.
- Do not change or add to without permission of the Documenation Project
- Editor.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-Customization.lyx
-\family default
- This document describes advanced features, most of which alter the look,
- feel, and behavior of LyX.
- This manual is still a bit incomplete, although that may change soon.
- Check for updates often.
-\end_layout
-
-\begin_deeper
-\begin_layout Standard
-If you are unsure whether or not something belongs in
-\family typewriter
-Customization.lyx
-\family default
-, then, most-likely, it
-\emph on
-really
-\emph default
- belongs in
-\family typewriter
-Extended.lyx
-\family default
-.
- Again, let the current editor of the LyX documentation decide if your new
- section should be migrated to
-\family typewriter
-Customization.lyx
-\family default
-.
-\end_layout
-
-\end_deeper
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-Reference.lyx
-\family default
- I'd prefer to completely finish this one before doing anything else, but
- that's unrealistic.
- LyX keeps changing so much that I think the
-\emph on
-Reference Manual
-\emph default
- will be the last one completed.
- However, I'd like it if the developer's would add entries anytime they
- create a new function or popup.
- That would help things immensely!
-\end_layout
-
-\begin_deeper
-\begin_layout Standard
-Note that the
-\emph on
-Reference Manual
-\emph default
- follows this Style Sheet for the most part.
- There are, however, additional rules to follow when making new entries.
- At the top of this manual, there are examples of and a template for
-\emph on
-Reference Manual
-\emph default
- entries.
- Use them.
-\end_layout
-
-\end_deeper
-\begin_layout Section
-Writing Style: The Primary Manuals
-\end_layout
-
-\begin_layout Standard
-While I want to make contributing to the Documentation Project as painless
- as possible for newcomers, I also want the newcomers to be painless on
- the existing Documentation Team! Ergo, I've written this section to give
- some flavor to guide everyone's individual style.
-
-\end_layout
-
-\begin_layout Subsection
-Language
-\end_layout
-
-\begin_layout Standard
-All contributions to the
-\emph on
-primary
-\emph default
- LyX documentation must be in English.
- I don't care if it's British, Australian, or American English.
- The DocTeam editor will proofread for glaring mistakes and fix them.
-\end_layout
-
-\begin_layout Standard
-Don't get hung up on semantics.
- English is a flexible language, and just because your Mothertongue-to-English
- dictionary gives only one translation for a word doesn't necessarily mean
- it's so.
- We've had some discussions and misunderstandings on the Developers' List
- because of this very problem.
- If something is unclear (or just plain weird) due to a translation problem,
- one of the American/British/Australian developers can fix it.
-\end_layout
-
-\begin_layout Standard
-Nota Bene: by
-\emph on
-primary
-\emph default
- documentation, I exclude the translations.
- We usually don't have enough people to cover the manuals in one language,
- let alone more than one.
- Subsequently, the tranlsations are just that --- translations of the English
- version of the LyX manuals.
- The translation efforts require have their own set of guidelines.
- See section
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sec:translations"
-
-\end_inset
-
- for more info.
-\end_layout
-
-\begin_layout Subsection
-Wearing Many Hats:
-\begin_inset Newline newline
-\end_inset
-
-Commentary from the Author (i.
-\begin_inset space ~
-\end_inset
-
-e.: You)
-\end_layout
-
-\begin_layout Standard
-\begin_inset CommandInset label
-LatexCommand label
-name "sec:author-notes"
-
-\end_inset
-
-I want to make it easy for everyone when it comes to documenting things.
- Some features are incomplete.
- Some, you might not know everything about.
- Sometimes, you may want to comminucate something to me or the reader or
- other DocTeam members.
- Sometimes, you may want to
-\begin_inset Quotes eld
-\end_inset
-
-speak for yourself;
-\begin_inset Quotes erd
-\end_inset
-
- you want to say something that is your personal opinion and using
-\begin_inset Quotes eld
-\end_inset
-
-we
-\begin_inset Quotes erd
-\end_inset
-
- would be inappropriate.
-\end_layout
-
-\begin_layout Standard
-In short, when you contribute to the LyX Docs, you wear many hats.
-\end_layout
-
-\begin_layout Standard
-For occasions when you need to switch hats, I've designed some special mechanism
-s.
-\end_layout
-
-\begin_layout Subsubsection
-Personal
-\begin_inset space ~
-\end_inset
-
-Notes: The
-\begin_inset Quotes eld
-\end_inset
-
-Me
-\begin_inset Quotes erd
-\end_inset
-
- Hat
-\end_layout
-
-\begin_layout Standard
-These are footnotes.
- They begin with the following:
-\end_layout
-
-\begin_layout Quote
-Note from
-\noun on
-Name of Person
-\noun default
-:
-\end_layout
-
-\begin_layout Standard
-\SpecialChar \ldots{}
-using the
-\noun on
-Noun Style
-\noun default
- for the person's name and without the quotes.
- The rest of the footnote is the actual comment.
-
-\end_layout
-
-\begin_layout 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
-\begin_inset Quotes eld
-\end_inset
-
-me
-\begin_inset Quotes erd
-\end_inset
-
- hat, i.
-\begin_inset space ~
-\end_inset
-
-e.
-\begin_inset space ~
-\end_inset
-
-to speak for yourself instead of for the LyX Team.
-\end_layout
-
-\begin_layout 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
-\begin_inset Quotes eld
-\end_inset
-
-Note from
-\noun on
-Name of Person
-\noun default
-:
-\begin_inset Quotes erd
-\end_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
-\family sans
-Quotation
-\family default
-.
-\end_layout
-
-\begin_layout Subsubsection
-Author's
-\begin_inset space ~
-\end_inset
-
-Notes: The
-\begin_inset Quotes eld
-\end_inset
-
-Author
-\begin_inset Quotes erd
-\end_inset
-
- Hat
-\end_layout
-
-\begin_layout 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:
-\end_layout
-
-\begin_layout 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.
-\end_layout
-
-\begin_layout Itemize
-You need to leave a note for yourself.
-\end_layout
-
-\begin_layout Itemize
-You need to leave a note for the editor or the other DocTeam members.
-\end_layout
-
-\begin_layout 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.
-\end_layout
-
-\begin_layout Standard
-At such times, you are wearing your
-\begin_inset Quotes eld
-\end_inset
-
-I am the Author
-\begin_inset Quotes erd
-\end_inset
-
- hat, if you will.
-\end_layout
-
-\begin_layout Standard
-The typography for an
-\begin_inset Quotes eld
-\end_inset
-
-Author's Note
-\begin_inset Quotes erd
-\end_inset
-
- is as follows:
-\end_layout
-
-\begin_layout Itemize
-They go in the body of the text, in brackets,
-\begin_inset Quotes eld
-\end_inset
-
-[]
-\begin_inset Quotes erd
-\end_inset
-
-, not any other form of parentheses.
- The bracket are in the default character style.
-\end_layout
-
-\begin_layout Itemize
-The text of the note itself, however, is emphasized.
-
-\end_layout
-
-\begin_layout Itemize
-Begin with the words,
-\begin_inset Quotes eld
-\end_inset
-
-
-\emph on
-Author's Note:
-\emph default
-
-\begin_inset Quotes erd
-\end_inset
-
- and end with an em-dash,
-\begin_inset Quotes eld
-\end_inset
-
----
-\begin_inset Quotes erd
-\end_inset
-
-, followed by your initials.
-
-\end_layout
-
-\begin_layout Standard
-Here's an example: [
-\emph on
-Author's Note: This is an example note.
- ---jw
-\emph default
-].
-\end_layout
-
-\begin_layout Standard
-The form of the Author's Note, by the way, isn't a suggestion or request.
- It is
-\emph on
-mandatory
-\emph default
-.
- All Author's Notes must begin with this text, verbatim:
-\begin_inset Quotes eld
-\end_inset
-
-[
-\emph on
-Author's Note:
-\emph default
-
-\begin_inset Quotes erd
-\end_inset
-
-.
- Abbreviations to
-\begin_inset Quotes eld
-\end_inset
-
-AN
-\begin_inset Quotes erd
-\end_inset
-
- are or any other variant are forbidden.
- The Author's Note must end with an em-dash, which is 3
-\begin_inset Quotes eld
-\end_inset
-
--
-\begin_inset Quotes erd
-\end_inset
-
- characters:
-\begin_inset Quotes eld
-\end_inset
-
----
-\begin_inset Quotes erd
-\end_inset
-
-.
- Do not use 2 or 1
-\begin_inset Quotes eld
-\end_inset
-
--
-\begin_inset Quotes erd
-\end_inset
-
-; you must use 3 (and 5 is right out).
-\end_layout
-
-\begin_layout Standard
-\begin_inset Quotes eld
-\end_inset
-
-Author's Notes
-\begin_inset Quotes erd
-\end_inset
-
- are inherently transient, and should disapear as a manual matures.
-\end_layout
-
-\begin_layout Subsubsection
-Footnotes:
-\end_layout
-
-\begin_layout Standard
-You are also free to use footnotes on their own in addition to the Personal
- Notes and/or Author's Notes.
- I've frequently used footnotes to \SpecialChar \ldots{}
- well, to comment on parts of a section
- without putting the commentary into the body of the text.
-\end_layout
-
-\begin_layout Paragraph*
-Mixing Footnotes and Personal Notes
-\end_layout
-
-\begin_layout 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
-\family sans
-Quotation
-\family default
- paragraph environment.
-\end_layout
-
-\begin_layout Paragraph*
-Mixing Footnotes and Author's Notes
-\end_layout
-
-\begin_layout Standard
-Author's Notes should
-\emph on
-never
-\emph default
- go in footnotes.
-
-\end_layout
-
-\begin_layout Paragraph*
-Mixing Personal Notes and Author's Notes
-\end_layout
-
-\begin_layout Standard
-Forbidden; these two are mutually exclusive.
-\end_layout
-
-\begin_layout Subsubsection
-Summary of Use
-\end_layout
-
-\begin_layout Itemize
-Personal Notes:
-\begin_inset Newline newline
-\end_inset
-
-A
-\emph on
-short
-\emph default
- opinion --- yours or another LyX developer's --- about anything.
- Anywhere in the manuals you wish to speak for yourself instead the the
- LyX Team, use this.
- If you have a long rant, however, quote yourself (see section
-\begin_inset space ~
-\end_inset
-
-
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sec:quote"
-
-\end_inset
-
-).
-\end_layout
-
-\begin_layout Itemize
-Author's Note:
-\begin_inset Newline newline
-\end_inset
-
-Use this to describe things in LyX (or the manuals) that may change in the
- future or are somehow incomplete.
- Author's Notes are supposed to disappear as a manual matures.
-\end_layout
-
-\begin_layout Itemize
-Plain Footnotes:
-\begin_inset Newline newline
-\end_inset
-
-Used for text fragments that almost fit into the flow of the text\SpecialChar \ldots{}
-but not
- quite.
-\end_layout
-
-\begin_layout Standard
-When using these three mechanisms, in addition to rigorously following their
- descriptions, please use them properly.
- I 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.
-\end_layout
-
-\begin_layout Subsection
-General Stylistic Guidelines
-\end_layout
-
-\begin_layout Standard
-Everything in this section is
-\emph on
-mandatory to all documenters
-\emph default
-, regardless the language you're writing in.
-
-\end_layout
-
-\begin_layout Subsubsection
-Typography
-\end_layout
-
-\begin_layout Enumerate
-Use the typography rules outlined in the beginning sections of this document.
-\end_layout
-
-\begin_layout Enumerate
-Don't, however, mimic the typography of this file.
- Yes, the Style Sheet doesn't follow the Style Sheet (grin).
-\end_layout
-
-\begin_layout Enumerate
-There is some typographic freedom in those rules in earlier sections.
- Use that freedom wisely.
- Most importanly, never sacrifice the online appearance for the printed
- appearance and vice versa.
-\end_layout
-
-\begin_deeper
-\begin_layout Standard
-An example is in the
-\emph on
-User's Guide
-\emph default
-.
- There is a footnote using the
-\family typewriter
-multcols
-\family default
- command to divide a long
-\family sans
-Itemize
-\family default
- environment into 3 columns.
- It adds some LaTeX commands to the online version, the so-called
-\begin_inset Quotes eld
-\end_inset
-
-Evil Red Text
-\begin_inset Quotes erd
-\end_inset
-
- that some so vehemently oppose.
- Without it, however, that footnote takes up over two pages, most of which
- is empty space.
- This is an example of permitting a little ugliness in the online version
- to get the printed version to look right.
-\end_layout
-
-\end_deeper
-\begin_layout Enumerate
-When in doubt, compromise.
-\end_layout
-
-\begin_deeper
-\begin_layout Standard
-When in doubt, use good judgement.
-\end_layout
-
-\end_deeper
-\begin_layout Subsubsection
-Semantics
-\end_layout
-
-\begin_layout Enumerate
-You are
-\begin_inset Quotes eld
-\end_inset
-
-we
-\begin_inset Quotes erd
-\end_inset
-
-.
-\end_layout
-
-\begin_deeper
-\begin_layout Standard
-When you speak, you speak for the entire LyX Team, so use
-\begin_inset Quotes eld
-\end_inset
-
-we
-\begin_inset Quotes erd
-\end_inset
-
- instead of
-\begin_inset Quotes eld
-\end_inset
-
-I
-\begin_inset Quotes erd
-\end_inset
-
-.
-\end_layout
-
-\end_deeper
-\begin_layout Enumerate
-The reader is
-\begin_inset Quotes eld
-\end_inset
-
-you
-\begin_inset Quotes erd
-\end_inset
-
-.
-\end_layout
-
-\begin_deeper
-\begin_layout Standard
-Whenever you want to say something to the reader, use
-\begin_inset Quotes eld
-\end_inset
-
-you,
-\begin_inset Quotes erd
-\end_inset
-
- not some contorted construction to avoid being too informal.
-
-\end_layout
-
-\end_deeper
-\begin_layout Enumerate
-Use the term
-\begin_inset Quotes eld
-\end_inset
-
-mouse
-\begin_inset Quotes erd
-\end_inset
-
- for both the physical pointing object (mouse, joystick, touch pad, track
- ball, etc.) and the mouse cursor which the physical object moves about the
- screen.
-\end_layout
-
-\begin_layout Enumerate
-Use the term
-\begin_inset Quotes eld
-\end_inset
-
-cursor
-\begin_inset Quotes erd
-\end_inset
-
- for the little blinking vertical bar that indicates where text can/will
- appear next.
-\end_layout
-
-\begin_layout Enumerate
-When in doubt, compromise.
-\end_layout
-
-\begin_deeper
-\begin_layout Standard
-When in doubt, use good judgement.
-\end_layout
-
-\end_deeper
-\begin_layout Subsubsection
-\begin_inset CommandInset label
-LatexCommand label
-name "sec:quote"
-
-\end_inset
-
-Quoting Yourself and Others
-\end_layout
-
-\begin_layout 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.
-\end_layout
-
-\begin_layout 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.
-
-\end_layout
-
-\begin_layout 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
-\family sans
-Figure
-\begin_inset space ~
-\end_inset
-
-Float
-\family default
-, for your convenience.
- Read them if you need to.
-\end_layout
-
-\begin_layout Standard
-\begin_inset Float figure
-placement htbp
-wide false
-sideways false
-status collapsed
-
-\begin_layout Plain Layout
-Quoting rules for English:
-\end_layout
-
-\begin_layout Itemize
-The body of the quote belongs in a
-\family sans
-Quotation
-\family default
- environment.
-\end_layout
-
-\begin_layout Itemize
-The sentences prior to the quote should flow logically and smoothly into
- the quote.
-\end_layout
-
-\begin_layout Itemize
-The sentences immediately following the quote should continue the flow of
- the text.
-\end_layout
-
-\begin_layout Itemize
-You must,
-\emph on
-must
-\emph default
- credit the original author of the quote in the sentences immediately before
- or after the quote.
-\end_layout
-
-\begin_layout Itemize
-Crediting the original author of the quote should not, however, disrupt
- the flow of the text.
-\end_layout
-
-\begin_layout Itemize
-If you omit text from the beginning of the first sentence in the quote,
- the quote must start with the text
-\begin_inset Quotes eld
-\end_inset
-
-[\SpecialChar \ldots{}
-]
-\begin_inset Quotes erd
-\end_inset
-
-.
- This is an ellipsis in square brackets.
-\end_layout
-
-\begin_layout Itemize
-If you omit text from the end of the last sentence in the quote, the quote
- must end with the text
-\begin_inset Quotes eld
-\end_inset
-
-[\SpecialChar \ldots{}
-]
-\begin_inset Quotes erd
-\end_inset
-
- followed by the sentence's punctuation mark.
-\end_layout
-
-\begin_layout 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
-\begin_inset Quotes eld
-\end_inset
-
-[\SpecialChar \ldots{}
-]
-\begin_inset Quotes erd
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Itemize
-The quote must be grammatically correct.
-
-\end_layout
-
-\begin_deeper
-\begin_layout Itemize
-If the original is wrong, you must correct it.
-\end_layout
-
-\begin_layout Itemize
-If omitting part of the quote
-\begin_inset Quotes eld
-\end_inset
-
-breaks
-\begin_inset Quotes erd
-\end_inset
-
- it, you must correct the problem.
-\end_layout
-
-\begin_layout Itemize
-For missing words (e.
-\begin_inset space ~
-\end_inset
-
-g.
-\begin_inset space ~
-\end_inset
-
-
-\begin_inset Quotes eld
-\end_inset
-
-the
-\begin_inset Quotes erd
-\end_inset
-
- goes missing), place the word in square brackets,
-\begin_inset Quotes eld
-\end_inset
-
-[\SpecialChar \ldots{}
-]
-\begin_inset Quotes erd
-\end_inset
-
- and insert in the quote where needed.
-\end_layout
-
-\begin_layout Itemize
-For mangled word order, correct the mangled text, following it with the
- text
-\begin_inset Quotes eld
-\end_inset
-
-[sic]
-\begin_inset Quotes erd
-\end_inset
-
-.
-\end_layout
-
-\end_deeper
-\begin_layout Itemize
-Spelling in the quote must be correct.
- Correct any misspelled words and place the text
-\begin_inset Quotes eld
-\end_inset
-
-[sic]
-\begin_inset Quotes erd
-\end_inset
-
- after the corrected word.
-\end_layout
-
-\begin_layout Itemize
-Back-to-back bracket blocks merge together.
- Example:
-\begin_inset Quotes eld
-\end_inset
-
-[\SpecialChar \ldots{}
-][the]
-\begin_inset Quotes erd
-\end_inset
-
- is wrong.
- It should be
-\begin_inset Quotes eld
-\end_inset
-
-[\SpecialChar \ldots{}
-the]
-\begin_inset Quotes erd
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Itemize
-If you correct the spelling in 2 or more consecutive words, you can get
- away with one
-\begin_inset Quotes eld
-\end_inset
-
-[sic]
-\begin_inset Quotes erd
-\end_inset
-
- after the last mistake.
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsubsection
-Coverage
-\end_layout
-
-\begin_layout Standard
-When describing a new feature or
-\family typewriter
-*.layout
-\family default
- file, be sure to:
-\end_layout
-
-\begin_layout Enumerate
-Be
-\emph on
-clear, concise,
-\emph default
- and
-\emph on
-to the point
-\emph default
-.
- KISS =
-\begin_inset Quotes eld
-\end_inset
-
-Keep It Short and Sweet
-\begin_inset Quotes erd
-\end_inset
-
- (or,
-\begin_inset Quotes eld
-\end_inset
-
-Keep It Simple, Stupid!
-\begin_inset Quotes erd
-\end_inset
-
-)
-\end_layout
-
-\begin_deeper
-\begin_layout Itemize
-Do
-\emph on
-not
-\emph default
- write paragraph after paragraph of verbage.
-
-\end_layout
-
-\begin_layout Itemize
-Get to the point.
-\end_layout
-
-\begin_layout Itemize
-Take a look at the manual for a commercial word processor --- it's a fine
- example of how
-\series bold
-NOT
-\series default
- to write documentation.
- It's all pithy, substanceless verbage, and its
-\emph on
-utterly useless!
-\emph default
-
-\end_layout
-
-\end_deeper
-\begin_layout Enumerate
-Avoid being pedantic like The Plague!
-\end_layout
-
-\begin_layout Enumerate
-In the same vein, don't write more than you have to.
- You're not working in a vacuum --- refer freely to other parts of the manual
- (and other parts of other manuals).
- Even if that
-\begin_inset Quotes eld
-\end_inset
-
-other part of the manual
-\begin_inset Quotes erd
-\end_inset
-
- is incomplete or empty, refer to it.
- Someone will fill it in eventually.
-\end_layout
-
-\begin_layout Enumerate
-On the other hand, BE THOROUGH!
-\end_layout
-
-\begin_deeper
-\begin_layout Enumerate
-You are documenting
-\emph on
-features
-\emph default
-, not widgets, not how the source code is organized.
-\end_layout
-
-\begin_layout Enumerate
-Group by feature, not by widget.
-\end_layout
-
-\begin_layout Enumerate
-Stay on topic --- one
-\family sans
-Section
-\family default
- should cover
-\emph on
-one
-\emph default
- feature.
- Use
-\family sans
-Subsection
-\family default
-s and further subdivisions to group things if you're documenting several
- related features in a single
-\family sans
-Section
-\family default
-.
-\end_layout
-
-\begin_layout Enumerate
-Describe EVERYTHING related to that feature, no matter where it is.
-\end_layout
-
-\begin_deeper
-\begin_layout Enumerate
-Example: Paragraph Indenting.
- Several popups control its behavior.
- You would document
-\emph on
-all
-\emph default
- of this: which popups control it, when you use which setting on which popup
- to do which operation, et cetera.
-\end_layout
-
-\begin_layout Enumerate
-Note from
-\noun on
-John Weiss
-\noun default
-:
-\begin_inset Newline newline
-\end_inset
-
-I've had people only document one popup --- literally.
- This added off-topic information and only described half of the feature,
- since other menus, popups, and even unbound functions contained additional
- stuff.
-\begin_inset Newline newline
-\end_inset
-
-I got
-\emph on
-really
-\emph default
- cranky when that happens, because it means
-\emph on
-I
-\emph default
- ended up fixing it.
- Bad help is worse than no help at all.
-\end_layout
-
-\begin_deeper
-\begin_layout Standard
-These remarks still hold true: you'll piss of the DocTeam editor if you
- do things wrong, because he'll have to fix your mistakes.
-\end_layout
-
-\end_deeper
-\end_deeper
-\begin_layout Enumerate
-Remember, there are people who will reference
-\emph on
-your
-\emph default
- section, just as you're referencing someone else's.
- You do want what you write to be useful, don't you?
-\end_layout
-
-\end_deeper
-\begin_layout Enumerate
-When in doubt, compromise.
-\end_layout
-
-\begin_deeper
-\begin_layout Standard
-When in doubt, use good judgement.
-\end_layout
-
-\end_deeper
-\begin_layout Subsubsection
-NEVER NEVER
-\emph on
-NEVER EVER
-\emph default
- Treat the Reader as if She is Stupid
-\end_layout
-
-\begin_layout Enumerate
-No dumbing-down.
-\end_layout
-
-\begin_layout Enumerate
-No talking down to the reader.
-\end_layout
-
-\begin_layout Enumerate
-The reader is smart enough to know what a mouse is.
-\end_layout
-
-\begin_layout Enumerate
-The reader is smart enough to know how to use a keyboard, including the
-
-\family sans
-Shift-
-\family default
-,
-\family sans
-Control-
-\family default
-, and
-\family sans
-Meta-
-\family default
- keys.
- (The introduction of most of the manuals takes care of the
-\begin_inset Quotes eld
-\end_inset
-
-
-\family sans
-Meta-
-\family default
- is the
-\family sans
-Alt-
-\family default
- key
-\begin_inset Quotes erd
-\end_inset
-
- issue, so you don't need to.)
-\end_layout
-
-\begin_layout Enumerate
-The reader is smart enough to know that
-\begin_inset Quotes eld
-\end_inset
-
-at the cursor
-\begin_inset Quotes erd
-\end_inset
-
- means
-\begin_inset Quotes eld
-\end_inset
-
-where the text cursor is sitting right now, in the buffer currently visible.
-\begin_inset Quotes erd
-\end_inset
-
-
-\size small
-(Anything more than the word
-\begin_inset Quotes eld
-\end_inset
-
-cursor
-\begin_inset Quotes erd
-\end_inset
-
- is, IMO, superfluous and wll be deleted .
- So, save yourself the typing, save the editor the cutting, and save the
- reader the strain of sifting through extra verbage that adds no content.)
-\end_layout
-
-\begin_layout Enumerate
-Rule of thumb: the reader is not an imbecile.
- The reader is merely lost; point them in the right direction, and they
- can take it from there.
-\end_layout
-
-\begin_layout Subsection
-Tips for the English Version
-\end_layout
-
-\begin_layout Standard
-\begin_inset CommandInset label
-LatexCommand label
-name "sec:english-only"
-
-\end_inset
-
-When contributing to the primary --- i.
-\begin_inset space ~
-\end_inset
-
-e.
-\begin_inset space ~
-\end_inset
-
-the English language version --- of the LyX manuals, keep the following
- in mind.
-\end_layout
-
-\begin_layout Subsubsection
-Write as if You're Talking with a Friend.
-
-\end_layout
-
-\begin_layout Enumerate
-Think that way when you write.
- Play the dialogue in your mind.
-\end_layout
-
-\begin_layout Enumerate
-Be as informal as you please (without being rude).
-\end_layout
-
-\begin_layout Subsubsection
-AVOID the Passive Voice
-\end_layout
-
-\begin_layout Enumerate
-No:
-\begin_inset Quotes eld
-\end_inset
-
-It is felt that this name best explains the command's purpose.
-\begin_inset Quotes erd
-\end_inset
-
- We know full well who wrote the command:
-\begin_inset Quotes eld
-\end_inset
-
-The LyX Team felt ...
-\begin_inset Quotes erd
-\end_inset
-
- Or, better yet,
-\begin_inset Quotes eld
-\end_inset
-
-We felt that ...
-\begin_inset Quotes erd
-\end_inset
-
-
-\end_layout
-
-\begin_layout Enumerate
-Things don't happen by magic - somebody or something did it.
- Only politicians use the passive voice to cover up who did something.
- If LyX reformats a paragraph, write,
-\begin_inset Quotes eld
-\end_inset
-
-LyX reformatted the paragraph.
-\begin_inset Quotes erd
-\end_inset
-
- If
-\family typewriter
-ispell
-\family default
- makes changes, write,
-\begin_inset Quotes eld
-\end_inset
-
-
-\family typewriter
-ispell
-\family default
- changes the document.
-\begin_inset Quotes erd
-\end_inset
-
-
-\end_layout
-
-\begin_deeper
-\begin_layout Standard
-Rule of thumb: any sentence you can express as,
-\begin_inset Quotes eld
-\end_inset
-
-It was done by foo,
-\begin_inset Quotes erd
-\end_inset
-
- you can express as,
-\begin_inset Quotes eld
-\end_inset
-
-Foo did it.
-\begin_inset Quotes erd
-\end_inset
-
- Much nicer.
-\end_layout
-
-\end_deeper
-\begin_layout Enumerate
-I know it's tough.
- We all hear way, way too much garbage English on the TV every day in the
- passive voice.
- Some people think it makes speech better.
- It doesn't.
- It makes speech baroque, if not outright byzantine.
- With a little effort, you can wean yourself off of it.
-\end_layout
-
-\begin_layout Enumerate
-I
-\emph on
-will make you rewrite
-\emph default
- anything in the passive voice.
- It's awkward and hard to read.
-\end_layout
-
-\begin_layout Enumerate
-Note to non-Americans:
-\end_layout
-
-\begin_deeper
-\begin_layout Standard
-Using passive voice is generally considered bad style in the U.
-\begin_inset space ~
-\end_inset
-
-S.
-\begin_inset space ~
-\end_inset
-
-as it is too easy to obfuscate your words with it.
- It also bloats sentences, often unnecessarily.
-\end_layout
-
-\end_deeper
-\begin_layout Subsubsection
-Short Sentences.
- Short Paragraphs.
-\end_layout
-
-\begin_layout Standard
-In English, there is a grammatical error known as the
-\begin_inset Quotes eld
-\end_inset
-
-run-on sentence.
-\begin_inset Quotes erd
-\end_inset
-
- The classic example of a run-on sentence is 7 clauses strung together with
- the word
-\begin_inset Quotes eld
-\end_inset
-
-and.
-\begin_inset Quotes erd
-\end_inset
-
- There are, however, less obvious run-on sentences, ones using too many
- subordinate clauses.
- Such sentences may look elegant because they are complex.
- However, they are also extremely difficult to read because they are so
- complex.
-\end_layout
-
-\begin_layout Standard
-In general, stick to short sentences in written English.
- Getting rid of passive voice (
-\begin_inset Quotes eld
-\end_inset
-
-\SpecialChar \ldots{}
-was done by\SpecialChar \ldots{}
-
-\begin_inset Quotes erd
-\end_inset
-
-) shortens and simplifies them.
- Hacking apart sentences with many dependent clauses is another way to shorten
- sentences.
- There are ways to do this yet still have a smooth-flowing paragraph.
-\end_layout
-
-\begin_layout Standard
-While I'm talking about paragraphs, I'll apply the
-\begin_inset Quotes eld
-\end_inset
-
-shorter is better
-\begin_inset Quotes erd
-\end_inset
-
- motto to them, 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.
-\end_layout
-
-\begin_layout Standard
-There is a single exception to the short sentence, short paragraph rule.
- Particularly complex ideas may need more
-\begin_inset Quotes eld
-\end_inset
-
-breathing room.
-\begin_inset Quotes erd
-\end_inset
-
- However, you shouldn't encounter such complex ideas often when documenting
- LyX.
- Try to keep things short, and use your judgement as needed.
-\end_layout
-
-\begin_layout Standard
-To reiterate, yet again, something I said before:
-\end_layout
-
-\begin_layout Quote
-When in doubt, compromise.
-\end_layout
-
-\begin_layout Quote
-When in doubt, use good judgement.
-\end_layout
-
-\begin_layout Standard
-Hopefully, you've got the idea (grin).
-\end_layout
-
-\begin_layout Section
-Translations
-\end_layout
-
-\begin_layout Subsection
-Rules of the Translating Trade
-\end_layout
-
-\begin_layout Standard
-While translating anything, there are certain
-\begin_inset Quotes eld
-\end_inset
-
-tools of the trade
-\begin_inset Quotes erd
-\end_inset
-
- you should use.
- They will help you greatly.
-\end_layout
-
-\begin_layout Subsubsection
-Translate one paragraph at a time.
-\end_layout
-
-\begin_layout 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.
-\end_layout
-
-\begin_layout Standard
-There is another level to the context issue, however.
- Your dictionary may translate multiple English words the same way.
- All those words mean
-\emph on
-roughly
-\emph 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.
-\end_layout
-
-\begin_layout Subsubsection
-You will not translate it correctly on the first try.
-\end_layout
-
-\begin_layout 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.
-\end_layout
-
-\begin_layout 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.
-\end_layout
-
-\begin_layout Subsubsection
-When in doubt, write down all of the meanings for a word.
-\end_layout
-
-\begin_layout 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
- in place of an
-\begin_inset Quotes eld
-\end_inset
-
-exact
-\begin_inset Quotes erd
-\end_inset
-
- translation.
-
-\end_layout
-
-\begin_layout Subsubsection
-Using context, fix the meanings on the next pass.
-\end_layout
-
-\begin_layout 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.
-\end_layout
-
-\begin_layout Subsubsection
-Fix the grammar only after you've finished translating the sentence.
-\end_layout
-
-\begin_layout 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.
-\end_layout
-
-\begin_layout Subsubsection
-If you can't translate it, skip it and come back to it on the next pass.
-\end_layout
-
-\begin_layout Standard
-Remember the earlier discussion of context and its immense usefulness? There
- is no sin in making multiple passes over a tricky passage.
-\end_layout
-
-\begin_layout Subsubsection
-Translate the meaning first.
- The rest can wait.
-\end_layout
-
-\begin_layout Standard
-The information content of the text under translation is the most important
- part.
- This is especially important for a manual, where the information
-\emph on
-is the only
-\emph default
- important part of the original document.
- Lose that, and you lose the very point of performing the translation.
-\end_layout
-
-\begin_layout Subsection
-Tips for the Translators
-\end_layout
-
-\begin_layout Standard
-Those of you contributing to a translation of the LyX manuals must follow
- a modified set of rules.
- The first few rules are analogous to those in section
-\begin_inset space ~
-\end_inset
-
-
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sec:english-only"
-
-\end_inset
-
-.
- There are additional rules and regulations that follow those first few.
-
-\end_layout
-
-\begin_layout Subsubsection
-Write as if you are explaining LyX to a colleague you know well.
-\end_layout
-
-\begin_layout Enumerate
-Think that way when you write.
- Play the dialogue in your mind.
-\end_layout
-
-\begin_layout Enumerate
-Use a conversational style in your writing.
- Pretend you are teaching LyX to a colleague you know well.
-\end_layout
-
-\begin_layout 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.
-\end_layout
-
-\begin_layout Subsubsection
-AVOID Snobby, Academic, Specialized, or
-\begin_inset Quotes eld
-\end_inset
-
-Dead
-\begin_inset Quotes erd
-\end_inset
-
- Writing.
-
-\end_layout
-
-\begin_layout 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
-\begin_inset Quotes eld
-\end_inset
-
-dead
-\begin_inset Quotes erd
-\end_inset
-
- writing.
-\end_layout
-
-\begin_layout Standard
-In Germany, there is a magazine known as
-\begin_inset Quotes gld
-\end_inset
-
-Der Spiegel.
-\begin_inset Quotes grd
-\end_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
-\begin_inset Quotes gld
-\end_inset
-
-Der Spiegel
-\begin_inset Quotes grd
-\end_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
-\begin_inset Quotes eld
-\end_inset
-
-dead
-\begin_inset Quotes erd
-\end_inset
-
- in the sense that they are seldom used by normal people in everyday speech.
-\end_layout
-
-\begin_layout Standard
-We who write the LyX manuals, original or translated, seek to
-\emph on
-inform
-\emph 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).
-
-\end_layout
-
-\begin_layout Subsubsection
-Keep the Writing Simple.
-\end_layout
-
-\begin_layout Standard
-For the English version, I wrote,
-\begin_inset Quotes eld
-\end_inset
-
-Use short sentences and short paragraphs.
-\begin_inset Quotes erd
-\end_inset
-
- What if, however, short sentences and paragraphs are something only children
- use in your language? What if, in yet another language, short sentences
- imply rudeness? Naturally, you would not want to use them in your translation.
-\end_layout
-
-\begin_layout 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.
-\end_layout
-
-\begin_layout 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:
-\end_layout
-
-\begin_layout Quote
-When in doubt, compromise.
-\end_layout
-
-\begin_layout Quote
-When in doubt, use good judgement.
-\end_layout
-
-\begin_layout Subsubsection
-Translators must follow the Style Sheet, too!
-\end_layout
-
-\begin_layout Standard
-Everything in this manual ---
-\emph on
-except section
-\begin_inset space ~
-\end_inset
-
-
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sec:english-only"
-
-\end_inset
-
-
-\emph default
- --- applies to every LyX documenter, no matter what the language.
-\end_layout
-
-\begin_layout Subsubsection
-Translators must read the Style Sheet Supplement for their language.
-\end_layout
-
-\begin_layout Standard
-For every translation project, there is a Supplement to the Style Sheet.
- It will be named:
-\end_layout
-
-\begin_layout Quote
-
-\family typewriter
-DocStyle_Supplement_<cn>.lyx
-\end_layout
-
-\begin_layout Standard
-\SpecialChar \ldots{}
-where
-\begin_inset Quotes eld
-\end_inset
-
-
-\family typewriter
-<cn>
-\family default
-
-\begin_inset Quotes erd
-\end_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! <
-\emph on
-wink!
-\emph default
->
-\end_layout
-
-\begin_layout Subsubsection
-The English versions of the manuals are not Sacred Text.
-\end_layout
-
-\begin_layout 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
-\emph on
-accurately
-\emph default
- and
-\emph on
-completely
-\emph default
- convey all of the information contained in the English versions.
-\end_layout
-
-\begin_layout Subsubsection
-Any information in the LyX manuals must also be in the translations.
-\end_layout
-
-\begin_layout Standard
-\begin_inset CommandInset label
-LatexCommand label
-name "sec:accuracy"
-
-\end_inset
-
-This falls under translating the orignals accurately and completely.
-
-\end_layout
-
-\begin_layout Itemize
-Omitting any feature description is
-\emph on
-stricly forbidden
-\emph default
-.
-\end_layout
-
-\begin_layout Itemize
-Misrepresenting or misdescribing any LyX feature or operation
-\emph on
-must be avoided
-\emph default
-.
-\end_layout
-
-\begin_layout Itemize
-The translation
-\emph on
-cannot
-\emph default
- outpace the original.
-\begin_inset Newline newline
-\end_inset
-
-If no one has documented new feature in the primary LyX manuals (i.
-\begin_inset space ~
-\end_inset
-
-e.
-\begin_inset space ~
-\end_inset
-
-the English versions), do not do so in the translations.
- If you're really looking for something to do, either:
-\end_layout
-
-\begin_deeper
-\begin_layout Itemize
-\SpecialChar \ldots{}
-focus on translating something you haven't yet,
-\begin_inset Newline newline
-\end_inset
-
-OR
-\end_layout
-
-\begin_layout Itemize
-\SpecialChar \ldots{}
-update or repair the primary manual.
-\end_layout
-
-\begin_layout Standard
-If you cannot or do not want to do one of the above, then take a break.
- Relax.
- Wait for the main manuals to catch up before translating anything else.
-\end_layout
-
-\end_deeper
-\begin_layout Subsubsection
-What you cannot translate, you may omit (usually).
-\end_layout
-
-\begin_layout 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\SpecialChar \ldots{}
-
- 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.
-\end_layout
-
-\begin_layout Standard
-There may be special cases where omitting part of a sentence or paragraph
- violates rule
-\begin_inset space ~
-\end_inset
-
-
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sec:accuracy"
-
-\end_inset
-
-.
- In those cases,
-\emph on
-do not omit!
-\emph default
- You must try and translate those tricky spots.
-\end_layout
-
-\begin_layout Subsubsection
-Translators may add their own fluff to the information content.
-\end_layout
-
-\begin_layout Standard
-After you do strip away all of the idioms, metaphors, slang, humor, and
- other
-\begin_inset Quotes eld
-\end_inset
-
-expendable text,
-\begin_inset Quotes erd
-\end_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
-\begin_inset Quotes eld
-\end_inset
-
-in context.
-\begin_inset Quotes erd
-\end_inset
-
- It should not clash with the explanation of LyX features and functions.
-\end_layout
-
-\begin_layout Subsection
-For Translation Project Chiefs
-\end_layout
-
-\begin_layout Subsubsection
-The First Is In Charge
-\end_layout
-
-\begin_layout Standard
-If you were the first person to start translating the manuals, you're the
- LyXDoc Translation Project Chief for your language.
- If you are the
-\emph on
-only
-\emph default
- person translating the LyXDocs, that automatically makes you the Translation
- Project Chief.
-\end_layout
-
-\begin_layout Standard
-Amongst other things, that means that you must read this section and perform
- the tasks described here.
-\end_layout
-
-\begin_layout Standard
-If you are a member of a LyX Documentation Translation Team, but
-\emph on
-are not
-\emph 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.
-\end_layout
-
-\begin_layout Standard
-If you have not read the Style Sheet Supplement for your language, you should
- read it now.
-
-\end_layout
-
-\begin_layout Subsubsection
-Read the Style Sheet
-\end_layout
-
-\begin_layout Standard
-No documenter is excused from following the Style Sheet, not even a Translation
- Project Chief.
-\end_layout
-
-\begin_layout Standard
-Actually, it is
-\emph on
-especially
-\emph default
- important that the Translation Project Chiefs read the Style Sheet.
-\end_layout
-
-\begin_layout Subsubsection
-Make your translators read the Style Sheet
-\end_layout
-
-\begin_layout Standard
-No documenter is excused from following the Style Sheet.
-\end_layout
-
-\begin_layout Standard
-Since your translation team is translating, they know
-\emph on
-some
-\emph default
- English, at least.
- Therefore, they should be able to read the Style Sheet.
-\end_layout
-
-\begin_layout Subsubsection
-Provide a
-\begin_inset Quotes eld
-\end_inset
-
-Supplement
-\begin_inset Quotes erd
-\end_inset
-
- to this Style Sheet
-\end_layout
-
-\begin_layout 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.
-
-\end_layout
-
-\begin_layout Standard
-That's where you, as head of a LyXDoc Translation Team, come in.
-\end_layout
-
-\begin_layout Standard
-Every Translation Team Chief is
-\emph on
-required
-\emph 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:
-\end_layout
-
-\begin_layout Enumerate
-Name the file:
-\begin_inset Newline newline
-\end_inset
-
-
-\family typewriter
-DocStyle_Supplement_<cn>.lyx
-\family default
-
-\begin_inset Newline newline
-\end_inset
-
-\SpecialChar \ldots{}
-where
-\begin_inset Quotes eld
-\end_inset
-
-
-\family typewriter
-<cn>
-\family default
-
-\begin_inset Quotes erd
-\end_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:
-\begin_inset Quotes eld
-\end_inset
-
-
-\family typewriter
-_de
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
- for German,
-\begin_inset Quotes eld
-\end_inset
-
-
-\family typewriter
-_sv
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
- for Swedish, and
-\begin_inset Quotes eld
-\end_inset
-
-
-\family typewriter
-_ru
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
- for Russian.
-\end_layout
-
-\begin_layout Enumerate
-Do not worry about where the file goes.
- The CVS maintainers will locate all documentation and Style Sheet Supplements
- in an appropriate place.
-\end_layout
-
-\begin_layout Enumerate
-Document Properties:
-\end_layout
-
-\begin_deeper
-\begin_layout Itemize
-For consistency, use the same document class and other document properties
- as the Style Sheet.
-\begin_inset Foot
-status collapsed
-
-\begin_layout Plain Layout
-Specifically, check the settings in the
-\family sans
-Document Layout
-\family default
- popup.
- Use those in your Supplement.
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Itemize
-Exceptions: Use margins, indentation/paragraph separation, language, and
- encoding appropriate for your language.
-\end_layout
-
-\end_deeper
-\begin_layout Enumerate
-The title of the Supplement:
-\end_layout
-
-\begin_deeper
-\begin_layout Itemize
-The title will use the
-\begin_inset Quotes eld
-\end_inset
-
-
-\family sans
-Title
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
- paragraph environment.
- In your native tongue, the title will read:
-\end_layout
-
-\begin_deeper
-\begin_layout Standard
-
-\family typewriter
-Documentation Project Style Sheet:
-\begin_inset Newline newline
-\end_inset
-
-Supplement for the <foo> Translation Project
-\end_layout
-
-\begin_layout Standard
-(Replace
-\begin_inset Quotes eld
-\end_inset
-
-
-\family typewriter
-<foo>
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
- with the name of your language.)
-\end_layout
-
-\end_deeper
-\begin_layout Itemize
-If, in your language,
-\begin_inset Quotes eld
-\end_inset
-
-supplement
-\begin_inset Quotes erd
-\end_inset
-
- translates into
-\begin_inset Quotes eld
-\end_inset
-
-appendix,
-\begin_inset Quotes erd
-\end_inset
-
- we have a problem.
- In English,
-\begin_inset Quotes eld
-\end_inset
-
-Supplement
-\begin_inset Quotes erd
-\end_inset
-
- and
-\begin_inset Quotes eld
-\end_inset
-
-Appendix
-\begin_inset Quotes erd
-\end_inset
-
- have somewhat different meanings.
- An appendix is an extra part of a document.
- A supplement is an extra document.
-
-\end_layout
-
-\begin_deeper
-\begin_layout Standard
-Choose a replacement word accordingly.
- Whatever you choose to replace
-\begin_inset Quotes eld
-\end_inset
-
-Supplement,
-\begin_inset Quotes erd
-\end_inset
-
- it must not have the same translation as the word
-\begin_inset Quotes eld
-\end_inset
-
-appendix.
-\begin_inset Quotes erd
-\end_inset
-
-
-\end_layout
-
-\end_deeper
-\end_deeper
-\begin_layout Enumerate
-Below the title, in the
-\begin_inset Quotes eld
-\end_inset
-
-
-\family sans
-Author
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
- paragraph environment, place your name.
-\end_layout
-
-\begin_deeper
-\begin_layout Standard
-There will be no abstract.
-\end_layout
-
-\end_deeper
-\begin_layout Enumerate
-The first
-\family sans
-Section
-\family default
- of the Supplement:
-\end_layout
-
-\begin_deeper
-\begin_layout Standard
-The first thing you will do is strongly yet politely encourage the reader
- to stop reading the
-\begin_inset Quotes eld
-\end_inset
-
-Supplement
-\begin_inset Quotes erd
-\end_inset
-
- and go read the Style Sheet.
- The reader should not return to the
-\begin_inset Quotes eld
-\end_inset
-
-Supplement
-\begin_inset Quotes erd
-\end_inset
-
- until he has read
-\emph on
-and
-\emph default
- understood the Style Sheet proper.
-\end_layout
-
-\end_deeper
-\begin_layout Subsubsection
-Keep the Supplement Succinct
-\end_layout
-
-\begin_layout 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.
-\end_layout
-
-\begin_layout Subsubsection
-Font Issues
-\end_layout
-
-\begin_layout Standard
-The second
-\family sans
-Section
-\family default
- will be about font issues\SpecialChar \ldots{}
- if you have any.
- Not all Translation Project Chiefs will need to deal with this issue.
- The fonts:
-\end_layout
-
-\begin_layout Itemize
-
-\family typewriter
-Typewriter
-\end_layout
-
-\begin_layout Itemize
-
-\family sans
-Sans Serif
-\end_layout
-
-\begin_layout Itemize
-Roman
-\begin_inset Newline newline
-\end_inset
-
-
-\emph on
-Emphasized (actually Italics)
-\end_layout
-
-\begin_layout Itemize
-
-\bar under
-Underlined
-\end_layout
-
-\begin_layout Itemize
-
-\series bold
-Bold
-\end_layout
-
-\begin_layout Itemize
-
-\noun on
-Noun (actually Small Caps)
-\end_layout
-
-\begin_layout Standard
-\SpecialChar \ldots{}
-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.
-
-\end_layout
-
-\begin_layout Standard
-There will be some languages for 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.
-\end_layout
-
-\begin_layout 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
-\begin_inset Quotes eld
-\end_inset
-
-fonts.
-\begin_inset Quotes erd
-\end_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:
-\end_layout
-
-\begin_layout Itemize
-Guidelines for
-\begin_inset Quotes eld
-\end_inset
-
-translating
-\begin_inset Quotes erd
-\end_inset
-
- fonts,
-\begin_inset Newline newline
-\end_inset
-
-or
-\begin_inset Newline newline
-\end_inset
-
-What to do when a font doesn't exist:
-\end_layout
-
-\begin_deeper
-\begin_layout List
-\labelwidthstring MMMMMMMM
-Roman Use the font that typesetters in your language use for printing books,
- manuals, etc.
- This will typically be the default font LyX (and LaTeX) uses in your language.
-\end_layout
-
-\begin_layout List
-\labelwidthstring MMMMMMMM
-
-\noun on
-Noun
-\begin_inset space ~
-\end_inset
-
-Style
-\noun 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.
-\end_layout
-
-\begin_layout List
-\labelwidthstring MMMMMMMM
-
-\emph on
-Emphasized
-\emph default
- Use the font with which your language normally emphasizes text.
-\end_layout
-
-\begin_deeper
-\begin_layout Standard
-Use a font that is different from your language's equivalent of
-\series bold
-Boldface
-\series default
-.
- In other words, your
-\family sans
-Section
-\family default
-,
-\family sans
-Subsection
-\family default
- and similar headers will be in one typeface, perhaps
-\series bold
-Boldface
-\series default
-, perhaps not.
- Whatever that font is, avoid using it for
-\emph on
-Emphasized
-\emph default
- if at all possible!
-\end_layout
-
-\end_deeper
-\begin_layout List
-\labelwidthstring MMMMMMMM
-
-\family typewriter
-Typewriter
-\family default
- Pick up a computer program manual written in your language.
- It will use a special typeface for filenames, for command names, program
- names, and such.
- Use that same font in place of
-\family typewriter
-Typewriter
-\family default
-.
-\end_layout
-
-\begin_layout List
-\labelwidthstring MMMMMMMM
-
-\family sans
-Sans
-\begin_inset space ~
-\end_inset
-
-Serif
-\family default
- Pick any other font that is different from the ones you're using in place
- of
-\emph on
-Emphasized
-\emph default
-,
-\series bold
-Boldface
-\series default
-, and
-\family typewriter
-Typewriter
-\family default
-.
- If you're unlucky, and your language's writing system doesn't have enough
- fonts, use the same font you picked to replace
-\family typewriter
-Typewriter
-\family default
-.
- Only do this, however, if your alphabet/writing system has very few fonts
- to pick from.
-\end_layout
-
-\begin_layout List
-\labelwidthstring MMMMMMMM
-
-\family sans
-\bar under
-U
-\bar default
-nderlined
-\begin_inset space ~
-\end_inset
-
-Sans
-\begin_inset space ~
-\end_inset
-
-Serif
-\family default
- Don't worry about this one.
-\end_layout
-
-\begin_deeper
-\begin_layout 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.
-\end_layout
-
-\end_deeper
-\end_deeper
-\begin_layout Standard
-Note that you may also want to describe fonts that your Translation Team
- should
-\emph on
-never
-\emph default
- use.
- For example, no contributer to the English/European versions may ever use
-
-\series bold
-Boldface
-\series default
-, as this is used for section-headings.
- Since there are enough other fonts, we who use the Roman alphabet and its
- variants can afford to omit
-\series bold
-Boldface
-\series default
-.
-
-\end_layout
-
-\begin_layout 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.
-
-\end_layout
-
-\begin_layout Standard
-Remember: stick to the font specifications in this Style Sheet as best you
- can, whenever you can.
-\end_layout
-
-\begin_layout Subsubsection
-Quoting Style and the
-\family sans
-Quote
-\family default
- vs.
-
-\family sans
-Quotation
-\family default
- Issue
-\end_layout
-
-\begin_layout Standard
-The next section of the Supplement will cover the issue of quoting.
- Give it an appropriate title.
-\end_layout
-
-\begin_layout Standard
-One of the first things you should do in that section is resolve the following
- issue:
-\end_layout
-
-\begin_layout Itemize
-Decide whether
-\family sans
-Quote
-\family default
- or
-\family sans
-Quotation
-\family default
- is the correct paragraph environment for your language.
-\end_layout
-
-\begin_layout Itemize
-In the Supplement, specify which one to use.
-\end_layout
-
-\begin_layout Standard
-English has its own typography and style for quoting others.
- The Style Sheet describes that typography in section
-\begin_inset space ~
-\end_inset
-
-
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sec:quote"
-
-\end_inset
-
-.
- Your language also has a specific typography and style for quotations.
- Describe that style in this section of the Supplement, too.
- Naturally, you do not need to go overboard.
- Section
-\begin_inset space ~
-\end_inset
-
-
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sec:quote"
-
-\end_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.
-\end_layout
-
-\begin_layout Subsubsection
-Translations of Style Sheet Terminology
-\end_layout
-
-\begin_layout 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.
-\end_layout
-
-\begin_layout Standard
-In particular, standardize the translations of the phrases:
-\end_layout
-
-\begin_layout Itemize
-Note from
-\noun on
-<foo>:
-\end_layout
-
-\begin_layout Itemize
-
-\emph on
-Author's Note:
-\end_layout
-
-\begin_layout Standard
-Do
-\emph on
-not
-\emph default
- change the typography of the
-\begin_inset Quotes eld
-\end_inset
-
-Personal Note
-\begin_inset Quotes erd
-\end_inset
-
- and
-\begin_inset Quotes eld
-\end_inset
-
-Author's Note,
-\begin_inset Quotes erd
-\end_inset
-
- however.
- Only provide a translation for the opening phrases.
- Insist that the members of your Translation Team use these two tools correctly.
-\end_layout
-
-\begin_layout Standard
-While we are discussing proper use of the
-\begin_inset Quotes eld
-\end_inset
-
-Personal Note
-\begin_inset Quotes erd
-\end_inset
-
- and
-\begin_inset Quotes eld
-\end_inset
-
-Author's Note
-\begin_inset Quotes erd
-\end_inset
-
- in translations, let's talk about a related problem.
- The
-\begin_inset Quotes eld
-\end_inset
-
-Author's Note
-\begin_inset Quotes erd
-\end_inset
-
- is meant to be a note from the author of a manual to the reader.
- In the case of a translation, however, the translator is
-\emph on
-not
-\emph default
- the author! How then should a translator translate an
-\begin_inset Quotes eld
-\end_inset
-
-Author's Note?
-\begin_inset Quotes erd
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-You, as Translation Project Chief, must decide.
- You can forbid translation of pre-existing
-\begin_inset Quotes eld
-\end_inset
-
-Author's Notes,
-\begin_inset Quotes erd
-\end_inset
-
- omitting them entirely instead.
- You could tell your translators to read any
-\begin_inset Quotes eld
-\end_inset
-
-Author's Note
-\begin_inset Quotes erd
-\end_inset
-
- they may encounter, understand it, then write their own
-\begin_inset Quotes eld
-\end_inset
-
-Author's Note
-\begin_inset Quotes erd
-\end_inset
-
- about the situation, not as a translation but as a personal opinion.
- You may decide on some other policy.
-\end_layout
-
-\begin_layout Standard
-Whatever you decide, codify your policy in its own
-\family sans
-Section
-\family default
- or
-\family sans
-Subsection
-\family default
- or whatever.
- Place it near the section where you translated
-\begin_inset Quotes eld
-\end_inset
-
-Personal Note
-\begin_inset Quotes erd
-\end_inset
-
- and
-\begin_inset Quotes eld
-\end_inset
-
-Author's Note
-\begin_inset Quotes erd
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Subsubsection
-Lost in Translation
-\end_layout
-
-\begin_layout Standard
-After describing all of the previous issues, create a new
-\family sans
-Section
-\family default
-.
- Give it the name,
-\begin_inset Quotes eld
-\end_inset
-
-Lost in Translation,
-\begin_inset Quotes erd
-\end_inset
-
- or something similar.
-\end_layout
-
-\begin_layout 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
-\family sans
-Subsection
-\family default
- --- or even
-\family sans
-Subsubsection
-\family default
-s --- to each specific issue.
-\end_layout
-
-\begin_layout Subsubsection
-\SpecialChar \ldots{}
-
-\begin_inset Quotes eld
-\end_inset
-
-Yes, we mean now.
-\begin_inset Quotes erd
-\end_inset
-
- \SpecialChar \ldots{}
-
-\end_layout
-
-\begin_layout Standard
-Throughout the manuals, the DocTeam has used the following sentences:
-\end_layout
-
-\begin_layout Quote
-If you haven't read the <
-\emph on
-Foo
-\emph default
-> manual, go read it.
- Yes, we mean now.
-\end_layout
-
-\begin_layout Standard
-This sentence will be tricky to translate, since it contains non-translatable
- connotations.
- Therefore, create a
-\family sans
-Subsection
-\family default
- for this issue in your
-\begin_inset Quotes eld
-\end_inset
-
-Lost in Translation
-\begin_inset Quotes erd
-\end_inset
-
- section.
- Present the
-\begin_inset Quotes eld
-\end_inset
-
-\SpecialChar \ldots{}
- Yes, we mean now\SpecialChar \ldots{}
-
-\begin_inset Quotes erd
-\end_inset
-
- sentences, then present a translation, along with any explanation you feel
- necessary.
-\end_layout
-
-\begin_layout Standard
-Here's what those two sentences, sitting alone in their own paragraph, mean:
-\end_layout
-
-\begin_layout Standard
-The first sentence uses the English conditional followed by an imperative.
- We, as the LyX team, are commanding the reader to go back to another manual.
- For example, the
-\emph on
-Intro
-\emph default
- manual is a prerequisite for all of the other manuals.
- The conditional clause preceeding the command means,
-\begin_inset Quotes eld
-\end_inset
-
-You do not need to perform this command twice.
-\begin_inset Quotes erd
-\end_inset
-
-
-\end_layout
-
-\begin_layout 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,
-\begin_inset Quotes eld
-\end_inset
-
-go read it,
-\begin_inset Quotes erd
-\end_inset
-
- is firm, yet polite.
- The reader may choose to ignore it.
- By following with,
-\begin_inset Quotes eld
-\end_inset
-
-Yes, we mean now,
-\begin_inset Quotes erd
-\end_inset
-
- we imply two things.
- First, we add some
-\begin_inset Quotes eld
-\end_inset
-
-resistive force
-\begin_inset Quotes erd
-\end_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 fulfill that command.
- The brief pragraph, and its sudden end, add still further subtle reinforcement
- to the command,
-\begin_inset Quotes eld
-\end_inset
-
-go do the required reading before using this manual.
-\begin_inset Quotes erd
-\end_inset
-
-
-\end_layout
-
-\begin_layout 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.
-\end_layout
-
-\begin_layout Subsubsection
-Firm Convincing vs.
- Rudeness
-\end_layout
-
-\begin_layout Standard
-In the same part of the Supplement that you place the
-\begin_inset Quotes eld
-\end_inset
-
-\SpecialChar \ldots{}
-Yes, we mean now\SpecialChar \ldots{}
-
-\begin_inset Quotes erd
-\end_inset
-
- translation, discuss the English version's use of
-\begin_inset Quotes eld
-\end_inset
-
-firm convincing.
-\begin_inset Quotes erd
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-You see, here in America, we often say 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
-\begin_inset Quotes eld
-\end_inset
-
-user-friendly.
-\begin_inset Quotes erd
-\end_inset
-
- This is where the use of
-\begin_inset Quotes eld
-\end_inset
-
-firm convincing
-\begin_inset Quotes erd
-\end_inset
-
- comes in.
-
-\end_layout
-
-\begin_layout 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.
-\end_layout
-
-\begin_layout 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.
-\end_layout
-
-\begin_layout 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.
-\begin_inset space ~
-\end_inset
-
-e.
-\begin_inset space ~
-\end_inset
-
-how you want such sentences translated.) If stumped, ask for help on the
- LyX Developer's List.
-\end_layout
-
-\begin_layout Subsubsection
-Anything Else?
-\end_layout
-
-\begin_layout 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
-\emph on
-short
-\emph default
-.
-
-\end_layout
-
-\end_body
-\end_document
projects / features.git / commitdiff