1 #LyX 1.5.0svn created this file. For more info see http://www.lyx.org/
10 \font_typewriter default
11 \font_default_family default
25 \paperorientation portrait
28 \paragraph_separation indent
30 \quotes_language english
34 \tracking_changes false
41 Documentation Project Style Sheet
48 \begin_layout Abstract
49 This article is a style sheet.
50 It describes, with examples, how the documentation should look and sound.
51 The first few sections explain the font conventions and typography conventions
52 all documentation writers should follow.
53 Those sections also contain examples.
54 It also explains the purpose of each of the different manuals.
55 Follow it not merely to the letter, but also in spirit.
58 \begin_layout Abstract
59 The Style Sheet for LyX documentation (hereafter known as the Style Sheet)
66 forms of LyX documenation, regardless of language.
67 There is a section for translators in the Style Sheet, towards the end.
72 Read the entire Style Sheet!
74 Even if you are a translator, I assume you know enough English to comprehend
79 Questions and Clarifications
82 \begin_layout Standard
83 After the second version of this Style Sheet grew uncomfortably large, the
84 LyX DocTeam decided it needed to lose some excess weight.
85 It seems the Style Sheet began to specify too many special cases, too many
86 points of clarification.
87 On the other hand, contributors to the documents were discovering many
88 creative ways of misinterpreting the Style Sheet specifications.
93 If you have any questions about anything in the Style Sheet,
97 ask first, write second!
100 \begin_layout Standard
101 Field all questions to the LyX Developer's Mailing List.
102 There are seasoned DocTeam members who can answer your questions.
103 If you have any problems with the Style Sheet itself, also contact the
107 \begin_layout Section
111 \begin_layout Standard
112 We'll start with the easiest section, yet also the most important.
115 \begin_layout Standard
116 This is how you should fontify text in the manuals:
120 \labelwidthstring MMMMMMMM
125 general emphasis, generic arguments, titles of books, names the other manuals
126 and of their sections, and notes from the authors
130 \begin_layout Standard
131 Do not overemphasize your text.
136 \labelwidthstring MMMMMMMM
141 program names, file names,
147 -page names, LaTeX code, LaTeX commands, LaTeX package names, and LyX code
152 \labelwidthstring MMMMMMMM
158 menu, button, or popup names, the names/lables of all widgets in a popup,
159 the names of keyboard keys, and certain
160 \begin_inset Quotes eld
164 \begin_inset Quotes erd
171 \labelwidthstring MMMMMMMM
181 \labelwidthstring MMMMMMMM
187 nderlined\InsetSpace ~
191 Rich Fields added this to mimick the underlining of letters in the menus
193 It helps to highlight the accelerator keys, and human brains store information
194 best when they see it frequently.
198 \begin_layout Description
199 WARNING! --- When you do this, make sure you
205 shut off the underlining.
206 Too many people send in things that look like:
216 \SpecialChar \ldots{}
219 they not only shut off underlining, they turned off
232 Make sure the entire word is still in
239 after you shut off the underlining.
244 \labelwidthstring MMMMMMMM
253 \begin_layout Standard
254 If you want to emphasize any text, use
261 LaTeX will put many things boldface on its own, such as
267 s, certain parts of equations, et cetera.
270 \begin_layout Standard
271 Repeat: do not use boldface.
275 \begin_layout Standard
276 Here are some examples:
279 \begin_layout Enumerate
286 appears in configuration files and in the LyX source.
287 Therefore, it (and all other LyX function names) count as code and is set
297 \begin_layout Enumerate
308 is a menu item in the
317 menu, so it appears in
332 nderlined\InsetSpace ~
336 for the accelerator keys.
339 \begin_layout Enumerate
340 Consider the following excerpt from the introduction of one of the manuals:
344 \begin_layout Quotation
355 both refer to the same key.
356 Some keyboards label the
363 \begin_inset Quotes eld
367 \begin_inset Quotes erd
371 \begin_inset Quotes eld
375 \begin_inset Quotes erd
378 still others have two keys.
379 LyX treats all of them as the same key, so we'll use
394 \begin_layout Standard
395 Notice that the key name,
414 when it references the key itself! When I described how the manufacturer
415 chose to label its keyboard, I used Roman and put the word in quotes.
416 There is a semantic difference.
420 \begin_layout Enumerate
421 Take the following command:
425 \begin_layout Standard
434 \begin_layout Standard
435 Notice that the argument to the
449 This is a case where you don't use
455 for code, because you want the generic argument label to stand out.
456 On the other hand, if you were specifying an argument, for example,
457 \begin_inset Quotes eld
465 \begin_inset Quotes erd
479 \begin_layout Enumerate
480 Any LaTeX commands and code, and any
486 LaTeX package names get set in
494 \begin_inset Quotes eld
502 \begin_inset Quotes erd
505 is the name of an unsupported LaTeX package, but
506 \begin_inset Quotes eld
514 \begin_inset Quotes erd
517 is a supported LaTeX class.
520 \begin_layout Section
524 \begin_layout Standard
525 The canonical keyboard contains these keys:
528 \begin_layout Itemize
542 \begin_layout Itemize
556 \begin_layout Itemize
571 \begin_layout Standard
577 use the abbreviations
583 \begin_layout Itemize
586 F1 F2 F3 F4 F5 F6 F7 F8 F9 F10 F11 F12
590 \begin_layout Standard
592 Most modern keyboards have all 12.
596 \begin_layout Itemize
605 \begin_layout Standard
607 \begin_inset Quotes eld
611 \begin_inset Quotes erd
618 \begin_layout Itemize
655 \begin_layout Standard
656 These are the 6 keys that appear above the cursor keys on many PC keyboards.
657 Consider them as part of the standard motion keys.
661 \begin_layout Itemize
668 \begin_layout Standard
669 The four standard motion keys.
670 There is no need to put the word
671 \begin_inset Quotes eld
675 \begin_inset Quotes erd
678 anywhere, since that's obvious.
682 \begin_layout Standard
684 \begin_inset Quotes eld
688 \begin_inset Quotes erd
693 \begin_inset Quotes eld
697 \begin_inset Quotes erd
700 after one of these may be redundant in certain situations.
709 \begin_layout Itemize
724 \begin_layout Standard
725 I won't throw a hissy fit if you use one instead of the other.
726 I'd prefer if you used
738 , but it's okay if you slip up and forget.
739 Since these two keys are bound to the same function in LyX, it doesn't
744 \begin_layout Standard
745 You do not need to explain everywhere what the
758 The user isn't stupid.
759 Also, someone will document anything that isn't clear (e.\InsetSpace ~
774 problem) someplace in the introduction.
775 No need for you to repeat someone else's work.
778 \begin_layout Standard
779 LyX does not support keyboards missing any of the keys described above,
781 LyX can support a keyboard missing
794 There is a keyboard accelerator for
800 , but this is the only function key LyX assumes exists.
801 Nevertheless, these details are of minor, if any, concern for the documentation.
802 Assume the aforementioned keys exist.
805 \begin_layout Section
809 \begin_layout Standard
811 \begin_inset Quotes eld
815 \begin_inset Quotes erd
818 and any description of the 3 mouse buttons have no special handling.
819 Don't typeset them in any other font than the default, which is Roman.
823 \begin_layout Standard
824 Exception: you're writing an Author's Note (see section
825 \begin_inset LatexCommand ref
826 reference "sec:author-notes"
829 ) and you need to mention something about the mouse.
830 Since the rest of the note is in
836 , your description of
837 \begin_inset Quotes eld
841 \begin_inset Quotes erd
844 should be emphasized, as well.
845 There are a couple of other cases like this one; use your judgement.
848 \begin_layout Standard
849 There are only 3 mouse buttons.
850 The use of them and of the mouse itself is obvious.
851 There are few --- if any --- nonstandard things we do with the mouse.
852 Therefore, there's no need to make the word
853 \begin_inset Quotes eld
857 \begin_inset Quotes erd
861 \begin_inset Quotes eld
865 \begin_inset Quotes erd
871 \begin_layout Section
875 \begin_layout Standard
879 \begin_layout Description
880 Multi-word\InsetSpace ~
885 Protected\InsetSpace ~
888 between the words for menu and widget names.
908 \begin_layout Standard
909 This holds for things in
923 If you have a long code example, one that can't simply be inlined and put
940 \begin_layout Standard
945 Protected\InsetSpace ~
948 so that the name doesn't get split between two lines, which is visually
954 Protected\InsetSpace ~
957 is near the end of a line and overflows the margin, use a
965 in that parargraph (consult a LaTeX book for more about
966 \begin_inset Quotes eld
976 \begin_inset Quotes erd
979 ) or manually add a hypenation point.
983 \begin_layout Description
985 Terms These are things like the following:
989 \begin_layout Itemize
997 \begin_layout Itemize
1005 \begin_layout Itemize
1012 \begin_layout Itemize
1020 \begin_layout Standard
1028 font and, in the case of
1041 , capitalize the first two letters.
1044 \begin_layout Standard
1045 Why are these terms special? They are concepts which the seasoned LaTeX-pert
1046 is familiar with, but which the new LyX user is not.
1047 I want them to stand out from the rest of the text, hence the use of
1059 \begin_layout Standard
1060 Seasoned LyX Team Members: Are there other terms that require this special
1061 status? On the other hand, should we eliminate this style completely?
1064 \begin_layout Description
1065 Terminology Note the following:
1068 \begin_layout Itemize
1069 \begin_inset Quotes eld
1073 \begin_inset Quotes erd
1077 \begin_inset Quotes eld
1081 \begin_inset Quotes erd
1085 \begin_inset Quotes eld
1089 \begin_inset Quotes erd
1094 \begin_inset Quotes eld
1098 \begin_inset Quotes erd
1102 \begin_inset Quotes eld
1106 \begin_inset Quotes erd
1112 \begin_layout Itemize
1113 PostScript® is a registered trademark of Adobe Corp.
1118 You must put the ® after it or we'll get sued!
1120 I also want it written as seen here, always capitalized.
1122 \begin_inset Quotes eld
1126 \begin_inset Quotes erd
1130 \begin_inset Quotes eld
1134 \begin_inset Quotes erd
1138 \begin_inset Quotes eld
1142 \begin_inset Quotes erd
1145 - both of them capitalized, in the default font (i.\InsetSpace ~
1148 If you must, cut and paste it from here.
1152 \begin_layout Standard
1153 I am going to say this again:
1156 \begin_layout Standard
1157 \begin_inset VSpace 0.37cm
1163 \begin_layout Standard
1168 You must put the ® after PostScript® or we'll get sued!
1171 \begin_layout Standard
1172 \begin_inset VSpace 0.51cm
1178 \begin_layout Standard
1179 I mean it! American companies like to sue anything that moves.
1186 by forgetting that ®.
1192 \begin_layout Itemize
1193 Similarly, if you use any other registered trademark in any documentation,
1194 put the ® after it, too.
1197 \begin_layout Description
1199 Items When quick-referencing an item in a menu, use the menu separator:
1201 \begin_inset Quotes eld
1204 \SpecialChar \menuseparator
1206 \begin_inset Quotes erd
1214 File\SpecialChar \menuseparator
1218 Notice that there are
1225 \begin_inset Quotes eld
1228 \SpecialChar \menuseparator
1230 \begin_inset Quotes erd
1240 , just like the menu and item names.
1244 \begin_layout Enumerate
1245 The reason why I want no spaces around the
1246 \begin_inset Quotes eld
1249 \SpecialChar \menuseparator
1251 \begin_inset Quotes erd
1254 is to prevent LyX from splitting terms across lines.
1255 The same goes for using
1259 Protected\InsetSpace ~
1262 s between multi-word terms.
1263 The split would be visually disruptive.
1266 \begin_layout Enumerate
1268 \begin_inset Quotes eld
1271 \SpecialChar \menuseparator
1273 \begin_inset Quotes erd
1276 goes between menu names and item names
1283 (Yes, submenus are okay, too).
1286 \begin_layout Enumerate
1292 \begin_inset Quotes eld
1295 \SpecialChar \menuseparator
1297 \begin_inset Quotes erd
1300 between menu items and dialog names.
1302 \begin_inset Quotes eld
1310 ayout\SpecialChar \menuseparator
1315 per\SpecialChar \menuseparator
1320 \begin_inset Quotes erd
1327 IS STRICTLY FORBIDDEN!
1333 \begin_layout Standard
1339 \begin_inset Quotes eld
1342 \SpecialChar \menuseparator
1344 \begin_inset Quotes erd
1347 between popup names and any dialog.
1349 \begin_inset Quotes eld
1355 Dialog\SpecialChar \menuseparator
1363 \begin_inset Quotes erd
1370 IS STRICTLY FORBIDDEN!
1373 \begin_layout Standard
1379 \begin_inset Quotes eld
1382 \SpecialChar \menuseparator
1384 \begin_inset Quotes erd
1387 between menu items and any dialog.
1389 \begin_inset Quotes eld
1397 ayout\SpecialChar \menuseparator
1402 per\SpecialChar \menuseparator
1410 \begin_inset Quotes erd
1417 IS STRICTLY FORBIDDEN!
1420 \begin_layout Standard
1421 Either write out the description, or use context to eliminate any need to
1422 repeat menu items, dialog names, etc.
1427 \begin_layout Description
1429 Boxes LyX has a feature for adding comments that appear only within
1432 \begin_inset Note Note
1435 \begin_layout Standard
1436 These should NEVER appear in the manuals.
1442 You will see nothing in a printout of the Style Sheet.
1443 Therefore, they have no place in the manuals.
1449 \begin_layout Standard
1450 If you have a parenthetical comment you want to make, the reader should
1451 see it too, even in the printed version.
1452 Use an Author's Note (see section
1453 \begin_inset LatexCommand ref
1454 reference "sec:author-notes"
1457 ) in place of the Note-Boxes.
1461 \begin_layout Description
1462 \begin_inset Quotes eld
1465 (\SpecialChar \ldots{}
1467 \begin_inset Quotes erd
1472 \begin_inset Quotes eld
1475 [\SpecialChar \ldots{}
1477 \begin_inset Quotes erd
1483 \begin_inset Quotes eld
1486 {\SpecialChar \ldots{}
1488 \begin_inset Quotes erd
1491 I have recently been corrected about the use of parentheses.
1492 Standard English typesetting uses the normal parentheses,
1493 \begin_inset Quotes eld
1496 (\SpecialChar \ldots{}
1498 \begin_inset Quotes erd
1501 , around any aside, remark, or parenthetical expression.
1503 \begin_inset Quotes eld
1506 [\SpecialChar \ldots{}
1508 \begin_inset Quotes erd
1511 , is used only within quotations (see section\InsetSpace ~
1513 \begin_inset LatexCommand ref
1514 reference "sec:quote"
1519 \begin_inset Quotes eld
1522 {\SpecialChar \ldots{}
1524 \begin_inset Quotes erd
1528 Therefore, never use
1529 \begin_inset Quotes eld
1532 [\SpecialChar \ldots{}
1534 \begin_inset Quotes erd
1538 \begin_inset Quotes eld
1541 {\SpecialChar \ldots{}
1543 \begin_inset Quotes erd
1546 unless otherwise specified by this Style Sheet.
1549 \begin_layout Description
1550 Dashes: Be sure to use the correct one.
1552 \begin_inset Quotes eld
1560 \begin_inset Quotes erd
1563 character is not a dash, it's a hyphen.
1564 Use it only as a hyphen.
1569 \begin_layout Standard
1571 \begin_inset Quotes eld
1575 \begin_inset Quotes erd
1579 \begin_inset Quotes eld
1583 \begin_inset Quotes erd
1587 \begin_inset Quotes eld
1595 \begin_inset Quotes erd
1598 characters form the en-dash.
1600 \begin_inset Quotes eld
1608 \begin_inset Quotes erd
1611 characters create an em-dash, which is slightly longer than the en-dash.
1612 In the printed version of any document, LyX will combine the two or three
1614 \begin_inset Quotes eld
1622 \begin_inset Quotes erd
1625 characters into a single, unbroken line.
1629 \begin_layout Section
1630 Cross-References and Labels
1633 \begin_layout Standard
1634 Use the following labelling conventions:
1638 \labelwidthstring 00.00.0000
1639 sec:xxx Use this for
1667 \labelwidthstring 00.00.0000
1668 eqn:xxx Use this for Equations, should you need to create any.
1672 \labelwidthstring 00.00.0000
1673 tbl:xxxx Use this for tables inside of a table float.
1677 \labelwidthstring 00.00.0000
1678 fig:xxx Use this for figures inside of figure floats.
1681 \begin_layout Standard
1682 Additionally, you should put the label at one of two locations:
1685 \begin_layout Enumerate
1690 beginning of the paragraph
1692 , after a section heading, or at the beginning of captions, etc.
1693 It should be the first thing on the first line.
1694 Don't put a space betweeen it and the first word.
1697 \begin_layout Enumerate
1698 If there is no paragraph after a section heading, put it at the
1702 end of the last line.
1709 \begin_layout Standard
1716 which is immediately followed by a
1723 This is a case where you need to put the label at the end of the
1730 I know it looks ugly; not much we can do about that, though.
1734 \begin_layout Section
1735 Content --- What Goes Where
1738 \begin_layout Standard
1745 important to anyone documenting a new feature.
1746 If you need to add new documentation, pay attention.
1750 \begin_layout Standard
1751 In the dim and distant past, whenever someone wanted to document a new feature
1752 they added, they either wrote a mini-doc and stuck it into the documentation
1753 directory, or they added a new section to the lone manual.
1754 No one paid much attention to organization in those days, either.
1755 The result was a totally bloated, totally unnavigable, and incomplete manual
1756 orbitted by a swarm of tiny, incomplete mini-docs.
1757 I don't want the docs to fall back into that mess.
1760 \begin_layout Standard
1761 With that in mind, I have some instructions for how to keep things organized:
1765 \labelwidthstring 00.00.0000
1771 Please, don't touch this file.
1772 It's essentially complete, anyhow.
1773 Only the editor(s) should make changes to this, as this file contains info
1774 about how to contribute to the doc project.
1775 That's really the only stuff that should need to change, and even then,
1776 only when a new maintainer comes along.
1780 \labelwidthstring 00.00.0000
1786 This file is complete.
1787 Any changes should be for updates
1794 DO NOT ADD new features to here willy-nilly.
1795 Let the editor decide if --- and when --- new sections go in here.
1796 Place any new features in\SpecialChar \ldots{}
1801 \labelwidthstring 00.00.0000
1806 This is where all new features go from now on.
1807 It's in the style of a bound journal --- each section is an
1808 \begin_inset Quotes eld
1812 \begin_inset Quotes erd
1815 from the author of the feature.
1816 Also, anyone who writes a
1822 file for a new document class should write a section describing that new
1823 class and how to use it.
1824 That also goes here.
1828 \begin_layout Standard
1829 Note, however, that you are
1835 excused from following this Style Sheet just because the sections of
1841 are in the form of a journal article.
1846 \labelwidthstring 00.00.0000
1851 This file is complete.
1852 Do not change or add to without permission of the Documenation Project
1857 \labelwidthstring 00.00.0000
1862 This document describes advanced features, most of which alter the look,
1863 feel, and behavior of LyX.
1864 This manual is still a bit incomplete, although that may change soon.
1865 Check for updates often.
1869 \begin_layout Standard
1870 If you are unsure whether or not something belongs in
1876 , then, most-likely, it
1889 Again, let the current editor of the LyX documentation decide if your new
1890 section should be migrated to
1901 \labelwidthstring 00.00.0000
1906 I'd prefer to completely finish this one before doing anything else, but
1908 LyX keeps changing so much that I think the
1914 will be the last one completed.
1915 However, I'd like it if the developer's would add entries anytime they
1916 create a new function or popup.
1917 That would help things immensely!
1921 \begin_layout Standard
1928 follows this Style Sheet for the most part.
1929 There are, however, additional rules to follow when making new entries.
1930 At the top of this manual, there are examples of and a template for
1941 \begin_layout Section
1942 Writing Style: The Primary Manuals
1945 \begin_layout Standard
1946 While I want to make contributing to the Documentation Project as painless
1947 as possible for newcomers, I also want the newcomers to be painless on
1948 the existing Documentation Team! Ergo, I've written this section to give
1949 some flavor to guide everyone's individual style.
1953 \begin_layout Subsection
1957 \begin_layout Standard
1958 All contributions to the
1964 LyX documentation must be in English.
1965 I don't care if it's British, Australian, or American English.
1966 The DocTeam editor will proofread for glaring mistakes and fix them.
1969 \begin_layout Standard
1970 Don't get hung up on semantics.
1971 English is a flexible language, and just because your Mothertongue-to-English
1972 dictionary gives only one translation for a word doesn't necessarily mean
1974 We've had some discussions and misunderstandings on the Developers' List
1975 because of this very problem.
1976 If something is unclear (or just plain weird) due to a translation problem,
1977 one of the American/British/Australian developers can fix it.
1980 \begin_layout Standard
1987 documentation, I exclude the translations.
1988 We usually don't have enough people to cover the manuals in one language,
1989 let alone more than one.
1990 Subsequently, the tranlsations are just that --- translations of the English
1991 version of the LyX manuals.
1992 The translation efforts require have their own set of guidelines.
1994 \begin_inset LatexCommand ref
1995 reference "sec:translations"
2001 \begin_layout Subsection
2004 Commentary from the Author (i.\InsetSpace ~
2008 \begin_layout Standard
2009 \begin_inset LatexCommand label
2010 name "sec:author-notes"
2013 I want to make it easy for everyone when it comes to documenting things.
2014 Some features are incomplete.
2015 Some, you might not know everything about.
2016 Sometimes, you may want to comminucate something to me or the reader or
2017 other DocTeam members.
2018 Sometimes, you may want to
2019 \begin_inset Quotes eld
2023 \begin_inset Quotes erd
2026 you want to say something that is your personal opinion and using
2027 \begin_inset Quotes eld
2031 \begin_inset Quotes erd
2034 would be inappropriate.
2037 \begin_layout Standard
2038 In short, when you contribute to the LyX Docs, you wear many hats.
2041 \begin_layout Standard
2042 For occasions when you need to switch hats, I've designed some special mechanism
2046 \begin_layout Subsubsection
2047 Personal\InsetSpace ~
2049 \begin_inset Quotes eld
2053 \begin_inset Quotes erd
2059 \begin_layout Standard
2060 These are footnotes.
2061 They begin with the following:
2072 \begin_layout Standard
2073 \SpecialChar \ldots{}
2078 for the person's name and without the quotes.
2079 The rest of the footnote is the actual comment.
2083 \begin_layout Standard
2084 Use these when you need to quote a comment by someone (usually yourself),
2085 and need to identify that person.
2086 This includes occasions when you need wear the
2087 \begin_inset Quotes eld
2091 \begin_inset Quotes erd
2094 hat, i.\InsetSpace ~
2096 to speak for yourself instead of for the LyX Team.
2099 \begin_layout Standard
2100 If the comment is too large to put in a footnote, don't use a Personal Note.
2101 When quoting more than about 3 sentences or 5 lines of text, use a bona
2103 Don't use any leading
2104 \begin_inset Quotes eld
2112 \begin_inset Quotes erd
2116 In a real quote, you'll give credit to the original speaker in either the
2117 paragraph before or after the body of the
2126 \begin_layout Subsubsection
2127 Author's\InsetSpace ~
2129 \begin_inset Quotes eld
2133 \begin_inset Quotes erd
2139 \begin_layout Standard
2140 There will be times when you are not speaking for the LyX Team, yet you
2141 are not entirely speaking for yourself.
2142 Instead, you are speaking on behalf of the manual itself, as the author
2144 Some examples of when you might need to do this are:
2147 \begin_layout Itemize
2148 You need to contradict something you just wrote because the feature isn't
2149 quite ready yet, but you wanted to document what it will do.
2152 \begin_layout Itemize
2153 You need to leave a note for yourself.
2156 \begin_layout Itemize
2157 You need to leave a note for the editor or the other DocTeam members.
2160 \begin_layout Itemize
2161 You need to point out something about the manuals to the reader, something
2162 that doesn't fit into the context of the current paragraph.
2165 \begin_layout Standard
2166 At such times, you are wearing your
2167 \begin_inset Quotes eld
2171 \begin_inset Quotes erd
2177 \begin_layout Standard
2178 The typography for an
2179 \begin_inset Quotes eld
2183 \begin_inset Quotes erd
2189 \begin_layout Itemize
2190 They go in the body of the text, in brackets,
2191 \begin_inset Quotes eld
2195 \begin_inset Quotes erd
2198 , not any other form of parentheses.
2199 The bracket are in the default character style.
2202 \begin_layout Itemize
2203 The text of the note itself, however, is emphasized.
2207 \begin_layout Itemize
2208 Begin with the words,
2209 \begin_inset Quotes eld
2217 \begin_inset Quotes erd
2220 and end with an em-dash,
2221 \begin_inset Quotes eld
2225 \begin_inset Quotes erd
2228 , followed by your initials.
2232 \begin_layout Standard
2233 Here's an example: [
2235 Author's Note: This is an example note.
2241 \begin_layout Standard
2242 The form of the Author's Note, by the way, isn't a suggestion or request.
2250 All Author's Notes must begin with this text, verbatim:
2251 \begin_inset Quotes eld
2259 \begin_inset Quotes erd
2264 \begin_inset Quotes eld
2268 \begin_inset Quotes erd
2271 are or any other variant are forbidden.
2272 The Author's Note must end with an em-dash, which is 3
2273 \begin_inset Quotes eld
2277 \begin_inset Quotes erd
2281 \begin_inset Quotes eld
2285 \begin_inset Quotes erd
2290 \begin_inset Quotes eld
2294 \begin_inset Quotes erd
2297 ; you must use 3 (and 5 is right out).
2300 \begin_layout Standard
2301 \begin_inset Quotes eld
2305 \begin_inset Quotes erd
2308 are inherently transient, and should disapear as a manual matures.
2311 \begin_layout Subsubsection
2315 \begin_layout Standard
2316 You are also free to use footnotes on their own in addition to the Personal
2317 Notes and/or Author's Notes.
2318 I've frequently used footnotes to \SpecialChar \ldots{}
2319 well, to comment on parts of a section
2320 without putting the commentary into the body of the text.
2323 \begin_layout Paragraph*
2324 Mixing Footnotes and Personal Notes
2327 \begin_layout Standard
2328 Personal Notes always go in footnotes, and should be 5 lines or fewer.
2329 Any larger quotation should be quoted properly, using the rules of standard
2337 paragraph environment.
2340 \begin_layout Paragraph*
2341 Mixing Footnotes and Author's Notes
2344 \begin_layout Standard
2345 Author's Notes should
2355 \begin_layout Paragraph*
2356 Mixing Personal Notes and Author's Notes
2359 \begin_layout Standard
2360 Forbidden; these two are mutually exclusive.
2363 \begin_layout Subsubsection
2367 \begin_layout Itemize
2376 opinion --- yours or another LyX developer's --- about anything.
2377 Anywhere in the manuals you wish to speak for yourself instead the the
2379 If you have a long rant, however, quote yourself (see section\InsetSpace ~
2381 \begin_inset LatexCommand ref
2382 reference "sec:quote"
2388 \begin_layout Itemize
2391 Use this to describe things in LyX (or the manuals) that may
2392 change in the future or are somehow incomplete.
2393 Author's Notes are supposed to disappear as a manual matures.
2396 \begin_layout Itemize
2399 Used for text fragments that almost fit into the flow of
2400 the text\SpecialChar \ldots{}
2404 \begin_layout Standard
2405 When using these three mechanisms, in addition to rigorously following their
2406 descriptions, please use them properly.
2407 I listed some additional restrictions previously.
2408 Some of you may balk at these restrictions.
2409 Nevertheless, there is a reason for them: if you have an overwhemling desire
2410 to mix or modify footnotes, Personal Notes, and Author's Notes, you shouldn't
2411 be using any of them.
2412 More specifically, you're trying to use a hammer to drive in a screw.
2413 What you want to say probably needs to go into the main body of the text.
2416 \begin_layout Subsection
2417 General Stylistic Guidelines
2420 \begin_layout Standard
2421 Everything in this section is
2425 mandatory to all documenters
2427 , regardless the language you're writing in.
2431 \begin_layout Subsubsection
2435 \begin_layout Enumerate
2436 Use the typography rules outlined in the beginning sections of this document.
2439 \begin_layout Enumerate
2440 Don't, however, mimic the typography of this file.
2441 Yes, the Style Sheet doesn't follow the Style Sheet (grin).
2444 \begin_layout Enumerate
2445 There is some typographic freedom in those rules in earlier sections.
2446 Use that freedom wisely.
2447 Most importanly, never sacrifice the online appearance for the printed
2448 appearance and vice versa.
2452 \begin_layout Standard
2453 An example is in the
2460 There is a footnote using the
2466 command to divide a long
2472 environment into 3 columns.
2473 It adds some LaTeX commands to the online version, the so-called
2474 \begin_inset Quotes eld
2478 \begin_inset Quotes erd
2481 that some so vehemently oppose.
2482 Without it, however, that footnote takes up over two pages, most of which
2484 This is an example of permitting a little ugliness in the online version
2485 to get the printed version to look right.
2489 \begin_layout Enumerate
2490 When in doubt, compromise.
2494 \begin_layout Standard
2495 When in doubt, use good judgement.
2499 \begin_layout Subsubsection
2503 \begin_layout Enumerate
2505 \begin_inset Quotes eld
2509 \begin_inset Quotes erd
2516 \begin_layout Standard
2517 When you speak, you speak for the entire LyX Team, so use
2518 \begin_inset Quotes eld
2522 \begin_inset Quotes erd
2526 \begin_inset Quotes eld
2530 \begin_inset Quotes erd
2537 \begin_layout Enumerate
2539 \begin_inset Quotes eld
2543 \begin_inset Quotes erd
2550 \begin_layout Standard
2551 Whenever you want to say something to the reader, use
2552 \begin_inset Quotes eld
2556 \begin_inset Quotes erd
2559 not some contorted construction to avoid being too informal.
2564 \begin_layout Enumerate
2566 \begin_inset Quotes eld
2570 \begin_inset Quotes erd
2573 for both the physical pointing object (mouse, joystick, touch pad, track
2574 ball, etc.) and the mouse cursor which the physical object moves about the
2578 \begin_layout Enumerate
2580 \begin_inset Quotes eld
2584 \begin_inset Quotes erd
2587 for the little blinking vertical bar that indicates where text can/will
2591 \begin_layout Enumerate
2592 When in doubt, compromise.
2596 \begin_layout Standard
2597 When in doubt, use good judgement.
2601 \begin_layout Subsubsection
2602 \begin_inset LatexCommand label
2606 Quoting Yourself and Others
2609 \begin_layout Standard
2610 In some cases, you'll have something to say, an opinion of yours.
2611 Since this is your opinion, you're not speaking for the LyX Team.
2612 You have so much to say, in fact, that it won't fit into a Personal Note
2613 or an Author's Note.
2614 In these cases you want to quote yourself.
2617 \begin_layout Standard
2618 Any time you wish to quote someone, be it yourself or someone else, there
2619 are standard rules one follows.
2620 Every language has its own rules.
2621 You should follow the rules that apply to the language of the document
2622 to which you are contributing.
2626 \begin_layout Standard
2627 This creates a problem for the primary documentation.
2628 The primary documentation is written in English, yet the contributors come
2629 from many countries.
2630 The quoting rules for English (well, American English, at least) are outlined
2638 , for your convenience.
2639 Read them if you need to.
2642 \begin_layout Standard
2643 \begin_inset Float figure
2649 \begin_layout Standard
2650 Quoting rules for English:
2653 \begin_layout Itemize
2654 The body of the quote belongs in a
2663 \begin_layout Itemize
2664 The sentences prior to the quote should flow logically and smoothly into
2668 \begin_layout Itemize
2669 The sentences immediately following the quote should continue the flow of
2673 \begin_layout Itemize
2680 credit the original author of the quote in the sentences immediately before
2684 \begin_layout Itemize
2685 Crediting the original author of the quote should not, however, disrupt
2686 the flow of the text.
2689 \begin_layout Itemize
2690 If you omit text from the beginning of the first sentence in the quote,
2691 the quote must start with the text
2692 \begin_inset Quotes eld
2695 [\SpecialChar \ldots{}
2697 \begin_inset Quotes erd
2701 This is an ellipsis in square brackets.
2704 \begin_layout Itemize
2705 If you omit text from the end of the last sentence in the quote, the quote
2706 must end with the text
2707 \begin_inset Quotes eld
2710 [\SpecialChar \ldots{}
2712 \begin_inset Quotes erd
2715 followed by the sentence's punctuation mark.
2718 \begin_layout Itemize
2719 If you omit any text from the middle of the quote, be it whole sentences
2720 or parts of sentences, replace it with the text
2721 \begin_inset Quotes eld
2724 [\SpecialChar \ldots{}
2726 \begin_inset Quotes erd
2732 \begin_layout Itemize
2733 The quote must be grammatically correct.
2738 \begin_layout Itemize
2739 If the original is wrong, you must correct it.
2742 \begin_layout Itemize
2743 If omitting part of the quote
2744 \begin_inset Quotes eld
2748 \begin_inset Quotes erd
2751 it, you must correct the problem.
2754 \begin_layout Itemize
2755 For missing words (e.\InsetSpace ~
2758 \begin_inset Quotes eld
2762 \begin_inset Quotes erd
2765 goes missing), place the word in square brackets,
2766 \begin_inset Quotes eld
2769 [\SpecialChar \ldots{}
2771 \begin_inset Quotes erd
2774 and insert in the quote where needed.
2777 \begin_layout Itemize
2778 For mangled word order, correct the mangled text, following it with the
2780 \begin_inset Quotes eld
2784 \begin_inset Quotes erd
2791 \begin_layout Itemize
2792 Spelling in the quote must be correct.
2793 Correct any misspelled words and place the text
2794 \begin_inset Quotes eld
2798 \begin_inset Quotes erd
2801 after the corrected word.
2804 \begin_layout Itemize
2805 Back-to-back bracket blocks merge together.
2807 \begin_inset Quotes eld
2810 [\SpecialChar \ldots{}
2812 \begin_inset Quotes erd
2817 \begin_inset Quotes eld
2820 [\SpecialChar \ldots{}
2822 \begin_inset Quotes erd
2828 \begin_layout Itemize
2829 If you correct the spelling in 2 or more consecutive words, you can get
2831 \begin_inset Quotes eld
2835 \begin_inset Quotes erd
2838 after the last mistake.
2846 \begin_layout Subsubsection
2850 \begin_layout Standard
2851 When describing a new feature or
2860 \begin_layout Enumerate
2876 \begin_inset Quotes eld
2879 Keep It Short and Sweet
2880 \begin_inset Quotes erd
2884 \begin_inset Quotes eld
2887 Keep It Simple, Stupid!
2888 \begin_inset Quotes erd
2895 \begin_layout Itemize
2902 write paragraph after paragraph of verbage.
2906 \begin_layout Itemize
2910 \begin_layout Itemize
2911 Take a look at the manual for a commercial word processor --- it's a fine
2918 to write documentation.
2919 It's all pithy, substanceless verbage, and its
2929 \begin_layout Enumerate
2930 Avoid being pedantic like The Plague!
2933 \begin_layout Enumerate
2934 In the same vein, don't write more than you have to.
2935 You're not working in a vacuum --- refer freely to other parts of the manual
2936 (and other parts of other manuals).
2938 \begin_inset Quotes eld
2941 other part of the manual
2942 \begin_inset Quotes erd
2945 is incomplete or empty, refer to it.
2946 Someone will fill it in eventually.
2949 \begin_layout Enumerate
2950 On the other hand, BE THOROUGH!
2954 \begin_layout Enumerate
2961 , not widgets, not how the source code is organized.
2964 \begin_layout Enumerate
2965 Group by feature, not by widget.
2968 \begin_layout Enumerate
2969 Stay on topic --- one
2988 s and further subdivisions to group things if you're documenting several
2989 related features in a single
2998 \begin_layout Enumerate
2999 Describe EVERYTHING related to that feature, no matter where it is.
3003 \begin_layout Enumerate
3004 Example: Paragraph Indenting.
3005 Several popups control its behavior.
3012 of this: which popups control it, when you use which setting on which popup
3013 to do which operation, et cetera.
3016 \begin_layout Enumerate
3023 I've had people only document one popup --- literally.
3024 This added off-topic information and only described half of the feature,
3025 since other menus, popups, and even unbound functions contained additional
3034 cranky when that happens, because it means
3042 Bad help is worse than no help at all.
3046 \begin_layout Standard
3047 These remarks still hold true: you'll piss of the DocTeam editor if you
3048 do things wrong, because he'll have to fix your mistakes.
3053 \begin_layout Enumerate
3054 Remember, there are people who will reference
3060 section, just as you're referencing someone else's.
3061 You do want what you write to be useful, don't you?
3065 \begin_layout Enumerate
3066 When in doubt, compromise.
3070 \begin_layout Standard
3071 When in doubt, use good judgement.
3075 \begin_layout Subsubsection
3082 Treat the Reader as if She is Stupid
3085 \begin_layout Enumerate
3089 \begin_layout Enumerate
3090 No talking down to the reader.
3093 \begin_layout Enumerate
3094 The reader is smart enough to know what a mouse is.
3097 \begin_layout Enumerate
3098 The reader is smart enough to know how to use a keyboard, including the
3118 (The introduction of most of the manuals takes care of the
3119 \begin_inset Quotes eld
3133 \begin_inset Quotes erd
3136 issue, so you don't need to.)
3139 \begin_layout Enumerate
3140 The reader is smart enough to know that
3141 \begin_inset Quotes eld
3145 \begin_inset Quotes erd
3149 \begin_inset Quotes eld
3152 where the text cursor is sitting right now, in the buffer currently visible.
3153 \begin_inset Quotes erd
3158 (Anything more than the word
3159 \begin_inset Quotes eld
3163 \begin_inset Quotes erd
3166 is, IMO, superfluous and wll be deleted .
3167 So, save yourself the typing, save the editor the cutting, and save the
3168 reader the strain of sifting through extra verbage that adds no content.)
3171 \begin_layout Enumerate
3172 Rule of thumb: the reader is not an imbecile.
3173 The reader is merely lost; point them in the right direction, and they
3174 can take it from there.
3177 \begin_layout Subsection
3178 Tips for the English Version
3181 \begin_layout Standard
3182 \begin_inset LatexCommand label
3183 name "sec:english-only"
3186 When contributing to the primary --- i.\InsetSpace ~
3188 the English language version ---
3189 of the LyX manuals, keep the following in mind.
3192 \begin_layout Subsubsection
3193 Write as if You're Talking with a Friend.
3197 \begin_layout Enumerate
3198 Think that way when you write.
3199 Play the dialogue in your mind.
3202 \begin_layout Enumerate
3203 Be as informal as you please (without being rude).
3206 \begin_layout Subsubsection
3207 AVOID the Passive Voice
3210 \begin_layout Enumerate
3212 \begin_inset Quotes eld
3215 It is felt that this name best explains the command's purpose.
3216 \begin_inset Quotes erd
3219 We know full well who wrote the command:
3220 \begin_inset Quotes eld
3223 The LyX Team felt ...
3224 \begin_inset Quotes erd
3228 \begin_inset Quotes eld
3232 \begin_inset Quotes erd
3238 \begin_layout Enumerate
3239 Things don't happen by magic - somebody or something did it.
3240 Only politicians use the passive voice to cover up who did something.
3241 If LyX reformats a paragraph, write,
3242 \begin_inset Quotes eld
3245 LyX reformatted the paragraph.
3246 \begin_inset Quotes erd
3255 makes changes, write,
3256 \begin_inset Quotes eld
3263 changes the document.
3264 \begin_inset Quotes erd
3271 \begin_layout Standard
3272 Rule of thumb: any sentence you can express as,
3273 \begin_inset Quotes eld
3277 \begin_inset Quotes erd
3281 \begin_inset Quotes eld
3285 \begin_inset Quotes erd
3292 \begin_layout Enumerate
3294 We all hear way, way too much garbage English on the TV every day in the
3296 Some people think it makes speech better.
3298 It makes speech baroque, if not outright byzantine.
3299 With a little effort, you can wean yourself off of it.
3302 \begin_layout Enumerate
3307 will make you rewrite
3309 anything in the passive voice.
3310 It's awkward and hard to read.
3313 \begin_layout Enumerate
3314 Note to non-Americans:
3318 \begin_layout Standard
3319 Using passive voice is generally considered bad style in the U.\InsetSpace ~
3322 too easy to obfuscate your words with it.
3323 It also bloats sentences, often unnecessarily.
3327 \begin_layout Subsubsection
3332 \begin_layout Standard
3333 In English, there is a grammatical error known as the
3334 \begin_inset Quotes eld
3338 \begin_inset Quotes erd
3341 The classic example of a run-on sentence is 7 clauses strung together with
3343 \begin_inset Quotes eld
3347 \begin_inset Quotes erd
3350 There are, however, less obvious run-on sentences, ones using too many
3351 subordinate clauses.
3352 Such sentences may look elegant because they are complex.
3353 However, they are also extremely difficult to read because they are so
3357 \begin_layout Standard
3358 In general, stick to short sentences in written English.
3359 Getting rid of passive voice (
3360 \begin_inset Quotes eld
3363 \SpecialChar \ldots{}
3364 was done by\SpecialChar \ldots{}
3366 \begin_inset Quotes erd
3369 ) shortens and simplifies them.
3370 Hacking apart sentences with many dependent clauses is another way to shorten
3372 There are ways to do this yet still have a smooth-flowing paragraph.
3375 \begin_layout Standard
3376 While I'm talking about paragraphs, I'll apply the
3377 \begin_inset Quotes eld
3381 \begin_inset Quotes erd
3384 motto to them, as well.
3385 At the time I started with the manuals (and this Style Sheet), I didn't
3386 pay too much attention to paragraph size.
3387 I've since become a big proponent of short paragraphs, with one idea per
3389 While long, flowing, multi-concept paragraphs can be nice in novels, we're
3391 Our goal is rapid information location and comprehension, not a literary
3395 \begin_layout Standard
3396 There is a single exception to the short sentence, short paragraph rule.
3397 Particularly complex ideas may need more
3398 \begin_inset Quotes eld
3402 \begin_inset Quotes erd
3405 However, you shouldn't encounter such complex ideas often when documenting
3407 Try to keep things short, and use your judgement as needed.
3410 \begin_layout Standard
3411 To reiterate, yet again, something I said before:
3415 When in doubt, compromise.
3419 When in doubt, use good judgement.
3422 \begin_layout Standard
3423 Hopefully, you've got the idea (grin).
3426 \begin_layout Section
3430 \begin_layout Subsection
3431 Rules of the Translating Trade
3434 \begin_layout Standard
3435 While translating anything, there are certain
3436 \begin_inset Quotes eld
3440 \begin_inset Quotes erd
3444 They will help you greatly.
3447 \begin_layout Subsubsection
3448 Translate one paragraph at a time.
3451 \begin_layout Standard
3452 Most people translate word by word.
3453 Clearly, you lose all context if you do that.
3454 A word may have multiple meanings.
3455 You can't tell which unless you look at the rest of the sentence.
3458 \begin_layout Standard
3459 There is another level to the context issue, however.
3460 Your dictionary may translate multiple English words the same way.
3461 All those words mean
3468 Each one, however, covers a different shade of meaning, a different mood
3470 It is often difficult to resolve those shades of meaning in the context
3471 of even one sentence.
3472 A paragraph, however, will provide that context.
3475 \begin_layout Subsubsection
3476 You will not translate it correctly on the first try.
3479 \begin_layout Standard
3480 Alright, I admit that you may be able to translate some of the sentences
3482 If you know a language well, you may even understand over half of the text.
3483 Nevertheless, overconfidence can lead you astray.
3484 There will be some sentences, no matter how few, that will simply confound
3488 \begin_layout Standard
3489 It is generally a good idea to make multiple passes over a paragraph you're
3491 Even if you translate the entire paragraph on the first pass, make a second
3493 You'll often improve upon your first attempt.
3496 \begin_layout Subsubsection
3497 When in doubt, write down all of the meanings for a word.
3500 \begin_layout Standard
3501 You can often translate tricky parts of a text using the context of the
3502 surrounding sentences.
3503 So, if you hit a word or phrase you don't know, translate it more than
3505 Picking the most likely translations, summarize them in one to three words
3507 \begin_inset Quotes eld
3511 \begin_inset Quotes erd
3518 \begin_layout Subsubsection
3519 Using context, fix the meanings on the next pass.
3522 \begin_layout Standard
3523 This is where your multiple translations of a single word become useful.
3524 Using the other sentences you translated, you can now translate that mystery--s
3525 entence without reconsulting your dictionary.
3528 \begin_layout Subsubsection
3529 Fix the grammar only after you've finished translating the sentence.
3532 \begin_layout Standard
3533 If there's a mystery phrase in the middle of a sentence, you can't translate
3534 the entire sentence.
3535 Why grammatically rearrange the words you translated already? You may need
3536 to restructure the sentence a second time once you figure out how to translate
3537 that mystery phrase.
3538 Better to wait until you've completely translated the sentence to clean
3540 That way, you do so only once.
3543 \begin_layout Subsubsection
3544 If you can't translate it, skip it and come back to it on the next pass.
3547 \begin_layout Standard
3548 Remember the earlier discussion of context and its immense usefulness? There
3549 is no sin in making multiple passes over a tricky passage.
3552 \begin_layout Subsubsection
3553 Translate the meaning first.
3557 \begin_layout Standard
3558 The information content of the text under translation is the most important
3560 This is especially important for a manual, where the information
3566 important part of the original document.
3567 Lose that, and you lose the very point of performing the translation.
3570 \begin_layout Subsection
3571 Tips for the Translators
3574 \begin_layout Standard
3575 Those of you contributing to a translation of the LyX manuals must follow
3576 a modified set of rules.
3577 The first few rules are analogous to those in section\InsetSpace ~
3579 \begin_inset LatexCommand ref
3580 reference "sec:english-only"
3584 There are additional rules and regulations that follow those first few.
3588 \begin_layout Subsubsection
3589 Write as if you are explaining LyX to a colleague you know well.
3592 \begin_layout Enumerate
3593 Think that way when you write.
3594 Play the dialogue in your mind.
3597 \begin_layout Enumerate
3598 Use a conversational style in your writing.
3599 Pretend you are teaching LyX to a colleague you know well.
3602 \begin_layout Enumerate
3603 Use a style that is polite without being too formal.
3604 If, in your culture, informal language is appropriate to use with a colleague,
3605 use informal speech in the translation of the manual.
3608 \begin_layout Subsubsection
3609 AVOID Snobby, Academic, Specialized, or
3610 \begin_inset Quotes eld
3614 \begin_inset Quotes erd
3621 \begin_layout Standard
3622 In English, the passive voice appears formal, dry, barren.
3623 It also often adds unnecessary complexity.
3624 In other langauges, however, this is not the case.
3625 There is nothing wrong with passive voice, and people use it frequently
3626 in everyday conversation.
3627 Nevertheless, your translation of the LyX manuals must avoid
3628 \begin_inset Quotes eld
3632 \begin_inset Quotes erd
3638 \begin_layout Standard
3639 In Germany, there is a magazine known as
3640 \begin_inset Quotes gld
3644 \begin_inset Quotes grd
3647 The writing in it is so complex, it is extremely difficult for non-native
3648 German speakers to understand.
3649 While sophisticated, the writing style of
3650 \begin_inset Quotes gld
3654 \begin_inset Quotes grd
3657 is not what a German uses in everyday conversation.
3658 Nor is the writing style for a Russian mathematics journal.
3659 Such specialized or overly-sophisticated styles are
3660 \begin_inset Quotes eld
3664 \begin_inset Quotes erd
3667 in the sense that they are seldom used by normal people in everyday speech.
3670 \begin_layout Standard
3671 We who write the LyX manuals, original or translated, seek to
3678 If we write in a style only a few people use, and use seldomly, we will
3680 Use a writing style that mirrors everyday speech (without being vulgar,
3685 \begin_layout Subsubsection
3686 Keep the Writing Simple.
3689 \begin_layout Standard
3690 For the English version, I wrote,
3691 \begin_inset Quotes eld
3694 Use short sentences and short paragraphs.
3695 \begin_inset Quotes erd
3698 What if, however, short sentences and paragraphs are something only children
3699 use in your language? What if, in yet another language, short sentences
3700 imply rudeness? Naturally, you would not want to use them in your translation.
3703 \begin_layout Standard
3704 Nevertheless, the translations of the LyX manuals should be as clear as
3706 So, for our international colleagues, we apply this rule: Keep your sentences
3707 and paragraphs as short as makes sense.
3710 \begin_layout Standard
3711 Remember: we're translating manuals here, folks.
3712 Our goal is rapid information location and comprehension, not a literary
3714 Try to keep your writing concise yet smooth-flowing.
3715 And use your judgement as needed:
3719 When in doubt, compromise.
3723 When in doubt, use good judgement.
3726 \begin_layout Subsubsection
3727 Translators must follow the Style Sheet, too!
3730 \begin_layout Standard
3731 Everything in this manual ---
3735 except section\InsetSpace ~
3737 \begin_inset LatexCommand ref
3738 reference "sec:english-only"
3743 --- applies to every LyX documenter, no matter what the language.
3746 \begin_layout Subsubsection
3747 Translators must read the Style Sheet Supplement for their language.
3750 \begin_layout Standard
3751 For every translation project, there is a Supplement to the Style Sheet.
3758 DocStyle_Supplement_<cn>.lyx
3761 \begin_layout Standard
3762 \SpecialChar \ldots{}
3764 \begin_inset Quotes eld
3772 \begin_inset Quotes erd
3775 is your language's two-letter locale code.
3776 The Translation Project Chief for your language wrote this.
3777 If he hasn't, pester him to do so! <
3784 \begin_layout Subsubsection
3785 The English versions of the manuals are not Sacred Text.
3788 \begin_layout Standard
3789 You do not need to translate everything word for word.
3790 In fact, you shouldn't.
3791 Keep to the spirit of the originals, not the letter.
3792 Be as creative as you want, as long as you
3804 convey all of the information contained in the English versions.
3807 \begin_layout Subsubsection
3808 Any information in the LyX manuals must also be in the translations.
3811 \begin_layout Standard
3812 \begin_inset LatexCommand label
3816 This falls under translating the orignals accurately and completely.
3820 \begin_layout Itemize
3821 Omitting any feature description is
3830 \begin_layout Itemize
3831 Misrepresenting or misdescribing any LyX feature or operation
3840 \begin_layout Itemize
3847 outpace the original.
3849 If no one has documented new feature in the primary
3850 LyX manuals (i.\InsetSpace ~
3852 the English versions), do not do so in the translations.
3853 If you're really looking for something to do, either:
3857 \begin_layout Itemize
3858 \SpecialChar \ldots{}
3859 focus on translating something you haven't yet,
3864 \begin_layout Itemize
3865 \SpecialChar \ldots{}
3866 update or repair the primary manual.
3869 \begin_layout Standard
3870 If you cannot or do not want to do one of the above, then take a break.
3872 Wait for the main manuals to catch up before translating anything else.
3876 \begin_layout Subsubsection
3877 What you cannot translate, you may omit (usually).
3880 \begin_layout Standard
3881 Prepositions, idioms, metaphors, slang, Oh My! There's a jungle of potentially
3882 untranslatable text you may face.
3883 Happily, none of these untranslatables are essential to the original text\SpecialChar \ldots{}
3886 If you can't translate a phrase or two, try omitting them.
3887 If the rest of the paragraph still makes sense, then don't worry about
3891 \begin_layout Standard
3892 There may be special cases where omitting part of a sentence or paragraph
3893 violates rule\InsetSpace ~
3895 \begin_inset LatexCommand ref
3896 reference "sec:accuracy"
3906 You must try and translate those tricky spots.
3909 \begin_layout Subsubsection
3910 Translators may add their own fluff to the information content.
3913 \begin_layout Standard
3914 After you do strip away all of the idioms, metaphors, slang, humor, and
3916 \begin_inset Quotes eld
3920 \begin_inset Quotes erd
3923 you may find that your translated manual is dull and dry.
3924 Why not add your own fluff? Add text that makes the manual a pleasure to
3925 read, that engages the reader.
3926 It may take the form of humor, or metaphors, or sayings.
3927 Whatever you add, it should be
3928 \begin_inset Quotes eld
3932 \begin_inset Quotes erd
3935 It should not clash with the explanation of LyX features and functions.
3938 \begin_layout Subsection
3939 For Translation Project Chiefs
3942 \begin_layout Subsubsection
3943 The First Is In Charge
3946 \begin_layout Standard
3947 If you were the first person to start translating the manuals, you're the
3948 LyXDoc Translation Project Chief for your language.
3955 person translating the LyXDocs, that automatically makes you the Translation
3959 \begin_layout Standard
3960 Amongst other things, that means that you must read this section and perform
3961 the tasks described here.
3964 \begin_layout Standard
3965 If you are a member of a LyX Documentation Translation Team, but
3971 its Chief, you may stop reading.
3972 The remainder of this section will be of no interest to you.
3973 If you came to the Style Sheet from the Supplement for your language, you
3977 \begin_layout Standard
3978 If you have not read the Style Sheet Supplement for your language, you should
3983 \begin_layout Subsubsection
3984 Read the Style Sheet
3987 \begin_layout Standard
3988 No documenter is excused from following the Style Sheet, not even a Translation
3992 \begin_layout Standard
3999 important that the Translation Project Chiefs read the Style Sheet.
4002 \begin_layout Subsubsection
4003 Make your translators read the Style Sheet
4006 \begin_layout Standard
4007 No documenter is excused from following the Style Sheet.
4010 \begin_layout Standard
4011 Since your translation team is translating, they know
4018 Therefore, they should be able to read the Style Sheet.
4021 \begin_layout Subsubsection
4023 \begin_inset Quotes eld
4027 \begin_inset Quotes erd
4033 \begin_layout Standard
4034 There are parts of this Style Sheet that are English-specific.
4035 I have tried to provide a general, language-independent description of
4036 certain details in this section.
4037 Unfortunately, that general description doesn't cover the specifics of
4042 \begin_layout Standard
4043 That's where you, as head of a LyXDoc Translation Team, come in.
4046 \begin_layout Standard
4047 Every Translation Team Chief is
4053 to write a Supplement to the official Documentation Style Sheet, with specifics
4054 issues affecting your language.
4055 (You are, after all, the LyX Team expert on your native tongue.) Follow
4056 these guidelines when writing the Supplement:
4059 \begin_layout Enumerate
4064 DocStyle_Supplement_<cn>.lyx
4068 \SpecialChar \ldots{}
4070 \begin_inset Quotes eld
4078 \begin_inset Quotes erd
4081 is the two-letter code for your language.
4082 This is the same two-letter code that is part of the filenames for the
4085 \begin_inset Quotes eld
4093 \begin_inset Quotes erd
4097 \begin_inset Quotes eld
4105 \begin_inset Quotes erd
4109 \begin_inset Quotes eld
4117 \begin_inset Quotes erd
4123 \begin_layout Enumerate
4124 Do not worry about where the file goes.
4125 The CVS maintainers will locate all documentation and Style Sheet Supplements
4126 in an appropriate place.
4129 \begin_layout Enumerate
4130 Document Properties:
4134 \begin_layout Itemize
4135 For consistency, use the same document class and other document properties
4140 \begin_layout Standard
4141 Specifically, check the settings in the
4148 Use those in your Supplement.
4156 \begin_layout Itemize
4157 Exceptions: Use margins, indentation/paragraph separation, language, and
4158 encoding appropriate for your language.
4162 \begin_layout Enumerate
4163 The title of the Supplement:
4167 \begin_layout Itemize
4168 The title will use the
4169 \begin_inset Quotes eld
4177 \begin_inset Quotes erd
4180 paragraph environment.
4181 In your native tongue, the title will read:
4185 \begin_layout Standard
4188 Documentation Project Style Sheet:
4190 Supplement for the <foo> Translation Project
4193 \begin_layout Standard
4195 \begin_inset Quotes eld
4203 \begin_inset Quotes erd
4206 with the name of your language.)
4210 \begin_layout Itemize
4211 If, in your language,
4212 \begin_inset Quotes eld
4216 \begin_inset Quotes erd
4220 \begin_inset Quotes eld
4224 \begin_inset Quotes erd
4229 \begin_inset Quotes eld
4233 \begin_inset Quotes erd
4237 \begin_inset Quotes eld
4241 \begin_inset Quotes erd
4244 have somewhat different meanings.
4245 An appendix is an extra part of a document.
4246 A supplement is an extra document.
4251 \begin_layout Standard
4252 Choose a replacement word accordingly.
4253 Whatever you choose to replace
4254 \begin_inset Quotes eld
4258 \begin_inset Quotes erd
4261 it must not have the same translation as the word
4262 \begin_inset Quotes eld
4266 \begin_inset Quotes erd
4274 \begin_layout Enumerate
4275 Below the title, in the
4276 \begin_inset Quotes eld
4284 \begin_inset Quotes erd
4287 paragraph environment, place your name.
4291 \begin_layout Standard
4292 There will be no abstract.
4296 \begin_layout Enumerate
4307 \begin_layout Standard
4308 The first thing you will do is strongly yet politely encourage the reader
4310 \begin_inset Quotes eld
4314 \begin_inset Quotes erd
4317 and go read the Style Sheet.
4318 The reader should not return to the
4319 \begin_inset Quotes eld
4323 \begin_inset Quotes erd
4332 understood the Style Sheet proper.
4336 \begin_layout Subsubsection
4337 Keep the Supplement Succinct
4340 \begin_layout Standard
4341 This Style Sheet is already very detailed.
4342 DocTeam members all have a lot to read.
4343 We don't want to place an extra burden on translators.
4344 Therefore, keep the Supplement as short as you can without losing information.
4347 \begin_layout Subsubsection
4351 \begin_layout Standard
4358 will be about font issues\SpecialChar \ldots{}
4360 Not all Translation Project Chiefs will need to deal with this issue.
4364 \begin_layout Itemize
4370 \begin_layout Itemize
4376 \begin_layout Itemize
4381 Emphasized (actually Italics)
4384 \begin_layout Itemize
4390 \begin_layout Itemize
4396 \begin_layout Itemize
4399 Noun (actually Small Caps)
4402 \begin_layout Standard
4403 \SpecialChar \ldots{}
4404 certainly exist for all languages that use the Roman alphabet.
4405 Do they exist, however, for Greek? How about Cyrillic? These different
4406 fonts almost certainly do not exist for Devanagri, Chinese, Korean, Japanese,
4407 Hebrew, Arabic, and other scripts.
4411 \begin_layout Standard
4412 There will be some languages for which following the font-scheme specified
4413 in this Style Sheet may not be possible.
4414 If you are the Translation Project Chief for such a language, you have
4418 \begin_layout Standard
4419 In the font section of the Supplement, you will provide a new typographic
4420 style, designed specifically for your writing system.
4421 For consistency, the title of this section in every Supplement should translate
4423 \begin_inset Quotes eld
4427 \begin_inset Quotes erd
4430 Before adding anything to this section, however, determine what this new
4431 typographic style will look like.
4432 Stick to the font specifications in this Style Sheet as best you can, whenever
4434 When you cannot, use the following suggestions:
4437 \begin_layout Itemize
4439 \begin_inset Quotes eld
4443 \begin_inset Quotes erd
4450 What to do when a font doesn't exist:
4455 \labelwidthstring MMMMMMMM
4456 Roman Use the font that typesetters in your language use for printing books,
4458 This will typically be the default font LyX (and LaTeX) uses in your language.
4462 \labelwidthstring MMMMMMMM
4468 This is for people's names.
4469 If there is special font for names in your alphabet/writing system, use
4470 it in place of this.
4471 Otherwise, write names in the default font, typeset according to the rules
4476 \labelwidthstring MMMMMMMM
4481 Use the font with which your language normally emphasizes text.
4485 \begin_layout Standard
4486 Use a font that is different from your language's equivalent of
4493 In other words, your
4505 and similar headers will be in one typeface, perhaps
4512 Whatever that font is, avoid using it for
4523 \labelwidthstring MMMMMMMM
4528 Pick up a computer program manual written in your language.
4529 It will use a special typeface for filenames, for command names, program
4531 Use that same font in place of
4541 \labelwidthstring MMMMMMMM
4547 Pick any other font that is different from the ones you're using in place
4567 If you're unlucky, and your language's writing system doesn't have enough
4568 fonts, use the same font you picked to replace
4575 Only do this, however, if your alphabet/writing system has very few fonts
4580 \labelwidthstring MMMMMMMM
4586 nderlined\InsetSpace ~
4590 Don't worry about this one.
4594 \begin_layout Standard
4595 If you use some special font on-screen to highlight the accelerator keys
4596 for menus, buttons, and other widgets, you might want to mimic that in
4598 It is not required, however.
4599 Therefore, if you can't mimic this typographic convention in your native
4600 writing system, don't.
4605 \begin_layout Standard
4606 Note that you may also want to describe fonts that your Translation Team
4614 For example, no contributer to the English/European versions may ever use
4621 , as this is used for section-headings.
4622 Since there are enough other fonts, we who use the Roman alphabet and its
4623 variants can afford to omit
4633 \begin_layout Standard
4634 Once you have determined which fonts in your native writing system will
4635 replace one or more of the above, propose it to the LyX Developer's Mailing
4637 You may receive valuable feedback this way.
4638 If not, that's okay.
4639 If no one can read your writing system, and therefore cannot comment, that's
4641 Go ahead and describe the typographic standard you created in the Supplement.
4645 \begin_layout Standard
4646 Remember: stick to the font specifications in this Style Sheet as best you
4647 can, whenever you can.
4650 \begin_layout Subsubsection
4651 Quoting Style and the
4667 \begin_layout Standard
4668 The next section of the Supplement will cover the issue of quoting.
4669 Give it an appropriate title.
4672 \begin_layout Standard
4673 One of the first things you should do in that section is resolve the following
4677 \begin_layout Itemize
4690 is the correct paragraph environment for your language.
4693 \begin_layout Itemize
4694 In the Supplement, specify which one to use.
4697 \begin_layout Standard
4698 English has its own typography and style for quoting others.
4699 The Style Sheet describes that typography in section\InsetSpace ~
4701 \begin_inset LatexCommand ref
4702 reference "sec:quote"
4706 Your language also has a specific typography and style for quotations.
4707 Describe that style in this section of the Supplement, too.
4708 Naturally, you do not need to go overboard.
4709 Section\InsetSpace ~
4711 \begin_inset LatexCommand ref
4712 reference "sec:quote"
4715 of this Style Sheet is overly detailed for a good reason.
4716 Authors of the primary LyX manuals are not necessarily native English speakers.
4717 The members of your Translation Team, however, will all likely be native
4718 speakers of your language.
4719 Therefore, discuss proper quoting style of your native tongue to an appropriate
4723 \begin_layout Subsubsection
4724 Translations of Style Sheet Terminology
4727 \begin_layout Standard
4728 In the Supplement, you must provide a standard translation of certain key
4729 phrases for the members of your Translation Team.
4730 Place this in a section following the one about quotations.
4733 \begin_layout Standard
4734 In particular, standardize the translations of the phrases:
4737 \begin_layout Itemize
4743 \begin_layout Itemize
4749 \begin_layout Standard
4756 change the typography of the
4757 \begin_inset Quotes eld
4761 \begin_inset Quotes erd
4765 \begin_inset Quotes eld
4769 \begin_inset Quotes erd
4773 Only provide a translation for the opening phrases.
4774 Insist that the members of your Translation Team use these two tools correctly.
4777 \begin_layout Standard
4778 While we are discussing proper use of the
4779 \begin_inset Quotes eld
4783 \begin_inset Quotes erd
4787 \begin_inset Quotes eld
4791 \begin_inset Quotes erd
4794 in translations, let's talk about a related problem.
4796 \begin_inset Quotes eld
4800 \begin_inset Quotes erd
4803 is meant to be a note from the author of a manual to the reader.
4804 In the case of a translation, however, the translator is
4810 the author! How then should a translator translate an
4811 \begin_inset Quotes eld
4815 \begin_inset Quotes erd
4821 \begin_layout Standard
4822 You, as Translation Project Chief, must decide.
4823 You can forbid translation of pre-existing
4824 \begin_inset Quotes eld
4828 \begin_inset Quotes erd
4831 omitting them entirely instead.
4832 You could tell your translators to read any
4833 \begin_inset Quotes eld
4837 \begin_inset Quotes erd
4840 they may encounter, understand it, then write their own
4841 \begin_inset Quotes eld
4845 \begin_inset Quotes erd
4848 about the situation, not as a translation but as a personal opinion.
4849 You may decide on some other policy.
4852 \begin_layout Standard
4853 Whatever you decide, codify your policy in its own
4866 Place it near the section where you translated
4867 \begin_inset Quotes eld
4871 \begin_inset Quotes erd
4875 \begin_inset Quotes eld
4879 \begin_inset Quotes erd
4885 \begin_layout Subsubsection
4889 \begin_layout Standard
4890 After describing all of the previous issues, create a new
4898 \begin_inset Quotes eld
4901 Lost in Translation,
4902 \begin_inset Quotes erd
4905 or something similar.
4908 \begin_layout Standard
4909 In this section you will discuss any common English metaphors, humor, connotatio
4910 n, or other difficult to translate text.
4911 Try to balance brevity and completeness.
4924 s --- to each specific issue.
4927 \begin_layout Subsubsection
4928 \SpecialChar \ldots{}
4930 \begin_inset Quotes eld
4934 \begin_inset Quotes erd
4937 \SpecialChar \ldots{}
4941 \begin_layout Standard
4942 Throughout the manuals, the DocTeam has used the following sentences:
4946 If you haven't read the <
4950 > manual, go read it.
4954 \begin_layout Standard
4955 This sentence will be tricky to translate, since it contains non-translatable
4963 for this issue in your
4964 \begin_inset Quotes eld
4968 \begin_inset Quotes erd
4973 \begin_inset Quotes eld
4976 \SpecialChar \ldots{}
4977 Yes, we mean now\SpecialChar \ldots{}
4979 \begin_inset Quotes erd
4982 sentences, then present a translation, along with any explanation you feel
4986 \begin_layout Standard
4987 Here's what those two sentences, sitting alone in their own paragraph, mean:
4990 \begin_layout Standard
4991 The first sentence uses the English conditional followed by an imperative.
4992 We, as the LyX team, are commanding the reader to go back to another manual.
4999 manual is a prerequisite for all of the other manuals.
5000 The conditional clause preceeding the command means,
5001 \begin_inset Quotes eld
5004 You do not need to perform this command twice.
5005 \begin_inset Quotes erd
5011 \begin_layout Standard
5012 The second sentence adds force to the command.
5013 Culturally, the imperative tense of a verb in English is not necessarily
5015 The way we wrote that command,
5016 \begin_inset Quotes eld
5020 \begin_inset Quotes erd
5023 is firm, yet polite.
5024 The reader may choose to ignore it.
5026 \begin_inset Quotes eld
5030 \begin_inset Quotes erd
5033 we imply two things.
5035 \begin_inset Quotes eld
5039 \begin_inset Quotes erd
5043 That second sentence reinforces the command, making it a bit harder to
5045 Second, the sentence itself implies a certain sense of urgency.
5046 You cannot merely wait until later to fulfill that command.
5047 The brief pragraph, and its sudden end, add still further subtle reinforcement
5049 \begin_inset Quotes eld
5052 go do the required reading before using this manual.
5053 \begin_inset Quotes erd
5059 \begin_layout Standard
5060 Note that all of this commanding and reinforcing is nevertheless in a polite
5062 Furthermore, it is in a subtle form.
5063 We are commanding the reader to do something, but in an indirect fashion.
5064 This way, the reader does not feel like we are bullying him.
5067 \begin_layout Subsubsection
5072 \begin_layout Standard
5073 In the same part of the Supplement that you place the
5074 \begin_inset Quotes eld
5077 \SpecialChar \ldots{}
5078 Yes, we mean now\SpecialChar \ldots{}
5080 \begin_inset Quotes erd
5083 translation, discuss the English version's use of
5084 \begin_inset Quotes eld
5088 \begin_inset Quotes erd
5094 \begin_layout Standard
5095 You see, here in America, we often say that everything is permitted unless
5096 explicitly banned by law.
5097 As a result, manuals for computer software are frequently ignored and the
5098 software subsequently blamed for not being
5099 \begin_inset Quotes eld
5103 \begin_inset Quotes erd
5106 This is where the use of
5107 \begin_inset Quotes eld
5111 \begin_inset Quotes erd
5118 \begin_layout Standard
5119 We who wrote the manuals added sentences insisting that the reader not ignore
5120 certain parts of the documentation.
5121 We wrote in a manner that was polite, yet firmly asserted that the user
5122 was misusing the software if he did not read the manual correctly.
5123 We did not, however, want to sound threatening, coercive, or bullying.
5126 \begin_layout Standard
5127 In your culture, cajoling the reader into using the manuals correctly may
5129 It may, in fact, be outright rude.
5130 Additionally, translating the firm-but-convincing bits may not work.
5131 The translation may sound weird, or rude, or hostile.
5132 Therefore, you and your translation team will face many sentences that
5133 you cannot translate.
5136 \begin_layout Standard
5137 You, the Translation Project Chief, must discuss this issue.
5138 Try and find parts of the original manuals where some friendly but firm
5139 convincing does not translate properly.
5140 Use these cases as the basis for examples of the problem.
5141 Be sure to then offer a solution (i.\InsetSpace ~
5143 how you want such sentences translated.)
5144 If stumped, ask for help on the LyX Developer's List.
5147 \begin_layout Subsubsection
5151 \begin_layout Standard
5152 You can add more sections to the Supplement if you need to discuss other
5154 There may be policies or guidelines that you want to set for your Translation
5156 Be careful, however! Keep the Supplement