X-Git-Url: https://git.lyx.org/gitweb/?a=blobdiff_plain;f=lib%2Fdoc%2FDocStyle.lyx;h=2559f8664f6aa9fb3404fa0486fa515175de1b46;hb=ea74988acc29767d2d34d9e4466e4993eb544171;hp=2b0a7775adcf1dbab1619a82837228f0a5d87858;hpb=d523271fb545efb658177369187105949f9a0932;p=lyx.git diff --git a/lib/doc/DocStyle.lyx b/lib/doc/DocStyle.lyx index 2b0a7775ad..2559f8664f 100644 --- a/lib/doc/DocStyle.lyx +++ b/lib/doc/DocStyle.lyx @@ -1,17 +1,25 @@ -#LyX 1.4.0cvs created this file. For more info see http://www.lyx.org/ -\lyxformat 243 +#LyX 1.5.0svn created this file. For more info see http://www.lyx.org/ +\lyxformat 276 \begin_document \begin_header \textclass article \language english \inputencoding latin1 -\fontscheme default +\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 \papersize default \use_geometry false \use_amsmath 0 +\use_esint 0 \cite_engine basic \use_bibtopic false \paperorientation portrait @@ -20,28 +28,24 @@ \paragraph_separation indent \defskip medskip \quotes_language english -\quotes_times 2 \papercolumns 1 \papersides 1 \paperpagestyle plain \tracking_changes false -\output_changes true +\output_changes false \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 @@ -52,14 +56,17 @@ This article is a style sheet. \end_layout \begin_layout Abstract - The Style Sheet for LyX documentation (hereafter known as the Style Sheet) - applies to + applies to +\emph default + \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 default \emph on Read the entire Style Sheet! @@ -69,12 +76,10 @@ Read the entire Style Sheet! \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 @@ -85,14 +90,14 @@ After the second version of this Style Sheet grew uncomfortably large, the \end_layout \begin_layout Quote - -If you have any questions about anything in the Style Sheet, +If you have any questions about anything in the Style Sheet, +\emph default + \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 @@ -100,24 +105,20 @@ Field all questions to the LyX Developer's 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 @@ -127,18 +128,19 @@ Emphasized \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, + program names, file names, +\family default + \family typewriter man \family default @@ -149,7 +151,6 @@ man \begin_layout List \labelwidthstring MMMMMMMM - \family sans Sans\InsetSpace ~ Serif @@ -169,7 +170,6 @@ special terms \begin_layout List \labelwidthstring MMMMMMMM - \noun on Noun\InsetSpace ~ Style @@ -180,7 +180,6 @@ Style \begin_layout List \labelwidthstring MMMMMMMM - \family sans \bar under U @@ -197,8 +196,9 @@ Serif \begin_deeper \begin_layout Description - -WARNING! --- When you do this, make sure you +WARNING! --- When you do this, make sure you +\emph default + \emph on only \emph default @@ -216,27 +216,33 @@ his \SpecialChar \ldots{} i.\InsetSpace ~ e.\InsetSpace ~ -they not only shut off underlining, they turned off +they not only shut off underlining, they turned off +\family default + \family sans Sans\InsetSpace ~ Serif \family default -, too! +, too! +\emph default + \emph on Don't do that! \emph default - Make sure the entire word is still in + Make sure the entire word is still in +\family default + \family sans Sans\InsetSpace ~ Serif \family default after you shut off the underlining. \end_layout + \end_deeper \begin_layout List \labelwidthstring MMMMMMMM - \series bold Bold \series default @@ -245,13 +251,16 @@ Bold \begin_deeper \begin_layout Standard - -If you want to emphasize any text, use +If you want to emphasize any text, use +\emph default + \emph on Emphasized \emph default . - LaTeX will put many things boldface on its own, such as + LaTeX will put many things boldface on its own, such as +\family default + \family sans Section \family default @@ -259,24 +268,26 @@ 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 +The function +\family default + \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 + in +\family default + \family typewriter Typewriter \family default @@ -284,8 +295,9 @@ Typewriter \end_layout \begin_layout Enumerate - -However, +However, +\family default + \family sans \bar under M @@ -293,20 +305,26 @@ M ath\InsetSpace ~ mode \family default - is a menu item in the + is a menu item in the +\family default + \family sans \bar under M \bar default ath \family default - menu, so it appears in + menu, so it appears in +\family default + \family sans Sans\InsetSpace ~ Serif \family default . - Notice the use of + Notice the use of +\family default + \family sans \bar under U @@ -319,23 +337,25 @@ Serif \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 + and +\family default + \family sans Enter \family default both refer to the same key. - Some keyboards label the + Some keyboards label the +\family default + \family sans Return \family default @@ -356,11 +376,15 @@ Enter, \end_inset still others have two keys. - LyX treats all of them as the same key, so we'll use + LyX treats all of them as the same key, so we'll use +\family default + \family sans Return \family default - and + and +\family default + \family sans Enter \family default @@ -368,17 +392,22 @@ Enter \end_layout \begin_layout Standard - -Notice that the key name, +Notice that the key name, +\family default + \family sans Return \family default -, is in +, is in +\family default + \family sans Sans\InsetSpace ~ Serif \family default -, but +, but +\emph default + \emph on only \emph default @@ -386,16 +415,15 @@ only 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 @@ -404,18 +432,23 @@ printername \end_layout \begin_layout Standard - -Notice that the argument to the +Notice that the argument to the +\family default + \family typewriter -P \family default - option is in + option is in +\emph default + \emph on Roman Italics \emph default (i.e. emphasized). - This is a case where you don't use + This is a case where you don't use +\family default + \family typewriter Typewriter \family default @@ -432,21 +465,27 @@ lpr -Pduaneps \begin_inset Quotes erd \end_inset -, you'd leave it in +, you'd leave it in +\family default + \family typewriter Typewriter \family default . \end_layout + \end_deeper \begin_layout Enumerate - -Any LaTeX commands and code, and any +Any LaTeX commands and code, and any +\emph default + \emph on unsupported \emph default - LaTeX package names get set in + LaTeX package names get set in +\family default + \family typewriter Typewriter \family default @@ -479,22 +518,21 @@ book \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 + or +\family default + \family sans Control- \family default @@ -503,11 +541,12 @@ Control- \begin_layout Itemize - \family sans S- \family default - or + or +\family default + \family sans Shift- \family default @@ -516,11 +555,12 @@ Shift- \begin_layout Itemize - \family sans M- \family default - or + or +\family default + \family sans Meta- \family default @@ -529,32 +569,32 @@ Meta- \begin_deeper \begin_layout Standard - Self-explanatory. - Be lazy and + Be lazy and +\emph default + \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 @@ -563,7 +603,6 @@ Esc \begin_deeper \begin_layout Standard - The \begin_inset Quotes eld \end_inset @@ -574,29 +613,39 @@ Escape key. \end_layout + \end_deeper \begin_layout Itemize - \family sans Insert \family default + +\family default \family sans Delete \family default + +\family default \family sans Home \family default + +\family default \family sans End \family default + +\family default \family sans PageUp \family default + +\family default \family sans PageDown @@ -604,21 +653,19 @@ PageDown \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 @@ -633,7 +680,6 @@ arrow status collapsed \begin_layout Standard - Same goes for \begin_inset Quotes eld \end_inset @@ -658,14 +704,16 @@ key \end_layout + \end_deeper \begin_layout Itemize - \family sans Return \family default - and + and +\family default + \family sans Enter \family default @@ -674,13 +722,16 @@ Enter \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 + I'd prefer if you used +\family default + \family sans Return \family default - over + over +\family default + \family sans Enter \family default @@ -688,14 +739,18 @@ Enter 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 +You do not need to explain everywhere what the +\family default + \family sans Meta \family default - key is or where the + key is or where the +\family default + \family sans Left \family default @@ -703,11 +758,15 @@ Left The user isn't stupid. Also, someone will document anything that isn't clear (e.\InsetSpace ~ g.\InsetSpace ~ -the +the +\family default + \family sans Meta \family default vs. + +\family default \family sans Alt @@ -717,19 +776,24 @@ Alt \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 + LyX can support a keyboard missing +\family default + \family sans F11 \family default - and + and +\family default + \family sans F12 \family default . - There is a keyboard accelerator for + There is a keyboard accelerator for +\family default + \family sans F10 \family default @@ -739,12 +803,10 @@ F10 \end_layout \begin_layout Section - Mice \end_layout \begin_layout Standard - The word \begin_inset Quotes eld \end_inset @@ -759,14 +821,15 @@ mouse \end_layout \begin_layout Standard - Exception: you're writing an Author's Note (see section -\begin_inset LatexCommand \ref{sec:author-notes} - +\begin_inset 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 + Since the rest of the note is in +\emph default + \emph on Emphasized \emph default @@ -783,7 +846,6 @@ middle mouse button \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. @@ -807,31 +869,34 @@ mouse button \end_layout \begin_layout Section - Special Typography \end_layout \begin_layout Standard - Do the following: \end_layout \begin_layout Description - Multi-word\InsetSpace ~ -names Use a +names Use a +\family default + \family sans Protected\InsetSpace ~ Blank \family default between the words for menu and widget names. E.\InsetSpace ~ -g.: +g.: +\family default + \family sans Save\InsetSpace ~ As \family default -, not +, not +\family default + \family sans Save As \family default @@ -841,23 +906,30 @@ Save As \begin_deeper \begin_layout Standard - -This holds for things in +This holds for things in +\family default + \family typewriter Typewriter \family default - as well as + as well as +\family default + \family sans Sans\InsetSpace ~ Serif \family default , with one caveat. If you have a long code example, one that can't simply be inlined and put - in + in +\family default + \family typewriter Typewriter \family default -, put that in a +, put that in a +\family default + \family sans LyX\InsetSpace ~ Code @@ -866,20 +938,25 @@ Code \end_layout \begin_layout Standard - -I want the +I want the +\family default + \family sans Protected\InsetSpace ~ Blank \family default so that the name doesn't get split between two lines, which is visually disruptive. - If something with a + If something with a +\family default + \family sans Protected\InsetSpace ~ Blank \family default - is near the end of a line and overflows the margin, use a + is near the end of a line and overflows the margin, use a +\family default + \family typewriter \backslash @@ -901,9 +978,9 @@ sloppypar ) or manually add a hypenation point. \end_layout + \end_deeper \begin_layout Description - Special\InsetSpace ~ Terms These are things like the following: \end_layout @@ -911,7 +988,6 @@ Terms These are things like the following: \begin_deeper \begin_layout Itemize - \family sans HFill \family default @@ -920,7 +996,6 @@ HFill \begin_layout Itemize - \family sans VFill \family default @@ -929,7 +1004,6 @@ VFill \begin_layout Itemize - \family sans Table\InsetSpace ~ Float @@ -937,7 +1011,6 @@ Float \begin_layout Itemize - \family sans Figure\InsetSpace ~ Float @@ -945,17 +1018,23 @@ Float \begin_deeper \begin_layout Standard - -Use +Use +\family default + \family sans Sans\InsetSpace ~ Serif \family default - font and, in the case of + font and, in the case of +\family default + \family sans -HFill +HFill +\family default + +and \family default -and + \family sans VFill \family default @@ -963,32 +1042,30 @@ VFill \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 + I want them to stand out from the rest of the text, hence the use of +\family default + \family sans Sans\InsetSpace ~ 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 @@ -1033,18 +1110,19 @@ dialog \end_layout \begin_layout Itemize +PostScript® is a registered trademark of Adobe Corp. -PostScript® is a registered trademark of Adobe Corp. +\emph default \emph on -You must put the ® after it or we'll get sued! +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®, +postscript®, \begin_inset Quotes erd \end_inset @@ -1052,7 +1130,7 @@ postscript \begin_inset Quotes eld \end_inset -Postscript® +Postscript® \begin_inset Quotes erd \end_inset @@ -1060,7 +1138,7 @@ Postscript \begin_inset Quotes eld \end_inset -PostScript® +PostScript® \begin_inset Quotes erd \end_inset @@ -1072,14 +1150,10 @@ Roman). \begin_deeper \begin_layout Standard - I am going to say this again: \end_layout - \begin_layout Standard - - \begin_inset VSpace 0.37cm \end_inset @@ -1091,39 +1165,36 @@ I am going to say this again: \size larger \emph on -You must put the ® after PostScript® or we'll get sued! +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 + We could get in +\emph default + \emph on major trouble \emph default - by forgetting that ®. + 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. + put the ® after it, too. \end_layout \begin_layout Description - Menu\InsetSpace ~ Items When quick-referencing an item in a menu, use the menu separator: @@ -1136,13 +1207,17 @@ Items When quick-referencing an item in a menu, use the menu separator: \end_inset . - Example: + Example: +\family default + \family sans File\SpecialChar \menuseparator Save \family default . - Notice that there are + Notice that there are +\emph default + \emph on no spaces \emph default @@ -1155,7 +1230,9 @@ no spaces \begin_inset Quotes erd \end_inset - and that it's in + and that it's in +\family default + \family sans Sans\InsetSpace ~ Serif @@ -1165,7 +1242,6 @@ Serif \begin_deeper \begin_layout Enumerate - The reason why I want no spaces around the \begin_inset Quotes eld \end_inset @@ -1176,7 +1252,9 @@ The reason why I want no spaces around the \end_inset is to prevent LyX from splitting terms across lines. - The same goes for using + The same goes for using +\family default + \family sans Protected\InsetSpace ~ Blank @@ -1186,7 +1264,6 @@ s between multi-word terms. \end_layout \begin_layout Enumerate - A \begin_inset Quotes eld \end_inset @@ -1196,7 +1273,9 @@ A \begin_inset Quotes erd \end_inset - goes between menu names and item names + goes between menu names and item names +\emph default + \emph on only \emph default @@ -1206,7 +1285,6 @@ only \begin_layout Enumerate - \emph on NEVER \emph default @@ -1242,6 +1320,8 @@ Dialog \begin_inset Quotes erd \end_inset + +\emph default \emph on IS STRICTLY FORBIDDEN! @@ -1252,7 +1332,6 @@ IS STRICTLY FORBIDDEN! \begin_deeper \begin_layout Standard - \emph on NEVER \emph default @@ -1284,6 +1363,8 @@ rtrait \begin_inset Quotes erd \end_inset + +\emph default \emph on IS STRICTLY FORBIDDEN! @@ -1291,7 +1372,6 @@ IS STRICTLY FORBIDDEN! \begin_layout Standard - \emph on NEVER \emph default @@ -1330,20 +1410,21 @@ rtrait \begin_inset Quotes erd \end_inset + +\emph default \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\InsetSpace ~ Boxes LyX has a feature for adding comments that appear only within the LyX GUI. @@ -1352,7 +1433,6 @@ Boxes LyX has a feature for adding comments that appear only within status collapsed \begin_layout Standard - These should NEVER appear in the manuals. \end_layout @@ -1367,20 +1447,18 @@ These should NEVER appear in the manuals. \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 LatexCommand \ref{sec:author-notes} - +\begin_inset 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 @@ -1432,8 +1510,8 @@ and\InsetSpace ~ , is used only within quotations (see section\InsetSpace ~ -\begin_inset LatexCommand \ref{sec:quote} - +\begin_inset LatexCommand ref +reference "sec:quote" \end_inset ). @@ -1469,7 +1547,6 @@ and\InsetSpace ~ \end_layout \begin_layout Description - Dashes: Be sure to use the correct one. A single \begin_inset Quotes eld @@ -1490,7 +1567,6 @@ Dashes: Be sure to use the correct one. \begin_deeper \begin_layout Standard - Instead, use an \begin_inset Quotes eld \end_inset @@ -1548,33 +1624,39 @@ em- dash. 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 +sec:xxx Use this for +\family default + \family sans Section \family default -s as well as +s as well as +\family default + \family sans Chapter \family default -s, +s, +\family default + \family sans Subsection \family default -s, +s, +\family default + \family sans Subsubsection \family default @@ -1583,30 +1665,27 @@ s, etc. \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 +The +\emph default + \emph on beginning of the paragraph \emph default @@ -1616,8 +1695,9 @@ beginning of the paragraph \end_layout \begin_layout Enumerate - -If there is no paragraph after a section heading, put it at the +If there is no paragraph after a section heading, put it at the +\emph default + \emph on end of the last line. @@ -1627,32 +1707,38 @@ end of the last line. \begin_deeper \begin_layout Standard - -Example: You have a +Example: You have a +\family default + \family sans Section \family default - which is immediately followed by a + which is immediately followed by a +\family default + \family sans Subsection \family default heading. - This is a case where you need to put the label at the end of the + This is a case where you need to put the label at the end of the +\family default + \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 +This is +\emph default + \emph on very \emph default @@ -1662,7 +1748,6 @@ very \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. @@ -1673,17 +1758,16 @@ In the dim and distant past, whenever someone wanted to document a new feature \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 +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 @@ -1695,12 +1779,14 @@ Please, don't touch this file. \begin_layout List \labelwidthstring 00.00.0000 - \family typewriter -UserGuide.lyx +UserGuide.lyx \family default + This file is complete. - Any changes should be for updates + Any changes should be for updates +\emph default + \emph on only \emph default @@ -1714,7 +1800,6 @@ only \begin_layout List \labelwidthstring 00.00.0000 - \family typewriter Extended.lyx \family default @@ -1728,7 +1813,9 @@ article \end_inset from the author of the feature. - Also, anyone who writes a + Also, anyone who writes a +\family default + \family typewriter .layout \family default @@ -1739,22 +1826,25 @@ article \begin_deeper \begin_layout Standard - -Note, however, that you are +Note, however, that you are +\emph default + \emph on not \emph default - excused from following this Style Sheet just because the sections of + excused from following this Style Sheet just because the sections of +\family default + \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 @@ -1766,7 +1856,6 @@ Tutorial.lyx \begin_layout List \labelwidthstring 00.00.0000 - \family typewriter Customization.lyx \family default @@ -1778,38 +1867,47 @@ Customization.lyx \begin_deeper \begin_layout Standard - -If you are unsure whether or not something belongs in +If you are unsure whether or not something belongs in +\family default + \family typewriter Customization.lyx \family default -, then, most-likely, it +, then, most-likely, it +\emph default + \emph on really \emph default - belongs in + belongs in +\family default + \family typewriter Extended.lyx \family default . Again, let the current editor of the LyX documentation decide if your new - section should be migrated to + section should be migrated to +\family default + \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 + LyX keeps changing so much that I think the +\emph default + \emph on Reference Manual \emph default @@ -1821,28 +1919,30 @@ Reference Manual \begin_deeper \begin_layout Standard - -Note that the +Note that the +\emph default + \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 + At the top of this manual, there are examples of and a template for +\emph default + \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 @@ -1851,13 +1951,13 @@ While I want to make contributing to the Documentation Project as painless \end_layout \begin_layout Subsection - Language \end_layout \begin_layout Standard - -All contributions to the +All contributions to the +\emph default + \emph on primary \emph default @@ -1867,7 +1967,6 @@ primary \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 @@ -1879,8 +1978,9 @@ Don't get hung up on semantics. \end_layout \begin_layout Standard - -Nota Bene: by +Nota Bene: by +\emph default + \emph on primary \emph default @@ -1891,15 +1991,14 @@ primary version of the LyX manuals. The translation efforts require have their own set of guidelines. See section -\begin_inset LatexCommand \ref{sec:translations} - +\begin_inset LatexCommand ref +reference "sec:translations" \end_inset for more info. \end_layout \begin_layout Subsection - Wearing Many Hats: \newline Commentary from the Author (i.\InsetSpace ~ @@ -1907,10 +2006,8 @@ e.: You) \end_layout \begin_layout Standard - - -\begin_inset LatexCommand \label{sec:author-notes} - +\begin_inset LatexCommand label +name "sec:author-notes" \end_inset I want to make it easy for everyone when it comes to documenting things. @@ -1938,18 +2035,15 @@ we \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\InsetSpace ~ Notes: The \begin_inset Quotes eld @@ -1963,13 +2057,11 @@ Me \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 @@ -1978,7 +2070,6 @@ Name of Person \end_layout \begin_layout Standard - \SpecialChar \ldots{} using the \noun on @@ -1990,7 +2081,6 @@ Noun Style \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 @@ -2007,7 +2097,6 @@ 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. @@ -2025,7 +2114,9 @@ Name of Person 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 + paragraph before or after the body of the +\family default + \family sans Quotation \family default @@ -2033,7 +2124,6 @@ Quotation \end_layout \begin_layout Subsubsection - Author's\InsetSpace ~ Notes: The \begin_inset Quotes eld @@ -2047,7 +2137,6 @@ Author \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 @@ -2056,29 +2145,24 @@ There will be times when you are not speaking for the LyX Team, yet you \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 @@ -2091,7 +2175,6 @@ I am the Author \end_layout \begin_layout Standard - The typography for an \begin_inset Quotes eld \end_inset @@ -2104,7 +2187,6 @@ Author's Note \end_layout \begin_layout Itemize - They go in the body of the text, in brackets, \begin_inset Quotes eld \end_inset @@ -2118,13 +2200,11 @@ They go in the body of the text, in brackets, \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 @@ -2150,7 +2230,6 @@ Author's Note: \end_layout \begin_layout Standard - Here's an example: [ \emph on Author's Note: This is an example note. @@ -2160,9 +2239,10 @@ Author's Note: This is an example note. \end_layout \begin_layout Standard - The form of the Author's Note, by the way, isn't a suggestion or request. - It is + It is +\emph default + \emph on mandatory \emph default @@ -2218,8 +2298,6 @@ AN \end_layout \begin_layout Standard - - \begin_inset Quotes eld \end_inset @@ -2231,12 +2309,10 @@ Author's Notes \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{} @@ -2245,16 +2321,16 @@ You are also free to use footnotes on their own in addition to the Personal \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 + Place quotes in a +\family default + \family sans Quotation \family default @@ -2262,13 +2338,13 @@ Quotation \end_layout \begin_layout Paragraph* - Mixing Footnotes and Author's Notes \end_layout \begin_layout Standard - -Author's Notes should +Author's Notes should +\emph default + \emph on never \emph default @@ -2277,25 +2353,23 @@ never \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: \newline -A +A +\emph default + \emph on short \emph default @@ -2304,33 +2378,30 @@ short LyX Team, use this. If you have a long rant, however, quote yourself (see section\InsetSpace ~ -\begin_inset LatexCommand \ref{sec:quote} - +\begin_inset LatexCommand ref +reference "sec:quote" \end_inset ). \end_layout \begin_layout Itemize - Author's Note: \newline -Use this to describe things in LyX (or the manuals) that may change in the - future or are somehow incomplete. +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: \newline -Used for text fragments that almost fit into the flow of the text\SpecialChar \ldots{} -but not - quite. +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. @@ -2343,13 +2414,13 @@ When using these three mechanisms, in addition to rigorously following their \end_layout \begin_layout Subsection - General Stylistic Guidelines \end_layout \begin_layout Standard - -Everything in this section is +Everything in this section is +\emph default + \emph on mandatory to all documenters \emph default @@ -2358,23 +2429,19 @@ mandatory to all documenters \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 @@ -2383,17 +2450,22 @@ There is some typographic freedom in those rules in earlier sections. \begin_deeper \begin_layout Standard - -An example is in the +An example is in the +\emph default + \emph on User's Guide \emph default . - There is a footnote using the + There is a footnote using the +\family default + \family typewriter multcols \family default - command to divide a long + command to divide a long +\family default + \family sans Itemize \family default @@ -2412,25 +2484,23 @@ Evil Red Text 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 @@ -2444,7 +2514,6 @@ we \begin_deeper \begin_layout Standard - When you speak, you speak for the entire LyX Team, so use \begin_inset Quotes eld \end_inset @@ -2463,9 +2532,9 @@ I . \end_layout + \end_deeper \begin_layout Enumerate - The reader is \begin_inset Quotes eld \end_inset @@ -2479,7 +2548,6 @@ you \begin_deeper \begin_layout Standard - Whenever you want to say something to the reader, use \begin_inset Quotes eld \end_inset @@ -2491,9 +2559,9 @@ you, 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 @@ -2508,7 +2576,6 @@ mouse \end_layout \begin_layout Enumerate - Use the term \begin_inset Quotes eld \end_inset @@ -2522,28 +2589,24 @@ cursor \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 LatexCommand \label{sec:quote} - +\begin_inset 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 @@ -2552,7 +2615,6 @@ In some cases, you'll have something to say, an opinion of yours. \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. @@ -2562,12 +2624,13 @@ Any time you wish to quote someone, be it yourself or someone else, there \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 + in the following +\family default + \family sans Figure\InsetSpace ~ Float @@ -2577,8 +2640,6 @@ Float \end_layout \begin_layout Standard - - \begin_inset Float figure placement htbp wide false @@ -2586,13 +2647,13 @@ sideways false status collapsed \begin_layout Standard - Quoting rules for English: \end_layout \begin_layout Itemize - -The body of the quote belongs in a +The body of the quote belongs in a +\family default + \family sans Quotation \family default @@ -2600,20 +2661,19 @@ Quotation \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, +You must, +\emph default + \emph on must \emph default @@ -2622,13 +2682,11 @@ must \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 @@ -2644,7 +2702,6 @@ If you omit text from the beginning of the first sentence in the quote, \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 @@ -2659,7 +2716,6 @@ If you omit text from the end of the last sentence in the quote, the quote \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 @@ -2674,19 +2730,16 @@ If you omit any text from the middle of the quote, be it whole sentences \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 @@ -2699,7 +2752,6 @@ breaks \end_layout \begin_layout Itemize - For missing words (e.\InsetSpace ~ g.\InsetSpace ~ @@ -2723,7 +2775,6 @@ the \end_layout \begin_layout Itemize - For mangled word order, correct the mangled text, following it with the text \begin_inset Quotes eld @@ -2735,9 +2786,9 @@ For mangled word order, correct the mangled text, following it with the . \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 @@ -2751,7 +2802,6 @@ Spelling in the quote must be correct. \end_layout \begin_layout Itemize - Back-to-back bracket blocks merge together. Example: \begin_inset Quotes eld @@ -2776,7 +2826,6 @@ the] \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 @@ -2795,13 +2844,13 @@ If you correct the spelling in 2 or more consecutive words, you can get \end_layout \begin_layout Subsubsection - Coverage \end_layout \begin_layout Standard - -When describing a new feature or +When describing a new feature or +\family default + \family typewriter *.layout \family default @@ -2809,12 +2858,16 @@ When describing a new feature or \end_layout \begin_layout Enumerate - -Be +Be +\emph default + \emph on -clear, concise, +clear, concise, \emph default -and + +and +\emph default + \emph on to the point \emph default @@ -2840,8 +2893,9 @@ Keep It Simple, Stupid! \begin_deeper \begin_layout Itemize - -Do +Do +\emph default + \emph on not \emph default @@ -2850,32 +2904,33 @@ not \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 + example of how +\series default + \series bold NOT \series default to write documentation. - It's all pithy, substanceless verbage, and its + It's all pithy, substanceless verbage, and its +\emph default + \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). @@ -2892,14 +2947,14 @@ other part of the manual \end_layout \begin_layout Enumerate - On the other hand, BE THOROUGH! \end_layout \begin_deeper \begin_layout Enumerate - -You are documenting +You are documenting +\emph default + \emph on features \emph default @@ -2907,27 +2962,33 @@ features \end_layout \begin_layout Enumerate - Group by feature, not by widget. \end_layout \begin_layout Enumerate - -Stay on topic --- one +Stay on topic --- one +\family default + \family sans Section \family default - should cover + should cover +\emph default + \emph on one \emph default feature. - Use + Use +\family default + \family sans Subsection \family default s and further subdivisions to group things if you're documenting several - related features in a single + related features in a single +\family default + \family sans Section \family default @@ -2935,16 +2996,16 @@ Section \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 + You would document +\emph default + \emph on all \emph default @@ -2953,7 +3014,6 @@ all \end_layout \begin_layout Enumerate - Note from \noun on John Weiss @@ -2965,50 +3025,57 @@ I've had people only document one popup --- literally. since other menus, popups, and even unbound functions contained additional stuff. \newline -I got +I got +\emph default + \emph on really \emph default - cranky when that happens, because it means + cranky when that happens, because it means +\emph default + \emph on -I +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 +Remember, there are people who will reference +\emph default + \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 +NEVER NEVER +\emph default + \emph on NEVER EVER \emph default @@ -3016,32 +3083,34 @@ NEVER EVER \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 default \family sans Shift- \family default -, +, +\family default + \family sans Control- \family default -, and +, and +\family default + \family sans Meta- \family default @@ -3054,7 +3123,9 @@ Meta- \family sans Meta- \family default - is the + is the +\family default + \family sans Alt- \family default @@ -3066,7 +3137,6 @@ Alt- \end_layout \begin_layout Enumerate - The reader is smart enough to know that \begin_inset Quotes eld \end_inset @@ -3099,22 +3169,18 @@ cursor \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 LatexCommand \label{sec:english-only} - +\begin_inset LatexCommand label +name "sec:english-only" \end_inset When contributing to the primary --- i.\InsetSpace ~ @@ -3124,29 +3190,24 @@ the English language version --- \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 @@ -3175,7 +3236,6 @@ We felt that ... \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, @@ -3186,7 +3246,9 @@ LyX reformatted the paragraph. \begin_inset Quotes erd \end_inset - If + If +\family default + \family typewriter ispell \family default @@ -3207,7 +3269,6 @@ ispell \begin_deeper \begin_layout Standard - Rule of thumb: any sentence you can express as, \begin_inset Quotes eld \end_inset @@ -3226,9 +3287,9 @@ Foo did it. 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. @@ -3239,8 +3300,9 @@ I know it's tough. \end_layout \begin_layout Enumerate - -I +I +\emph default + \emph on will make you rewrite \emph default @@ -3249,28 +3311,25 @@ will make you rewrite \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.\InsetSpace ~ S.\InsetSpace ~ 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 @@ -3296,7 +3355,6 @@ and. \end_layout \begin_layout Standard - In general, stick to short sentences in written English. Getting rid of passive voice ( \begin_inset Quotes eld @@ -3315,7 +3373,6 @@ was done by\SpecialChar \ldots{} \end_layout \begin_layout Standard - While I'm talking about paragraphs, I'll apply the \begin_inset Quotes eld \end_inset @@ -3336,7 +3393,6 @@ shorter is better \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 @@ -3352,37 +3408,30 @@ breathing room. \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 @@ -3396,12 +3445,10 @@ tools of the trade \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. @@ -3409,10 +3456,11 @@ Most people translate word by word. \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 + All those words mean +\emph default + \emph on roughly \emph default @@ -3425,12 +3473,10 @@ roughly \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. @@ -3440,7 +3486,6 @@ Alright, I admit that you may be able to translate some of the sentences \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 @@ -3449,12 +3494,10 @@ It is generally a good idea to make multiple passes over a paragraph you're \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 @@ -3473,24 +3516,20 @@ exact \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 @@ -3502,27 +3541,25 @@ If there's a mystery phrase in the middle of a sentence, you can't translate \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 + This is especially important for a manual, where the information +\emph default + \emph on is the only \emph default @@ -3531,18 +3568,16 @@ is the only \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\InsetSpace ~ -\begin_inset LatexCommand \ref{sec:english-only} - +\begin_inset LatexCommand ref +reference "sec:english-only" \end_inset . @@ -3551,31 +3586,26 @@ Those of you contributing to a translation of the LyX manuals must follow \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 @@ -3589,7 +3619,6 @@ Dead \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. @@ -3607,7 +3636,6 @@ dead \end_layout \begin_layout Standard - In Germany, there is a magazine known as \begin_inset Quotes gld \end_inset @@ -3640,8 +3668,9 @@ dead \end_layout \begin_layout Standard - -We who write the LyX manuals, original or translated, seek to +We who write the LyX manuals, original or translated, seek to +\emph default + \emph on inform \emph default @@ -3654,12 +3683,10 @@ inform \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 @@ -3674,7 +3701,6 @@ Use short sentences and short paragraphs. \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 @@ -3682,7 +3708,6 @@ Nevertheless, the translations of the LyX manuals should be as clear as \end_layout \begin_layout Standard - Remember: we're translating manuals here, folks. Our goal is rapid information location and comprehension, not a literary prize. @@ -3691,28 +3716,26 @@ Remember: we're translating manuals here, folks. \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 --- +Everything in this manual --- +\emph default + \emph on except section\InsetSpace ~ -\begin_inset LatexCommand \ref{sec:english-only} - +\begin_inset LatexCommand ref +reference "sec:english-only" \end_inset @@ -3721,25 +3744,21 @@ except section\InsetSpace ~ \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 @@ -3763,20 +3782,22 @@ wink! \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 + Be as creative as you want, as long as you +\emph default + \emph on accurately \emph default - and + and +\emph default + \emph on completely \emph default @@ -3784,15 +3805,12 @@ completely \end_layout \begin_layout Subsubsection - Any information in the LyX manuals must also be in the translations. \end_layout \begin_layout Standard - - -\begin_inset LatexCommand \label{sec:accuracy} - +\begin_inset LatexCommand label +name "sec:accuracy" \end_inset This falls under translating the orignals accurately and completely. @@ -3800,17 +3818,19 @@ This falls under translating the orignals accurately and completely. \end_layout \begin_layout Itemize - Omitting any feature description is +\emph default + \emph on - stricly forbidden +stricly forbidden \emph default . \end_layout \begin_layout Itemize - -Misrepresenting or misdescribing any LyX feature or operation +Misrepresenting or misdescribing any LyX feature or operation +\emph default + \emph on must be avoided \emph default @@ -3818,23 +3838,23 @@ must be avoided \end_layout \begin_layout Itemize - -The translation +The translation +\emph default + \emph on cannot \emph default outpace the original. \newline -If no one has documented new feature in the primary LyX manuals (i.\InsetSpace ~ +If no one has documented new feature in the primary + LyX manuals (i.\InsetSpace ~ e.\InsetSpace ~ -the English - versions), do not do so in the translations. +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, \newline @@ -3842,25 +3862,22 @@ 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{} @@ -3872,16 +3889,17 @@ Prepositions, idioms, metaphors, slang, Oh My! There's a jungle of potentially \end_layout \begin_layout Standard - There may be special cases where omitting part of a sentence or paragraph violates rule\InsetSpace ~ -\begin_inset LatexCommand \ref{sec:accuracy} - +\begin_inset LatexCommand ref +reference "sec:accuracy" \end_inset . - In those cases, + In those cases, +\emph default + \emph on do not omit! \emph default @@ -3889,12 +3907,10 @@ do not omit! \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 @@ -3920,20 +3936,19 @@ in context. \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 + If you are the +\emph default + \emph on only \emph default @@ -3942,14 +3957,14 @@ only \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 +If you are a member of a LyX Documentation Translation Team, but +\emph default + \emph on are not \emph default @@ -3960,26 +3975,24 @@ are not \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 +Actually, it is +\emph default + \emph on especially \emph default @@ -3987,18 +4000,17 @@ especially \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 +Since your translation team is translating, they know +\emph default + \emph on some \emph default @@ -4007,7 +4019,6 @@ some \end_layout \begin_layout Subsubsection - Provide a \begin_inset Quotes eld \end_inset @@ -4020,7 +4031,6 @@ Supplement \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. @@ -4030,13 +4040,13 @@ There are parts of this Style Sheet that are English-specific. \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 +Every Translation Team Chief is +\emph default + \emph on required \emph default @@ -4047,7 +4057,6 @@ required \end_layout \begin_layout Enumerate - Name the file: \newline @@ -4112,28 +4121,26 @@ _ru \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 Standard - -Specifically, check the settings in the +Specifically, check the settings in the +\family default + \family sans Document Layout \family default @@ -4147,19 +4154,17 @@ Document Layout \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 @@ -4179,7 +4184,6 @@ Title \begin_deeper \begin_layout Standard - \family typewriter Documentation Project Style Sheet: \newline @@ -4187,7 +4191,6 @@ Supplement for the Translation Project \end_layout \begin_layout Standard - (Replace \begin_inset Quotes eld \end_inset @@ -4202,9 +4205,9 @@ Supplement for the Translation Project with the name of your language.) \end_layout + \end_deeper \begin_layout Itemize - If, in your language, \begin_inset Quotes eld \end_inset @@ -4246,7 +4249,6 @@ Appendix \begin_deeper \begin_layout Standard - Choose a replacement word accordingly. Whatever you choose to replace \begin_inset Quotes eld @@ -4266,10 +4268,10 @@ appendix. \end_layout + \end_deeper \end_deeper \begin_layout Enumerate - Below the title, in the \begin_inset Quotes eld \end_inset @@ -4287,13 +4289,14 @@ Author \begin_deeper \begin_layout Standard - There will be no abstract. \end_layout + \end_deeper \begin_layout Enumerate - -The first +The first +\family default + \family sans Section \family default @@ -4302,7 +4305,6 @@ Section \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 @@ -4321,20 +4323,21 @@ Supplement \begin_inset Quotes erd \end_inset - until he has read + until he has read +\emph default + \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. @@ -4342,13 +4345,13 @@ This Style Sheet is already very detailed. \end_layout \begin_layout Subsubsection - Font Issues \end_layout \begin_layout Standard - -The second +The second +\family default + \family sans Section \family default @@ -4360,20 +4363,17 @@ Section \begin_layout Itemize - \family typewriter Typewriter \end_layout \begin_layout Itemize - \family sans Sans Serif \end_layout \begin_layout Itemize - Roman \newline @@ -4383,27 +4383,23 @@ Emphasized (actually Italics) \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 @@ -4413,7 +4409,6 @@ certainly exist for all languages that use the Roman alphabet. \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 @@ -4421,7 +4416,6 @@ There will be some languages for which following the font-scheme specified \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 @@ -4441,7 +4435,6 @@ fonts. \end_layout \begin_layout Itemize - Guidelines for \begin_inset Quotes eld \end_inset @@ -4460,7 +4453,6 @@ What to do when a font doesn't exist: \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. @@ -4469,7 +4461,6 @@ Roman Use the font that typesetters in your language use for printing books, \begin_layout List \labelwidthstring MMMMMMMM - \noun on Noun\InsetSpace ~ Style @@ -4484,7 +4475,6 @@ Style \begin_layout List \labelwidthstring MMMMMMMM - \emph on Emphasized \emph default @@ -4493,43 +4483,54 @@ Emphasized \begin_deeper \begin_layout Standard - -Use a font that is different from your language's equivalent of +Use a font that is different from your language's equivalent of +\series default + \series bold Boldface \series default . - In other words, your + In other words, your +\family default + \family sans Section \family default -, +, +\family default + \family sans Subsection \family default - and similar headers will be in one typeface, perhaps + and similar headers will be in one typeface, perhaps +\series default + \series bold Boldface \series default , perhaps not. - Whatever that font is, avoid using it for + Whatever that font is, avoid using it for +\emph default + \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 + Use that same font in place of +\family default + \family typewriter Typewriter \family default @@ -4539,27 +4540,34 @@ Typewriter \begin_layout List \labelwidthstring MMMMMMMM - \family sans Sans\InsetSpace ~ Serif \family default Pick any other font that is different from the ones you're using in place - of + of +\emph default + \emph on Emphasized \emph default -, +, +\series default + \series bold Boldface \series default -, and +, and +\family default + \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 + fonts, use the same font you picked to replace +\family default + \family typewriter Typewriter \family default @@ -4571,7 +4579,6 @@ Typewriter \begin_layout List \labelwidthstring MMMMMMMM - \family sans \bar under U @@ -4585,7 +4592,6 @@ Serif \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. @@ -4593,24 +4599,30 @@ If you use some special font on-screen to highlight the accelerator keys 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 + should +\emph default + \emph on never \emph default use. For example, no contributer to the English/European versions may ever use + +\series default \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 + variants can afford to omit +\series default + \series bold Boldface \series default @@ -4619,7 +4631,6 @@ Boldface \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. @@ -4632,18 +4643,20 @@ Once you have determined which fonts in your native writing system will \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 +Quoting Style and the +\family default + \family sans Quote \family default vs. + +\family default \family sans Quotation @@ -4652,24 +4665,25 @@ Quotation \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 +Decide whether +\family default + \family sans Quote \family default - or + or +\family default + \family sans Quotation \family default @@ -4677,17 +4691,15 @@ Quotation \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\InsetSpace ~ -\begin_inset LatexCommand \ref{sec:quote} - +\begin_inset LatexCommand ref +reference "sec:quote" \end_inset . @@ -4696,8 +4708,8 @@ English has its own typography and style for quoting others. Naturally, you do not need to go overboard. Section\InsetSpace ~ -\begin_inset LatexCommand \ref{sec:quote} - +\begin_inset LatexCommand ref +reference "sec:quote" \end_inset of this Style Sheet is overly detailed for a good reason. @@ -4709,24 +4721,20 @@ English has its own typography and style for quoting others. \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 : @@ -4734,14 +4742,14 @@ Note from \begin_layout Itemize - \emph on Author's Note: \end_layout \begin_layout Standard - -Do +Do +\emph default + \emph on not \emph default @@ -4767,7 +4775,6 @@ Author's Note, \end_layout \begin_layout Standard - While we are discussing proper use of the \begin_inset Quotes eld \end_inset @@ -4794,7 +4801,9 @@ Author's Note \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 + In the case of a translation, however, the translator is +\emph default + \emph on not \emph default @@ -4810,7 +4819,6 @@ Author's Note? \end_layout \begin_layout Standard - You, as Translation Project Chief, must decide. You can forbid translation of pre-existing \begin_inset Quotes eld @@ -4842,12 +4850,15 @@ Author's Note \end_layout \begin_layout Standard - -Whatever you decide, codify your policy in its own +Whatever you decide, codify your policy in its own +\family default + \family sans Section \family default - or + or +\family default + \family sans Subsection \family default @@ -4872,13 +4883,13 @@ Author's Note \end_layout \begin_layout Subsubsection - Lost in Translation \end_layout \begin_layout Standard - -After describing all of the previous issues, create a new +After describing all of the previous issues, create a new +\family default + \family sans Section \family default @@ -4895,15 +4906,18 @@ Lost in Translation, \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 + Devote a +\family default + \family sans Subsection \family default - --- or even + --- or even +\family default + \family sans Subsubsection \family default @@ -4911,7 +4925,6 @@ s --- to each specific issue. \end_layout \begin_layout Subsubsection - \SpecialChar \ldots{} \begin_inset Quotes eld @@ -4926,12 +4939,10 @@ Yes, we mean now. \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 @@ -4941,12 +4952,13 @@ Foo \end_layout \begin_layout Standard - This sentence will be tricky to translate, since it contains non-translatable connotations. Therefore, create a +\family default + \family sans - Subsection +Subsection \family default for this issue in your \begin_inset Quotes eld @@ -4972,15 +4984,15 @@ Lost in Translation \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 + For example, the +\emph default + \emph on Intro \emph default @@ -4997,7 +5009,6 @@ You do not need to perform this command twice. \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. @@ -5046,7 +5057,6 @@ go do the required reading before using this manual. \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. @@ -5055,13 +5065,11 @@ Note that all of this commanding and reinforcing is nevertheless in a polite \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 @@ -5084,7 +5092,6 @@ firm convincing. \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 @@ -5109,7 +5116,6 @@ firm convincing \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 @@ -5118,7 +5124,6 @@ We who wrote the manuals added sentences insisting that the reader not ignore \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. @@ -5129,7 +5134,6 @@ In your culture, cajoling the reader into using the manuals correctly may \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. @@ -5141,17 +5145,17 @@ how you want such sentences translated.) \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 + Be careful, however! Keep the Supplement +\emph default + \emph on short \emph default