From: Uwe Stöhr Date: Fri, 19 Jun 2009 22:40:31 +0000 (+0000) Subject: DocStyle.lyx: remove this outdated file. It has not been used since years. Every... X-Git-Tag: 2.0.0~6248 X-Git-Url: https://git.lyx.org/gitweb/?a=commitdiff_plain;h=3830bd3dba028781d613bf72841e4949969c3a9c;p=features.git DocStyle.lyx: remove this outdated file. It has not been used since years. Every doc file currently has its own format which is OK since the format is the same for each whole file. (People started now translating DocStyle.lyx while it isn't worth it.) git-svn-id: svn://svn.lyx.org/lyx/lyx-devel/trunk@30196 a592a061-630c-0410-9148-cb99ea01b6c8 --- diff --git a/development/scons/scons_manifest.py b/development/scons/scons_manifest.py index d59bd0ac3c..4b5b06eb48 100644 --- a/development/scons/scons_manifest.py +++ b/development/scons/scons_manifest.py @@ -2082,7 +2082,6 @@ lib_tex_files = Split(''' lib_doc_files = Split(''' Customization.lyx - DocStyle.lyx DummyDocument1.lyx DummyDocument2.lyx DummyTextDocument.txt diff --git a/lib/doc/DocStyle.lyx b/lib/doc/DocStyle.lyx deleted file mode 100644 index a25d51d035..0000000000 --- a/lib/doc/DocStyle.lyx +++ /dev/null @@ -1,5078 +0,0 @@ -#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 diff --git a/lib/doc/Makefile.am b/lib/doc/Makefile.am index d670666e4c..6c9ac73198 100644 --- a/lib/doc/Makefile.am +++ b/lib/doc/Makefile.am @@ -5,7 +5,6 @@ EXTRA_DIST = README.Documentation docdir = $(pkgdatadir)/doc dist_doc_DATA = \ Customization.lyx \ - DocStyle.lyx \ DummyTextDocument.txt \ DummyDocument1.lyx \ DummyDocument2.lyx \ diff --git a/lib/doc/de/Intro.lyx b/lib/doc/de/Intro.lyx index 867f4de489..c5f1f9bcca 100644 --- a/lib/doc/de/Intro.lyx +++ b/lib/doc/de/Intro.lyx @@ -1,4 +1,4 @@ -#LyX 1.6.3 created this file. For more info see http://www.lyx.org/ +#LyX 1.6.4svn created this file. For more info see http://www.lyx.org/ \lyxformat 345 \begin_document \begin_header @@ -142,7 +142,7 @@ Peter Sütterlin \end_layout \begin_layout Date -letzte Änderung: 6. +letzte Änderung: 20. Juni 2009 \end_layout @@ -1913,24 +1913,10 @@ Sie können sich die aktuellste Version auch aus dem LyX-SVN-Archiv besorgen. lib/doc \family default . - Darin befindet sich die Datei -\family typewriter -DocStyle.lyx -\family default -. - Lesen Sie sie, sie ist ein Stil-Leitfaden für die Dokumentation. -\end_layout - -\begin_layout Enumerate -Gönnen Sie sich ein oder zwei Tage Pause und lesen Sie -\family typewriter -DocStyle.lyx -\family default - nochmal. \end_layout \begin_layout Enumerate -Als nächstes lesen Sie +Lesen Sie \emph on Tutorium \emph default diff --git a/lib/doc/es/Intro.lyx b/lib/doc/es/Intro.lyx index dab2a087f8..fedee52d36 100644 --- a/lib/doc/es/Intro.lyx +++ b/lib/doc/es/Intro.lyx @@ -1,4 +1,4 @@ -#LyX 1.6.3 created this file. For more info see http://www.lyx.org/ +#LyX 1.6.4svn created this file. For more info see http://www.lyx.org/ \lyxformat 345 \begin_document \begin_header @@ -2170,19 +2170,10 @@ http://www.lyx.org/trac/browser/lyx-devel/trunk/lib/doc \end_inset -\begin_inset Newline newline -\end_inset - -En ese directorio hay un archivo llamado -\family typewriter -DocStyle.lyx -\family default -. - Léelo; es la hoja de estilo para la documentación. \end_layout \begin_layout Enumerate -Después lee el +Léelo el \emph on Tutorial \emph default diff --git a/lib/doc/fr/Intro.lyx b/lib/doc/fr/Intro.lyx index 8062777d8d..68b52a64ff 100644 --- a/lib/doc/fr/Intro.lyx +++ b/lib/doc/fr/Intro.lyx @@ -1,4 +1,4 @@ -#LyX 1.6.3 created this file. For more info see http://www.lyx.org/ +#LyX 1.6.4svn created this file. For more info see http://www.lyx.org/ \lyxformat 345 \begin_document \begin_header @@ -2616,19 +2616,10 @@ http://www.lyx.org/trac/browser/lyx-devel/trunk/lib/doc \end_inset -\begin_inset Newline newline -\end_inset - -Dans ce répertoire il existe un fichier appelé -\family typewriter -DocStyle.lyx -\family default -. - Lisez-le ; c'est la feuille de style de la documentation. \end_layout \begin_layout Enumerate -Ensuite, lisez le +Lisez le \shape italic Guide \begin_inset space ~