1 #LyX 1.6.0rc5 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
46 Documentation Project Style Sheet
53 \begin_layout Abstract
54 This article is a style sheet.
55 It describes, with examples, how the documentation should look and sound.
56 The first few sections explain the font conventions and typography conventions
57 all documentation writers should follow.
58 Those sections also contain examples.
59 It also explains the purpose of each of the different manuals.
60 Follow it not merely to the letter, but also in spirit.
63 \begin_layout Abstract
64 The Style Sheet for LyX documentation (hereafter known as the Style Sheet)
69 forms of LyX documenation, regardless of language.
70 There is a section for translators in the Style Sheet, towards the end.
73 Read the entire Style Sheet!
75 Even if you are a translator, I assume you know enough English to comprehend
80 Questions and Clarifications
83 \begin_layout Standard
84 After the second version of this Style Sheet grew uncomfortably large, the
85 LyX DocTeam decided it needed to lose some excess weight.
86 It seems the Style Sheet began to specify too many special cases, too many
87 points of clarification.
88 On the other hand, contributors to the documents were discovering many
89 creative ways of misinterpreting the Style Sheet specifications.
94 If you have any questions about anything in the Style Sheet,
96 ask first, write second!
99 \begin_layout Standard
100 Field all questions to the LyX Developer's Mailing List.
101 There are seasoned DocTeam members who can answer your questions.
102 If you have any problems with the Style Sheet itself, also contact the
106 \begin_layout Section
110 \begin_layout Standard
111 We'll start with the easiest section, yet also the most important.
114 \begin_layout Standard
115 This is how you should fontify text in the manuals:
119 \labelwidthstring MMMMMMMM
124 general emphasis, generic arguments, titles of books, names the other manuals
125 and of their sections, and notes from the authors
129 \begin_layout Standard
130 Do not overemphasize your text.
135 \labelwidthstring MMMMMMMM
140 program names, file names,
144 -page names, LaTeX code, LaTeX commands, LaTeX package names, and LyX code
149 \labelwidthstring MMMMMMMM
158 menu, button, or popup names, the names/lables of all widgets in a popup,
159 the names of keyboard keys, and certain
160 \begin_inset Quotes eld
164 \begin_inset Quotes erd
171 \labelwidthstring MMMMMMMM
184 \labelwidthstring MMMMMMMM
200 Rich Fields added this to mimick the underlining of letters in the menus
202 It helps to highlight the accelerator keys, and human brains store information
203 best when they see it frequently.
207 \begin_layout Description
208 WARNING! --- When you do this, make sure you
212 shut off the underlining.
213 Too many people send in things that look like:
214 \begin_inset Newline newline
224 \begin_inset Newline newline
227 \SpecialChar \ldots{}
236 they not only shut off underlining, they turned off
248 Make sure the entire word is still in
256 after you shut off the underlining.
261 \labelwidthstring MMMMMMMM
270 \begin_layout Standard
271 If you want to emphasize any text, use
276 LaTeX will put many things boldface on its own, such as
280 s, certain parts of equations, et cetera.
283 \begin_layout Standard
284 Repeat: do not use boldface.
288 \begin_layout Standard
289 Here are some examples:
292 \begin_layout Enumerate
297 appears in configuration files and in the LyX source.
298 Therefore, it (and all other LyX function names) count as code and is set
306 \begin_layout Enumerate
318 is a menu item in the
325 menu, so it appears in
349 for the accelerator keys.
352 \begin_layout Enumerate
353 Consider the following excerpt from the introduction of one of the manuals:
357 \begin_layout Quotation
366 both refer to the same key.
367 Some keyboards label the
372 \begin_inset Quotes eld
376 \begin_inset Quotes erd
380 \begin_inset Quotes eld
384 \begin_inset Quotes erd
387 still others have two keys.
388 LyX treats all of them as the same key, so we'll use
399 \begin_layout Standard
400 Notice that the key name,
416 when it references the key itself! When I described how the manufacturer
417 chose to label its keyboard, I used Roman and put the word in quotes.
418 There is a semantic difference.
422 \begin_layout Enumerate
423 Take the following command:
427 \begin_layout Standard
436 \begin_layout Standard
437 Notice that the argument to the
446 \begin_inset space \thinspace{}
451 This is a case where you don't use
455 for code, because you want the generic argument label to stand out.
456 On the other hand, if you were specifying an argument, for example,
457 \begin_inset Quotes eld
465 \begin_inset Quotes erd
477 \begin_layout Enumerate
478 Any LaTeX commands and code, and any
482 LaTeX package names get set in
488 \begin_inset Quotes eld
496 \begin_inset Quotes erd
499 is the name of an unsupported LaTeX package, but
500 \begin_inset Quotes eld
508 \begin_inset Quotes erd
511 is a supported LaTeX class.
514 \begin_layout Section
518 \begin_layout Standard
519 The canonical keyboard contains these keys:
522 \begin_layout Itemize
534 \begin_layout Itemize
546 \begin_layout Itemize
559 \begin_layout Standard
563 use the abbreviations
569 \begin_layout Itemize
572 F1 F2 F3 F4 F5 F6 F7 F8 F9 F10 F11 F12
576 \begin_layout Standard
578 Most modern keyboards have all 12.
582 \begin_layout Itemize
591 \begin_layout Standard
593 \begin_inset Quotes eld
597 \begin_inset Quotes erd
604 \begin_layout Itemize
631 \begin_layout Standard
632 These are the 6 keys that appear above the cursor keys on many PC keyboards.
633 Consider them as part of the standard motion keys.
637 \begin_layout Itemize
644 \begin_layout Standard
645 The four standard motion keys.
646 There is no need to put the word
647 \begin_inset Quotes eld
651 \begin_inset Quotes erd
654 anywhere, since that's obvious.
658 \begin_layout Plain Layout
660 \begin_inset Quotes eld
664 \begin_inset Quotes erd
669 \begin_inset Quotes eld
673 \begin_inset Quotes erd
676 after one of these may be redundant in certain situations.
685 \begin_layout Itemize
698 \begin_layout Standard
699 I won't throw a hissy fit if you use one instead of the other.
700 I'd prefer if you used
708 , but it's okay if you slip up and forget.
709 Since these two keys are bound to the same function in LyX, it doesn't
714 \begin_layout Standard
715 You do not need to explain everywhere what the
724 The user isn't stupid.
725 Also, someone will document anything that isn't clear (e.
742 problem) someplace in the introduction.
743 No need for you to repeat someone else's work.
746 \begin_layout Standard
747 LyX does not support keyboards missing any of the keys described above,
749 LyX can support a keyboard missing
758 There is a keyboard accelerator for
762 , but this is the only function key LyX assumes exists.
763 Nevertheless, these details are of minor, if any, concern for the documentation.
764 Assume the aforementioned keys exist.
767 \begin_layout Section
771 \begin_layout Standard
773 \begin_inset Quotes eld
777 \begin_inset Quotes erd
780 and any description of the 3 mouse buttons have no special handling.
781 Don't typeset them in any other font than the default, which is Roman.
785 \begin_layout Standard
786 Exception: you're writing an Author's Note (see section
787 \begin_inset CommandInset ref
789 reference "sec:author-notes"
793 ) and you need to mention something about the mouse.
794 Since the rest of the note is in
798 , your description of
799 \begin_inset Quotes eld
803 \begin_inset Quotes erd
806 should be emphasized, as well.
807 There are a couple of other cases like this one; use your judgement.
810 \begin_layout Standard
811 There are only 3 mouse buttons.
812 The use of them and of the mouse itself is obvious.
813 There are few --- if any --- nonstandard things we do with the mouse.
814 Therefore, there's no need to make the word
815 \begin_inset Quotes eld
819 \begin_inset Quotes erd
823 \begin_inset Quotes eld
827 \begin_inset Quotes erd
833 \begin_layout Section
837 \begin_layout Standard
841 \begin_layout Description
854 between the words for menu and widget names.
876 \begin_layout Standard
877 This holds for things in
890 If you have a long code example, one that can't simply be inlined and put
906 \begin_layout Standard
915 so that the name doesn't get split between two lines, which is visually
925 is near the end of a line and overflows the margin, use a
931 in that parargraph (consult a LaTeX book for more about
932 \begin_inset Quotes eld
942 \begin_inset Quotes erd
945 ) or manually add a hypenation point.
949 \begin_layout Description
954 Terms These are things like the following:
958 \begin_layout Itemize
966 \begin_layout Itemize
974 \begin_layout Itemize
984 \begin_layout Itemize
995 \begin_layout Standard
1004 font and, in the case of
1012 , capitalize the first two letters.
1015 \begin_layout Standard
1016 Why are these terms special? They are concepts which the seasoned LaTeX-pert
1017 is familiar with, but which the new LyX user is not.
1018 I want them to stand out from the rest of the text, hence the use of
1021 \begin_inset space ~
1031 \begin_layout Standard
1032 Seasoned LyX Team Members: Are there other terms that require this special
1033 status? On the other hand, should we eliminate this style completely?
1036 \begin_layout Description
1037 Terminology Note the following:
1040 \begin_layout Itemize
1041 \begin_inset Quotes eld
1045 \begin_inset Quotes erd
1049 \begin_inset Quotes eld
1053 \begin_inset Quotes erd
1057 \begin_inset Quotes eld
1061 \begin_inset Quotes erd
1066 \begin_inset Quotes eld
1070 \begin_inset Quotes erd
1074 \begin_inset Quotes eld
1078 \begin_inset Quotes erd
1084 \begin_layout Itemize
1085 PostScript® is a registered trademark of Adobe Corp.
1088 You must put the ® after it or we'll get sued!
1090 I also want it written as seen here, always capitalized.
1092 \begin_inset Quotes eld
1096 \begin_inset Quotes erd
1100 \begin_inset Quotes eld
1104 \begin_inset Quotes erd
1108 \begin_inset Quotes eld
1112 \begin_inset Quotes erd
1115 - both of them capitalized, in the default font (i.
1116 \begin_inset space ~
1120 \begin_inset space \thinspace{}
1124 \begin_inset space ~
1128 If you must, cut and paste it from here.
1132 \begin_layout Standard
1133 I am going to say this again:
1136 \begin_layout Standard
1137 \begin_inset VSpace 0.37cm
1143 \begin_layout Standard
1148 You must put the ® after PostScript® or we'll get sued!
1151 \begin_layout Standard
1152 \begin_inset VSpace 0.51cm
1158 \begin_layout Standard
1159 I mean it! American companies like to sue anything that moves.
1164 by forgetting that ®.
1170 \begin_layout Itemize
1171 Similarly, if you use any other registered trademark in any documentation,
1172 put the ® after it, too.
1175 \begin_layout Description
1177 \begin_inset space ~
1180 Items When quick-referencing an item in a menu, use the menu separator:
1182 \begin_inset Quotes eld
1185 \SpecialChar \menuseparator
1187 \begin_inset Quotes erd
1193 File\SpecialChar \menuseparator
1197 Notice that there are
1202 \begin_inset Quotes eld
1205 \SpecialChar \menuseparator
1207 \begin_inset Quotes erd
1213 \begin_inset space ~
1218 , just like the menu and item names.
1222 \begin_layout Enumerate
1223 The reason why I want no spaces around the
1224 \begin_inset Quotes eld
1227 \SpecialChar \menuseparator
1229 \begin_inset Quotes erd
1232 is to prevent LyX from splitting terms across lines.
1233 The same goes for using
1236 \begin_inset space ~
1241 s between multi-word terms.
1242 The split would be visually disruptive.
1245 \begin_layout Enumerate
1247 \begin_inset Quotes eld
1250 \SpecialChar \menuseparator
1252 \begin_inset Quotes erd
1255 goes between menu names and item names
1260 (Yes, submenus are okay, too).
1263 \begin_layout Enumerate
1269 \begin_inset Quotes eld
1272 \SpecialChar \menuseparator
1274 \begin_inset Quotes erd
1277 between menu items and dialog names.
1279 \begin_inset Quotes eld
1287 ayout\SpecialChar \menuseparator
1292 per\SpecialChar \menuseparator
1294 \begin_inset space ~
1300 \begin_inset Quotes erd
1305 IS STRICTLY FORBIDDEN!
1311 \begin_layout Standard
1317 \begin_inset Quotes eld
1320 \SpecialChar \menuseparator
1322 \begin_inset Quotes erd
1325 between popup names and any dialog.
1327 \begin_inset Quotes eld
1333 \begin_inset space ~
1336 Dialog\SpecialChar \menuseparator
1344 \begin_inset Quotes erd
1349 IS STRICTLY FORBIDDEN!
1352 \begin_layout Standard
1358 \begin_inset Quotes eld
1361 \SpecialChar \menuseparator
1363 \begin_inset Quotes erd
1366 between menu items and any dialog.
1368 \begin_inset Quotes eld
1376 ayout\SpecialChar \menuseparator
1381 per\SpecialChar \menuseparator
1389 \begin_inset Quotes erd
1394 IS STRICTLY FORBIDDEN!
1397 \begin_layout Standard
1398 Either write out the description, or use context to eliminate any need to
1399 repeat menu items, dialog names, etc.
1404 \begin_layout Description
1406 \begin_inset space ~
1409 Boxes LyX has a feature for adding comments that appear only within the
1412 \begin_inset Note Note
1415 \begin_layout Plain Layout
1416 These should NEVER appear in the manuals.
1422 You will see nothing in a printout of the Style Sheet.
1423 Therefore, they have no place in the manuals.
1429 \begin_layout Standard
1430 If you have a parenthetical comment you want to make, the reader should
1431 see it too, even in the printed version.
1432 Use an Author's Note (see section
1433 \begin_inset CommandInset ref
1435 reference "sec:author-notes"
1439 ) in place of the Note-Boxes.
1443 \begin_layout Description
1444 \begin_inset Quotes eld
1447 (\SpecialChar \ldots{}
1449 \begin_inset Quotes erd
1453 \begin_inset space ~
1457 \begin_inset Quotes eld
1460 [\SpecialChar \ldots{}
1462 \begin_inset Quotes erd
1466 \begin_inset space ~
1470 \begin_inset space ~
1474 \begin_inset Quotes eld
1477 {\SpecialChar \ldots{}
1479 \begin_inset Quotes erd
1482 I have recently been corrected about the use of parentheses.
1483 Standard English typesetting uses the normal parentheses,
1484 \begin_inset Quotes eld
1487 (\SpecialChar \ldots{}
1489 \begin_inset Quotes erd
1492 , around any aside, remark, or parenthetical expression.
1494 \begin_inset Quotes eld
1497 [\SpecialChar \ldots{}
1499 \begin_inset Quotes erd
1502 , is used only within quotations (see section
1503 \begin_inset space ~
1507 \begin_inset CommandInset ref
1509 reference "sec:quote"
1515 \begin_inset Quotes eld
1518 {\SpecialChar \ldots{}
1520 \begin_inset Quotes erd
1524 Therefore, never use
1525 \begin_inset Quotes eld
1528 [\SpecialChar \ldots{}
1530 \begin_inset Quotes erd
1534 \begin_inset Quotes eld
1537 {\SpecialChar \ldots{}
1539 \begin_inset Quotes erd
1542 unless otherwise specified by this Style Sheet.
1545 \begin_layout Description
1546 Dashes: Be sure to use the correct one.
1548 \begin_inset Quotes eld
1556 \begin_inset Quotes erd
1559 character is not a dash, it's a hyphen.
1560 Use it only as a hyphen.
1565 \begin_layout Standard
1567 \begin_inset Quotes eld
1571 \begin_inset Quotes erd
1575 \begin_inset Quotes eld
1579 \begin_inset Quotes erd
1583 \begin_inset Quotes eld
1591 \begin_inset Quotes erd
1594 characters form the en-dash.
1596 \begin_inset Quotes eld
1604 \begin_inset Quotes erd
1607 characters create an em-dash, which is slightly longer than the en-dash.
1608 In the printed version of any document, LyX will combine the two or three
1610 \begin_inset Quotes eld
1618 \begin_inset Quotes erd
1621 characters into a single, unbroken line.
1625 \begin_layout Section
1626 Cross-References and Labels
1629 \begin_layout Standard
1630 Use the following labelling conventions:
1634 \labelwidthstring 00.00.0000
1635 sec:xxx Use this for
1655 \labelwidthstring 00.00.0000
1656 eqn:xxx Use this for Equations, should you need to create any.
1660 \labelwidthstring 00.00.0000
1661 tbl:xxxx Use this for tables inside of a table float.
1665 \labelwidthstring 00.00.0000
1666 fig:xxx Use this for figures inside of figure floats.
1669 \begin_layout Standard
1670 Additionally, you should put the label at one of two locations:
1673 \begin_layout Enumerate
1676 beginning of the paragraph
1678 , after a section heading, or at the beginning of captions, etc.
1679 It should be the first thing on the first line.
1680 Don't put a space betweeen it and the first word.
1683 \begin_layout Enumerate
1684 If there is no paragraph after a section heading, put it at the
1686 end of the last line.
1693 \begin_layout Standard
1698 which is immediately followed by a
1703 This is a case where you need to put the label at the end of the
1708 I know it looks ugly; not much we can do about that, though.
1712 \begin_layout Section
1713 Content --- What Goes Where
1716 \begin_layout Standard
1721 important to anyone documenting a new feature.
1722 If you need to add new documentation, pay attention.
1726 \begin_layout Standard
1727 In the dim and distant past, whenever someone wanted to document a new feature
1728 they added, they either wrote a mini-doc and stuck it into the documentation
1729 directory, or they added a new section to the lone manual.
1730 No one paid much attention to organization in those days, either.
1731 The result was a totally bloated, totally unnavigable, and incomplete manual
1732 orbitted by a swarm of tiny, incomplete mini-docs.
1733 I don't want the docs to fall back into that mess.
1736 \begin_layout Standard
1737 With that in mind, I have some instructions for how to keep things organized:
1741 \labelwidthstring 00.00.0000
1746 Please, don't touch this file.
1747 It's essentially complete, anyhow.
1748 Only the editor(s) should make changes to this, as this file contains info
1749 about how to contribute to the doc project.
1750 That's really the only stuff that should need to change, and even then,
1751 only when a new maintainer comes along.
1755 \labelwidthstring 00.00.0000
1760 This file is complete.
1761 Any changes should be for updates
1766 DO NOT ADD new features to here willy-nilly.
1767 Let the editor decide if --- and when --- new sections go in here.
1768 Place any new features in\SpecialChar \ldots{}
1773 \labelwidthstring 00.00.0000
1778 This is where all new features go from now on.
1779 It's in the style of a bound journal --- each section is an
1780 \begin_inset Quotes eld
1784 \begin_inset Quotes erd
1787 from the author of the feature.
1788 Also, anyone who writes a
1792 file for a new document class should write a section describing that new
1793 class and how to use it.
1794 That also goes here.
1798 \begin_layout Standard
1799 Note, however, that you are
1803 excused from following this Style Sheet just because the sections of
1807 are in the form of a journal article.
1812 \labelwidthstring 00.00.0000
1817 This file is complete.
1818 Do not change or add to without permission of the Documenation Project
1823 \labelwidthstring 00.00.0000
1828 This document describes advanced features, most of which alter the look,
1829 feel, and behavior of LyX.
1830 This manual is still a bit incomplete, although that may change soon.
1831 Check for updates often.
1835 \begin_layout Standard
1836 If you are unsure whether or not something belongs in
1840 , then, most-likely, it
1849 Again, let the current editor of the LyX documentation decide if your new
1850 section should be migrated to
1859 \labelwidthstring 00.00.0000
1864 I'd prefer to completely finish this one before doing anything else, but
1866 LyX keeps changing so much that I think the
1870 will be the last one completed.
1871 However, I'd like it if the developer's would add entries anytime they
1872 create a new function or popup.
1873 That would help things immensely!
1877 \begin_layout Standard
1882 follows this Style Sheet for the most part.
1883 There are, however, additional rules to follow when making new entries.
1884 At the top of this manual, there are examples of and a template for
1893 \begin_layout Section
1894 Writing Style: The Primary Manuals
1897 \begin_layout Standard
1898 While I want to make contributing to the Documentation Project as painless
1899 as possible for newcomers, I also want the newcomers to be painless on
1900 the existing Documentation Team! Ergo, I've written this section to give
1901 some flavor to guide everyone's individual style.
1905 \begin_layout Subsection
1909 \begin_layout Standard
1910 All contributions to the
1914 LyX documentation must be in English.
1915 I don't care if it's British, Australian, or American English.
1916 The DocTeam editor will proofread for glaring mistakes and fix them.
1919 \begin_layout Standard
1920 Don't get hung up on semantics.
1921 English is a flexible language, and just because your Mothertongue-to-English
1922 dictionary gives only one translation for a word doesn't necessarily mean
1924 We've had some discussions and misunderstandings on the Developers' List
1925 because of this very problem.
1926 If something is unclear (or just plain weird) due to a translation problem,
1927 one of the American/British/Australian developers can fix it.
1930 \begin_layout Standard
1935 documentation, I exclude the translations.
1936 We usually don't have enough people to cover the manuals in one language,
1937 let alone more than one.
1938 Subsequently, the tranlsations are just that --- translations of the English
1939 version of the LyX manuals.
1940 The translation efforts require have their own set of guidelines.
1942 \begin_inset CommandInset ref
1944 reference "sec:translations"
1951 \begin_layout Subsection
1953 \begin_inset Newline newline
1956 Commentary from the Author (i.
1957 \begin_inset space ~
1963 \begin_layout Standard
1964 \begin_inset CommandInset label
1966 name "sec:author-notes"
1970 I want to make it easy for everyone when it comes to documenting things.
1971 Some features are incomplete.
1972 Some, you might not know everything about.
1973 Sometimes, you may want to comminucate something to me or the reader or
1974 other DocTeam members.
1975 Sometimes, you may want to
1976 \begin_inset Quotes eld
1980 \begin_inset Quotes erd
1983 you want to say something that is your personal opinion and using
1984 \begin_inset Quotes eld
1988 \begin_inset Quotes erd
1991 would be inappropriate.
1994 \begin_layout Standard
1995 In short, when you contribute to the LyX Docs, you wear many hats.
1998 \begin_layout Standard
1999 For occasions when you need to switch hats, I've designed some special mechanism
2003 \begin_layout Subsubsection
2005 \begin_inset space ~
2009 \begin_inset Quotes eld
2013 \begin_inset Quotes erd
2019 \begin_layout Standard
2020 These are footnotes.
2021 They begin with the following:
2032 \begin_layout Standard
2033 \SpecialChar \ldots{}
2038 for the person's name and without the quotes.
2039 The rest of the footnote is the actual comment.
2043 \begin_layout Standard
2044 Use these when you need to quote a comment by someone (usually yourself),
2045 and need to identify that person.
2046 This includes occasions when you need wear the
2047 \begin_inset Quotes eld
2051 \begin_inset Quotes erd
2055 \begin_inset space ~
2059 \begin_inset space ~
2062 to speak for yourself instead of for the LyX Team.
2065 \begin_layout Standard
2066 If the comment is too large to put in a footnote, don't use a Personal Note.
2067 When quoting more than about 3 sentences or 5 lines of text, use a bona
2069 Don't use any leading
2070 \begin_inset Quotes eld
2078 \begin_inset Quotes erd
2082 In a real quote, you'll give credit to the original speaker in either the
2083 paragraph before or after the body of the
2090 \begin_layout Subsubsection
2092 \begin_inset space ~
2096 \begin_inset Quotes eld
2100 \begin_inset Quotes erd
2106 \begin_layout Standard
2107 There will be times when you are not speaking for the LyX Team, yet you
2108 are not entirely speaking for yourself.
2109 Instead, you are speaking on behalf of the manual itself, as the author
2111 Some examples of when you might need to do this are:
2114 \begin_layout Itemize
2115 You need to contradict something you just wrote because the feature isn't
2116 quite ready yet, but you wanted to document what it will do.
2119 \begin_layout Itemize
2120 You need to leave a note for yourself.
2123 \begin_layout Itemize
2124 You need to leave a note for the editor or the other DocTeam members.
2127 \begin_layout Itemize
2128 You need to point out something about the manuals to the reader, something
2129 that doesn't fit into the context of the current paragraph.
2132 \begin_layout Standard
2133 At such times, you are wearing your
2134 \begin_inset Quotes eld
2138 \begin_inset Quotes erd
2144 \begin_layout Standard
2145 The typography for an
2146 \begin_inset Quotes eld
2150 \begin_inset Quotes erd
2156 \begin_layout Itemize
2157 They go in the body of the text, in brackets,
2158 \begin_inset Quotes eld
2162 \begin_inset Quotes erd
2165 , not any other form of parentheses.
2166 The bracket are in the default character style.
2169 \begin_layout Itemize
2170 The text of the note itself, however, is emphasized.
2174 \begin_layout Itemize
2175 Begin with the words,
2176 \begin_inset Quotes eld
2184 \begin_inset Quotes erd
2187 and end with an em-dash,
2188 \begin_inset Quotes eld
2192 \begin_inset Quotes erd
2195 , followed by your initials.
2199 \begin_layout Standard
2200 Here's an example: [
2202 Author's Note: This is an example note.
2208 \begin_layout Standard
2209 The form of the Author's Note, by the way, isn't a suggestion or request.
2215 All Author's Notes must begin with this text, verbatim:
2216 \begin_inset Quotes eld
2224 \begin_inset Quotes erd
2229 \begin_inset Quotes eld
2233 \begin_inset Quotes erd
2236 are or any other variant are forbidden.
2237 The Author's Note must end with an em-dash, which is 3
2238 \begin_inset Quotes eld
2242 \begin_inset Quotes erd
2246 \begin_inset Quotes eld
2250 \begin_inset Quotes erd
2255 \begin_inset Quotes eld
2259 \begin_inset Quotes erd
2262 ; you must use 3 (and 5 is right out).
2265 \begin_layout Standard
2266 \begin_inset Quotes eld
2270 \begin_inset Quotes erd
2273 are inherently transient, and should disapear as a manual matures.
2276 \begin_layout Subsubsection
2280 \begin_layout Standard
2281 You are also free to use footnotes on their own in addition to the Personal
2282 Notes and/or Author's Notes.
2283 I've frequently used footnotes to \SpecialChar \ldots{}
2284 well, to comment on parts of a section
2285 without putting the commentary into the body of the text.
2288 \begin_layout Paragraph*
2289 Mixing Footnotes and Personal Notes
2292 \begin_layout Standard
2293 Personal Notes always go in footnotes, and should be 5 lines or fewer.
2294 Any larger quotation should be quoted properly, using the rules of standard
2300 paragraph environment.
2303 \begin_layout Paragraph*
2304 Mixing Footnotes and Author's Notes
2307 \begin_layout Standard
2308 Author's Notes should
2316 \begin_layout Paragraph*
2317 Mixing Personal Notes and Author's Notes
2320 \begin_layout Standard
2321 Forbidden; these two are mutually exclusive.
2324 \begin_layout Subsubsection
2328 \begin_layout Itemize
2330 \begin_inset Newline newline
2337 opinion --- yours or another LyX developer's --- about anything.
2338 Anywhere in the manuals you wish to speak for yourself instead the the
2340 If you have a long rant, however, quote yourself (see section
2341 \begin_inset space ~
2345 \begin_inset CommandInset ref
2347 reference "sec:quote"
2354 \begin_layout Itemize
2356 \begin_inset Newline newline
2359 Use this to describe things in LyX (or the manuals) that may change in the
2360 future or are somehow incomplete.
2361 Author's Notes are supposed to disappear as a manual matures.
2364 \begin_layout Itemize
2366 \begin_inset Newline newline
2369 Used for text fragments that almost fit into the flow of the text\SpecialChar \ldots{}
2374 \begin_layout Standard
2375 When using these three mechanisms, in addition to rigorously following their
2376 descriptions, please use them properly.
2377 I listed some additional restrictions previously.
2378 Some of you may balk at these restrictions.
2379 Nevertheless, there is a reason for them: if you have an overwhemling desire
2380 to mix or modify footnotes, Personal Notes, and Author's Notes, you shouldn't
2381 be using any of them.
2382 More specifically, you're trying to use a hammer to drive in a screw.
2383 What you want to say probably needs to go into the main body of the text.
2386 \begin_layout Subsection
2387 General Stylistic Guidelines
2390 \begin_layout Standard
2391 Everything in this section is
2393 mandatory to all documenters
2395 , regardless the language you're writing in.
2399 \begin_layout Subsubsection
2403 \begin_layout Enumerate
2404 Use the typography rules outlined in the beginning sections of this document.
2407 \begin_layout Enumerate
2408 Don't, however, mimic the typography of this file.
2409 Yes, the Style Sheet doesn't follow the Style Sheet (grin).
2412 \begin_layout Enumerate
2413 There is some typographic freedom in those rules in earlier sections.
2414 Use that freedom wisely.
2415 Most importanly, never sacrifice the online appearance for the printed
2416 appearance and vice versa.
2420 \begin_layout Standard
2421 An example is in the
2426 There is a footnote using the
2430 command to divide a long
2434 environment into 3 columns.
2435 It adds some LaTeX commands to the online version, the so-called
2436 \begin_inset Quotes eld
2440 \begin_inset Quotes erd
2443 that some so vehemently oppose.
2444 Without it, however, that footnote takes up over two pages, most of which
2446 This is an example of permitting a little ugliness in the online version
2447 to get the printed version to look right.
2451 \begin_layout Enumerate
2452 When in doubt, compromise.
2456 \begin_layout Standard
2457 When in doubt, use good judgement.
2461 \begin_layout Subsubsection
2465 \begin_layout Enumerate
2467 \begin_inset Quotes eld
2471 \begin_inset Quotes erd
2478 \begin_layout Standard
2479 When you speak, you speak for the entire LyX Team, so use
2480 \begin_inset Quotes eld
2484 \begin_inset Quotes erd
2488 \begin_inset Quotes eld
2492 \begin_inset Quotes erd
2499 \begin_layout Enumerate
2501 \begin_inset Quotes eld
2505 \begin_inset Quotes erd
2512 \begin_layout Standard
2513 Whenever you want to say something to the reader, use
2514 \begin_inset Quotes eld
2518 \begin_inset Quotes erd
2521 not some contorted construction to avoid being too informal.
2526 \begin_layout Enumerate
2528 \begin_inset Quotes eld
2532 \begin_inset Quotes erd
2535 for both the physical pointing object (mouse, joystick, touch pad, track
2536 ball, etc.) and the mouse cursor which the physical object moves about the
2540 \begin_layout Enumerate
2542 \begin_inset Quotes eld
2546 \begin_inset Quotes erd
2549 for the little blinking vertical bar that indicates where text can/will
2553 \begin_layout Enumerate
2554 When in doubt, compromise.
2558 \begin_layout Standard
2559 When in doubt, use good judgement.
2563 \begin_layout Subsubsection
2564 \begin_inset CommandInset label
2570 Quoting Yourself and Others
2573 \begin_layout Standard
2574 In some cases, you'll have something to say, an opinion of yours.
2575 Since this is your opinion, you're not speaking for the LyX Team.
2576 You have so much to say, in fact, that it won't fit into a Personal Note
2577 or an Author's Note.
2578 In these cases you want to quote yourself.
2581 \begin_layout Standard
2582 Any time you wish to quote someone, be it yourself or someone else, there
2583 are standard rules one follows.
2584 Every language has its own rules.
2585 You should follow the rules that apply to the language of the document
2586 to which you are contributing.
2590 \begin_layout Standard
2591 This creates a problem for the primary documentation.
2592 The primary documentation is written in English, yet the contributors come
2593 from many countries.
2594 The quoting rules for English (well, American English, at least) are outlined
2598 \begin_inset space ~
2603 , for your convenience.
2604 Read them if you need to.
2607 \begin_layout Standard
2608 \begin_inset Float figure
2614 \begin_layout Plain Layout
2615 Quoting rules for English:
2618 \begin_layout Itemize
2619 The body of the quote belongs in a
2626 \begin_layout Itemize
2627 The sentences prior to the quote should flow logically and smoothly into
2631 \begin_layout Itemize
2632 The sentences immediately following the quote should continue the flow of
2636 \begin_layout Itemize
2641 credit the original author of the quote in the sentences immediately before
2645 \begin_layout Itemize
2646 Crediting the original author of the quote should not, however, disrupt
2647 the flow of the text.
2650 \begin_layout Itemize
2651 If you omit text from the beginning of the first sentence in the quote,
2652 the quote must start with the text
2653 \begin_inset Quotes eld
2656 [\SpecialChar \ldots{}
2658 \begin_inset Quotes erd
2662 This is an ellipsis in square brackets.
2665 \begin_layout Itemize
2666 If you omit text from the end of the last sentence in the quote, the quote
2667 must end with the text
2668 \begin_inset Quotes eld
2671 [\SpecialChar \ldots{}
2673 \begin_inset Quotes erd
2676 followed by the sentence's punctuation mark.
2679 \begin_layout Itemize
2680 If you omit any text from the middle of the quote, be it whole sentences
2681 or parts of sentences, replace it with the text
2682 \begin_inset Quotes eld
2685 [\SpecialChar \ldots{}
2687 \begin_inset Quotes erd
2693 \begin_layout Itemize
2694 The quote must be grammatically correct.
2699 \begin_layout Itemize
2700 If the original is wrong, you must correct it.
2703 \begin_layout Itemize
2704 If omitting part of the quote
2705 \begin_inset Quotes eld
2709 \begin_inset Quotes erd
2712 it, you must correct the problem.
2715 \begin_layout Itemize
2716 For missing words (e.
2717 \begin_inset space ~
2721 \begin_inset space ~
2725 \begin_inset Quotes eld
2729 \begin_inset Quotes erd
2732 goes missing), place the word in square brackets,
2733 \begin_inset Quotes eld
2736 [\SpecialChar \ldots{}
2738 \begin_inset Quotes erd
2741 and insert in the quote where needed.
2744 \begin_layout Itemize
2745 For mangled word order, correct the mangled text, following it with the
2747 \begin_inset Quotes eld
2751 \begin_inset Quotes erd
2758 \begin_layout Itemize
2759 Spelling in the quote must be correct.
2760 Correct any misspelled words and place the text
2761 \begin_inset Quotes eld
2765 \begin_inset Quotes erd
2768 after the corrected word.
2771 \begin_layout Itemize
2772 Back-to-back bracket blocks merge together.
2774 \begin_inset Quotes eld
2777 [\SpecialChar \ldots{}
2779 \begin_inset Quotes erd
2784 \begin_inset Quotes eld
2787 [\SpecialChar \ldots{}
2789 \begin_inset Quotes erd
2795 \begin_layout Itemize
2796 If you correct the spelling in 2 or more consecutive words, you can get
2798 \begin_inset Quotes eld
2802 \begin_inset Quotes erd
2805 after the last mistake.
2813 \begin_layout Subsubsection
2817 \begin_layout Standard
2818 When describing a new feature or
2825 \begin_layout Enumerate
2836 \begin_inset Quotes eld
2839 Keep It Short and Sweet
2840 \begin_inset Quotes erd
2844 \begin_inset Quotes eld
2847 Keep It Simple, Stupid!
2848 \begin_inset Quotes erd
2855 \begin_layout Itemize
2860 write paragraph after paragraph of verbage.
2864 \begin_layout Itemize
2868 \begin_layout Itemize
2869 Take a look at the manual for a commercial word processor --- it's a fine
2874 to write documentation.
2875 It's all pithy, substanceless verbage, and its
2883 \begin_layout Enumerate
2884 Avoid being pedantic like The Plague!
2887 \begin_layout Enumerate
2888 In the same vein, don't write more than you have to.
2889 You're not working in a vacuum --- refer freely to other parts of the manual
2890 (and other parts of other manuals).
2892 \begin_inset Quotes eld
2895 other part of the manual
2896 \begin_inset Quotes erd
2899 is incomplete or empty, refer to it.
2900 Someone will fill it in eventually.
2903 \begin_layout Enumerate
2904 On the other hand, BE THOROUGH!
2908 \begin_layout Enumerate
2913 , not widgets, not how the source code is organized.
2916 \begin_layout Enumerate
2917 Group by feature, not by widget.
2920 \begin_layout Enumerate
2921 Stay on topic --- one
2934 s and further subdivisions to group things if you're documenting several
2935 related features in a single
2942 \begin_layout Enumerate
2943 Describe EVERYTHING related to that feature, no matter where it is.
2947 \begin_layout Enumerate
2948 Example: Paragraph Indenting.
2949 Several popups control its behavior.
2954 of this: which popups control it, when you use which setting on which popup
2955 to do which operation, et cetera.
2958 \begin_layout Enumerate
2964 \begin_inset Newline newline
2967 I've had people only document one popup --- literally.
2968 This added off-topic information and only described half of the feature,
2969 since other menus, popups, and even unbound functions contained additional
2971 \begin_inset Newline newline
2978 cranky when that happens, because it means
2983 Bad help is worse than no help at all.
2987 \begin_layout Standard
2988 These remarks still hold true: you'll piss of the DocTeam editor if you
2989 do things wrong, because he'll have to fix your mistakes.
2994 \begin_layout Enumerate
2995 Remember, there are people who will reference
2999 section, just as you're referencing someone else's.
3000 You do want what you write to be useful, don't you?
3004 \begin_layout Enumerate
3005 When in doubt, compromise.
3009 \begin_layout Standard
3010 When in doubt, use good judgement.
3014 \begin_layout Subsubsection
3019 Treat the Reader as if She is Stupid
3022 \begin_layout Enumerate
3026 \begin_layout Enumerate
3027 No talking down to the reader.
3030 \begin_layout Enumerate
3031 The reader is smart enough to know what a mouse is.
3034 \begin_layout Enumerate
3035 The reader is smart enough to know how to use a keyboard, including the
3049 (The introduction of most of the manuals takes care of the
3050 \begin_inset Quotes eld
3062 \begin_inset Quotes erd
3065 issue, so you don't need to.)
3068 \begin_layout Enumerate
3069 The reader is smart enough to know that
3070 \begin_inset Quotes eld
3074 \begin_inset Quotes erd
3078 \begin_inset Quotes eld
3081 where the text cursor is sitting right now, in the buffer currently visible.
3082 \begin_inset Quotes erd
3087 (Anything more than the word
3088 \begin_inset Quotes eld
3092 \begin_inset Quotes erd
3095 is, IMO, superfluous and wll be deleted .
3096 So, save yourself the typing, save the editor the cutting, and save the
3097 reader the strain of sifting through extra verbage that adds no content.)
3100 \begin_layout Enumerate
3101 Rule of thumb: the reader is not an imbecile.
3102 The reader is merely lost; point them in the right direction, and they
3103 can take it from there.
3106 \begin_layout Subsection
3107 Tips for the English Version
3110 \begin_layout Standard
3111 \begin_inset CommandInset label
3113 name "sec:english-only"
3117 When contributing to the primary --- i.
3118 \begin_inset space ~
3122 \begin_inset space ~
3125 the English language version --- of the LyX manuals, keep the following
3129 \begin_layout Subsubsection
3130 Write as if You're Talking with a Friend.
3134 \begin_layout Enumerate
3135 Think that way when you write.
3136 Play the dialogue in your mind.
3139 \begin_layout Enumerate
3140 Be as informal as you please (without being rude).
3143 \begin_layout Subsubsection
3144 AVOID the Passive Voice
3147 \begin_layout Enumerate
3149 \begin_inset Quotes eld
3152 It is felt that this name best explains the command's purpose.
3153 \begin_inset Quotes erd
3156 We know full well who wrote the command:
3157 \begin_inset Quotes eld
3160 The LyX Team felt ...
3161 \begin_inset Quotes erd
3165 \begin_inset Quotes eld
3169 \begin_inset Quotes erd
3175 \begin_layout Enumerate
3176 Things don't happen by magic - somebody or something did it.
3177 Only politicians use the passive voice to cover up who did something.
3178 If LyX reformats a paragraph, write,
3179 \begin_inset Quotes eld
3182 LyX reformatted the paragraph.
3183 \begin_inset Quotes erd
3190 makes changes, write,
3191 \begin_inset Quotes eld
3198 changes the document.
3199 \begin_inset Quotes erd
3206 \begin_layout Standard
3207 Rule of thumb: any sentence you can express as,
3208 \begin_inset Quotes eld
3212 \begin_inset Quotes erd
3216 \begin_inset Quotes eld
3220 \begin_inset Quotes erd
3227 \begin_layout Enumerate
3229 We all hear way, way too much garbage English on the TV every day in the
3231 Some people think it makes speech better.
3233 It makes speech baroque, if not outright byzantine.
3234 With a little effort, you can wean yourself off of it.
3237 \begin_layout Enumerate
3240 will make you rewrite
3242 anything in the passive voice.
3243 It's awkward and hard to read.
3246 \begin_layout Enumerate
3247 Note to non-Americans:
3251 \begin_layout Standard
3252 Using passive voice is generally considered bad style in the U.
3253 \begin_inset space ~
3257 \begin_inset space ~
3260 as it is too easy to obfuscate your words with it.
3261 It also bloats sentences, often unnecessarily.
3265 \begin_layout Subsubsection
3270 \begin_layout Standard
3271 In English, there is a grammatical error known as the
3272 \begin_inset Quotes eld
3276 \begin_inset Quotes erd
3279 The classic example of a run-on sentence is 7 clauses strung together with
3281 \begin_inset Quotes eld
3285 \begin_inset Quotes erd
3288 There are, however, less obvious run-on sentences, ones using too many
3289 subordinate clauses.
3290 Such sentences may look elegant because they are complex.
3291 However, they are also extremely difficult to read because they are so
3295 \begin_layout Standard
3296 In general, stick to short sentences in written English.
3297 Getting rid of passive voice (
3298 \begin_inset Quotes eld
3301 \SpecialChar \ldots{}
3302 was done by\SpecialChar \ldots{}
3304 \begin_inset Quotes erd
3307 ) shortens and simplifies them.
3308 Hacking apart sentences with many dependent clauses is another way to shorten
3310 There are ways to do this yet still have a smooth-flowing paragraph.
3313 \begin_layout Standard
3314 While I'm talking about paragraphs, I'll apply the
3315 \begin_inset Quotes eld
3319 \begin_inset Quotes erd
3322 motto to them, as well.
3323 At the time I started with the manuals (and this Style Sheet), I didn't
3324 pay too much attention to paragraph size.
3325 I've since become a big proponent of short paragraphs, with one idea per
3327 While long, flowing, multi-concept paragraphs can be nice in novels, we're
3329 Our goal is rapid information location and comprehension, not a literary
3333 \begin_layout Standard
3334 There is a single exception to the short sentence, short paragraph rule.
3335 Particularly complex ideas may need more
3336 \begin_inset Quotes eld
3340 \begin_inset Quotes erd
3343 However, you shouldn't encounter such complex ideas often when documenting
3345 Try to keep things short, and use your judgement as needed.
3348 \begin_layout Standard
3349 To reiterate, yet again, something I said before:
3353 When in doubt, compromise.
3357 When in doubt, use good judgement.
3360 \begin_layout Standard
3361 Hopefully, you've got the idea (grin).
3364 \begin_layout Section
3368 \begin_layout Subsection
3369 Rules of the Translating Trade
3372 \begin_layout Standard
3373 While translating anything, there are certain
3374 \begin_inset Quotes eld
3378 \begin_inset Quotes erd
3382 They will help you greatly.
3385 \begin_layout Subsubsection
3386 Translate one paragraph at a time.
3389 \begin_layout Standard
3390 Most people translate word by word.
3391 Clearly, you lose all context if you do that.
3392 A word may have multiple meanings.
3393 You can't tell which unless you look at the rest of the sentence.
3396 \begin_layout Standard
3397 There is another level to the context issue, however.
3398 Your dictionary may translate multiple English words the same way.
3399 All those words mean
3404 Each one, however, covers a different shade of meaning, a different mood
3406 It is often difficult to resolve those shades of meaning in the context
3407 of even one sentence.
3408 A paragraph, however, will provide that context.
3411 \begin_layout Subsubsection
3412 You will not translate it correctly on the first try.
3415 \begin_layout Standard
3416 Alright, I admit that you may be able to translate some of the sentences
3418 If you know a language well, you may even understand over half of the text.
3419 Nevertheless, overconfidence can lead you astray.
3420 There will be some sentences, no matter how few, that will simply confound
3424 \begin_layout Standard
3425 It is generally a good idea to make multiple passes over a paragraph you're
3427 Even if you translate the entire paragraph on the first pass, make a second
3429 You'll often improve upon your first attempt.
3432 \begin_layout Subsubsection
3433 When in doubt, write down all of the meanings for a word.
3436 \begin_layout Standard
3437 You can often translate tricky parts of a text using the context of the
3438 surrounding sentences.
3439 So, if you hit a word or phrase you don't know, translate it more than
3441 Picking the most likely translations, summarize them in one to three words
3443 \begin_inset Quotes eld
3447 \begin_inset Quotes erd
3454 \begin_layout Subsubsection
3455 Using context, fix the meanings on the next pass.
3458 \begin_layout Standard
3459 This is where your multiple translations of a single word become useful.
3460 Using the other sentences you translated, you can now translate that mystery--s
3461 entence without reconsulting your dictionary.
3464 \begin_layout Subsubsection
3465 Fix the grammar only after you've finished translating the sentence.
3468 \begin_layout Standard
3469 If there's a mystery phrase in the middle of a sentence, you can't translate
3470 the entire sentence.
3471 Why grammatically rearrange the words you translated already? You may need
3472 to restructure the sentence a second time once you figure out how to translate
3473 that mystery phrase.
3474 Better to wait until you've completely translated the sentence to clean
3476 That way, you do so only once.
3479 \begin_layout Subsubsection
3480 If you can't translate it, skip it and come back to it on the next pass.
3483 \begin_layout Standard
3484 Remember the earlier discussion of context and its immense usefulness? There
3485 is no sin in making multiple passes over a tricky passage.
3488 \begin_layout Subsubsection
3489 Translate the meaning first.
3493 \begin_layout Standard
3494 The information content of the text under translation is the most important
3496 This is especially important for a manual, where the information
3500 important part of the original document.
3501 Lose that, and you lose the very point of performing the translation.
3504 \begin_layout Subsection
3505 Tips for the Translators
3508 \begin_layout Standard
3509 Those of you contributing to a translation of the LyX manuals must follow
3510 a modified set of rules.
3511 The first few rules are analogous to those in section
3512 \begin_inset space ~
3516 \begin_inset CommandInset ref
3518 reference "sec:english-only"
3523 There are additional rules and regulations that follow those first few.
3527 \begin_layout Subsubsection
3528 Write as if you are explaining LyX to a colleague you know well.
3531 \begin_layout Enumerate
3532 Think that way when you write.
3533 Play the dialogue in your mind.
3536 \begin_layout Enumerate
3537 Use a conversational style in your writing.
3538 Pretend you are teaching LyX to a colleague you know well.
3541 \begin_layout Enumerate
3542 Use a style that is polite without being too formal.
3543 If, in your culture, informal language is appropriate to use with a colleague,
3544 use informal speech in the translation of the manual.
3547 \begin_layout Subsubsection
3548 AVOID Snobby, Academic, Specialized, or
3549 \begin_inset Quotes eld
3553 \begin_inset Quotes erd
3560 \begin_layout Standard
3561 In English, the passive voice appears formal, dry, barren.
3562 It also often adds unnecessary complexity.
3563 In other langauges, however, this is not the case.
3564 There is nothing wrong with passive voice, and people use it frequently
3565 in everyday conversation.
3566 Nevertheless, your translation of the LyX manuals must avoid
3567 \begin_inset Quotes eld
3571 \begin_inset Quotes erd
3577 \begin_layout Standard
3578 In Germany, there is a magazine known as
3579 \begin_inset Quotes gld
3583 \begin_inset Quotes grd
3586 The writing in it is so complex, it is extremely difficult for non-native
3587 German speakers to understand.
3588 While sophisticated, the writing style of
3589 \begin_inset Quotes gld
3593 \begin_inset Quotes grd
3596 is not what a German uses in everyday conversation.
3597 Nor is the writing style for a Russian mathematics journal.
3598 Such specialized or overly-sophisticated styles are
3599 \begin_inset Quotes eld
3603 \begin_inset Quotes erd
3606 in the sense that they are seldom used by normal people in everyday speech.
3609 \begin_layout Standard
3610 We who write the LyX manuals, original or translated, seek to
3615 If we write in a style only a few people use, and use seldomly, we will
3617 Use a writing style that mirrors everyday speech (without being vulgar,
3622 \begin_layout Subsubsection
3623 Keep the Writing Simple.
3626 \begin_layout Standard
3627 For the English version, I wrote,
3628 \begin_inset Quotes eld
3631 Use short sentences and short paragraphs.
3632 \begin_inset Quotes erd
3635 What if, however, short sentences and paragraphs are something only children
3636 use in your language? What if, in yet another language, short sentences
3637 imply rudeness? Naturally, you would not want to use them in your translation.
3640 \begin_layout Standard
3641 Nevertheless, the translations of the LyX manuals should be as clear as
3643 So, for our international colleagues, we apply this rule: Keep your sentences
3644 and paragraphs as short as makes sense.
3647 \begin_layout Standard
3648 Remember: we're translating manuals here, folks.
3649 Our goal is rapid information location and comprehension, not a literary
3651 Try to keep your writing concise yet smooth-flowing.
3652 And use your judgement as needed:
3656 When in doubt, compromise.
3660 When in doubt, use good judgement.
3663 \begin_layout Subsubsection
3664 Translators must follow the Style Sheet, too!
3667 \begin_layout Standard
3668 Everything in this manual ---
3671 \begin_inset space ~
3675 \begin_inset CommandInset ref
3677 reference "sec:english-only"
3683 --- applies to every LyX documenter, no matter what the language.
3686 \begin_layout Subsubsection
3687 Translators must read the Style Sheet Supplement for their language.
3690 \begin_layout Standard
3691 For every translation project, there is a Supplement to the Style Sheet.
3698 DocStyle_Supplement_<cn>.lyx
3701 \begin_layout Standard
3702 \SpecialChar \ldots{}
3704 \begin_inset Quotes eld
3712 \begin_inset Quotes erd
3715 is your language's two-letter locale code.
3716 The Translation Project Chief for your language wrote this.
3717 If he hasn't, pester him to do so! <
3724 \begin_layout Subsubsection
3725 The English versions of the manuals are not Sacred Text.
3728 \begin_layout Standard
3729 You do not need to translate everything word for word.
3730 In fact, you shouldn't.
3731 Keep to the spirit of the originals, not the letter.
3732 Be as creative as you want, as long as you
3740 convey all of the information contained in the English versions.
3743 \begin_layout Subsubsection
3744 Any information in the LyX manuals must also be in the translations.
3747 \begin_layout Standard
3748 \begin_inset CommandInset label
3754 This falls under translating the orignals accurately and completely.
3758 \begin_layout Itemize
3759 Omitting any feature description is
3766 \begin_layout Itemize
3767 Misrepresenting or misdescribing any LyX feature or operation
3774 \begin_layout Itemize
3779 outpace the original.
3780 \begin_inset Newline newline
3783 If no one has documented new feature in the primary LyX manuals (i.
3784 \begin_inset space ~
3788 \begin_inset space ~
3791 the English versions), do not do so in the translations.
3792 If you're really looking for something to do, either:
3796 \begin_layout Itemize
3797 \SpecialChar \ldots{}
3798 focus on translating something you haven't yet,
3799 \begin_inset Newline newline
3805 \begin_layout Itemize
3806 \SpecialChar \ldots{}
3807 update or repair the primary manual.
3810 \begin_layout Standard
3811 If you cannot or do not want to do one of the above, then take a break.
3813 Wait for the main manuals to catch up before translating anything else.
3817 \begin_layout Subsubsection
3818 What you cannot translate, you may omit (usually).
3821 \begin_layout Standard
3822 Prepositions, idioms, metaphors, slang, Oh My! There's a jungle of potentially
3823 untranslatable text you may face.
3824 Happily, none of these untranslatables are essential to the original text\SpecialChar \ldots{}
3827 If you can't translate a phrase or two, try omitting them.
3828 If the rest of the paragraph still makes sense, then don't worry about
3832 \begin_layout Standard
3833 There may be special cases where omitting part of a sentence or paragraph
3835 \begin_inset space ~
3839 \begin_inset CommandInset ref
3841 reference "sec:accuracy"
3850 You must try and translate those tricky spots.
3853 \begin_layout Subsubsection
3854 Translators may add their own fluff to the information content.
3857 \begin_layout Standard
3858 After you do strip away all of the idioms, metaphors, slang, humor, and
3860 \begin_inset Quotes eld
3864 \begin_inset Quotes erd
3867 you may find that your translated manual is dull and dry.
3868 Why not add your own fluff? Add text that makes the manual a pleasure to
3869 read, that engages the reader.
3870 It may take the form of humor, or metaphors, or sayings.
3871 Whatever you add, it should be
3872 \begin_inset Quotes eld
3876 \begin_inset Quotes erd
3879 It should not clash with the explanation of LyX features and functions.
3882 \begin_layout Subsection
3883 For Translation Project Chiefs
3886 \begin_layout Subsubsection
3887 The First Is In Charge
3890 \begin_layout Standard
3891 If you were the first person to start translating the manuals, you're the
3892 LyXDoc Translation Project Chief for your language.
3897 person translating the LyXDocs, that automatically makes you the Translation
3901 \begin_layout Standard
3902 Amongst other things, that means that you must read this section and perform
3903 the tasks described here.
3906 \begin_layout Standard
3907 If you are a member of a LyX Documentation Translation Team, but
3911 its Chief, you may stop reading.
3912 The remainder of this section will be of no interest to you.
3913 If you came to the Style Sheet from the Supplement for your language, you
3917 \begin_layout Standard
3918 If you have not read the Style Sheet Supplement for your language, you should
3923 \begin_layout Subsubsection
3924 Read the Style Sheet
3927 \begin_layout Standard
3928 No documenter is excused from following the Style Sheet, not even a Translation
3932 \begin_layout Standard
3937 important that the Translation Project Chiefs read the Style Sheet.
3940 \begin_layout Subsubsection
3941 Make your translators read the Style Sheet
3944 \begin_layout Standard
3945 No documenter is excused from following the Style Sheet.
3948 \begin_layout Standard
3949 Since your translation team is translating, they know
3954 Therefore, they should be able to read the Style Sheet.
3957 \begin_layout Subsubsection
3959 \begin_inset Quotes eld
3963 \begin_inset Quotes erd
3969 \begin_layout Standard
3970 There are parts of this Style Sheet that are English-specific.
3971 I have tried to provide a general, language-independent description of
3972 certain details in this section.
3973 Unfortunately, that general description doesn't cover the specifics of
3978 \begin_layout Standard
3979 That's where you, as head of a LyXDoc Translation Team, come in.
3982 \begin_layout Standard
3983 Every Translation Team Chief is
3987 to write a Supplement to the official Documentation Style Sheet, with specifics
3988 issues affecting your language.
3989 (You are, after all, the LyX Team expert on your native tongue.) Follow
3990 these guidelines when writing the Supplement:
3993 \begin_layout Enumerate
3995 \begin_inset Newline newline
4000 DocStyle_Supplement_<cn>.lyx
4003 \begin_inset Newline newline
4006 \SpecialChar \ldots{}
4008 \begin_inset Quotes eld
4016 \begin_inset Quotes erd
4019 is the two-letter code for your language.
4020 This is the same two-letter code that is part of the filenames for the
4023 \begin_inset Quotes eld
4031 \begin_inset Quotes erd
4035 \begin_inset Quotes eld
4043 \begin_inset Quotes erd
4047 \begin_inset Quotes eld
4055 \begin_inset Quotes erd
4061 \begin_layout Enumerate
4062 Do not worry about where the file goes.
4063 The CVS maintainers will locate all documentation and Style Sheet Supplements
4064 in an appropriate place.
4067 \begin_layout Enumerate
4068 Document Properties:
4072 \begin_layout Itemize
4073 For consistency, use the same document class and other document properties
4078 \begin_layout Plain Layout
4079 Specifically, check the settings in the
4084 Use those in your Supplement.
4092 \begin_layout Itemize
4093 Exceptions: Use margins, indentation/paragraph separation, language, and
4094 encoding appropriate for your language.
4098 \begin_layout Enumerate
4099 The title of the Supplement:
4103 \begin_layout Itemize
4104 The title will use the
4105 \begin_inset Quotes eld
4113 \begin_inset Quotes erd
4116 paragraph environment.
4117 In your native tongue, the title will read:
4121 \begin_layout Standard
4124 Documentation Project Style Sheet:
4125 \begin_inset Newline newline
4128 Supplement for the <foo> Translation Project
4131 \begin_layout Standard
4133 \begin_inset Quotes eld
4141 \begin_inset Quotes erd
4144 with the name of your language.)
4148 \begin_layout Itemize
4149 If, in your language,
4150 \begin_inset Quotes eld
4154 \begin_inset Quotes erd
4158 \begin_inset Quotes eld
4162 \begin_inset Quotes erd
4167 \begin_inset Quotes eld
4171 \begin_inset Quotes erd
4175 \begin_inset Quotes eld
4179 \begin_inset Quotes erd
4182 have somewhat different meanings.
4183 An appendix is an extra part of a document.
4184 A supplement is an extra document.
4189 \begin_layout Standard
4190 Choose a replacement word accordingly.
4191 Whatever you choose to replace
4192 \begin_inset Quotes eld
4196 \begin_inset Quotes erd
4199 it must not have the same translation as the word
4200 \begin_inset Quotes eld
4204 \begin_inset Quotes erd
4212 \begin_layout Enumerate
4213 Below the title, in the
4214 \begin_inset Quotes eld
4222 \begin_inset Quotes erd
4225 paragraph environment, place your name.
4229 \begin_layout Standard
4230 There will be no abstract.
4234 \begin_layout Enumerate
4243 \begin_layout Standard
4244 The first thing you will do is strongly yet politely encourage the reader
4246 \begin_inset Quotes eld
4250 \begin_inset Quotes erd
4253 and go read the Style Sheet.
4254 The reader should not return to the
4255 \begin_inset Quotes eld
4259 \begin_inset Quotes erd
4266 understood the Style Sheet proper.
4270 \begin_layout Subsubsection
4271 Keep the Supplement Succinct
4274 \begin_layout Standard
4275 This Style Sheet is already very detailed.
4276 DocTeam members all have a lot to read.
4277 We don't want to place an extra burden on translators.
4278 Therefore, keep the Supplement as short as you can without losing information.
4281 \begin_layout Subsubsection
4285 \begin_layout Standard
4290 will be about font issues\SpecialChar \ldots{}
4292 Not all Translation Project Chiefs will need to deal with this issue.
4296 \begin_layout Itemize
4302 \begin_layout Itemize
4308 \begin_layout Itemize
4310 \begin_inset Newline newline
4315 Emphasized (actually Italics)
4318 \begin_layout Itemize
4324 \begin_layout Itemize
4330 \begin_layout Itemize
4333 Noun (actually Small Caps)
4336 \begin_layout Standard
4337 \SpecialChar \ldots{}
4338 certainly exist for all languages that use the Roman alphabet.
4339 Do they exist, however, for Greek? How about Cyrillic? These different
4340 fonts almost certainly do not exist for Devanagri, Chinese, Korean, Japanese,
4341 Hebrew, Arabic, and other scripts.
4345 \begin_layout Standard
4346 There will be some languages for which following the font-scheme specified
4347 in this Style Sheet may not be possible.
4348 If you are the Translation Project Chief for such a language, you have
4352 \begin_layout Standard
4353 In the font section of the Supplement, you will provide a new typographic
4354 style, designed specifically for your writing system.
4355 For consistency, the title of this section in every Supplement should translate
4357 \begin_inset Quotes eld
4361 \begin_inset Quotes erd
4364 Before adding anything to this section, however, determine what this new
4365 typographic style will look like.
4366 Stick to the font specifications in this Style Sheet as best you can, whenever
4368 When you cannot, use the following suggestions:
4371 \begin_layout Itemize
4373 \begin_inset Quotes eld
4377 \begin_inset Quotes erd
4381 \begin_inset Newline newline
4385 \begin_inset Newline newline
4388 What to do when a font doesn't exist:
4393 \labelwidthstring MMMMMMMM
4394 Roman Use the font that typesetters in your language use for printing books,
4396 This will typically be the default font LyX (and LaTeX) uses in your language.
4400 \labelwidthstring MMMMMMMM
4404 \begin_inset space ~
4409 This is for people's names.
4410 If there is special font for names in your alphabet/writing system, use
4411 it in place of this.
4412 Otherwise, write names in the default font, typeset according to the rules
4417 \labelwidthstring MMMMMMMM
4422 Use the font with which your language normally emphasizes text.
4426 \begin_layout Standard
4427 Use a font that is different from your language's equivalent of
4432 In other words, your
4440 and similar headers will be in one typeface, perhaps
4445 Whatever that font is, avoid using it for
4454 \labelwidthstring MMMMMMMM
4459 Pick up a computer program manual written in your language.
4460 It will use a special typeface for filenames, for command names, program
4462 Use that same font in place of
4470 \labelwidthstring MMMMMMMM
4474 \begin_inset space ~
4479 Pick any other font that is different from the ones you're using in place
4493 If you're unlucky, and your language's writing system doesn't have enough
4494 fonts, use the same font you picked to replace
4499 Only do this, however, if your alphabet/writing system has very few fonts
4504 \labelwidthstring MMMMMMMM
4511 \begin_inset space ~
4515 \begin_inset space ~
4520 Don't worry about this one.
4524 \begin_layout Standard
4525 If you use some special font on-screen to highlight the accelerator keys
4526 for menus, buttons, and other widgets, you might want to mimic that in
4528 It is not required, however.
4529 Therefore, if you can't mimic this typographic convention in your native
4530 writing system, don't.
4535 \begin_layout Standard
4536 Note that you may also want to describe fonts that your Translation Team
4542 For example, no contributer to the English/European versions may ever use
4547 , as this is used for section-headings.
4548 Since there are enough other fonts, we who use the Roman alphabet and its
4549 variants can afford to omit
4557 \begin_layout Standard
4558 Once you have determined which fonts in your native writing system will
4559 replace one or more of the above, propose it to the LyX Developer's Mailing
4561 You may receive valuable feedback this way.
4562 If not, that's okay.
4563 If no one can read your writing system, and therefore cannot comment, that's
4565 Go ahead and describe the typographic standard you created in the Supplement.
4569 \begin_layout Standard
4570 Remember: stick to the font specifications in this Style Sheet as best you
4571 can, whenever you can.
4574 \begin_layout Subsubsection
4575 Quoting Style and the
4587 \begin_layout Standard
4588 The next section of the Supplement will cover the issue of quoting.
4589 Give it an appropriate title.
4592 \begin_layout Standard
4593 One of the first things you should do in that section is resolve the following
4597 \begin_layout Itemize
4606 is the correct paragraph environment for your language.
4609 \begin_layout Itemize
4610 In the Supplement, specify which one to use.
4613 \begin_layout Standard
4614 English has its own typography and style for quoting others.
4615 The Style Sheet describes that typography in section
4616 \begin_inset space ~
4620 \begin_inset CommandInset ref
4622 reference "sec:quote"
4627 Your language also has a specific typography and style for quotations.
4628 Describe that style in this section of the Supplement, too.
4629 Naturally, you do not need to go overboard.
4631 \begin_inset space ~
4635 \begin_inset CommandInset ref
4637 reference "sec:quote"
4641 of this Style Sheet is overly detailed for a good reason.
4642 Authors of the primary LyX manuals are not necessarily native English speakers.
4643 The members of your Translation Team, however, will all likely be native
4644 speakers of your language.
4645 Therefore, discuss proper quoting style of your native tongue to an appropriate
4649 \begin_layout Subsubsection
4650 Translations of Style Sheet Terminology
4653 \begin_layout Standard
4654 In the Supplement, you must provide a standard translation of certain key
4655 phrases for the members of your Translation Team.
4656 Place this in a section following the one about quotations.
4659 \begin_layout Standard
4660 In particular, standardize the translations of the phrases:
4663 \begin_layout Itemize
4669 \begin_layout Itemize
4675 \begin_layout Standard
4680 change the typography of the
4681 \begin_inset Quotes eld
4685 \begin_inset Quotes erd
4689 \begin_inset Quotes eld
4693 \begin_inset Quotes erd
4697 Only provide a translation for the opening phrases.
4698 Insist that the members of your Translation Team use these two tools correctly.
4701 \begin_layout Standard
4702 While we are discussing proper use of the
4703 \begin_inset Quotes eld
4707 \begin_inset Quotes erd
4711 \begin_inset Quotes eld
4715 \begin_inset Quotes erd
4718 in translations, let's talk about a related problem.
4720 \begin_inset Quotes eld
4724 \begin_inset Quotes erd
4727 is meant to be a note from the author of a manual to the reader.
4728 In the case of a translation, however, the translator is
4732 the author! How then should a translator translate an
4733 \begin_inset Quotes eld
4737 \begin_inset Quotes erd
4743 \begin_layout Standard
4744 You, as Translation Project Chief, must decide.
4745 You can forbid translation of pre-existing
4746 \begin_inset Quotes eld
4750 \begin_inset Quotes erd
4753 omitting them entirely instead.
4754 You could tell your translators to read any
4755 \begin_inset Quotes eld
4759 \begin_inset Quotes erd
4762 they may encounter, understand it, then write their own
4763 \begin_inset Quotes eld
4767 \begin_inset Quotes erd
4770 about the situation, not as a translation but as a personal opinion.
4771 You may decide on some other policy.
4774 \begin_layout Standard
4775 Whatever you decide, codify your policy in its own
4784 Place it near the section where you translated
4785 \begin_inset Quotes eld
4789 \begin_inset Quotes erd
4793 \begin_inset Quotes eld
4797 \begin_inset Quotes erd
4803 \begin_layout Subsubsection
4807 \begin_layout Standard
4808 After describing all of the previous issues, create a new
4814 \begin_inset Quotes eld
4817 Lost in Translation,
4818 \begin_inset Quotes erd
4821 or something similar.
4824 \begin_layout Standard
4825 In this section you will discuss any common English metaphors, humor, connotatio
4826 n, or other difficult to translate text.
4827 Try to balance brevity and completeness.
4836 s --- to each specific issue.
4839 \begin_layout Subsubsection
4840 \SpecialChar \ldots{}
4842 \begin_inset Quotes eld
4846 \begin_inset Quotes erd
4849 \SpecialChar \ldots{}
4853 \begin_layout Standard
4854 Throughout the manuals, the DocTeam has used the following sentences:
4858 If you haven't read the <
4862 > manual, go read it.
4866 \begin_layout Standard
4867 This sentence will be tricky to translate, since it contains non-translatable
4873 for this issue in your
4874 \begin_inset Quotes eld
4878 \begin_inset Quotes erd
4883 \begin_inset Quotes eld
4886 \SpecialChar \ldots{}
4887 Yes, we mean now\SpecialChar \ldots{}
4889 \begin_inset Quotes erd
4892 sentences, then present a translation, along with any explanation you feel
4896 \begin_layout Standard
4897 Here's what those two sentences, sitting alone in their own paragraph, mean:
4900 \begin_layout Standard
4901 The first sentence uses the English conditional followed by an imperative.
4902 We, as the LyX team, are commanding the reader to go back to another manual.
4907 manual is a prerequisite for all of the other manuals.
4908 The conditional clause preceeding the command means,
4909 \begin_inset Quotes eld
4912 You do not need to perform this command twice.
4913 \begin_inset Quotes erd
4919 \begin_layout Standard
4920 The second sentence adds force to the command.
4921 Culturally, the imperative tense of a verb in English is not necessarily
4923 The way we wrote that command,
4924 \begin_inset Quotes eld
4928 \begin_inset Quotes erd
4931 is firm, yet polite.
4932 The reader may choose to ignore it.
4934 \begin_inset Quotes eld
4938 \begin_inset Quotes erd
4941 we imply two things.
4943 \begin_inset Quotes eld
4947 \begin_inset Quotes erd
4951 That second sentence reinforces the command, making it a bit harder to
4953 Second, the sentence itself implies a certain sense of urgency.
4954 You cannot merely wait until later to fulfill that command.
4955 The brief pragraph, and its sudden end, add still further subtle reinforcement
4957 \begin_inset Quotes eld
4960 go do the required reading before using this manual.
4961 \begin_inset Quotes erd
4967 \begin_layout Standard
4968 Note that all of this commanding and reinforcing is nevertheless in a polite
4970 Furthermore, it is in a subtle form.
4971 We are commanding the reader to do something, but in an indirect fashion.
4972 This way, the reader does not feel like we are bullying him.
4975 \begin_layout Subsubsection
4980 \begin_layout Standard
4981 In the same part of the Supplement that you place the
4982 \begin_inset Quotes eld
4985 \SpecialChar \ldots{}
4986 Yes, we mean now\SpecialChar \ldots{}
4988 \begin_inset Quotes erd
4991 translation, discuss the English version's use of
4992 \begin_inset Quotes eld
4996 \begin_inset Quotes erd
5002 \begin_layout Standard
5003 You see, here in America, we often say that everything is permitted unless
5004 explicitly banned by law.
5005 As a result, manuals for computer software are frequently ignored and the
5006 software subsequently blamed for not being
5007 \begin_inset Quotes eld
5011 \begin_inset Quotes erd
5014 This is where the use of
5015 \begin_inset Quotes eld
5019 \begin_inset Quotes erd
5026 \begin_layout Standard
5027 We who wrote the manuals added sentences insisting that the reader not ignore
5028 certain parts of the documentation.
5029 We wrote in a manner that was polite, yet firmly asserted that the user
5030 was misusing the software if he did not read the manual correctly.
5031 We did not, however, want to sound threatening, coercive, or bullying.
5034 \begin_layout Standard
5035 In your culture, cajoling the reader into using the manuals correctly may
5037 It may, in fact, be outright rude.
5038 Additionally, translating the firm-but-convincing bits may not work.
5039 The translation may sound weird, or rude, or hostile.
5040 Therefore, you and your translation team will face many sentences that
5041 you cannot translate.
5044 \begin_layout Standard
5045 You, the Translation Project Chief, must discuss this issue.
5046 Try and find parts of the original manuals where some friendly but firm
5047 convincing does not translate properly.
5048 Use these cases as the basis for examples of the problem.
5049 Be sure to then offer a solution (i.
5050 \begin_inset space ~
5054 \begin_inset space ~
5057 how you want such sentences translated.) If stumped, ask for help on the
5058 LyX Developer's List.
5061 \begin_layout Subsubsection
5065 \begin_layout Standard
5066 You can add more sections to the Supplement if you need to discuss other
5068 There may be policies or guidelines that you want to set for your Translation
5070 Be careful, however! Keep the Supplement