From: Uwe Stöhr Date: Tue, 23 Jun 2009 01:25:12 +0000 (+0000) Subject: move the obsolete DocStyle.lyx file to an attic folder as requested X-Git-Tag: 2.0.0~6221 X-Git-Url: https://git.lyx.org/gitweb/?a=commitdiff_plain;h=8a765440cbc8b3fc8a7bc7177e7bd9dfe2eed3b1;p=features.git move the obsolete DocStyle.lyx file to an attic folder as requested git-svn-id: svn://svn.lyx.org/lyx/lyx-devel/trunk@30237 a592a061-630c-0410-9148-cb99ea01b6c8 --- diff --git a/lib/doc/attic/DocStyle.lyx b/lib/doc/attic/DocStyle.lyx new file mode 100644 index 0000000000..a25d51d035 --- /dev/null +++ b/lib/doc/attic/DocStyle.lyx @@ -0,0 +1,5078 @@ +#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_.lyx +\end_layout + +\begin_layout Standard +\SpecialChar \ldots{} +where +\begin_inset Quotes eld +\end_inset + + +\family typewriter + +\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_.lyx +\family default + +\begin_inset Newline newline +\end_inset + +\SpecialChar \ldots{} +where +\begin_inset Quotes eld +\end_inset + + +\family typewriter + +\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 Translation Project +\end_layout + +\begin_layout Standard +(Replace +\begin_inset Quotes eld +\end_inset + + +\family typewriter + +\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 +: +\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