1 #LyX 1.6.0svn created this file. For more info see http://www.lyx.org/
6 \use_default_options false
11 \font_typewriter default
12 \font_default_family default
28 \paperorientation portrait
31 \paragraph_separation indent
33 \quotes_language english
37 \tracking_changes false
45 Documentation Project Style Sheet
52 \begin_layout Abstract
53 This article is a style sheet.
54 It describes, with examples, how the documentation should look and sound.
55 The first few sections explain the font conventions and typography conventions
56 all documentation writers should follow.
57 Those sections also contain examples.
58 It also explains the purpose of each of the different manuals.
59 Follow it not merely to the letter, but also in spirit.
62 \begin_layout Abstract
63 The Style Sheet for LyX documentation (hereafter known as the Style Sheet)
68 forms of LyX documenation, regardless of language.
69 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,
95 ask first, write second!
98 \begin_layout Standard
99 Field all questions to the LyX Developer's Mailing List.
100 There are seasoned DocTeam members who can answer your questions.
101 If you have any problems with the Style Sheet itself, also contact the
105 \begin_layout Section
109 \begin_layout Standard
110 We'll start with the easiest section, yet also the most important.
113 \begin_layout Standard
114 This is how you should fontify text in the manuals:
118 \labelwidthstring MMMMMMMM
123 general emphasis, generic arguments, titles of books, names the other manuals
124 and of their sections, and notes from the authors
128 \begin_layout Standard
129 Do not overemphasize your text.
134 \labelwidthstring MMMMMMMM
139 program names, file names,
143 -page names, LaTeX code, LaTeX commands, LaTeX package names, and LyX code
148 \labelwidthstring MMMMMMMM
157 menu, button, or popup names, the names/lables of all widgets in a popup,
158 the names of keyboard keys, and certain
159 \begin_inset Quotes eld
163 \begin_inset Quotes erd
170 \labelwidthstring MMMMMMMM
183 \labelwidthstring MMMMMMMM
199 Rich Fields added this to mimick the underlining of letters in the menus
201 It helps to highlight the accelerator keys, and human brains store information
202 best when they see it frequently.
206 \begin_layout Description
207 WARNING! --- When you do this, make sure you
211 shut off the underlining.
212 Too many people send in things that look like:
213 \begin_inset Newline newline
223 \begin_inset Newline newline
226 \SpecialChar \ldots{}
235 they not only shut off underlining, they turned off
247 Make sure the entire word is still in
255 after you shut off the underlining.
260 \labelwidthstring MMMMMMMM
269 \begin_layout Standard
270 If you want to emphasize any text, use
275 LaTeX will put many things boldface on its own, such as
279 s, certain parts of equations, et cetera.
282 \begin_layout Standard
283 Repeat: do not use boldface.
287 \begin_layout Standard
288 Here are some examples:
291 \begin_layout Enumerate
296 appears in configuration files and in the LyX source.
297 Therefore, it (and all other LyX function names) count as code and is set
305 \begin_layout Enumerate
317 is a menu item in the
324 menu, so it appears in
348 for the accelerator keys.
351 \begin_layout Enumerate
352 Consider the following excerpt from the introduction of one of the manuals:
356 \begin_layout Quotation
365 both refer to the same key.
366 Some keyboards label the
371 \begin_inset Quotes eld
375 \begin_inset Quotes erd
379 \begin_inset Quotes eld
383 \begin_inset Quotes erd
386 still others have two keys.
387 LyX treats all of them as the same key, so we'll use
398 \begin_layout Standard
399 Notice that the key name,
415 when it references the key itself! When I described how the manufacturer
416 chose to label its keyboard, I used Roman and put the word in quotes.
417 There is a semantic difference.
421 \begin_layout Enumerate
422 Take the following command:
426 \begin_layout Standard
435 \begin_layout Standard
436 Notice that the argument to the
446 This is a case where you don't use
450 for code, because you want the generic argument label to stand out.
451 On the other hand, if you were specifying an argument, for example,
452 \begin_inset Quotes eld
460 \begin_inset Quotes erd
472 \begin_layout Enumerate
473 Any LaTeX commands and code, and any
477 LaTeX package names get set in
483 \begin_inset Quotes eld
491 \begin_inset Quotes erd
494 is the name of an unsupported LaTeX package, but
495 \begin_inset Quotes eld
503 \begin_inset Quotes erd
506 is a supported LaTeX class.
509 \begin_layout Section
513 \begin_layout Standard
514 The canonical keyboard contains these keys:
517 \begin_layout Itemize
529 \begin_layout Itemize
541 \begin_layout Itemize
554 \begin_layout Standard
558 use the abbreviations
564 \begin_layout Itemize
567 F1 F2 F3 F4 F5 F6 F7 F8 F9 F10 F11 F12
571 \begin_layout Standard
573 Most modern keyboards have all 12.
577 \begin_layout Itemize
586 \begin_layout Standard
588 \begin_inset Quotes eld
592 \begin_inset Quotes erd
599 \begin_layout Itemize
626 \begin_layout Standard
627 These are the 6 keys that appear above the cursor keys on many PC keyboards.
628 Consider them as part of the standard motion keys.
632 \begin_layout Itemize
639 \begin_layout Standard
640 The four standard motion keys.
641 There is no need to put the word
642 \begin_inset Quotes eld
646 \begin_inset Quotes erd
649 anywhere, since that's obvious.
653 \begin_layout Plain Layout
655 \begin_inset Quotes eld
659 \begin_inset Quotes erd
664 \begin_inset Quotes eld
668 \begin_inset Quotes erd
671 after one of these may be redundant in certain situations.
680 \begin_layout Itemize
693 \begin_layout Standard
694 I won't throw a hissy fit if you use one instead of the other.
695 I'd prefer if you used
703 , but it's okay if you slip up and forget.
704 Since these two keys are bound to the same function in LyX, it doesn't
709 \begin_layout Standard
710 You do not need to explain everywhere what the
719 The user isn't stupid.
720 Also, someone will document anything that isn't clear (e.
737 problem) someplace in the introduction.
738 No need for you to repeat someone else's work.
741 \begin_layout Standard
742 LyX does not support keyboards missing any of the keys described above,
744 LyX can support a keyboard missing
753 There is a keyboard accelerator for
757 , but this is the only function key LyX assumes exists.
758 Nevertheless, these details are of minor, if any, concern for the documentation.
759 Assume the aforementioned keys exist.
762 \begin_layout Section
766 \begin_layout Standard
768 \begin_inset Quotes eld
772 \begin_inset Quotes erd
775 and any description of the 3 mouse buttons have no special handling.
776 Don't typeset them in any other font than the default, which is Roman.
780 \begin_layout Standard
781 Exception: you're writing an Author's Note (see section
782 \begin_inset CommandInset ref
784 reference "sec:author-notes"
788 ) and you need to mention something about the mouse.
789 Since the rest of the note is in
793 , your description of
794 \begin_inset Quotes eld
798 \begin_inset Quotes erd
801 should be emphasized, as well.
802 There are a couple of other cases like this one; use your judgement.
805 \begin_layout Standard
806 There are only 3 mouse buttons.
807 The use of them and of the mouse itself is obvious.
808 There are few --- if any --- nonstandard things we do with the mouse.
809 Therefore, there's no need to make the word
810 \begin_inset Quotes eld
814 \begin_inset Quotes erd
818 \begin_inset Quotes eld
822 \begin_inset Quotes erd
828 \begin_layout Section
832 \begin_layout Standard
836 \begin_layout Description
849 between the words for menu and widget names.
871 \begin_layout Standard
872 This holds for things in
885 If you have a long code example, one that can't simply be inlined and put
901 \begin_layout Standard
910 so that the name doesn't get split between two lines, which is visually
920 is near the end of a line and overflows the margin, use a
926 in that parargraph (consult a LaTeX book for more about
927 \begin_inset Quotes eld
937 \begin_inset Quotes erd
940 ) or manually add a hypenation point.
944 \begin_layout Description
949 Terms These are things like the following:
953 \begin_layout Itemize
961 \begin_layout Itemize
969 \begin_layout Itemize
979 \begin_layout Itemize
990 \begin_layout Standard
999 font and, in the case of
1007 , capitalize the first two letters.
1010 \begin_layout Standard
1011 Why are these terms special? They are concepts which the seasoned LaTeX-pert
1012 is familiar with, but which the new LyX user is not.
1013 I want them to stand out from the rest of the text, hence the use of
1016 \begin_inset space ~
1026 \begin_layout Standard
1027 Seasoned LyX Team Members: Are there other terms that require this special
1028 status? On the other hand, should we eliminate this style completely?
1031 \begin_layout Description
1032 Terminology Note the following:
1035 \begin_layout Itemize
1036 \begin_inset Quotes eld
1040 \begin_inset Quotes erd
1044 \begin_inset Quotes eld
1048 \begin_inset Quotes erd
1052 \begin_inset Quotes eld
1056 \begin_inset Quotes erd
1061 \begin_inset Quotes eld
1065 \begin_inset Quotes erd
1069 \begin_inset Quotes eld
1073 \begin_inset Quotes erd
1079 \begin_layout Itemize
1080 PostScript® is a registered trademark of Adobe Corp.
1083 You must put the ® after it or we'll get sued!
1085 I also want it written as seen here, always capitalized.
1087 \begin_inset Quotes eld
1091 \begin_inset Quotes erd
1095 \begin_inset Quotes eld
1099 \begin_inset Quotes erd
1103 \begin_inset Quotes eld
1107 \begin_inset Quotes erd
1110 - both of them capitalized, in the default font (i.
1111 \begin_inset space ~
1115 \begin_inset space ~
1119 If you must, cut and paste it from here.
1123 \begin_layout Standard
1124 I am going to say this again:
1127 \begin_layout Standard
1128 \begin_inset VSpace 0.37cm
1134 \begin_layout Standard
1139 You must put the ® after PostScript® or we'll get sued!
1142 \begin_layout Standard
1143 \begin_inset VSpace 0.51cm
1149 \begin_layout Standard
1150 I mean it! American companies like to sue anything that moves.
1155 by forgetting that ®.
1161 \begin_layout Itemize
1162 Similarly, if you use any other registered trademark in any documentation,
1163 put the ® after it, too.
1166 \begin_layout Description
1168 \begin_inset space ~
1171 Items When quick-referencing an item in a menu, use the menu separator:
1173 \begin_inset Quotes eld
1176 \SpecialChar \menuseparator
1178 \begin_inset Quotes erd
1184 File\SpecialChar \menuseparator
1188 Notice that there are
1193 \begin_inset Quotes eld
1196 \SpecialChar \menuseparator
1198 \begin_inset Quotes erd
1204 \begin_inset space ~
1209 , just like the menu and item names.
1213 \begin_layout Enumerate
1214 The reason why I want no spaces around the
1215 \begin_inset Quotes eld
1218 \SpecialChar \menuseparator
1220 \begin_inset Quotes erd
1223 is to prevent LyX from splitting terms across lines.
1224 The same goes for using
1227 \begin_inset space ~
1232 s between multi-word terms.
1233 The split would be visually disruptive.
1236 \begin_layout Enumerate
1238 \begin_inset Quotes eld
1241 \SpecialChar \menuseparator
1243 \begin_inset Quotes erd
1246 goes between menu names and item names
1251 (Yes, submenus are okay, too).
1254 \begin_layout Enumerate
1260 \begin_inset Quotes eld
1263 \SpecialChar \menuseparator
1265 \begin_inset Quotes erd
1268 between menu items and dialog names.
1270 \begin_inset Quotes eld
1278 ayout\SpecialChar \menuseparator
1283 per\SpecialChar \menuseparator
1285 \begin_inset space ~
1291 \begin_inset Quotes erd
1296 IS STRICTLY FORBIDDEN!
1302 \begin_layout Standard
1308 \begin_inset Quotes eld
1311 \SpecialChar \menuseparator
1313 \begin_inset Quotes erd
1316 between popup names and any dialog.
1318 \begin_inset Quotes eld
1324 \begin_inset space ~
1327 Dialog\SpecialChar \menuseparator
1335 \begin_inset Quotes erd
1340 IS STRICTLY FORBIDDEN!
1343 \begin_layout Standard
1349 \begin_inset Quotes eld
1352 \SpecialChar \menuseparator
1354 \begin_inset Quotes erd
1357 between menu items and any dialog.
1359 \begin_inset Quotes eld
1367 ayout\SpecialChar \menuseparator
1372 per\SpecialChar \menuseparator
1380 \begin_inset Quotes erd
1385 IS STRICTLY FORBIDDEN!
1388 \begin_layout Standard
1389 Either write out the description, or use context to eliminate any need to
1390 repeat menu items, dialog names, etc.
1395 \begin_layout Description
1397 \begin_inset space ~
1400 Boxes LyX has a feature for adding comments that appear only within the
1403 \begin_inset Note Note
1406 \begin_layout Plain Layout
1407 These should NEVER appear in the manuals.
1413 You will see nothing in a printout of the Style Sheet.
1414 Therefore, they have no place in the manuals.
1420 \begin_layout Standard
1421 If you have a parenthetical comment you want to make, the reader should
1422 see it too, even in the printed version.
1423 Use an Author's Note (see section
1424 \begin_inset CommandInset ref
1426 reference "sec:author-notes"
1430 ) in place of the Note-Boxes.
1434 \begin_layout Description
1435 \begin_inset Quotes eld
1438 (\SpecialChar \ldots{}
1440 \begin_inset Quotes erd
1444 \begin_inset space ~
1448 \begin_inset Quotes eld
1451 [\SpecialChar \ldots{}
1453 \begin_inset Quotes erd
1457 \begin_inset space ~
1461 \begin_inset space ~
1465 \begin_inset Quotes eld
1468 {\SpecialChar \ldots{}
1470 \begin_inset Quotes erd
1473 I have recently been corrected about the use of parentheses.
1474 Standard English typesetting uses the normal parentheses,
1475 \begin_inset Quotes eld
1478 (\SpecialChar \ldots{}
1480 \begin_inset Quotes erd
1483 , around any aside, remark, or parenthetical expression.
1485 \begin_inset Quotes eld
1488 [\SpecialChar \ldots{}
1490 \begin_inset Quotes erd
1493 , is used only within quotations (see section
1494 \begin_inset space ~
1498 \begin_inset CommandInset ref
1500 reference "sec:quote"
1506 \begin_inset Quotes eld
1509 {\SpecialChar \ldots{}
1511 \begin_inset Quotes erd
1515 Therefore, never use
1516 \begin_inset Quotes eld
1519 [\SpecialChar \ldots{}
1521 \begin_inset Quotes erd
1525 \begin_inset Quotes eld
1528 {\SpecialChar \ldots{}
1530 \begin_inset Quotes erd
1533 unless otherwise specified by this Style Sheet.
1536 \begin_layout Description
1537 Dashes: Be sure to use the correct one.
1539 \begin_inset Quotes eld
1547 \begin_inset Quotes erd
1550 character is not a dash, it's a hyphen.
1551 Use it only as a hyphen.
1556 \begin_layout Standard
1558 \begin_inset Quotes eld
1562 \begin_inset Quotes erd
1566 \begin_inset Quotes eld
1570 \begin_inset Quotes erd
1574 \begin_inset Quotes eld
1582 \begin_inset Quotes erd
1585 characters form the en-dash.
1587 \begin_inset Quotes eld
1595 \begin_inset Quotes erd
1598 characters create an em-dash, which is slightly longer than the en-dash.
1599 In the printed version of any document, LyX will combine the two or three
1601 \begin_inset Quotes eld
1609 \begin_inset Quotes erd
1612 characters into a single, unbroken line.
1616 \begin_layout Section
1617 Cross-References and Labels
1620 \begin_layout Standard
1621 Use the following labelling conventions:
1625 \labelwidthstring 00.00.0000
1626 sec:xxx Use this for
1646 \labelwidthstring 00.00.0000
1647 eqn:xxx Use this for Equations, should you need to create any.
1651 \labelwidthstring 00.00.0000
1652 tbl:xxxx Use this for tables inside of a table float.
1656 \labelwidthstring 00.00.0000
1657 fig:xxx Use this for figures inside of figure floats.
1660 \begin_layout Standard
1661 Additionally, you should put the label at one of two locations:
1664 \begin_layout Enumerate
1667 beginning of the paragraph
1669 , after a section heading, or at the beginning of captions, etc.
1670 It should be the first thing on the first line.
1671 Don't put a space betweeen it and the first word.
1674 \begin_layout Enumerate
1675 If there is no paragraph after a section heading, put it at the
1677 end of the last line.
1684 \begin_layout Standard
1689 which is immediately followed by a
1694 This is a case where you need to put the label at the end of the
1699 I know it looks ugly; not much we can do about that, though.
1703 \begin_layout Section
1704 Content --- What Goes Where
1707 \begin_layout Standard
1712 important to anyone documenting a new feature.
1713 If you need to add new documentation, pay attention.
1717 \begin_layout Standard
1718 In the dim and distant past, whenever someone wanted to document a new feature
1719 they added, they either wrote a mini-doc and stuck it into the documentation
1720 directory, or they added a new section to the lone manual.
1721 No one paid much attention to organization in those days, either.
1722 The result was a totally bloated, totally unnavigable, and incomplete manual
1723 orbitted by a swarm of tiny, incomplete mini-docs.
1724 I don't want the docs to fall back into that mess.
1727 \begin_layout Standard
1728 With that in mind, I have some instructions for how to keep things organized:
1732 \labelwidthstring 00.00.0000
1737 Please, don't touch this file.
1738 It's essentially complete, anyhow.
1739 Only the editor(s) should make changes to this, as this file contains info
1740 about how to contribute to the doc project.
1741 That's really the only stuff that should need to change, and even then,
1742 only when a new maintainer comes along.
1746 \labelwidthstring 00.00.0000
1751 This file is complete.
1752 Any changes should be for updates
1757 DO NOT ADD new features to here willy-nilly.
1758 Let the editor decide if --- and when --- new sections go in here.
1759 Place any new features in\SpecialChar \ldots{}
1764 \labelwidthstring 00.00.0000
1769 This is where all new features go from now on.
1770 It's in the style of a bound journal --- each section is an
1771 \begin_inset Quotes eld
1775 \begin_inset Quotes erd
1778 from the author of the feature.
1779 Also, anyone who writes a
1783 file for a new document class should write a section describing that new
1784 class and how to use it.
1785 That also goes here.
1789 \begin_layout Standard
1790 Note, however, that you are
1794 excused from following this Style Sheet just because the sections of
1798 are in the form of a journal article.
1803 \labelwidthstring 00.00.0000
1808 This file is complete.
1809 Do not change or add to without permission of the Documenation Project
1814 \labelwidthstring 00.00.0000
1819 This document describes advanced features, most of which alter the look,
1820 feel, and behavior of LyX.
1821 This manual is still a bit incomplete, although that may change soon.
1822 Check for updates often.
1826 \begin_layout Standard
1827 If you are unsure whether or not something belongs in
1831 , then, most-likely, it
1840 Again, let the current editor of the LyX documentation decide if your new
1841 section should be migrated to
1850 \labelwidthstring 00.00.0000
1855 I'd prefer to completely finish this one before doing anything else, but
1857 LyX keeps changing so much that I think the
1861 will be the last one completed.
1862 However, I'd like it if the developer's would add entries anytime they
1863 create a new function or popup.
1864 That would help things immensely!
1868 \begin_layout Standard
1873 follows this Style Sheet for the most part.
1874 There are, however, additional rules to follow when making new entries.
1875 At the top of this manual, there are examples of and a template for
1884 \begin_layout Section
1885 Writing Style: The Primary Manuals
1888 \begin_layout Standard
1889 While I want to make contributing to the Documentation Project as painless
1890 as possible for newcomers, I also want the newcomers to be painless on
1891 the existing Documentation Team! Ergo, I've written this section to give
1892 some flavor to guide everyone's individual style.
1896 \begin_layout Subsection
1900 \begin_layout Standard
1901 All contributions to the
1905 LyX documentation must be in English.
1906 I don't care if it's British, Australian, or American English.
1907 The DocTeam editor will proofread for glaring mistakes and fix them.
1910 \begin_layout Standard
1911 Don't get hung up on semantics.
1912 English is a flexible language, and just because your Mothertongue-to-English
1913 dictionary gives only one translation for a word doesn't necessarily mean
1915 We've had some discussions and misunderstandings on the Developers' List
1916 because of this very problem.
1917 If something is unclear (or just plain weird) due to a translation problem,
1918 one of the American/British/Australian developers can fix it.
1921 \begin_layout Standard
1926 documentation, I exclude the translations.
1927 We usually don't have enough people to cover the manuals in one language,
1928 let alone more than one.
1929 Subsequently, the tranlsations are just that --- translations of the English
1930 version of the LyX manuals.
1931 The translation efforts require have their own set of guidelines.
1933 \begin_inset CommandInset ref
1935 reference "sec:translations"
1942 \begin_layout Subsection
1944 \begin_inset Newline newline
1947 Commentary from the Author (i.
1948 \begin_inset space ~
1954 \begin_layout Standard
1955 \begin_inset CommandInset label
1957 name "sec:author-notes"
1961 I want to make it easy for everyone when it comes to documenting things.
1962 Some features are incomplete.
1963 Some, you might not know everything about.
1964 Sometimes, you may want to comminucate something to me or the reader or
1965 other DocTeam members.
1966 Sometimes, you may want to
1967 \begin_inset Quotes eld
1971 \begin_inset Quotes erd
1974 you want to say something that is your personal opinion and using
1975 \begin_inset Quotes eld
1979 \begin_inset Quotes erd
1982 would be inappropriate.
1985 \begin_layout Standard
1986 In short, when you contribute to the LyX Docs, you wear many hats.
1989 \begin_layout Standard
1990 For occasions when you need to switch hats, I've designed some special mechanism
1994 \begin_layout Subsubsection
1996 \begin_inset space ~
2000 \begin_inset Quotes eld
2004 \begin_inset Quotes erd
2010 \begin_layout Standard
2011 These are footnotes.
2012 They begin with the following:
2023 \begin_layout Standard
2024 \SpecialChar \ldots{}
2029 for the person's name and without the quotes.
2030 The rest of the footnote is the actual comment.
2034 \begin_layout Standard
2035 Use these when you need to quote a comment by someone (usually yourself),
2036 and need to identify that person.
2037 This includes occasions when you need wear the
2038 \begin_inset Quotes eld
2042 \begin_inset Quotes erd
2046 \begin_inset space ~
2050 \begin_inset space ~
2053 to speak for yourself instead of for the LyX Team.
2056 \begin_layout Standard
2057 If the comment is too large to put in a footnote, don't use a Personal Note.
2058 When quoting more than about 3 sentences or 5 lines of text, use a bona
2060 Don't use any leading
2061 \begin_inset Quotes eld
2069 \begin_inset Quotes erd
2073 In a real quote, you'll give credit to the original speaker in either the
2074 paragraph before or after the body of the
2081 \begin_layout Subsubsection
2083 \begin_inset space ~
2087 \begin_inset Quotes eld
2091 \begin_inset Quotes erd
2097 \begin_layout Standard
2098 There will be times when you are not speaking for the LyX Team, yet you
2099 are not entirely speaking for yourself.
2100 Instead, you are speaking on behalf of the manual itself, as the author
2102 Some examples of when you might need to do this are:
2105 \begin_layout Itemize
2106 You need to contradict something you just wrote because the feature isn't
2107 quite ready yet, but you wanted to document what it will do.
2110 \begin_layout Itemize
2111 You need to leave a note for yourself.
2114 \begin_layout Itemize
2115 You need to leave a note for the editor or the other DocTeam members.
2118 \begin_layout Itemize
2119 You need to point out something about the manuals to the reader, something
2120 that doesn't fit into the context of the current paragraph.
2123 \begin_layout Standard
2124 At such times, you are wearing your
2125 \begin_inset Quotes eld
2129 \begin_inset Quotes erd
2135 \begin_layout Standard
2136 The typography for an
2137 \begin_inset Quotes eld
2141 \begin_inset Quotes erd
2147 \begin_layout Itemize
2148 They go in the body of the text, in brackets,
2149 \begin_inset Quotes eld
2153 \begin_inset Quotes erd
2156 , not any other form of parentheses.
2157 The bracket are in the default character style.
2160 \begin_layout Itemize
2161 The text of the note itself, however, is emphasized.
2165 \begin_layout Itemize
2166 Begin with the words,
2167 \begin_inset Quotes eld
2175 \begin_inset Quotes erd
2178 and end with an em-dash,
2179 \begin_inset Quotes eld
2183 \begin_inset Quotes erd
2186 , followed by your initials.
2190 \begin_layout Standard
2191 Here's an example: [
2193 Author's Note: This is an example note.
2199 \begin_layout Standard
2200 The form of the Author's Note, by the way, isn't a suggestion or request.
2206 All Author's Notes must begin with this text, verbatim:
2207 \begin_inset Quotes eld
2215 \begin_inset Quotes erd
2220 \begin_inset Quotes eld
2224 \begin_inset Quotes erd
2227 are or any other variant are forbidden.
2228 The Author's Note must end with an em-dash, which is 3
2229 \begin_inset Quotes eld
2233 \begin_inset Quotes erd
2237 \begin_inset Quotes eld
2241 \begin_inset Quotes erd
2246 \begin_inset Quotes eld
2250 \begin_inset Quotes erd
2253 ; you must use 3 (and 5 is right out).
2256 \begin_layout Standard
2257 \begin_inset Quotes eld
2261 \begin_inset Quotes erd
2264 are inherently transient, and should disapear as a manual matures.
2267 \begin_layout Subsubsection
2271 \begin_layout Standard
2272 You are also free to use footnotes on their own in addition to the Personal
2273 Notes and/or Author's Notes.
2274 I've frequently used footnotes to \SpecialChar \ldots{}
2275 well, to comment on parts of a section
2276 without putting the commentary into the body of the text.
2279 \begin_layout Paragraph*
2280 Mixing Footnotes and Personal Notes
2283 \begin_layout Standard
2284 Personal Notes always go in footnotes, and should be 5 lines or fewer.
2285 Any larger quotation should be quoted properly, using the rules of standard
2291 paragraph environment.
2294 \begin_layout Paragraph*
2295 Mixing Footnotes and Author's Notes
2298 \begin_layout Standard
2299 Author's Notes should
2307 \begin_layout Paragraph*
2308 Mixing Personal Notes and Author's Notes
2311 \begin_layout Standard
2312 Forbidden; these two are mutually exclusive.
2315 \begin_layout Subsubsection
2319 \begin_layout Itemize
2321 \begin_inset Newline newline
2328 opinion --- yours or another LyX developer's --- about anything.
2329 Anywhere in the manuals you wish to speak for yourself instead the the
2331 If you have a long rant, however, quote yourself (see section
2332 \begin_inset space ~
2336 \begin_inset CommandInset ref
2338 reference "sec:quote"
2345 \begin_layout Itemize
2347 \begin_inset Newline newline
2350 Use this to describe things in LyX (or the manuals) that may change in the
2351 future or are somehow incomplete.
2352 Author's Notes are supposed to disappear as a manual matures.
2355 \begin_layout Itemize
2357 \begin_inset Newline newline
2360 Used for text fragments that almost fit into the flow of the text\SpecialChar \ldots{}
2365 \begin_layout Standard
2366 When using these three mechanisms, in addition to rigorously following their
2367 descriptions, please use them properly.
2368 I listed some additional restrictions previously.
2369 Some of you may balk at these restrictions.
2370 Nevertheless, there is a reason for them: if you have an overwhemling desire
2371 to mix or modify footnotes, Personal Notes, and Author's Notes, you shouldn't
2372 be using any of them.
2373 More specifically, you're trying to use a hammer to drive in a screw.
2374 What you want to say probably needs to go into the main body of the text.
2377 \begin_layout Subsection
2378 General Stylistic Guidelines
2381 \begin_layout Standard
2382 Everything in this section is
2384 mandatory to all documenters
2386 , regardless the language you're writing in.
2390 \begin_layout Subsubsection
2394 \begin_layout Enumerate
2395 Use the typography rules outlined in the beginning sections of this document.
2398 \begin_layout Enumerate
2399 Don't, however, mimic the typography of this file.
2400 Yes, the Style Sheet doesn't follow the Style Sheet (grin).
2403 \begin_layout Enumerate
2404 There is some typographic freedom in those rules in earlier sections.
2405 Use that freedom wisely.
2406 Most importanly, never sacrifice the online appearance for the printed
2407 appearance and vice versa.
2411 \begin_layout Standard
2412 An example is in the
2417 There is a footnote using the
2421 command to divide a long
2425 environment into 3 columns.
2426 It adds some LaTeX commands to the online version, the so-called
2427 \begin_inset Quotes eld
2431 \begin_inset Quotes erd
2434 that some so vehemently oppose.
2435 Without it, however, that footnote takes up over two pages, most of which
2437 This is an example of permitting a little ugliness in the online version
2438 to get the printed version to look right.
2442 \begin_layout Enumerate
2443 When in doubt, compromise.
2447 \begin_layout Standard
2448 When in doubt, use good judgement.
2452 \begin_layout Subsubsection
2456 \begin_layout Enumerate
2458 \begin_inset Quotes eld
2462 \begin_inset Quotes erd
2469 \begin_layout Standard
2470 When you speak, you speak for the entire LyX Team, so use
2471 \begin_inset Quotes eld
2475 \begin_inset Quotes erd
2479 \begin_inset Quotes eld
2483 \begin_inset Quotes erd
2490 \begin_layout Enumerate
2492 \begin_inset Quotes eld
2496 \begin_inset Quotes erd
2503 \begin_layout Standard
2504 Whenever you want to say something to the reader, use
2505 \begin_inset Quotes eld
2509 \begin_inset Quotes erd
2512 not some contorted construction to avoid being too informal.
2517 \begin_layout Enumerate
2519 \begin_inset Quotes eld
2523 \begin_inset Quotes erd
2526 for both the physical pointing object (mouse, joystick, touch pad, track
2527 ball, etc.) and the mouse cursor which the physical object moves about the
2531 \begin_layout Enumerate
2533 \begin_inset Quotes eld
2537 \begin_inset Quotes erd
2540 for the little blinking vertical bar that indicates where text can/will
2544 \begin_layout Enumerate
2545 When in doubt, compromise.
2549 \begin_layout Standard
2550 When in doubt, use good judgement.
2554 \begin_layout Subsubsection
2555 \begin_inset CommandInset label
2561 Quoting Yourself and Others
2564 \begin_layout Standard
2565 In some cases, you'll have something to say, an opinion of yours.
2566 Since this is your opinion, you're not speaking for the LyX Team.
2567 You have so much to say, in fact, that it won't fit into a Personal Note
2568 or an Author's Note.
2569 In these cases you want to quote yourself.
2572 \begin_layout Standard
2573 Any time you wish to quote someone, be it yourself or someone else, there
2574 are standard rules one follows.
2575 Every language has its own rules.
2576 You should follow the rules that apply to the language of the document
2577 to which you are contributing.
2581 \begin_layout Standard
2582 This creates a problem for the primary documentation.
2583 The primary documentation is written in English, yet the contributors come
2584 from many countries.
2585 The quoting rules for English (well, American English, at least) are outlined
2589 \begin_inset space ~
2594 , for your convenience.
2595 Read them if you need to.
2598 \begin_layout Standard
2599 \begin_inset Float figure
2605 \begin_layout Plain Layout
2606 Quoting rules for English:
2609 \begin_layout Itemize
2610 The body of the quote belongs in a
2617 \begin_layout Itemize
2618 The sentences prior to the quote should flow logically and smoothly into
2622 \begin_layout Itemize
2623 The sentences immediately following the quote should continue the flow of
2627 \begin_layout Itemize
2632 credit the original author of the quote in the sentences immediately before
2636 \begin_layout Itemize
2637 Crediting the original author of the quote should not, however, disrupt
2638 the flow of the text.
2641 \begin_layout Itemize
2642 If you omit text from the beginning of the first sentence in the quote,
2643 the quote must start with the text
2644 \begin_inset Quotes eld
2647 [\SpecialChar \ldots{}
2649 \begin_inset Quotes erd
2653 This is an ellipsis in square brackets.
2656 \begin_layout Itemize
2657 If you omit text from the end of the last sentence in the quote, the quote
2658 must end with the text
2659 \begin_inset Quotes eld
2662 [\SpecialChar \ldots{}
2664 \begin_inset Quotes erd
2667 followed by the sentence's punctuation mark.
2670 \begin_layout Itemize
2671 If you omit any text from the middle of the quote, be it whole sentences
2672 or parts of sentences, replace it with the text
2673 \begin_inset Quotes eld
2676 [\SpecialChar \ldots{}
2678 \begin_inset Quotes erd
2684 \begin_layout Itemize
2685 The quote must be grammatically correct.
2690 \begin_layout Itemize
2691 If the original is wrong, you must correct it.
2694 \begin_layout Itemize
2695 If omitting part of the quote
2696 \begin_inset Quotes eld
2700 \begin_inset Quotes erd
2703 it, you must correct the problem.
2706 \begin_layout Itemize
2707 For missing words (e.
2708 \begin_inset space ~
2712 \begin_inset space ~
2716 \begin_inset Quotes eld
2720 \begin_inset Quotes erd
2723 goes missing), place the word in square brackets,
2724 \begin_inset Quotes eld
2727 [\SpecialChar \ldots{}
2729 \begin_inset Quotes erd
2732 and insert in the quote where needed.
2735 \begin_layout Itemize
2736 For mangled word order, correct the mangled text, following it with the
2738 \begin_inset Quotes eld
2742 \begin_inset Quotes erd
2749 \begin_layout Itemize
2750 Spelling in the quote must be correct.
2751 Correct any misspelled words and place the text
2752 \begin_inset Quotes eld
2756 \begin_inset Quotes erd
2759 after the corrected word.
2762 \begin_layout Itemize
2763 Back-to-back bracket blocks merge together.
2765 \begin_inset Quotes eld
2768 [\SpecialChar \ldots{}
2770 \begin_inset Quotes erd
2775 \begin_inset Quotes eld
2778 [\SpecialChar \ldots{}
2780 \begin_inset Quotes erd
2786 \begin_layout Itemize
2787 If you correct the spelling in 2 or more consecutive words, you can get
2789 \begin_inset Quotes eld
2793 \begin_inset Quotes erd
2796 after the last mistake.
2804 \begin_layout Subsubsection
2808 \begin_layout Standard
2809 When describing a new feature or
2816 \begin_layout Enumerate
2827 \begin_inset Quotes eld
2830 Keep It Short and Sweet
2831 \begin_inset Quotes erd
2835 \begin_inset Quotes eld
2838 Keep It Simple, Stupid!
2839 \begin_inset Quotes erd
2846 \begin_layout Itemize
2851 write paragraph after paragraph of verbage.
2855 \begin_layout Itemize
2859 \begin_layout Itemize
2860 Take a look at the manual for a commercial word processor --- it's a fine
2865 to write documentation.
2866 It's all pithy, substanceless verbage, and its
2874 \begin_layout Enumerate
2875 Avoid being pedantic like The Plague!
2878 \begin_layout Enumerate
2879 In the same vein, don't write more than you have to.
2880 You're not working in a vacuum --- refer freely to other parts of the manual
2881 (and other parts of other manuals).
2883 \begin_inset Quotes eld
2886 other part of the manual
2887 \begin_inset Quotes erd
2890 is incomplete or empty, refer to it.
2891 Someone will fill it in eventually.
2894 \begin_layout Enumerate
2895 On the other hand, BE THOROUGH!
2899 \begin_layout Enumerate
2904 , not widgets, not how the source code is organized.
2907 \begin_layout Enumerate
2908 Group by feature, not by widget.
2911 \begin_layout Enumerate
2912 Stay on topic --- one
2925 s and further subdivisions to group things if you're documenting several
2926 related features in a single
2933 \begin_layout Enumerate
2934 Describe EVERYTHING related to that feature, no matter where it is.
2938 \begin_layout Enumerate
2939 Example: Paragraph Indenting.
2940 Several popups control its behavior.
2945 of this: which popups control it, when you use which setting on which popup
2946 to do which operation, et cetera.
2949 \begin_layout Enumerate
2955 \begin_inset Newline newline
2958 I've had people only document one popup --- literally.
2959 This added off-topic information and only described half of the feature,
2960 since other menus, popups, and even unbound functions contained additional
2962 \begin_inset Newline newline
2969 cranky when that happens, because it means
2974 Bad help is worse than no help at all.
2978 \begin_layout Standard
2979 These remarks still hold true: you'll piss of the DocTeam editor if you
2980 do things wrong, because he'll have to fix your mistakes.
2985 \begin_layout Enumerate
2986 Remember, there are people who will reference
2990 section, just as you're referencing someone else's.
2991 You do want what you write to be useful, don't you?
2995 \begin_layout Enumerate
2996 When in doubt, compromise.
3000 \begin_layout Standard
3001 When in doubt, use good judgement.
3005 \begin_layout Subsubsection
3010 Treat the Reader as if She is Stupid
3013 \begin_layout Enumerate
3017 \begin_layout Enumerate
3018 No talking down to the reader.
3021 \begin_layout Enumerate
3022 The reader is smart enough to know what a mouse is.
3025 \begin_layout Enumerate
3026 The reader is smart enough to know how to use a keyboard, including the
3040 (The introduction of most of the manuals takes care of the
3041 \begin_inset Quotes eld
3053 \begin_inset Quotes erd
3056 issue, so you don't need to.)
3059 \begin_layout Enumerate
3060 The reader is smart enough to know that
3061 \begin_inset Quotes eld
3065 \begin_inset Quotes erd
3069 \begin_inset Quotes eld
3072 where the text cursor is sitting right now, in the buffer currently visible.
3073 \begin_inset Quotes erd
3078 (Anything more than the word
3079 \begin_inset Quotes eld
3083 \begin_inset Quotes erd
3086 is, IMO, superfluous and wll be deleted .
3087 So, save yourself the typing, save the editor the cutting, and save the
3088 reader the strain of sifting through extra verbage that adds no content.)
3091 \begin_layout Enumerate
3092 Rule of thumb: the reader is not an imbecile.
3093 The reader is merely lost; point them in the right direction, and they
3094 can take it from there.
3097 \begin_layout Subsection
3098 Tips for the English Version
3101 \begin_layout Standard
3102 \begin_inset CommandInset label
3104 name "sec:english-only"
3108 When contributing to the primary --- i.
3109 \begin_inset space ~
3113 \begin_inset space ~
3116 the English language version --- of the LyX manuals, keep the following
3120 \begin_layout Subsubsection
3121 Write as if You're Talking with a Friend.
3125 \begin_layout Enumerate
3126 Think that way when you write.
3127 Play the dialogue in your mind.
3130 \begin_layout Enumerate
3131 Be as informal as you please (without being rude).
3134 \begin_layout Subsubsection
3135 AVOID the Passive Voice
3138 \begin_layout Enumerate
3140 \begin_inset Quotes eld
3143 It is felt that this name best explains the command's purpose.
3144 \begin_inset Quotes erd
3147 We know full well who wrote the command:
3148 \begin_inset Quotes eld
3151 The LyX Team felt ...
3152 \begin_inset Quotes erd
3156 \begin_inset Quotes eld
3160 \begin_inset Quotes erd
3166 \begin_layout Enumerate
3167 Things don't happen by magic - somebody or something did it.
3168 Only politicians use the passive voice to cover up who did something.
3169 If LyX reformats a paragraph, write,
3170 \begin_inset Quotes eld
3173 LyX reformatted the paragraph.
3174 \begin_inset Quotes erd
3181 makes changes, write,
3182 \begin_inset Quotes eld
3189 changes the document.
3190 \begin_inset Quotes erd
3197 \begin_layout Standard
3198 Rule of thumb: any sentence you can express as,
3199 \begin_inset Quotes eld
3203 \begin_inset Quotes erd
3207 \begin_inset Quotes eld
3211 \begin_inset Quotes erd
3218 \begin_layout Enumerate
3220 We all hear way, way too much garbage English on the TV every day in the
3222 Some people think it makes speech better.
3224 It makes speech baroque, if not outright byzantine.
3225 With a little effort, you can wean yourself off of it.
3228 \begin_layout Enumerate
3231 will make you rewrite
3233 anything in the passive voice.
3234 It's awkward and hard to read.
3237 \begin_layout Enumerate
3238 Note to non-Americans:
3242 \begin_layout Standard
3243 Using passive voice is generally considered bad style in the U.
3244 \begin_inset space ~
3248 \begin_inset space ~
3251 as it is too easy to obfuscate your words with it.
3252 It also bloats sentences, often unnecessarily.
3256 \begin_layout Subsubsection
3261 \begin_layout Standard
3262 In English, there is a grammatical error known as the
3263 \begin_inset Quotes eld
3267 \begin_inset Quotes erd
3270 The classic example of a run-on sentence is 7 clauses strung together with
3272 \begin_inset Quotes eld
3276 \begin_inset Quotes erd
3279 There are, however, less obvious run-on sentences, ones using too many
3280 subordinate clauses.
3281 Such sentences may look elegant because they are complex.
3282 However, they are also extremely difficult to read because they are so
3286 \begin_layout Standard
3287 In general, stick to short sentences in written English.
3288 Getting rid of passive voice (
3289 \begin_inset Quotes eld
3292 \SpecialChar \ldots{}
3293 was done by\SpecialChar \ldots{}
3295 \begin_inset Quotes erd
3298 ) shortens and simplifies them.
3299 Hacking apart sentences with many dependent clauses is another way to shorten
3301 There are ways to do this yet still have a smooth-flowing paragraph.
3304 \begin_layout Standard
3305 While I'm talking about paragraphs, I'll apply the
3306 \begin_inset Quotes eld
3310 \begin_inset Quotes erd
3313 motto to them, as well.
3314 At the time I started with the manuals (and this Style Sheet), I didn't
3315 pay too much attention to paragraph size.
3316 I've since become a big proponent of short paragraphs, with one idea per
3318 While long, flowing, multi-concept paragraphs can be nice in novels, we're
3320 Our goal is rapid information location and comprehension, not a literary
3324 \begin_layout Standard
3325 There is a single exception to the short sentence, short paragraph rule.
3326 Particularly complex ideas may need more
3327 \begin_inset Quotes eld
3331 \begin_inset Quotes erd
3334 However, you shouldn't encounter such complex ideas often when documenting
3336 Try to keep things short, and use your judgement as needed.
3339 \begin_layout Standard
3340 To reiterate, yet again, something I said before:
3344 When in doubt, compromise.
3348 When in doubt, use good judgement.
3351 \begin_layout Standard
3352 Hopefully, you've got the idea (grin).
3355 \begin_layout Section
3359 \begin_layout Subsection
3360 Rules of the Translating Trade
3363 \begin_layout Standard
3364 While translating anything, there are certain
3365 \begin_inset Quotes eld
3369 \begin_inset Quotes erd
3373 They will help you greatly.
3376 \begin_layout Subsubsection
3377 Translate one paragraph at a time.
3380 \begin_layout Standard
3381 Most people translate word by word.
3382 Clearly, you lose all context if you do that.
3383 A word may have multiple meanings.
3384 You can't tell which unless you look at the rest of the sentence.
3387 \begin_layout Standard
3388 There is another level to the context issue, however.
3389 Your dictionary may translate multiple English words the same way.
3390 All those words mean
3395 Each one, however, covers a different shade of meaning, a different mood
3397 It is often difficult to resolve those shades of meaning in the context
3398 of even one sentence.
3399 A paragraph, however, will provide that context.
3402 \begin_layout Subsubsection
3403 You will not translate it correctly on the first try.
3406 \begin_layout Standard
3407 Alright, I admit that you may be able to translate some of the sentences
3409 If you know a language well, you may even understand over half of the text.
3410 Nevertheless, overconfidence can lead you astray.
3411 There will be some sentences, no matter how few, that will simply confound
3415 \begin_layout Standard
3416 It is generally a good idea to make multiple passes over a paragraph you're
3418 Even if you translate the entire paragraph on the first pass, make a second
3420 You'll often improve upon your first attempt.
3423 \begin_layout Subsubsection
3424 When in doubt, write down all of the meanings for a word.
3427 \begin_layout Standard
3428 You can often translate tricky parts of a text using the context of the
3429 surrounding sentences.
3430 So, if you hit a word or phrase you don't know, translate it more than
3432 Picking the most likely translations, summarize them in one to three words
3434 \begin_inset Quotes eld
3438 \begin_inset Quotes erd
3445 \begin_layout Subsubsection
3446 Using context, fix the meanings on the next pass.
3449 \begin_layout Standard
3450 This is where your multiple translations of a single word become useful.
3451 Using the other sentences you translated, you can now translate that mystery--s
3452 entence without reconsulting your dictionary.
3455 \begin_layout Subsubsection
3456 Fix the grammar only after you've finished translating the sentence.
3459 \begin_layout Standard
3460 If there's a mystery phrase in the middle of a sentence, you can't translate
3461 the entire sentence.
3462 Why grammatically rearrange the words you translated already? You may need
3463 to restructure the sentence a second time once you figure out how to translate
3464 that mystery phrase.
3465 Better to wait until you've completely translated the sentence to clean
3467 That way, you do so only once.
3470 \begin_layout Subsubsection
3471 If you can't translate it, skip it and come back to it on the next pass.
3474 \begin_layout Standard
3475 Remember the earlier discussion of context and its immense usefulness? There
3476 is no sin in making multiple passes over a tricky passage.
3479 \begin_layout Subsubsection
3480 Translate the meaning first.
3484 \begin_layout Standard
3485 The information content of the text under translation is the most important
3487 This is especially important for a manual, where the information
3491 important part of the original document.
3492 Lose that, and you lose the very point of performing the translation.
3495 \begin_layout Subsection
3496 Tips for the Translators
3499 \begin_layout Standard
3500 Those of you contributing to a translation of the LyX manuals must follow
3501 a modified set of rules.
3502 The first few rules are analogous to those in section
3503 \begin_inset space ~
3507 \begin_inset CommandInset ref
3509 reference "sec:english-only"
3514 There are additional rules and regulations that follow those first few.
3518 \begin_layout Subsubsection
3519 Write as if you are explaining LyX to a colleague you know well.
3522 \begin_layout Enumerate
3523 Think that way when you write.
3524 Play the dialogue in your mind.
3527 \begin_layout Enumerate
3528 Use a conversational style in your writing.
3529 Pretend you are teaching LyX to a colleague you know well.
3532 \begin_layout Enumerate
3533 Use a style that is polite without being too formal.
3534 If, in your culture, informal language is appropriate to use with a colleague,
3535 use informal speech in the translation of the manual.
3538 \begin_layout Subsubsection
3539 AVOID Snobby, Academic, Specialized, or
3540 \begin_inset Quotes eld
3544 \begin_inset Quotes erd
3551 \begin_layout Standard
3552 In English, the passive voice appears formal, dry, barren.
3553 It also often adds unnecessary complexity.
3554 In other langauges, however, this is not the case.
3555 There is nothing wrong with passive voice, and people use it frequently
3556 in everyday conversation.
3557 Nevertheless, your translation of the LyX manuals must avoid
3558 \begin_inset Quotes eld
3562 \begin_inset Quotes erd
3568 \begin_layout Standard
3569 In Germany, there is a magazine known as
3570 \begin_inset Quotes gld
3574 \begin_inset Quotes grd
3577 The writing in it is so complex, it is extremely difficult for non-native
3578 German speakers to understand.
3579 While sophisticated, the writing style of
3580 \begin_inset Quotes gld
3584 \begin_inset Quotes grd
3587 is not what a German uses in everyday conversation.
3588 Nor is the writing style for a Russian mathematics journal.
3589 Such specialized or overly-sophisticated styles are
3590 \begin_inset Quotes eld
3594 \begin_inset Quotes erd
3597 in the sense that they are seldom used by normal people in everyday speech.
3600 \begin_layout Standard
3601 We who write the LyX manuals, original or translated, seek to
3606 If we write in a style only a few people use, and use seldomly, we will
3608 Use a writing style that mirrors everyday speech (without being vulgar,
3613 \begin_layout Subsubsection
3614 Keep the Writing Simple.
3617 \begin_layout Standard
3618 For the English version, I wrote,
3619 \begin_inset Quotes eld
3622 Use short sentences and short paragraphs.
3623 \begin_inset Quotes erd
3626 What if, however, short sentences and paragraphs are something only children
3627 use in your language? What if, in yet another language, short sentences
3628 imply rudeness? Naturally, you would not want to use them in your translation.
3631 \begin_layout Standard
3632 Nevertheless, the translations of the LyX manuals should be as clear as
3634 So, for our international colleagues, we apply this rule: Keep your sentences
3635 and paragraphs as short as makes sense.
3638 \begin_layout Standard
3639 Remember: we're translating manuals here, folks.
3640 Our goal is rapid information location and comprehension, not a literary
3642 Try to keep your writing concise yet smooth-flowing.
3643 And use your judgement as needed:
3647 When in doubt, compromise.
3651 When in doubt, use good judgement.
3654 \begin_layout Subsubsection
3655 Translators must follow the Style Sheet, too!
3658 \begin_layout Standard
3659 Everything in this manual ---
3662 \begin_inset space ~
3666 \begin_inset CommandInset ref
3668 reference "sec:english-only"
3674 --- applies to every LyX documenter, no matter what the language.
3677 \begin_layout Subsubsection
3678 Translators must read the Style Sheet Supplement for their language.
3681 \begin_layout Standard
3682 For every translation project, there is a Supplement to the Style Sheet.
3689 DocStyle_Supplement_<cn>.lyx
3692 \begin_layout Standard
3693 \SpecialChar \ldots{}
3695 \begin_inset Quotes eld
3703 \begin_inset Quotes erd
3706 is your language's two-letter locale code.
3707 The Translation Project Chief for your language wrote this.
3708 If he hasn't, pester him to do so! <
3715 \begin_layout Subsubsection
3716 The English versions of the manuals are not Sacred Text.
3719 \begin_layout Standard
3720 You do not need to translate everything word for word.
3721 In fact, you shouldn't.
3722 Keep to the spirit of the originals, not the letter.
3723 Be as creative as you want, as long as you
3731 convey all of the information contained in the English versions.
3734 \begin_layout Subsubsection
3735 Any information in the LyX manuals must also be in the translations.
3738 \begin_layout Standard
3739 \begin_inset CommandInset label
3745 This falls under translating the orignals accurately and completely.
3749 \begin_layout Itemize
3750 Omitting any feature description is
3757 \begin_layout Itemize
3758 Misrepresenting or misdescribing any LyX feature or operation
3765 \begin_layout Itemize
3770 outpace the original.
3771 \begin_inset Newline newline
3774 If no one has documented new feature in the primary LyX manuals (i.
3775 \begin_inset space ~
3779 \begin_inset space ~
3782 the English versions), do not do so in the translations.
3783 If you're really looking for something to do, either:
3787 \begin_layout Itemize
3788 \SpecialChar \ldots{}
3789 focus on translating something you haven't yet,
3790 \begin_inset Newline newline
3796 \begin_layout Itemize
3797 \SpecialChar \ldots{}
3798 update or repair the primary manual.
3801 \begin_layout Standard
3802 If you cannot or do not want to do one of the above, then take a break.
3804 Wait for the main manuals to catch up before translating anything else.
3808 \begin_layout Subsubsection
3809 What you cannot translate, you may omit (usually).
3812 \begin_layout Standard
3813 Prepositions, idioms, metaphors, slang, Oh My! There's a jungle of potentially
3814 untranslatable text you may face.
3815 Happily, none of these untranslatables are essential to the original text\SpecialChar \ldots{}
3818 If you can't translate a phrase or two, try omitting them.
3819 If the rest of the paragraph still makes sense, then don't worry about
3823 \begin_layout Standard
3824 There may be special cases where omitting part of a sentence or paragraph
3826 \begin_inset space ~
3830 \begin_inset CommandInset ref
3832 reference "sec:accuracy"
3841 You must try and translate those tricky spots.
3844 \begin_layout Subsubsection
3845 Translators may add their own fluff to the information content.
3848 \begin_layout Standard
3849 After you do strip away all of the idioms, metaphors, slang, humor, and
3851 \begin_inset Quotes eld
3855 \begin_inset Quotes erd
3858 you may find that your translated manual is dull and dry.
3859 Why not add your own fluff? Add text that makes the manual a pleasure to
3860 read, that engages the reader.
3861 It may take the form of humor, or metaphors, or sayings.
3862 Whatever you add, it should be
3863 \begin_inset Quotes eld
3867 \begin_inset Quotes erd
3870 It should not clash with the explanation of LyX features and functions.
3873 \begin_layout Subsection
3874 For Translation Project Chiefs
3877 \begin_layout Subsubsection
3878 The First Is In Charge
3881 \begin_layout Standard
3882 If you were the first person to start translating the manuals, you're the
3883 LyXDoc Translation Project Chief for your language.
3888 person translating the LyXDocs, that automatically makes you the Translation
3892 \begin_layout Standard
3893 Amongst other things, that means that you must read this section and perform
3894 the tasks described here.
3897 \begin_layout Standard
3898 If you are a member of a LyX Documentation Translation Team, but
3902 its Chief, you may stop reading.
3903 The remainder of this section will be of no interest to you.
3904 If you came to the Style Sheet from the Supplement for your language, you
3908 \begin_layout Standard
3909 If you have not read the Style Sheet Supplement for your language, you should
3914 \begin_layout Subsubsection
3915 Read the Style Sheet
3918 \begin_layout Standard
3919 No documenter is excused from following the Style Sheet, not even a Translation
3923 \begin_layout Standard
3928 important that the Translation Project Chiefs read the Style Sheet.
3931 \begin_layout Subsubsection
3932 Make your translators read the Style Sheet
3935 \begin_layout Standard
3936 No documenter is excused from following the Style Sheet.
3939 \begin_layout Standard
3940 Since your translation team is translating, they know
3945 Therefore, they should be able to read the Style Sheet.
3948 \begin_layout Subsubsection
3950 \begin_inset Quotes eld
3954 \begin_inset Quotes erd
3960 \begin_layout Standard
3961 There are parts of this Style Sheet that are English-specific.
3962 I have tried to provide a general, language-independent description of
3963 certain details in this section.
3964 Unfortunately, that general description doesn't cover the specifics of
3969 \begin_layout Standard
3970 That's where you, as head of a LyXDoc Translation Team, come in.
3973 \begin_layout Standard
3974 Every Translation Team Chief is
3978 to write a Supplement to the official Documentation Style Sheet, with specifics
3979 issues affecting your language.
3980 (You are, after all, the LyX Team expert on your native tongue.) Follow
3981 these guidelines when writing the Supplement:
3984 \begin_layout Enumerate
3986 \begin_inset Newline newline
3991 DocStyle_Supplement_<cn>.lyx
3994 \begin_inset Newline newline
3997 \SpecialChar \ldots{}
3999 \begin_inset Quotes eld
4007 \begin_inset Quotes erd
4010 is the two-letter code for your language.
4011 This is the same two-letter code that is part of the filenames for the
4014 \begin_inset Quotes eld
4022 \begin_inset Quotes erd
4026 \begin_inset Quotes eld
4034 \begin_inset Quotes erd
4038 \begin_inset Quotes eld
4046 \begin_inset Quotes erd
4052 \begin_layout Enumerate
4053 Do not worry about where the file goes.
4054 The CVS maintainers will locate all documentation and Style Sheet Supplements
4055 in an appropriate place.
4058 \begin_layout Enumerate
4059 Document Properties:
4063 \begin_layout Itemize
4064 For consistency, use the same document class and other document properties
4069 \begin_layout Plain Layout
4070 Specifically, check the settings in the
4075 Use those in your Supplement.
4083 \begin_layout Itemize
4084 Exceptions: Use margins, indentation/paragraph separation, language, and
4085 encoding appropriate for your language.
4089 \begin_layout Enumerate
4090 The title of the Supplement:
4094 \begin_layout Itemize
4095 The title will use the
4096 \begin_inset Quotes eld
4104 \begin_inset Quotes erd
4107 paragraph environment.
4108 In your native tongue, the title will read:
4112 \begin_layout Standard
4115 Documentation Project Style Sheet:
4116 \begin_inset Newline newline
4119 Supplement for the <foo> Translation Project
4122 \begin_layout Standard
4124 \begin_inset Quotes eld
4132 \begin_inset Quotes erd
4135 with the name of your language.)
4139 \begin_layout Itemize
4140 If, in your language,
4141 \begin_inset Quotes eld
4145 \begin_inset Quotes erd
4149 \begin_inset Quotes eld
4153 \begin_inset Quotes erd
4158 \begin_inset Quotes eld
4162 \begin_inset Quotes erd
4166 \begin_inset Quotes eld
4170 \begin_inset Quotes erd
4173 have somewhat different meanings.
4174 An appendix is an extra part of a document.
4175 A supplement is an extra document.
4180 \begin_layout Standard
4181 Choose a replacement word accordingly.
4182 Whatever you choose to replace
4183 \begin_inset Quotes eld
4187 \begin_inset Quotes erd
4190 it must not have the same translation as the word
4191 \begin_inset Quotes eld
4195 \begin_inset Quotes erd
4203 \begin_layout Enumerate
4204 Below the title, in the
4205 \begin_inset Quotes eld
4213 \begin_inset Quotes erd
4216 paragraph environment, place your name.
4220 \begin_layout Standard
4221 There will be no abstract.
4225 \begin_layout Enumerate
4234 \begin_layout Standard
4235 The first thing you will do is strongly yet politely encourage the reader
4237 \begin_inset Quotes eld
4241 \begin_inset Quotes erd
4244 and go read the Style Sheet.
4245 The reader should not return to the
4246 \begin_inset Quotes eld
4250 \begin_inset Quotes erd
4257 understood the Style Sheet proper.
4261 \begin_layout Subsubsection
4262 Keep the Supplement Succinct
4265 \begin_layout Standard
4266 This Style Sheet is already very detailed.
4267 DocTeam members all have a lot to read.
4268 We don't want to place an extra burden on translators.
4269 Therefore, keep the Supplement as short as you can without losing information.
4272 \begin_layout Subsubsection
4276 \begin_layout Standard
4281 will be about font issues\SpecialChar \ldots{}
4283 Not all Translation Project Chiefs will need to deal with this issue.
4287 \begin_layout Itemize
4293 \begin_layout Itemize
4299 \begin_layout Itemize
4301 \begin_inset Newline newline
4306 Emphasized (actually Italics)
4309 \begin_layout Itemize
4315 \begin_layout Itemize
4321 \begin_layout Itemize
4324 Noun (actually Small Caps)
4327 \begin_layout Standard
4328 \SpecialChar \ldots{}
4329 certainly exist for all languages that use the Roman alphabet.
4330 Do they exist, however, for Greek? How about Cyrillic? These different
4331 fonts almost certainly do not exist for Devanagri, Chinese, Korean, Japanese,
4332 Hebrew, Arabic, and other scripts.
4336 \begin_layout Standard
4337 There will be some languages for which following the font-scheme specified
4338 in this Style Sheet may not be possible.
4339 If you are the Translation Project Chief for such a language, you have
4343 \begin_layout Standard
4344 In the font section of the Supplement, you will provide a new typographic
4345 style, designed specifically for your writing system.
4346 For consistency, the title of this section in every Supplement should translate
4348 \begin_inset Quotes eld
4352 \begin_inset Quotes erd
4355 Before adding anything to this section, however, determine what this new
4356 typographic style will look like.
4357 Stick to the font specifications in this Style Sheet as best you can, whenever
4359 When you cannot, use the following suggestions:
4362 \begin_layout Itemize
4364 \begin_inset Quotes eld
4368 \begin_inset Quotes erd
4372 \begin_inset Newline newline
4376 \begin_inset Newline newline
4379 What to do when a font doesn't exist:
4384 \labelwidthstring MMMMMMMM
4385 Roman Use the font that typesetters in your language use for printing books,
4387 This will typically be the default font LyX (and LaTeX) uses in your language.
4391 \labelwidthstring MMMMMMMM
4395 \begin_inset space ~
4400 This is for people's names.
4401 If there is special font for names in your alphabet/writing system, use
4402 it in place of this.
4403 Otherwise, write names in the default font, typeset according to the rules
4408 \labelwidthstring MMMMMMMM
4413 Use the font with which your language normally emphasizes text.
4417 \begin_layout Standard
4418 Use a font that is different from your language's equivalent of
4423 In other words, your
4431 and similar headers will be in one typeface, perhaps
4436 Whatever that font is, avoid using it for
4445 \labelwidthstring MMMMMMMM
4450 Pick up a computer program manual written in your language.
4451 It will use a special typeface for filenames, for command names, program
4453 Use that same font in place of
4461 \labelwidthstring MMMMMMMM
4465 \begin_inset space ~
4470 Pick any other font that is different from the ones you're using in place
4484 If you're unlucky, and your language's writing system doesn't have enough
4485 fonts, use the same font you picked to replace
4490 Only do this, however, if your alphabet/writing system has very few fonts
4495 \labelwidthstring MMMMMMMM
4502 \begin_inset space ~
4506 \begin_inset space ~
4511 Don't worry about this one.
4515 \begin_layout Standard
4516 If you use some special font on-screen to highlight the accelerator keys
4517 for menus, buttons, and other widgets, you might want to mimic that in
4519 It is not required, however.
4520 Therefore, if you can't mimic this typographic convention in your native
4521 writing system, don't.
4526 \begin_layout Standard
4527 Note that you may also want to describe fonts that your Translation Team
4533 For example, no contributer to the English/European versions may ever use
4538 , as this is used for section-headings.
4539 Since there are enough other fonts, we who use the Roman alphabet and its
4540 variants can afford to omit
4548 \begin_layout Standard
4549 Once you have determined which fonts in your native writing system will
4550 replace one or more of the above, propose it to the LyX Developer's Mailing
4552 You may receive valuable feedback this way.
4553 If not, that's okay.
4554 If no one can read your writing system, and therefore cannot comment, that's
4556 Go ahead and describe the typographic standard you created in the Supplement.
4560 \begin_layout Standard
4561 Remember: stick to the font specifications in this Style Sheet as best you
4562 can, whenever you can.
4565 \begin_layout Subsubsection
4566 Quoting Style and the
4578 \begin_layout Standard
4579 The next section of the Supplement will cover the issue of quoting.
4580 Give it an appropriate title.
4583 \begin_layout Standard
4584 One of the first things you should do in that section is resolve the following
4588 \begin_layout Itemize
4597 is the correct paragraph environment for your language.
4600 \begin_layout Itemize
4601 In the Supplement, specify which one to use.
4604 \begin_layout Standard
4605 English has its own typography and style for quoting others.
4606 The Style Sheet describes that typography in section
4607 \begin_inset space ~
4611 \begin_inset CommandInset ref
4613 reference "sec:quote"
4618 Your language also has a specific typography and style for quotations.
4619 Describe that style in this section of the Supplement, too.
4620 Naturally, you do not need to go overboard.
4622 \begin_inset space ~
4626 \begin_inset CommandInset ref
4628 reference "sec:quote"
4632 of this Style Sheet is overly detailed for a good reason.
4633 Authors of the primary LyX manuals are not necessarily native English speakers.
4634 The members of your Translation Team, however, will all likely be native
4635 speakers of your language.
4636 Therefore, discuss proper quoting style of your native tongue to an appropriate
4640 \begin_layout Subsubsection
4641 Translations of Style Sheet Terminology
4644 \begin_layout Standard
4645 In the Supplement, you must provide a standard translation of certain key
4646 phrases for the members of your Translation Team.
4647 Place this in a section following the one about quotations.
4650 \begin_layout Standard
4651 In particular, standardize the translations of the phrases:
4654 \begin_layout Itemize
4660 \begin_layout Itemize
4666 \begin_layout Standard
4671 change the typography of the
4672 \begin_inset Quotes eld
4676 \begin_inset Quotes erd
4680 \begin_inset Quotes eld
4684 \begin_inset Quotes erd
4688 Only provide a translation for the opening phrases.
4689 Insist that the members of your Translation Team use these two tools correctly.
4692 \begin_layout Standard
4693 While we are discussing proper use of the
4694 \begin_inset Quotes eld
4698 \begin_inset Quotes erd
4702 \begin_inset Quotes eld
4706 \begin_inset Quotes erd
4709 in translations, let's talk about a related problem.
4711 \begin_inset Quotes eld
4715 \begin_inset Quotes erd
4718 is meant to be a note from the author of a manual to the reader.
4719 In the case of a translation, however, the translator is
4723 the author! How then should a translator translate an
4724 \begin_inset Quotes eld
4728 \begin_inset Quotes erd
4734 \begin_layout Standard
4735 You, as Translation Project Chief, must decide.
4736 You can forbid translation of pre-existing
4737 \begin_inset Quotes eld
4741 \begin_inset Quotes erd
4744 omitting them entirely instead.
4745 You could tell your translators to read any
4746 \begin_inset Quotes eld
4750 \begin_inset Quotes erd
4753 they may encounter, understand it, then write their own
4754 \begin_inset Quotes eld
4758 \begin_inset Quotes erd
4761 about the situation, not as a translation but as a personal opinion.
4762 You may decide on some other policy.
4765 \begin_layout Standard
4766 Whatever you decide, codify your policy in its own
4775 Place it near the section where you translated
4776 \begin_inset Quotes eld
4780 \begin_inset Quotes erd
4784 \begin_inset Quotes eld
4788 \begin_inset Quotes erd
4794 \begin_layout Subsubsection
4798 \begin_layout Standard
4799 After describing all of the previous issues, create a new
4805 \begin_inset Quotes eld
4808 Lost in Translation,
4809 \begin_inset Quotes erd
4812 or something similar.
4815 \begin_layout Standard
4816 In this section you will discuss any common English metaphors, humor, connotatio
4817 n, or other difficult to translate text.
4818 Try to balance brevity and completeness.
4827 s --- to each specific issue.
4830 \begin_layout Subsubsection
4831 \SpecialChar \ldots{}
4833 \begin_inset Quotes eld
4837 \begin_inset Quotes erd
4840 \SpecialChar \ldots{}
4844 \begin_layout Standard
4845 Throughout the manuals, the DocTeam has used the following sentences:
4849 If you haven't read the <
4853 > manual, go read it.
4857 \begin_layout Standard
4858 This sentence will be tricky to translate, since it contains non-translatable
4864 for this issue in your
4865 \begin_inset Quotes eld
4869 \begin_inset Quotes erd
4874 \begin_inset Quotes eld
4877 \SpecialChar \ldots{}
4878 Yes, we mean now\SpecialChar \ldots{}
4880 \begin_inset Quotes erd
4883 sentences, then present a translation, along with any explanation you feel
4887 \begin_layout Standard
4888 Here's what those two sentences, sitting alone in their own paragraph, mean:
4891 \begin_layout Standard
4892 The first sentence uses the English conditional followed by an imperative.
4893 We, as the LyX team, are commanding the reader to go back to another manual.
4898 manual is a prerequisite for all of the other manuals.
4899 The conditional clause preceeding the command means,
4900 \begin_inset Quotes eld
4903 You do not need to perform this command twice.
4904 \begin_inset Quotes erd
4910 \begin_layout Standard
4911 The second sentence adds force to the command.
4912 Culturally, the imperative tense of a verb in English is not necessarily
4914 The way we wrote that command,
4915 \begin_inset Quotes eld
4919 \begin_inset Quotes erd
4922 is firm, yet polite.
4923 The reader may choose to ignore it.
4925 \begin_inset Quotes eld
4929 \begin_inset Quotes erd
4932 we imply two things.
4934 \begin_inset Quotes eld
4938 \begin_inset Quotes erd
4942 That second sentence reinforces the command, making it a bit harder to
4944 Second, the sentence itself implies a certain sense of urgency.
4945 You cannot merely wait until later to fulfill that command.
4946 The brief pragraph, and its sudden end, add still further subtle reinforcement
4948 \begin_inset Quotes eld
4951 go do the required reading before using this manual.
4952 \begin_inset Quotes erd
4958 \begin_layout Standard
4959 Note that all of this commanding and reinforcing is nevertheless in a polite
4961 Furthermore, it is in a subtle form.
4962 We are commanding the reader to do something, but in an indirect fashion.
4963 This way, the reader does not feel like we are bullying him.
4966 \begin_layout Subsubsection
4971 \begin_layout Standard
4972 In the same part of the Supplement that you place the
4973 \begin_inset Quotes eld
4976 \SpecialChar \ldots{}
4977 Yes, we mean now\SpecialChar \ldots{}
4979 \begin_inset Quotes erd
4982 translation, discuss the English version's use of
4983 \begin_inset Quotes eld
4987 \begin_inset Quotes erd
4993 \begin_layout Standard
4994 You see, here in America, we often say that everything is permitted unless
4995 explicitly banned by law.
4996 As a result, manuals for computer software are frequently ignored and the
4997 software subsequently blamed for not being
4998 \begin_inset Quotes eld
5002 \begin_inset Quotes erd
5005 This is where the use of
5006 \begin_inset Quotes eld
5010 \begin_inset Quotes erd
5017 \begin_layout Standard
5018 We who wrote the manuals added sentences insisting that the reader not ignore
5019 certain parts of the documentation.
5020 We wrote in a manner that was polite, yet firmly asserted that the user
5021 was misusing the software if he did not read the manual correctly.
5022 We did not, however, want to sound threatening, coercive, or bullying.
5025 \begin_layout Standard
5026 In your culture, cajoling the reader into using the manuals correctly may
5028 It may, in fact, be outright rude.
5029 Additionally, translating the firm-but-convincing bits may not work.
5030 The translation may sound weird, or rude, or hostile.
5031 Therefore, you and your translation team will face many sentences that
5032 you cannot translate.
5035 \begin_layout Standard
5036 You, the Translation Project Chief, must discuss this issue.
5037 Try and find parts of the original manuals where some friendly but firm
5038 convincing does not translate properly.
5039 Use these cases as the basis for examples of the problem.
5040 Be sure to then offer a solution (i.
5041 \begin_inset space ~
5045 \begin_inset space ~
5048 how you want such sentences translated.) If stumped, ask for help on the
5049 LyX Developer's List.
5052 \begin_layout Subsubsection
5056 \begin_layout Standard
5057 You can add more sections to the Supplement if you need to discuss other
5059 There may be policies or guidelines that you want to set for your Translation
5061 Be careful, however! Keep the Supplement