1 #LyX 1.6.0 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
27 \paperorientation portrait
30 \paragraph_separation indent
32 \quotes_language english
36 \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
445 \begin_inset space \thinspace{}
450 This is a case where you don't use
454 for code, because you want the generic argument label to stand out.
455 On the other hand, if you were specifying an argument, for example,
456 \begin_inset Quotes eld
464 \begin_inset Quotes erd
476 \begin_layout Enumerate
477 Any LaTeX commands and code, and any
481 LaTeX package names get set in
487 \begin_inset Quotes eld
495 \begin_inset Quotes erd
498 is the name of an unsupported LaTeX package, but
499 \begin_inset Quotes eld
507 \begin_inset Quotes erd
510 is a supported LaTeX class.
513 \begin_layout Section
517 \begin_layout Standard
518 The canonical keyboard contains these keys:
521 \begin_layout Itemize
533 \begin_layout Itemize
545 \begin_layout Itemize
558 \begin_layout Standard
562 use the abbreviations
568 \begin_layout Itemize
571 F1 F2 F3 F4 F5 F6 F7 F8 F9 F10 F11 F12
575 \begin_layout Standard
577 Most modern keyboards have all 12.
581 \begin_layout Itemize
590 \begin_layout Standard
592 \begin_inset Quotes eld
596 \begin_inset Quotes erd
603 \begin_layout Itemize
630 \begin_layout Standard
631 These are the 6 keys that appear above the cursor keys on many PC keyboards.
632 Consider them as part of the standard motion keys.
636 \begin_layout Itemize
643 \begin_layout Standard
644 The four standard motion keys.
645 There is no need to put the word
646 \begin_inset Quotes eld
650 \begin_inset Quotes erd
653 anywhere, since that's obvious.
657 \begin_layout Plain Layout
659 \begin_inset Quotes eld
663 \begin_inset Quotes erd
668 \begin_inset Quotes eld
672 \begin_inset Quotes erd
675 after one of these may be redundant in certain situations.
684 \begin_layout Itemize
697 \begin_layout Standard
698 I won't throw a hissy fit if you use one instead of the other.
699 I'd prefer if you used
707 , but it's okay if you slip up and forget.
708 Since these two keys are bound to the same function in LyX, it doesn't
713 \begin_layout Standard
714 You do not need to explain everywhere what the
723 The user isn't stupid.
724 Also, someone will document anything that isn't clear (e.
741 problem) someplace in the introduction.
742 No need for you to repeat someone else's work.
745 \begin_layout Standard
746 LyX does not support keyboards missing any of the keys described above,
748 LyX can support a keyboard missing
757 There is a keyboard accelerator for
761 , but this is the only function key LyX assumes exists.
762 Nevertheless, these details are of minor, if any, concern for the documentation.
763 Assume the aforementioned keys exist.
766 \begin_layout Section
770 \begin_layout Standard
772 \begin_inset Quotes eld
776 \begin_inset Quotes erd
779 and any description of the 3 mouse buttons have no special handling.
780 Don't typeset them in any other font than the default, which is Roman.
784 \begin_layout Standard
785 Exception: you're writing an Author's Note (see section
786 \begin_inset CommandInset ref
788 reference "sec:author-notes"
792 ) and you need to mention something about the mouse.
793 Since the rest of the note is in
797 , your description of
798 \begin_inset Quotes eld
802 \begin_inset Quotes erd
805 should be emphasized, as well.
806 There are a couple of other cases like this one; use your judgement.
809 \begin_layout Standard
810 There are only 3 mouse buttons.
811 The use of them and of the mouse itself is obvious.
812 There are few --- if any --- nonstandard things we do with the mouse.
813 Therefore, there's no need to make the word
814 \begin_inset Quotes eld
818 \begin_inset Quotes erd
822 \begin_inset Quotes eld
826 \begin_inset Quotes erd
832 \begin_layout Section
836 \begin_layout Standard
840 \begin_layout Description
853 between the words for menu and widget names.
875 \begin_layout Standard
876 This holds for things in
889 If you have a long code example, one that can't simply be inlined and put
905 \begin_layout Standard
914 so that the name doesn't get split between two lines, which is visually
924 is near the end of a line and overflows the margin, use a
930 in that parargraph (consult a LaTeX book for more about
931 \begin_inset Quotes eld
941 \begin_inset Quotes erd
944 ) or manually add a hypenation point.
948 \begin_layout Description
953 Terms These are things like the following:
957 \begin_layout Itemize
965 \begin_layout Itemize
973 \begin_layout Itemize
983 \begin_layout Itemize
994 \begin_layout Standard
1003 font and, in the case of
1011 , capitalize the first two letters.
1014 \begin_layout Standard
1015 Why are these terms special? They are concepts which the seasoned LaTeX-pert
1016 is familiar with, but which the new LyX user is not.
1017 I want them to stand out from the rest of the text, hence the use of
1020 \begin_inset space ~
1030 \begin_layout Standard
1031 Seasoned LyX Team Members: Are there other terms that require this special
1032 status? On the other hand, should we eliminate this style completely?
1035 \begin_layout Description
1036 Terminology Note the following:
1039 \begin_layout Itemize
1040 \begin_inset Quotes eld
1044 \begin_inset Quotes erd
1048 \begin_inset Quotes eld
1052 \begin_inset Quotes erd
1056 \begin_inset Quotes eld
1060 \begin_inset Quotes erd
1065 \begin_inset Quotes eld
1069 \begin_inset Quotes erd
1073 \begin_inset Quotes eld
1077 \begin_inset Quotes erd
1083 \begin_layout Itemize
1084 PostScript® is a registered trademark of Adobe Corp.
1087 You must put the ® after it or we'll get sued!
1089 I also want it written as seen here, always capitalized.
1091 \begin_inset Quotes eld
1095 \begin_inset Quotes erd
1099 \begin_inset Quotes eld
1103 \begin_inset Quotes erd
1107 \begin_inset Quotes eld
1111 \begin_inset Quotes erd
1114 - both of them capitalized, in the default font (i.
1115 \begin_inset space ~
1119 \begin_inset space \thinspace{}
1123 \begin_inset space ~
1127 If you must, cut and paste it from here.
1131 \begin_layout Standard
1132 I am going to say this again:
1135 \begin_layout Standard
1136 \begin_inset VSpace 0.37cm
1142 \begin_layout Standard
1147 You must put the ® after PostScript® or we'll get sued!
1150 \begin_layout Standard
1151 \begin_inset VSpace 0.51cm
1157 \begin_layout Standard
1158 I mean it! American companies like to sue anything that moves.
1163 by forgetting that ®.
1169 \begin_layout Itemize
1170 Similarly, if you use any other registered trademark in any documentation,
1171 put the ® after it, too.
1174 \begin_layout Description
1176 \begin_inset space ~
1179 Items When quick-referencing an item in a menu, use the menu separator:
1181 \begin_inset Quotes eld
1184 \SpecialChar \menuseparator
1186 \begin_inset Quotes erd
1192 File\SpecialChar \menuseparator
1196 Notice that there are
1201 \begin_inset Quotes eld
1204 \SpecialChar \menuseparator
1206 \begin_inset Quotes erd
1212 \begin_inset space ~
1217 , just like the menu and item names.
1221 \begin_layout Enumerate
1222 The reason why I want no spaces around the
1223 \begin_inset Quotes eld
1226 \SpecialChar \menuseparator
1228 \begin_inset Quotes erd
1231 is to prevent LyX from splitting terms across lines.
1232 The same goes for using
1235 \begin_inset space ~
1240 s between multi-word terms.
1241 The split would be visually disruptive.
1244 \begin_layout Enumerate
1246 \begin_inset Quotes eld
1249 \SpecialChar \menuseparator
1251 \begin_inset Quotes erd
1254 goes between menu names and item names
1259 (Yes, submenus are okay, too).
1262 \begin_layout Enumerate
1268 \begin_inset Quotes eld
1271 \SpecialChar \menuseparator
1273 \begin_inset Quotes erd
1276 between menu items and dialog names.
1278 \begin_inset Quotes eld
1286 ayout\SpecialChar \menuseparator
1291 per\SpecialChar \menuseparator
1293 \begin_inset space ~
1299 \begin_inset Quotes erd
1304 IS STRICTLY FORBIDDEN!
1310 \begin_layout Standard
1316 \begin_inset Quotes eld
1319 \SpecialChar \menuseparator
1321 \begin_inset Quotes erd
1324 between popup names and any dialog.
1326 \begin_inset Quotes eld
1332 \begin_inset space ~
1335 Dialog\SpecialChar \menuseparator
1343 \begin_inset Quotes erd
1348 IS STRICTLY FORBIDDEN!
1351 \begin_layout Standard
1357 \begin_inset Quotes eld
1360 \SpecialChar \menuseparator
1362 \begin_inset Quotes erd
1365 between menu items and any dialog.
1367 \begin_inset Quotes eld
1375 ayout\SpecialChar \menuseparator
1380 per\SpecialChar \menuseparator
1388 \begin_inset Quotes erd
1393 IS STRICTLY FORBIDDEN!
1396 \begin_layout Standard
1397 Either write out the description, or use context to eliminate any need to
1398 repeat menu items, dialog names, etc.
1403 \begin_layout Description
1405 \begin_inset space ~
1408 Boxes LyX has a feature for adding comments that appear only within the
1411 \begin_inset Note Note
1414 \begin_layout Plain Layout
1415 These should NEVER appear in the manuals.
1421 You will see nothing in a printout of the Style Sheet.
1422 Therefore, they have no place in the manuals.
1428 \begin_layout Standard
1429 If you have a parenthetical comment you want to make, the reader should
1430 see it too, even in the printed version.
1431 Use an Author's Note (see section
1432 \begin_inset CommandInset ref
1434 reference "sec:author-notes"
1438 ) in place of the Note-Boxes.
1442 \begin_layout Description
1443 \begin_inset Quotes eld
1446 (\SpecialChar \ldots{}
1448 \begin_inset Quotes erd
1452 \begin_inset space ~
1456 \begin_inset Quotes eld
1459 [\SpecialChar \ldots{}
1461 \begin_inset Quotes erd
1465 \begin_inset space ~
1469 \begin_inset space ~
1473 \begin_inset Quotes eld
1476 {\SpecialChar \ldots{}
1478 \begin_inset Quotes erd
1481 I have recently been corrected about the use of parentheses.
1482 Standard English typesetting uses the normal parentheses,
1483 \begin_inset Quotes eld
1486 (\SpecialChar \ldots{}
1488 \begin_inset Quotes erd
1491 , around any aside, remark, or parenthetical expression.
1493 \begin_inset Quotes eld
1496 [\SpecialChar \ldots{}
1498 \begin_inset Quotes erd
1501 , is used only within quotations (see section
1502 \begin_inset space ~
1506 \begin_inset CommandInset ref
1508 reference "sec:quote"
1514 \begin_inset Quotes eld
1517 {\SpecialChar \ldots{}
1519 \begin_inset Quotes erd
1523 Therefore, never use
1524 \begin_inset Quotes eld
1527 [\SpecialChar \ldots{}
1529 \begin_inset Quotes erd
1533 \begin_inset Quotes eld
1536 {\SpecialChar \ldots{}
1538 \begin_inset Quotes erd
1541 unless otherwise specified by this Style Sheet.
1544 \begin_layout Description
1545 Dashes: Be sure to use the correct one.
1547 \begin_inset Quotes eld
1555 \begin_inset Quotes erd
1558 character is not a dash, it's a hyphen.
1559 Use it only as a hyphen.
1564 \begin_layout Standard
1566 \begin_inset Quotes eld
1570 \begin_inset Quotes erd
1574 \begin_inset Quotes eld
1578 \begin_inset Quotes erd
1582 \begin_inset Quotes eld
1590 \begin_inset Quotes erd
1593 characters form the en-dash.
1595 \begin_inset Quotes eld
1603 \begin_inset Quotes erd
1606 characters create an em-dash, which is slightly longer than the en-dash.
1607 In the printed version of any document, LyX will combine the two or three
1609 \begin_inset Quotes eld
1617 \begin_inset Quotes erd
1620 characters into a single, unbroken line.
1624 \begin_layout Section
1625 Cross-References and Labels
1628 \begin_layout Standard
1629 Use the following labelling conventions:
1633 \labelwidthstring 00.00.0000
1634 sec:xxx Use this for
1654 \labelwidthstring 00.00.0000
1655 eqn:xxx Use this for Equations, should you need to create any.
1659 \labelwidthstring 00.00.0000
1660 tbl:xxxx Use this for tables inside of a table float.
1664 \labelwidthstring 00.00.0000
1665 fig:xxx Use this for figures inside of figure floats.
1668 \begin_layout Standard
1669 Additionally, you should put the label at one of two locations:
1672 \begin_layout Enumerate
1675 beginning of the paragraph
1677 , after a section heading, or at the beginning of captions, etc.
1678 It should be the first thing on the first line.
1679 Don't put a space betweeen it and the first word.
1682 \begin_layout Enumerate
1683 If there is no paragraph after a section heading, put it at the
1685 end of the last line.
1692 \begin_layout Standard
1697 which is immediately followed by a
1702 This is a case where you need to put the label at the end of the
1707 I know it looks ugly; not much we can do about that, though.
1711 \begin_layout Section
1712 Content --- What Goes Where
1715 \begin_layout Standard
1720 important to anyone documenting a new feature.
1721 If you need to add new documentation, pay attention.
1725 \begin_layout Standard
1726 In the dim and distant past, whenever someone wanted to document a new feature
1727 they added, they either wrote a mini-doc and stuck it into the documentation
1728 directory, or they added a new section to the lone manual.
1729 No one paid much attention to organization in those days, either.
1730 The result was a totally bloated, totally unnavigable, and incomplete manual
1731 orbitted by a swarm of tiny, incomplete mini-docs.
1732 I don't want the docs to fall back into that mess.
1735 \begin_layout Standard
1736 With that in mind, I have some instructions for how to keep things organized:
1740 \labelwidthstring 00.00.0000
1745 Please, don't touch this file.
1746 It's essentially complete, anyhow.
1747 Only the editor(s) should make changes to this, as this file contains info
1748 about how to contribute to the doc project.
1749 That's really the only stuff that should need to change, and even then,
1750 only when a new maintainer comes along.
1754 \labelwidthstring 00.00.0000
1759 This file is complete.
1760 Any changes should be for updates
1765 DO NOT ADD new features to here willy-nilly.
1766 Let the editor decide if --- and when --- new sections go in here.
1767 Place any new features in\SpecialChar \ldots{}
1772 \labelwidthstring 00.00.0000
1777 This is where all new features go from now on.
1778 It's in the style of a bound journal --- each section is an
1779 \begin_inset Quotes eld
1783 \begin_inset Quotes erd
1786 from the author of the feature.
1787 Also, anyone who writes a
1791 file for a new document class should write a section describing that new
1792 class and how to use it.
1793 That also goes here.
1797 \begin_layout Standard
1798 Note, however, that you are
1802 excused from following this Style Sheet just because the sections of
1806 are in the form of a journal article.
1811 \labelwidthstring 00.00.0000
1816 This file is complete.
1817 Do not change or add to without permission of the Documenation Project
1822 \labelwidthstring 00.00.0000
1827 This document describes advanced features, most of which alter the look,
1828 feel, and behavior of LyX.
1829 This manual is still a bit incomplete, although that may change soon.
1830 Check for updates often.
1834 \begin_layout Standard
1835 If you are unsure whether or not something belongs in
1839 , then, most-likely, it
1848 Again, let the current editor of the LyX documentation decide if your new
1849 section should be migrated to
1858 \labelwidthstring 00.00.0000
1863 I'd prefer to completely finish this one before doing anything else, but
1865 LyX keeps changing so much that I think the
1869 will be the last one completed.
1870 However, I'd like it if the developer's would add entries anytime they
1871 create a new function or popup.
1872 That would help things immensely!
1876 \begin_layout Standard
1881 follows this Style Sheet for the most part.
1882 There are, however, additional rules to follow when making new entries.
1883 At the top of this manual, there are examples of and a template for
1892 \begin_layout Section
1893 Writing Style: The Primary Manuals
1896 \begin_layout Standard
1897 While I want to make contributing to the Documentation Project as painless
1898 as possible for newcomers, I also want the newcomers to be painless on
1899 the existing Documentation Team! Ergo, I've written this section to give
1900 some flavor to guide everyone's individual style.
1904 \begin_layout Subsection
1908 \begin_layout Standard
1909 All contributions to the
1913 LyX documentation must be in English.
1914 I don't care if it's British, Australian, or American English.
1915 The DocTeam editor will proofread for glaring mistakes and fix them.
1918 \begin_layout Standard
1919 Don't get hung up on semantics.
1920 English is a flexible language, and just because your Mothertongue-to-English
1921 dictionary gives only one translation for a word doesn't necessarily mean
1923 We've had some discussions and misunderstandings on the Developers' List
1924 because of this very problem.
1925 If something is unclear (or just plain weird) due to a translation problem,
1926 one of the American/British/Australian developers can fix it.
1929 \begin_layout Standard
1934 documentation, I exclude the translations.
1935 We usually don't have enough people to cover the manuals in one language,
1936 let alone more than one.
1937 Subsequently, the tranlsations are just that --- translations of the English
1938 version of the LyX manuals.
1939 The translation efforts require have their own set of guidelines.
1941 \begin_inset CommandInset ref
1943 reference "sec:translations"
1950 \begin_layout Subsection
1952 \begin_inset Newline newline
1955 Commentary from the Author (i.
1956 \begin_inset space ~
1962 \begin_layout Standard
1963 \begin_inset CommandInset label
1965 name "sec:author-notes"
1969 I want to make it easy for everyone when it comes to documenting things.
1970 Some features are incomplete.
1971 Some, you might not know everything about.
1972 Sometimes, you may want to comminucate something to me or the reader or
1973 other DocTeam members.
1974 Sometimes, you may want to
1975 \begin_inset Quotes eld
1979 \begin_inset Quotes erd
1982 you want to say something that is your personal opinion and using
1983 \begin_inset Quotes eld
1987 \begin_inset Quotes erd
1990 would be inappropriate.
1993 \begin_layout Standard
1994 In short, when you contribute to the LyX Docs, you wear many hats.
1997 \begin_layout Standard
1998 For occasions when you need to switch hats, I've designed some special mechanism
2002 \begin_layout Subsubsection
2004 \begin_inset space ~
2008 \begin_inset Quotes eld
2012 \begin_inset Quotes erd
2018 \begin_layout Standard
2019 These are footnotes.
2020 They begin with the following:
2031 \begin_layout Standard
2032 \SpecialChar \ldots{}
2037 for the person's name and without the quotes.
2038 The rest of the footnote is the actual comment.
2042 \begin_layout Standard
2043 Use these when you need to quote a comment by someone (usually yourself),
2044 and need to identify that person.
2045 This includes occasions when you need wear the
2046 \begin_inset Quotes eld
2050 \begin_inset Quotes erd
2054 \begin_inset space ~
2058 \begin_inset space ~
2061 to speak for yourself instead of for the LyX Team.
2064 \begin_layout Standard
2065 If the comment is too large to put in a footnote, don't use a Personal Note.
2066 When quoting more than about 3 sentences or 5 lines of text, use a bona
2068 Don't use any leading
2069 \begin_inset Quotes eld
2077 \begin_inset Quotes erd
2081 In a real quote, you'll give credit to the original speaker in either the
2082 paragraph before or after the body of the
2089 \begin_layout Subsubsection
2091 \begin_inset space ~
2095 \begin_inset Quotes eld
2099 \begin_inset Quotes erd
2105 \begin_layout Standard
2106 There will be times when you are not speaking for the LyX Team, yet you
2107 are not entirely speaking for yourself.
2108 Instead, you are speaking on behalf of the manual itself, as the author
2110 Some examples of when you might need to do this are:
2113 \begin_layout Itemize
2114 You need to contradict something you just wrote because the feature isn't
2115 quite ready yet, but you wanted to document what it will do.
2118 \begin_layout Itemize
2119 You need to leave a note for yourself.
2122 \begin_layout Itemize
2123 You need to leave a note for the editor or the other DocTeam members.
2126 \begin_layout Itemize
2127 You need to point out something about the manuals to the reader, something
2128 that doesn't fit into the context of the current paragraph.
2131 \begin_layout Standard
2132 At such times, you are wearing your
2133 \begin_inset Quotes eld
2137 \begin_inset Quotes erd
2143 \begin_layout Standard
2144 The typography for an
2145 \begin_inset Quotes eld
2149 \begin_inset Quotes erd
2155 \begin_layout Itemize
2156 They go in the body of the text, in brackets,
2157 \begin_inset Quotes eld
2161 \begin_inset Quotes erd
2164 , not any other form of parentheses.
2165 The bracket are in the default character style.
2168 \begin_layout Itemize
2169 The text of the note itself, however, is emphasized.
2173 \begin_layout Itemize
2174 Begin with the words,
2175 \begin_inset Quotes eld
2183 \begin_inset Quotes erd
2186 and end with an em-dash,
2187 \begin_inset Quotes eld
2191 \begin_inset Quotes erd
2194 , followed by your initials.
2198 \begin_layout Standard
2199 Here's an example: [
2201 Author's Note: This is an example note.
2207 \begin_layout Standard
2208 The form of the Author's Note, by the way, isn't a suggestion or request.
2214 All Author's Notes must begin with this text, verbatim:
2215 \begin_inset Quotes eld
2223 \begin_inset Quotes erd
2228 \begin_inset Quotes eld
2232 \begin_inset Quotes erd
2235 are or any other variant are forbidden.
2236 The Author's Note must end with an em-dash, which is 3
2237 \begin_inset Quotes eld
2241 \begin_inset Quotes erd
2245 \begin_inset Quotes eld
2249 \begin_inset Quotes erd
2254 \begin_inset Quotes eld
2258 \begin_inset Quotes erd
2261 ; you must use 3 (and 5 is right out).
2264 \begin_layout Standard
2265 \begin_inset Quotes eld
2269 \begin_inset Quotes erd
2272 are inherently transient, and should disapear as a manual matures.
2275 \begin_layout Subsubsection
2279 \begin_layout Standard
2280 You are also free to use footnotes on their own in addition to the Personal
2281 Notes and/or Author's Notes.
2282 I've frequently used footnotes to \SpecialChar \ldots{}
2283 well, to comment on parts of a section
2284 without putting the commentary into the body of the text.
2287 \begin_layout Paragraph*
2288 Mixing Footnotes and Personal Notes
2291 \begin_layout Standard
2292 Personal Notes always go in footnotes, and should be 5 lines or fewer.
2293 Any larger quotation should be quoted properly, using the rules of standard
2299 paragraph environment.
2302 \begin_layout Paragraph*
2303 Mixing Footnotes and Author's Notes
2306 \begin_layout Standard
2307 Author's Notes should
2315 \begin_layout Paragraph*
2316 Mixing Personal Notes and Author's Notes
2319 \begin_layout Standard
2320 Forbidden; these two are mutually exclusive.
2323 \begin_layout Subsubsection
2327 \begin_layout Itemize
2329 \begin_inset Newline newline
2336 opinion --- yours or another LyX developer's --- about anything.
2337 Anywhere in the manuals you wish to speak for yourself instead the the
2339 If you have a long rant, however, quote yourself (see section
2340 \begin_inset space ~
2344 \begin_inset CommandInset ref
2346 reference "sec:quote"
2353 \begin_layout Itemize
2355 \begin_inset Newline newline
2358 Use this to describe things in LyX (or the manuals) that may change in the
2359 future or are somehow incomplete.
2360 Author's Notes are supposed to disappear as a manual matures.
2363 \begin_layout Itemize
2365 \begin_inset Newline newline
2368 Used for text fragments that almost fit into the flow of the text\SpecialChar \ldots{}
2373 \begin_layout Standard
2374 When using these three mechanisms, in addition to rigorously following their
2375 descriptions, please use them properly.
2376 I listed some additional restrictions previously.
2377 Some of you may balk at these restrictions.
2378 Nevertheless, there is a reason for them: if you have an overwhemling desire
2379 to mix or modify footnotes, Personal Notes, and Author's Notes, you shouldn't
2380 be using any of them.
2381 More specifically, you're trying to use a hammer to drive in a screw.
2382 What you want to say probably needs to go into the main body of the text.
2385 \begin_layout Subsection
2386 General Stylistic Guidelines
2389 \begin_layout Standard
2390 Everything in this section is
2392 mandatory to all documenters
2394 , regardless the language you're writing in.
2398 \begin_layout Subsubsection
2402 \begin_layout Enumerate
2403 Use the typography rules outlined in the beginning sections of this document.
2406 \begin_layout Enumerate
2407 Don't, however, mimic the typography of this file.
2408 Yes, the Style Sheet doesn't follow the Style Sheet (grin).
2411 \begin_layout Enumerate
2412 There is some typographic freedom in those rules in earlier sections.
2413 Use that freedom wisely.
2414 Most importanly, never sacrifice the online appearance for the printed
2415 appearance and vice versa.
2419 \begin_layout Standard
2420 An example is in the
2425 There is a footnote using the
2429 command to divide a long
2433 environment into 3 columns.
2434 It adds some LaTeX commands to the online version, the so-called
2435 \begin_inset Quotes eld
2439 \begin_inset Quotes erd
2442 that some so vehemently oppose.
2443 Without it, however, that footnote takes up over two pages, most of which
2445 This is an example of permitting a little ugliness in the online version
2446 to get the printed version to look right.
2450 \begin_layout Enumerate
2451 When in doubt, compromise.
2455 \begin_layout Standard
2456 When in doubt, use good judgement.
2460 \begin_layout Subsubsection
2464 \begin_layout Enumerate
2466 \begin_inset Quotes eld
2470 \begin_inset Quotes erd
2477 \begin_layout Standard
2478 When you speak, you speak for the entire LyX Team, so use
2479 \begin_inset Quotes eld
2483 \begin_inset Quotes erd
2487 \begin_inset Quotes eld
2491 \begin_inset Quotes erd
2498 \begin_layout Enumerate
2500 \begin_inset Quotes eld
2504 \begin_inset Quotes erd
2511 \begin_layout Standard
2512 Whenever you want to say something to the reader, use
2513 \begin_inset Quotes eld
2517 \begin_inset Quotes erd
2520 not some contorted construction to avoid being too informal.
2525 \begin_layout Enumerate
2527 \begin_inset Quotes eld
2531 \begin_inset Quotes erd
2534 for both the physical pointing object (mouse, joystick, touch pad, track
2535 ball, etc.) and the mouse cursor which the physical object moves about the
2539 \begin_layout Enumerate
2541 \begin_inset Quotes eld
2545 \begin_inset Quotes erd
2548 for the little blinking vertical bar that indicates where text can/will
2552 \begin_layout Enumerate
2553 When in doubt, compromise.
2557 \begin_layout Standard
2558 When in doubt, use good judgement.
2562 \begin_layout Subsubsection
2563 \begin_inset CommandInset label
2569 Quoting Yourself and Others
2572 \begin_layout Standard
2573 In some cases, you'll have something to say, an opinion of yours.
2574 Since this is your opinion, you're not speaking for the LyX Team.
2575 You have so much to say, in fact, that it won't fit into a Personal Note
2576 or an Author's Note.
2577 In these cases you want to quote yourself.
2580 \begin_layout Standard
2581 Any time you wish to quote someone, be it yourself or someone else, there
2582 are standard rules one follows.
2583 Every language has its own rules.
2584 You should follow the rules that apply to the language of the document
2585 to which you are contributing.
2589 \begin_layout Standard
2590 This creates a problem for the primary documentation.
2591 The primary documentation is written in English, yet the contributors come
2592 from many countries.
2593 The quoting rules for English (well, American English, at least) are outlined
2597 \begin_inset space ~
2602 , for your convenience.
2603 Read them if you need to.
2606 \begin_layout Standard
2607 \begin_inset Float figure
2613 \begin_layout Plain Layout
2614 Quoting rules for English:
2617 \begin_layout Itemize
2618 The body of the quote belongs in a
2625 \begin_layout Itemize
2626 The sentences prior to the quote should flow logically and smoothly into
2630 \begin_layout Itemize
2631 The sentences immediately following the quote should continue the flow of
2635 \begin_layout Itemize
2640 credit the original author of the quote in the sentences immediately before
2644 \begin_layout Itemize
2645 Crediting the original author of the quote should not, however, disrupt
2646 the flow of the text.
2649 \begin_layout Itemize
2650 If you omit text from the beginning of the first sentence in the quote,
2651 the quote must start with the text
2652 \begin_inset Quotes eld
2655 [\SpecialChar \ldots{}
2657 \begin_inset Quotes erd
2661 This is an ellipsis in square brackets.
2664 \begin_layout Itemize
2665 If you omit text from the end of the last sentence in the quote, the quote
2666 must end with the text
2667 \begin_inset Quotes eld
2670 [\SpecialChar \ldots{}
2672 \begin_inset Quotes erd
2675 followed by the sentence's punctuation mark.
2678 \begin_layout Itemize
2679 If you omit any text from the middle of the quote, be it whole sentences
2680 or parts of sentences, replace it with the text
2681 \begin_inset Quotes eld
2684 [\SpecialChar \ldots{}
2686 \begin_inset Quotes erd
2692 \begin_layout Itemize
2693 The quote must be grammatically correct.
2698 \begin_layout Itemize
2699 If the original is wrong, you must correct it.
2702 \begin_layout Itemize
2703 If omitting part of the quote
2704 \begin_inset Quotes eld
2708 \begin_inset Quotes erd
2711 it, you must correct the problem.
2714 \begin_layout Itemize
2715 For missing words (e.
2716 \begin_inset space ~
2720 \begin_inset space ~
2724 \begin_inset Quotes eld
2728 \begin_inset Quotes erd
2731 goes missing), place the word in square brackets,
2732 \begin_inset Quotes eld
2735 [\SpecialChar \ldots{}
2737 \begin_inset Quotes erd
2740 and insert in the quote where needed.
2743 \begin_layout Itemize
2744 For mangled word order, correct the mangled text, following it with the
2746 \begin_inset Quotes eld
2750 \begin_inset Quotes erd
2757 \begin_layout Itemize
2758 Spelling in the quote must be correct.
2759 Correct any misspelled words and place the text
2760 \begin_inset Quotes eld
2764 \begin_inset Quotes erd
2767 after the corrected word.
2770 \begin_layout Itemize
2771 Back-to-back bracket blocks merge together.
2773 \begin_inset Quotes eld
2776 [\SpecialChar \ldots{}
2778 \begin_inset Quotes erd
2783 \begin_inset Quotes eld
2786 [\SpecialChar \ldots{}
2788 \begin_inset Quotes erd
2794 \begin_layout Itemize
2795 If you correct the spelling in 2 or more consecutive words, you can get
2797 \begin_inset Quotes eld
2801 \begin_inset Quotes erd
2804 after the last mistake.
2812 \begin_layout Subsubsection
2816 \begin_layout Standard
2817 When describing a new feature or
2824 \begin_layout Enumerate
2835 \begin_inset Quotes eld
2838 Keep It Short and Sweet
2839 \begin_inset Quotes erd
2843 \begin_inset Quotes eld
2846 Keep It Simple, Stupid!
2847 \begin_inset Quotes erd
2854 \begin_layout Itemize
2859 write paragraph after paragraph of verbage.
2863 \begin_layout Itemize
2867 \begin_layout Itemize
2868 Take a look at the manual for a commercial word processor --- it's a fine
2873 to write documentation.
2874 It's all pithy, substanceless verbage, and its
2882 \begin_layout Enumerate
2883 Avoid being pedantic like The Plague!
2886 \begin_layout Enumerate
2887 In the same vein, don't write more than you have to.
2888 You're not working in a vacuum --- refer freely to other parts of the manual
2889 (and other parts of other manuals).
2891 \begin_inset Quotes eld
2894 other part of the manual
2895 \begin_inset Quotes erd
2898 is incomplete or empty, refer to it.
2899 Someone will fill it in eventually.
2902 \begin_layout Enumerate
2903 On the other hand, BE THOROUGH!
2907 \begin_layout Enumerate
2912 , not widgets, not how the source code is organized.
2915 \begin_layout Enumerate
2916 Group by feature, not by widget.
2919 \begin_layout Enumerate
2920 Stay on topic --- one
2933 s and further subdivisions to group things if you're documenting several
2934 related features in a single
2941 \begin_layout Enumerate
2942 Describe EVERYTHING related to that feature, no matter where it is.
2946 \begin_layout Enumerate
2947 Example: Paragraph Indenting.
2948 Several popups control its behavior.
2953 of this: which popups control it, when you use which setting on which popup
2954 to do which operation, et cetera.
2957 \begin_layout Enumerate
2963 \begin_inset Newline newline
2966 I've had people only document one popup --- literally.
2967 This added off-topic information and only described half of the feature,
2968 since other menus, popups, and even unbound functions contained additional
2970 \begin_inset Newline newline
2977 cranky when that happens, because it means
2982 Bad help is worse than no help at all.
2986 \begin_layout Standard
2987 These remarks still hold true: you'll piss of the DocTeam editor if you
2988 do things wrong, because he'll have to fix your mistakes.
2993 \begin_layout Enumerate
2994 Remember, there are people who will reference
2998 section, just as you're referencing someone else's.
2999 You do want what you write to be useful, don't you?
3003 \begin_layout Enumerate
3004 When in doubt, compromise.
3008 \begin_layout Standard
3009 When in doubt, use good judgement.
3013 \begin_layout Subsubsection
3018 Treat the Reader as if She is Stupid
3021 \begin_layout Enumerate
3025 \begin_layout Enumerate
3026 No talking down to the reader.
3029 \begin_layout Enumerate
3030 The reader is smart enough to know what a mouse is.
3033 \begin_layout Enumerate
3034 The reader is smart enough to know how to use a keyboard, including the
3048 (The introduction of most of the manuals takes care of the
3049 \begin_inset Quotes eld
3061 \begin_inset Quotes erd
3064 issue, so you don't need to.)
3067 \begin_layout Enumerate
3068 The reader is smart enough to know that
3069 \begin_inset Quotes eld
3073 \begin_inset Quotes erd
3077 \begin_inset Quotes eld
3080 where the text cursor is sitting right now, in the buffer currently visible.
3081 \begin_inset Quotes erd
3086 (Anything more than the word
3087 \begin_inset Quotes eld
3091 \begin_inset Quotes erd
3094 is, IMO, superfluous and wll be deleted .
3095 So, save yourself the typing, save the editor the cutting, and save the
3096 reader the strain of sifting through extra verbage that adds no content.)
3099 \begin_layout Enumerate
3100 Rule of thumb: the reader is not an imbecile.
3101 The reader is merely lost; point them in the right direction, and they
3102 can take it from there.
3105 \begin_layout Subsection
3106 Tips for the English Version
3109 \begin_layout Standard
3110 \begin_inset CommandInset label
3112 name "sec:english-only"
3116 When contributing to the primary --- i.
3117 \begin_inset space ~
3121 \begin_inset space ~
3124 the English language version --- of the LyX manuals, keep the following
3128 \begin_layout Subsubsection
3129 Write as if You're Talking with a Friend.
3133 \begin_layout Enumerate
3134 Think that way when you write.
3135 Play the dialogue in your mind.
3138 \begin_layout Enumerate
3139 Be as informal as you please (without being rude).
3142 \begin_layout Subsubsection
3143 AVOID the Passive Voice
3146 \begin_layout Enumerate
3148 \begin_inset Quotes eld
3151 It is felt that this name best explains the command's purpose.
3152 \begin_inset Quotes erd
3155 We know full well who wrote the command:
3156 \begin_inset Quotes eld
3159 The LyX Team felt ...
3160 \begin_inset Quotes erd
3164 \begin_inset Quotes eld
3168 \begin_inset Quotes erd
3174 \begin_layout Enumerate
3175 Things don't happen by magic - somebody or something did it.
3176 Only politicians use the passive voice to cover up who did something.
3177 If LyX reformats a paragraph, write,
3178 \begin_inset Quotes eld
3181 LyX reformatted the paragraph.
3182 \begin_inset Quotes erd
3189 makes changes, write,
3190 \begin_inset Quotes eld
3197 changes the document.
3198 \begin_inset Quotes erd
3205 \begin_layout Standard
3206 Rule of thumb: any sentence you can express as,
3207 \begin_inset Quotes eld
3211 \begin_inset Quotes erd
3215 \begin_inset Quotes eld
3219 \begin_inset Quotes erd
3226 \begin_layout Enumerate
3228 We all hear way, way too much garbage English on the TV every day in the
3230 Some people think it makes speech better.
3232 It makes speech baroque, if not outright byzantine.
3233 With a little effort, you can wean yourself off of it.
3236 \begin_layout Enumerate
3239 will make you rewrite
3241 anything in the passive voice.
3242 It's awkward and hard to read.
3245 \begin_layout Enumerate
3246 Note to non-Americans:
3250 \begin_layout Standard
3251 Using passive voice is generally considered bad style in the U.
3252 \begin_inset space ~
3256 \begin_inset space ~
3259 as it is too easy to obfuscate your words with it.
3260 It also bloats sentences, often unnecessarily.
3264 \begin_layout Subsubsection
3269 \begin_layout Standard
3270 In English, there is a grammatical error known as the
3271 \begin_inset Quotes eld
3275 \begin_inset Quotes erd
3278 The classic example of a run-on sentence is 7 clauses strung together with
3280 \begin_inset Quotes eld
3284 \begin_inset Quotes erd
3287 There are, however, less obvious run-on sentences, ones using too many
3288 subordinate clauses.
3289 Such sentences may look elegant because they are complex.
3290 However, they are also extremely difficult to read because they are so
3294 \begin_layout Standard
3295 In general, stick to short sentences in written English.
3296 Getting rid of passive voice (
3297 \begin_inset Quotes eld
3300 \SpecialChar \ldots{}
3301 was done by\SpecialChar \ldots{}
3303 \begin_inset Quotes erd
3306 ) shortens and simplifies them.
3307 Hacking apart sentences with many dependent clauses is another way to shorten
3309 There are ways to do this yet still have a smooth-flowing paragraph.
3312 \begin_layout Standard
3313 While I'm talking about paragraphs, I'll apply the
3314 \begin_inset Quotes eld
3318 \begin_inset Quotes erd
3321 motto to them, as well.
3322 At the time I started with the manuals (and this Style Sheet), I didn't
3323 pay too much attention to paragraph size.
3324 I've since become a big proponent of short paragraphs, with one idea per
3326 While long, flowing, multi-concept paragraphs can be nice in novels, we're
3328 Our goal is rapid information location and comprehension, not a literary
3332 \begin_layout Standard
3333 There is a single exception to the short sentence, short paragraph rule.
3334 Particularly complex ideas may need more
3335 \begin_inset Quotes eld
3339 \begin_inset Quotes erd
3342 However, you shouldn't encounter such complex ideas often when documenting
3344 Try to keep things short, and use your judgement as needed.
3347 \begin_layout Standard
3348 To reiterate, yet again, something I said before:
3352 When in doubt, compromise.
3356 When in doubt, use good judgement.
3359 \begin_layout Standard
3360 Hopefully, you've got the idea (grin).
3363 \begin_layout Section
3367 \begin_layout Subsection
3368 Rules of the Translating Trade
3371 \begin_layout Standard
3372 While translating anything, there are certain
3373 \begin_inset Quotes eld
3377 \begin_inset Quotes erd
3381 They will help you greatly.
3384 \begin_layout Subsubsection
3385 Translate one paragraph at a time.
3388 \begin_layout Standard
3389 Most people translate word by word.
3390 Clearly, you lose all context if you do that.
3391 A word may have multiple meanings.
3392 You can't tell which unless you look at the rest of the sentence.
3395 \begin_layout Standard
3396 There is another level to the context issue, however.
3397 Your dictionary may translate multiple English words the same way.
3398 All those words mean
3403 Each one, however, covers a different shade of meaning, a different mood
3405 It is often difficult to resolve those shades of meaning in the context
3406 of even one sentence.
3407 A paragraph, however, will provide that context.
3410 \begin_layout Subsubsection
3411 You will not translate it correctly on the first try.
3414 \begin_layout Standard
3415 Alright, I admit that you may be able to translate some of the sentences
3417 If you know a language well, you may even understand over half of the text.
3418 Nevertheless, overconfidence can lead you astray.
3419 There will be some sentences, no matter how few, that will simply confound
3423 \begin_layout Standard
3424 It is generally a good idea to make multiple passes over a paragraph you're
3426 Even if you translate the entire paragraph on the first pass, make a second
3428 You'll often improve upon your first attempt.
3431 \begin_layout Subsubsection
3432 When in doubt, write down all of the meanings for a word.
3435 \begin_layout Standard
3436 You can often translate tricky parts of a text using the context of the
3437 surrounding sentences.
3438 So, if you hit a word or phrase you don't know, translate it more than
3440 Picking the most likely translations, summarize them in one to three words
3442 \begin_inset Quotes eld
3446 \begin_inset Quotes erd
3453 \begin_layout Subsubsection
3454 Using context, fix the meanings on the next pass.
3457 \begin_layout Standard
3458 This is where your multiple translations of a single word become useful.
3459 Using the other sentences you translated, you can now translate that mystery--s
3460 entence without reconsulting your dictionary.
3463 \begin_layout Subsubsection
3464 Fix the grammar only after you've finished translating the sentence.
3467 \begin_layout Standard
3468 If there's a mystery phrase in the middle of a sentence, you can't translate
3469 the entire sentence.
3470 Why grammatically rearrange the words you translated already? You may need
3471 to restructure the sentence a second time once you figure out how to translate
3472 that mystery phrase.
3473 Better to wait until you've completely translated the sentence to clean
3475 That way, you do so only once.
3478 \begin_layout Subsubsection
3479 If you can't translate it, skip it and come back to it on the next pass.
3482 \begin_layout Standard
3483 Remember the earlier discussion of context and its immense usefulness? There
3484 is no sin in making multiple passes over a tricky passage.
3487 \begin_layout Subsubsection
3488 Translate the meaning first.
3492 \begin_layout Standard
3493 The information content of the text under translation is the most important
3495 This is especially important for a manual, where the information
3499 important part of the original document.
3500 Lose that, and you lose the very point of performing the translation.
3503 \begin_layout Subsection
3504 Tips for the Translators
3507 \begin_layout Standard
3508 Those of you contributing to a translation of the LyX manuals must follow
3509 a modified set of rules.
3510 The first few rules are analogous to those in section
3511 \begin_inset space ~
3515 \begin_inset CommandInset ref
3517 reference "sec:english-only"
3522 There are additional rules and regulations that follow those first few.
3526 \begin_layout Subsubsection
3527 Write as if you are explaining LyX to a colleague you know well.
3530 \begin_layout Enumerate
3531 Think that way when you write.
3532 Play the dialogue in your mind.
3535 \begin_layout Enumerate
3536 Use a conversational style in your writing.
3537 Pretend you are teaching LyX to a colleague you know well.
3540 \begin_layout Enumerate
3541 Use a style that is polite without being too formal.
3542 If, in your culture, informal language is appropriate to use with a colleague,
3543 use informal speech in the translation of the manual.
3546 \begin_layout Subsubsection
3547 AVOID Snobby, Academic, Specialized, or
3548 \begin_inset Quotes eld
3552 \begin_inset Quotes erd
3559 \begin_layout Standard
3560 In English, the passive voice appears formal, dry, barren.
3561 It also often adds unnecessary complexity.
3562 In other langauges, however, this is not the case.
3563 There is nothing wrong with passive voice, and people use it frequently
3564 in everyday conversation.
3565 Nevertheless, your translation of the LyX manuals must avoid
3566 \begin_inset Quotes eld
3570 \begin_inset Quotes erd
3576 \begin_layout Standard
3577 In Germany, there is a magazine known as
3578 \begin_inset Quotes gld
3582 \begin_inset Quotes grd
3585 The writing in it is so complex, it is extremely difficult for non-native
3586 German speakers to understand.
3587 While sophisticated, the writing style of
3588 \begin_inset Quotes gld
3592 \begin_inset Quotes grd
3595 is not what a German uses in everyday conversation.
3596 Nor is the writing style for a Russian mathematics journal.
3597 Such specialized or overly-sophisticated styles are
3598 \begin_inset Quotes eld
3602 \begin_inset Quotes erd
3605 in the sense that they are seldom used by normal people in everyday speech.
3608 \begin_layout Standard
3609 We who write the LyX manuals, original or translated, seek to
3614 If we write in a style only a few people use, and use seldomly, we will
3616 Use a writing style that mirrors everyday speech (without being vulgar,
3621 \begin_layout Subsubsection
3622 Keep the Writing Simple.
3625 \begin_layout Standard
3626 For the English version, I wrote,
3627 \begin_inset Quotes eld
3630 Use short sentences and short paragraphs.
3631 \begin_inset Quotes erd
3634 What if, however, short sentences and paragraphs are something only children
3635 use in your language? What if, in yet another language, short sentences
3636 imply rudeness? Naturally, you would not want to use them in your translation.
3639 \begin_layout Standard
3640 Nevertheless, the translations of the LyX manuals should be as clear as
3642 So, for our international colleagues, we apply this rule: Keep your sentences
3643 and paragraphs as short as makes sense.
3646 \begin_layout Standard
3647 Remember: we're translating manuals here, folks.
3648 Our goal is rapid information location and comprehension, not a literary
3650 Try to keep your writing concise yet smooth-flowing.
3651 And use your judgement as needed:
3655 When in doubt, compromise.
3659 When in doubt, use good judgement.
3662 \begin_layout Subsubsection
3663 Translators must follow the Style Sheet, too!
3666 \begin_layout Standard
3667 Everything in this manual ---
3670 \begin_inset space ~
3674 \begin_inset CommandInset ref
3676 reference "sec:english-only"
3682 --- applies to every LyX documenter, no matter what the language.
3685 \begin_layout Subsubsection
3686 Translators must read the Style Sheet Supplement for their language.
3689 \begin_layout Standard
3690 For every translation project, there is a Supplement to the Style Sheet.
3697 DocStyle_Supplement_<cn>.lyx
3700 \begin_layout Standard
3701 \SpecialChar \ldots{}
3703 \begin_inset Quotes eld
3711 \begin_inset Quotes erd
3714 is your language's two-letter locale code.
3715 The Translation Project Chief for your language wrote this.
3716 If he hasn't, pester him to do so! <
3723 \begin_layout Subsubsection
3724 The English versions of the manuals are not Sacred Text.
3727 \begin_layout Standard
3728 You do not need to translate everything word for word.
3729 In fact, you shouldn't.
3730 Keep to the spirit of the originals, not the letter.
3731 Be as creative as you want, as long as you
3739 convey all of the information contained in the English versions.
3742 \begin_layout Subsubsection
3743 Any information in the LyX manuals must also be in the translations.
3746 \begin_layout Standard
3747 \begin_inset CommandInset label
3753 This falls under translating the orignals accurately and completely.
3757 \begin_layout Itemize
3758 Omitting any feature description is
3765 \begin_layout Itemize
3766 Misrepresenting or misdescribing any LyX feature or operation
3773 \begin_layout Itemize
3778 outpace the original.
3779 \begin_inset Newline newline
3782 If no one has documented new feature in the primary LyX manuals (i.
3783 \begin_inset space ~
3787 \begin_inset space ~
3790 the English versions), do not do so in the translations.
3791 If you're really looking for something to do, either:
3795 \begin_layout Itemize
3796 \SpecialChar \ldots{}
3797 focus on translating something you haven't yet,
3798 \begin_inset Newline newline
3804 \begin_layout Itemize
3805 \SpecialChar \ldots{}
3806 update or repair the primary manual.
3809 \begin_layout Standard
3810 If you cannot or do not want to do one of the above, then take a break.
3812 Wait for the main manuals to catch up before translating anything else.
3816 \begin_layout Subsubsection
3817 What you cannot translate, you may omit (usually).
3820 \begin_layout Standard
3821 Prepositions, idioms, metaphors, slang, Oh My! There's a jungle of potentially
3822 untranslatable text you may face.
3823 Happily, none of these untranslatables are essential to the original text\SpecialChar \ldots{}
3826 If you can't translate a phrase or two, try omitting them.
3827 If the rest of the paragraph still makes sense, then don't worry about
3831 \begin_layout Standard
3832 There may be special cases where omitting part of a sentence or paragraph
3834 \begin_inset space ~
3838 \begin_inset CommandInset ref
3840 reference "sec:accuracy"
3849 You must try and translate those tricky spots.
3852 \begin_layout Subsubsection
3853 Translators may add their own fluff to the information content.
3856 \begin_layout Standard
3857 After you do strip away all of the idioms, metaphors, slang, humor, and
3859 \begin_inset Quotes eld
3863 \begin_inset Quotes erd
3866 you may find that your translated manual is dull and dry.
3867 Why not add your own fluff? Add text that makes the manual a pleasure to
3868 read, that engages the reader.
3869 It may take the form of humor, or metaphors, or sayings.
3870 Whatever you add, it should be
3871 \begin_inset Quotes eld
3875 \begin_inset Quotes erd
3878 It should not clash with the explanation of LyX features and functions.
3881 \begin_layout Subsection
3882 For Translation Project Chiefs
3885 \begin_layout Subsubsection
3886 The First Is In Charge
3889 \begin_layout Standard
3890 If you were the first person to start translating the manuals, you're the
3891 LyXDoc Translation Project Chief for your language.
3896 person translating the LyXDocs, that automatically makes you the Translation
3900 \begin_layout Standard
3901 Amongst other things, that means that you must read this section and perform
3902 the tasks described here.
3905 \begin_layout Standard
3906 If you are a member of a LyX Documentation Translation Team, but
3910 its Chief, you may stop reading.
3911 The remainder of this section will be of no interest to you.
3912 If you came to the Style Sheet from the Supplement for your language, you
3916 \begin_layout Standard
3917 If you have not read the Style Sheet Supplement for your language, you should
3922 \begin_layout Subsubsection
3923 Read the Style Sheet
3926 \begin_layout Standard
3927 No documenter is excused from following the Style Sheet, not even a Translation
3931 \begin_layout Standard
3936 important that the Translation Project Chiefs read the Style Sheet.
3939 \begin_layout Subsubsection
3940 Make your translators read the Style Sheet
3943 \begin_layout Standard
3944 No documenter is excused from following the Style Sheet.
3947 \begin_layout Standard
3948 Since your translation team is translating, they know
3953 Therefore, they should be able to read the Style Sheet.
3956 \begin_layout Subsubsection
3958 \begin_inset Quotes eld
3962 \begin_inset Quotes erd
3968 \begin_layout Standard
3969 There are parts of this Style Sheet that are English-specific.
3970 I have tried to provide a general, language-independent description of
3971 certain details in this section.
3972 Unfortunately, that general description doesn't cover the specifics of
3977 \begin_layout Standard
3978 That's where you, as head of a LyXDoc Translation Team, come in.
3981 \begin_layout Standard
3982 Every Translation Team Chief is
3986 to write a Supplement to the official Documentation Style Sheet, with specifics
3987 issues affecting your language.
3988 (You are, after all, the LyX Team expert on your native tongue.) Follow
3989 these guidelines when writing the Supplement:
3992 \begin_layout Enumerate
3994 \begin_inset Newline newline
3999 DocStyle_Supplement_<cn>.lyx
4002 \begin_inset Newline newline
4005 \SpecialChar \ldots{}
4007 \begin_inset Quotes eld
4015 \begin_inset Quotes erd
4018 is the two-letter code for your language.
4019 This is the same two-letter code that is part of the filenames for the
4022 \begin_inset Quotes eld
4030 \begin_inset Quotes erd
4034 \begin_inset Quotes eld
4042 \begin_inset Quotes erd
4046 \begin_inset Quotes eld
4054 \begin_inset Quotes erd
4060 \begin_layout Enumerate
4061 Do not worry about where the file goes.
4062 The CVS maintainers will locate all documentation and Style Sheet Supplements
4063 in an appropriate place.
4066 \begin_layout Enumerate
4067 Document Properties:
4071 \begin_layout Itemize
4072 For consistency, use the same document class and other document properties
4077 \begin_layout Plain Layout
4078 Specifically, check the settings in the
4083 Use those in your Supplement.
4091 \begin_layout Itemize
4092 Exceptions: Use margins, indentation/paragraph separation, language, and
4093 encoding appropriate for your language.
4097 \begin_layout Enumerate
4098 The title of the Supplement:
4102 \begin_layout Itemize
4103 The title will use the
4104 \begin_inset Quotes eld
4112 \begin_inset Quotes erd
4115 paragraph environment.
4116 In your native tongue, the title will read:
4120 \begin_layout Standard
4123 Documentation Project Style Sheet:
4124 \begin_inset Newline newline
4127 Supplement for the <foo> Translation Project
4130 \begin_layout Standard
4132 \begin_inset Quotes eld
4140 \begin_inset Quotes erd
4143 with the name of your language.)
4147 \begin_layout Itemize
4148 If, in your language,
4149 \begin_inset Quotes eld
4153 \begin_inset Quotes erd
4157 \begin_inset Quotes eld
4161 \begin_inset Quotes erd
4166 \begin_inset Quotes eld
4170 \begin_inset Quotes erd
4174 \begin_inset Quotes eld
4178 \begin_inset Quotes erd
4181 have somewhat different meanings.
4182 An appendix is an extra part of a document.
4183 A supplement is an extra document.
4188 \begin_layout Standard
4189 Choose a replacement word accordingly.
4190 Whatever you choose to replace
4191 \begin_inset Quotes eld
4195 \begin_inset Quotes erd
4198 it must not have the same translation as the word
4199 \begin_inset Quotes eld
4203 \begin_inset Quotes erd
4211 \begin_layout Enumerate
4212 Below the title, in the
4213 \begin_inset Quotes eld
4221 \begin_inset Quotes erd
4224 paragraph environment, place your name.
4228 \begin_layout Standard
4229 There will be no abstract.
4233 \begin_layout Enumerate
4242 \begin_layout Standard
4243 The first thing you will do is strongly yet politely encourage the reader
4245 \begin_inset Quotes eld
4249 \begin_inset Quotes erd
4252 and go read the Style Sheet.
4253 The reader should not return to the
4254 \begin_inset Quotes eld
4258 \begin_inset Quotes erd
4265 understood the Style Sheet proper.
4269 \begin_layout Subsubsection
4270 Keep the Supplement Succinct
4273 \begin_layout Standard
4274 This Style Sheet is already very detailed.
4275 DocTeam members all have a lot to read.
4276 We don't want to place an extra burden on translators.
4277 Therefore, keep the Supplement as short as you can without losing information.
4280 \begin_layout Subsubsection
4284 \begin_layout Standard
4289 will be about font issues\SpecialChar \ldots{}
4291 Not all Translation Project Chiefs will need to deal with this issue.
4295 \begin_layout Itemize
4301 \begin_layout Itemize
4307 \begin_layout Itemize
4309 \begin_inset Newline newline
4314 Emphasized (actually Italics)
4317 \begin_layout Itemize
4323 \begin_layout Itemize
4329 \begin_layout Itemize
4332 Noun (actually Small Caps)
4335 \begin_layout Standard
4336 \SpecialChar \ldots{}
4337 certainly exist for all languages that use the Roman alphabet.
4338 Do they exist, however, for Greek? How about Cyrillic? These different
4339 fonts almost certainly do not exist for Devanagri, Chinese, Korean, Japanese,
4340 Hebrew, Arabic, and other scripts.
4344 \begin_layout Standard
4345 There will be some languages for which following the font-scheme specified
4346 in this Style Sheet may not be possible.
4347 If you are the Translation Project Chief for such a language, you have
4351 \begin_layout Standard
4352 In the font section of the Supplement, you will provide a new typographic
4353 style, designed specifically for your writing system.
4354 For consistency, the title of this section in every Supplement should translate
4356 \begin_inset Quotes eld
4360 \begin_inset Quotes erd
4363 Before adding anything to this section, however, determine what this new
4364 typographic style will look like.
4365 Stick to the font specifications in this Style Sheet as best you can, whenever
4367 When you cannot, use the following suggestions:
4370 \begin_layout Itemize
4372 \begin_inset Quotes eld
4376 \begin_inset Quotes erd
4380 \begin_inset Newline newline
4384 \begin_inset Newline newline
4387 What to do when a font doesn't exist:
4392 \labelwidthstring MMMMMMMM
4393 Roman Use the font that typesetters in your language use for printing books,
4395 This will typically be the default font LyX (and LaTeX) uses in your language.
4399 \labelwidthstring MMMMMMMM
4403 \begin_inset space ~
4408 This is for people's names.
4409 If there is special font for names in your alphabet/writing system, use
4410 it in place of this.
4411 Otherwise, write names in the default font, typeset according to the rules
4416 \labelwidthstring MMMMMMMM
4421 Use the font with which your language normally emphasizes text.
4425 \begin_layout Standard
4426 Use a font that is different from your language's equivalent of
4431 In other words, your
4439 and similar headers will be in one typeface, perhaps
4444 Whatever that font is, avoid using it for
4453 \labelwidthstring MMMMMMMM
4458 Pick up a computer program manual written in your language.
4459 It will use a special typeface for filenames, for command names, program
4461 Use that same font in place of
4469 \labelwidthstring MMMMMMMM
4473 \begin_inset space ~
4478 Pick any other font that is different from the ones you're using in place
4492 If you're unlucky, and your language's writing system doesn't have enough
4493 fonts, use the same font you picked to replace
4498 Only do this, however, if your alphabet/writing system has very few fonts
4503 \labelwidthstring MMMMMMMM
4510 \begin_inset space ~
4514 \begin_inset space ~
4519 Don't worry about this one.
4523 \begin_layout Standard
4524 If you use some special font on-screen to highlight the accelerator keys
4525 for menus, buttons, and other widgets, you might want to mimic that in
4527 It is not required, however.
4528 Therefore, if you can't mimic this typographic convention in your native
4529 writing system, don't.
4534 \begin_layout Standard
4535 Note that you may also want to describe fonts that your Translation Team
4541 For example, no contributer to the English/European versions may ever use
4546 , as this is used for section-headings.
4547 Since there are enough other fonts, we who use the Roman alphabet and its
4548 variants can afford to omit
4556 \begin_layout Standard
4557 Once you have determined which fonts in your native writing system will
4558 replace one or more of the above, propose it to the LyX Developer's Mailing
4560 You may receive valuable feedback this way.
4561 If not, that's okay.
4562 If no one can read your writing system, and therefore cannot comment, that's
4564 Go ahead and describe the typographic standard you created in the Supplement.
4568 \begin_layout Standard
4569 Remember: stick to the font specifications in this Style Sheet as best you
4570 can, whenever you can.
4573 \begin_layout Subsubsection
4574 Quoting Style and the
4586 \begin_layout Standard
4587 The next section of the Supplement will cover the issue of quoting.
4588 Give it an appropriate title.
4591 \begin_layout Standard
4592 One of the first things you should do in that section is resolve the following
4596 \begin_layout Itemize
4605 is the correct paragraph environment for your language.
4608 \begin_layout Itemize
4609 In the Supplement, specify which one to use.
4612 \begin_layout Standard
4613 English has its own typography and style for quoting others.
4614 The Style Sheet describes that typography in section
4615 \begin_inset space ~
4619 \begin_inset CommandInset ref
4621 reference "sec:quote"
4626 Your language also has a specific typography and style for quotations.
4627 Describe that style in this section of the Supplement, too.
4628 Naturally, you do not need to go overboard.
4630 \begin_inset space ~
4634 \begin_inset CommandInset ref
4636 reference "sec:quote"
4640 of this Style Sheet is overly detailed for a good reason.
4641 Authors of the primary LyX manuals are not necessarily native English speakers.
4642 The members of your Translation Team, however, will all likely be native
4643 speakers of your language.
4644 Therefore, discuss proper quoting style of your native tongue to an appropriate
4648 \begin_layout Subsubsection
4649 Translations of Style Sheet Terminology
4652 \begin_layout Standard
4653 In the Supplement, you must provide a standard translation of certain key
4654 phrases for the members of your Translation Team.
4655 Place this in a section following the one about quotations.
4658 \begin_layout Standard
4659 In particular, standardize the translations of the phrases:
4662 \begin_layout Itemize
4668 \begin_layout Itemize
4674 \begin_layout Standard
4679 change the typography of the
4680 \begin_inset Quotes eld
4684 \begin_inset Quotes erd
4688 \begin_inset Quotes eld
4692 \begin_inset Quotes erd
4696 Only provide a translation for the opening phrases.
4697 Insist that the members of your Translation Team use these two tools correctly.
4700 \begin_layout Standard
4701 While we are discussing proper use of the
4702 \begin_inset Quotes eld
4706 \begin_inset Quotes erd
4710 \begin_inset Quotes eld
4714 \begin_inset Quotes erd
4717 in translations, let's talk about a related problem.
4719 \begin_inset Quotes eld
4723 \begin_inset Quotes erd
4726 is meant to be a note from the author of a manual to the reader.
4727 In the case of a translation, however, the translator is
4731 the author! How then should a translator translate an
4732 \begin_inset Quotes eld
4736 \begin_inset Quotes erd
4742 \begin_layout Standard
4743 You, as Translation Project Chief, must decide.
4744 You can forbid translation of pre-existing
4745 \begin_inset Quotes eld
4749 \begin_inset Quotes erd
4752 omitting them entirely instead.
4753 You could tell your translators to read any
4754 \begin_inset Quotes eld
4758 \begin_inset Quotes erd
4761 they may encounter, understand it, then write their own
4762 \begin_inset Quotes eld
4766 \begin_inset Quotes erd
4769 about the situation, not as a translation but as a personal opinion.
4770 You may decide on some other policy.
4773 \begin_layout Standard
4774 Whatever you decide, codify your policy in its own
4783 Place it near the section where you translated
4784 \begin_inset Quotes eld
4788 \begin_inset Quotes erd
4792 \begin_inset Quotes eld
4796 \begin_inset Quotes erd
4802 \begin_layout Subsubsection
4806 \begin_layout Standard
4807 After describing all of the previous issues, create a new
4813 \begin_inset Quotes eld
4816 Lost in Translation,
4817 \begin_inset Quotes erd
4820 or something similar.
4823 \begin_layout Standard
4824 In this section you will discuss any common English metaphors, humor, connotatio
4825 n, or other difficult to translate text.
4826 Try to balance brevity and completeness.
4835 s --- to each specific issue.
4838 \begin_layout Subsubsection
4839 \SpecialChar \ldots{}
4841 \begin_inset Quotes eld
4845 \begin_inset Quotes erd
4848 \SpecialChar \ldots{}
4852 \begin_layout Standard
4853 Throughout the manuals, the DocTeam has used the following sentences:
4857 If you haven't read the <
4861 > manual, go read it.
4865 \begin_layout Standard
4866 This sentence will be tricky to translate, since it contains non-translatable
4872 for this issue in your
4873 \begin_inset Quotes eld
4877 \begin_inset Quotes erd
4882 \begin_inset Quotes eld
4885 \SpecialChar \ldots{}
4886 Yes, we mean now\SpecialChar \ldots{}
4888 \begin_inset Quotes erd
4891 sentences, then present a translation, along with any explanation you feel
4895 \begin_layout Standard
4896 Here's what those two sentences, sitting alone in their own paragraph, mean:
4899 \begin_layout Standard
4900 The first sentence uses the English conditional followed by an imperative.
4901 We, as the LyX team, are commanding the reader to go back to another manual.
4906 manual is a prerequisite for all of the other manuals.
4907 The conditional clause preceeding the command means,
4908 \begin_inset Quotes eld
4911 You do not need to perform this command twice.
4912 \begin_inset Quotes erd
4918 \begin_layout Standard
4919 The second sentence adds force to the command.
4920 Culturally, the imperative tense of a verb in English is not necessarily
4922 The way we wrote that command,
4923 \begin_inset Quotes eld
4927 \begin_inset Quotes erd
4930 is firm, yet polite.
4931 The reader may choose to ignore it.
4933 \begin_inset Quotes eld
4937 \begin_inset Quotes erd
4940 we imply two things.
4942 \begin_inset Quotes eld
4946 \begin_inset Quotes erd
4950 That second sentence reinforces the command, making it a bit harder to
4952 Second, the sentence itself implies a certain sense of urgency.
4953 You cannot merely wait until later to fulfill that command.
4954 The brief pragraph, and its sudden end, add still further subtle reinforcement
4956 \begin_inset Quotes eld
4959 go do the required reading before using this manual.
4960 \begin_inset Quotes erd
4966 \begin_layout Standard
4967 Note that all of this commanding and reinforcing is nevertheless in a polite
4969 Furthermore, it is in a subtle form.
4970 We are commanding the reader to do something, but in an indirect fashion.
4971 This way, the reader does not feel like we are bullying him.
4974 \begin_layout Subsubsection
4979 \begin_layout Standard
4980 In the same part of the Supplement that you place the
4981 \begin_inset Quotes eld
4984 \SpecialChar \ldots{}
4985 Yes, we mean now\SpecialChar \ldots{}
4987 \begin_inset Quotes erd
4990 translation, discuss the English version's use of
4991 \begin_inset Quotes eld
4995 \begin_inset Quotes erd
5001 \begin_layout Standard
5002 You see, here in America, we often say that everything is permitted unless
5003 explicitly banned by law.
5004 As a result, manuals for computer software are frequently ignored and the
5005 software subsequently blamed for not being
5006 \begin_inset Quotes eld
5010 \begin_inset Quotes erd
5013 This is where the use of
5014 \begin_inset Quotes eld
5018 \begin_inset Quotes erd
5025 \begin_layout Standard
5026 We who wrote the manuals added sentences insisting that the reader not ignore
5027 certain parts of the documentation.
5028 We wrote in a manner that was polite, yet firmly asserted that the user
5029 was misusing the software if he did not read the manual correctly.
5030 We did not, however, want to sound threatening, coercive, or bullying.
5033 \begin_layout Standard
5034 In your culture, cajoling the reader into using the manuals correctly may
5036 It may, in fact, be outright rude.
5037 Additionally, translating the firm-but-convincing bits may not work.
5038 The translation may sound weird, or rude, or hostile.
5039 Therefore, you and your translation team will face many sentences that
5040 you cannot translate.
5043 \begin_layout Standard
5044 You, the Translation Project Chief, must discuss this issue.
5045 Try and find parts of the original manuals where some friendly but firm
5046 convincing does not translate properly.
5047 Use these cases as the basis for examples of the problem.
5048 Be sure to then offer a solution (i.
5049 \begin_inset space ~
5053 \begin_inset space ~
5056 how you want such sentences translated.) If stumped, ask for help on the
5057 LyX Developer's List.
5060 \begin_layout Subsubsection
5064 \begin_layout Standard
5065 You can add more sections to the Supplement if you need to discuss other
5067 There may be policies or guidelines that you want to set for your Translation
5069 Be careful, however! Keep the Supplement