1 #LyX 2.1 created this file. For more info see http://www.lyx.org/
6 \use_default_options false
7 \maintain_unincluded_children false
9 \language_package default
10 \inputencoding iso8859-1
14 \font_typewriter default
16 \font_default_family default
17 \use_non_tex_fonts false
23 \default_output_format default
25 \bibtex_command default
26 \index_command default
32 \use_package amsmath 0
33 \use_package amssymb 0
36 \use_package mathdots 0
37 \use_package mathtools 0
39 \use_package stackrel 0
40 \use_package stmaryrd 0
41 \use_package undertilde 0
43 \cite_engine_type default
47 \paperorientation portrait
57 \paragraph_separation indent
58 \paragraph_indentation default
59 \quotes_language english
63 \tracking_changes false
73 Documentation Project Style Sheet
80 \begin_layout Abstract
81 This article is a style sheet.
82 It describes, with examples, how the documentation should look and sound.
83 The first few sections explain the font conventions and typography conventions
84 all documentation writers should follow.
85 Those sections also contain examples.
86 It also explains the purpose of each of the different manuals.
87 Follow it not merely to the letter, but also in spirit.
90 \begin_layout Abstract
91 The Style Sheet for LyX documentation (hereafter known as the Style Sheet)
96 forms of LyX documenation, regardless of language.
97 There is a section for translators in the Style Sheet, towards the end.
100 Read the entire Style Sheet!
102 Even if you are a translator, I assume you know enough English to comprehend
106 \begin_layout Section
107 Questions and Clarifications
110 \begin_layout Standard
111 After the second version of this Style Sheet grew uncomfortably large, the
112 LyX DocTeam decided it needed to lose some excess weight.
113 It seems the Style Sheet began to specify too many special cases, too many
114 points of clarification.
115 On the other hand, contributors to the documents were discovering many
116 creative ways of misinterpreting the Style Sheet specifications.
121 If you have any questions about anything in the Style Sheet,
123 ask first, write second!
126 \begin_layout Standard
127 Field all questions to the LyX Developer's Mailing List.
128 There are seasoned DocTeam members who can answer your questions.
129 If you have any problems with the Style Sheet itself, also contact the
133 \begin_layout Section
137 \begin_layout Standard
138 We'll start with the easiest section, yet also the most important.
141 \begin_layout Standard
142 This is how you should fontify text in the manuals:
145 \begin_layout Labeling
146 \labelwidthstring MMMMMMMM
151 general emphasis, generic arguments, titles of books, names the other manuals
152 and of their sections, and notes from the authors
156 \begin_layout Standard
157 Do not overemphasize your text.
161 \begin_layout Labeling
162 \labelwidthstring MMMMMMMM
167 program names, file names,
171 -page names, LaTeX code, LaTeX commands, LaTeX package names, and LyX code
175 \begin_layout Labeling
176 \labelwidthstring MMMMMMMM
185 menu, button, or popup names, the names/lables of all widgets in a popup,
186 the names of keyboard keys, and certain
187 \begin_inset Quotes eld
191 \begin_inset Quotes erd
197 \begin_layout Labeling
198 \labelwidthstring MMMMMMMM
210 \begin_layout Labeling
211 \labelwidthstring MMMMMMMM
227 Rich Fields added this to mimick the underlining of letters in the menus
229 It helps to highlight the accelerator keys, and human brains store information
230 best when they see it frequently.
234 \begin_layout Description
235 WARNING! --- When you do this, make sure you
239 shut off the underlining.
240 Too many people send in things that look like:
241 \begin_inset Newline newline
251 \begin_inset Newline newline
254 \SpecialChar \ldots{}
263 they not only shut off underlining, they turned off
275 Make sure the entire word is still in
283 after you shut off the underlining.
287 \begin_layout Labeling
288 \labelwidthstring MMMMMMMM
297 \begin_layout Standard
298 If you want to emphasize any text, use
303 LaTeX will put many things boldface on its own, such as
307 s, certain parts of equations, et cetera.
310 \begin_layout Standard
311 Repeat: do not use boldface.
315 \begin_layout Standard
316 Here are some examples:
319 \begin_layout Enumerate
324 appears in configuration files and in the LyX source.
325 Therefore, it (and all other LyX function names) count as code and is set
333 \begin_layout Enumerate
345 is a menu item in the
352 menu, so it appears in
376 for the accelerator keys.
379 \begin_layout Enumerate
380 Consider the following excerpt from the introduction of one of the manuals:
384 \begin_layout Quotation
393 both refer to the same key.
394 Some keyboards label the
399 \begin_inset Quotes eld
403 \begin_inset Quotes erd
407 \begin_inset Quotes eld
411 \begin_inset Quotes erd
414 still others have two keys.
415 LyX treats all of them as the same key, so we'll use
426 \begin_layout Standard
427 Notice that the key name,
443 when it references the key itself! When I described how the manufacturer
444 chose to label its keyboard, I used Roman and put the word in quotes.
445 There is a semantic difference.
449 \begin_layout Enumerate
450 Take the following command:
454 \begin_layout Standard
463 \begin_layout Standard
464 Notice that the argument to the
473 \begin_inset space \thinspace{}
478 This is a case where you don't use
482 for code, because you want the generic argument label to stand out.
483 On the other hand, if you were specifying an argument, for example,
484 \begin_inset Quotes eld
492 \begin_inset Quotes erd
504 \begin_layout Enumerate
505 Any LaTeX commands and code, and any
509 LaTeX package names get set in
515 \begin_inset Quotes eld
523 \begin_inset Quotes erd
526 is the name of an unsupported LaTeX package, but
527 \begin_inset Quotes eld
535 \begin_inset Quotes erd
538 is a supported LaTeX class.
541 \begin_layout Section
545 \begin_layout Standard
546 The canonical keyboard contains these keys:
549 \begin_layout Itemize
561 \begin_layout Itemize
573 \begin_layout Itemize
586 \begin_layout Standard
590 use the abbreviations
596 \begin_layout Itemize
599 F1 F2 F3 F4 F5 F6 F7 F8 F9 F10 F11 F12
603 \begin_layout Standard
605 Most modern keyboards have all 12.
609 \begin_layout Itemize
618 \begin_layout Standard
620 \begin_inset Quotes eld
624 \begin_inset Quotes erd
631 \begin_layout Itemize
658 \begin_layout Standard
659 These are the 6 keys that appear above the cursor keys on many PC keyboards.
660 Consider them as part of the standard motion keys.
664 \begin_layout Itemize
671 \begin_layout Standard
672 The four standard motion keys.
673 There is no need to put the word
674 \begin_inset Quotes eld
678 \begin_inset Quotes erd
681 anywhere, since that's obvious.
685 \begin_layout Plain Layout
687 \begin_inset Quotes eld
691 \begin_inset Quotes erd
696 \begin_inset Quotes eld
700 \begin_inset Quotes erd
703 after one of these may be redundant in certain situations.
712 \begin_layout Itemize
725 \begin_layout Standard
726 I won't throw a hissy fit if you use one instead of the other.
727 I'd prefer if you used
735 , but it's okay if you slip up and forget.
736 Since these two keys are bound to the same function in LyX, it doesn't
741 \begin_layout Standard
742 You do not need to explain everywhere what the
751 The user isn't stupid.
752 Also, someone will document anything that isn't clear (e.
769 problem) someplace in the introduction.
770 No need for you to repeat someone else's work.
773 \begin_layout Standard
774 LyX does not support keyboards missing any of the keys described above,
776 LyX can support a keyboard missing
785 There is a keyboard accelerator for
789 , but this is the only function key LyX assumes exists.
790 Nevertheless, these details are of minor, if any, concern for the documentation.
791 Assume the aforementioned keys exist.
794 \begin_layout Section
798 \begin_layout Standard
800 \begin_inset Quotes eld
804 \begin_inset Quotes erd
807 and any description of the 3 mouse buttons have no special handling.
808 Don't typeset them in any other font than the default, which is Roman.
812 \begin_layout Standard
813 Exception: you're writing an Author's Note (see section
814 \begin_inset CommandInset ref
816 reference "sec:author-notes"
820 ) and you need to mention something about the mouse.
821 Since the rest of the note is in
825 , your description of
826 \begin_inset Quotes eld
830 \begin_inset Quotes erd
833 should be emphasized, as well.
834 There are a couple of other cases like this one; use your judgement.
837 \begin_layout Standard
838 There are only 3 mouse buttons.
839 The use of them and of the mouse itself is obvious.
840 There are few --- if any --- nonstandard things we do with the mouse.
841 Therefore, there's no need to make the word
842 \begin_inset Quotes eld
846 \begin_inset Quotes erd
850 \begin_inset Quotes eld
854 \begin_inset Quotes erd
860 \begin_layout Section
864 \begin_layout Standard
868 \begin_layout Description
881 between the words for menu and widget names.
903 \begin_layout Standard
904 This holds for things in
917 If you have a long code example, one that can't simply be inlined and put
933 \begin_layout Standard
942 so that the name doesn't get split between two lines, which is visually
952 is near the end of a line and overflows the margin, use a
958 in that parargraph (consult a LaTeX book for more about
959 \begin_inset Quotes eld
969 \begin_inset Quotes erd
972 ) or manually add a hypenation point.
976 \begin_layout Description
981 Terms These are things like the following:
985 \begin_layout Itemize
993 \begin_layout Itemize
1001 \begin_layout Itemize
1005 \begin_inset space ~
1011 \begin_layout Itemize
1015 \begin_inset space ~
1022 \begin_layout Standard
1026 \begin_inset space ~
1031 font and, in the case of
1039 , capitalize the first two letters.
1042 \begin_layout Standard
1043 Why are these terms special? They are concepts which the seasoned LaTeX-pert
1044 is familiar with, but which the new LyX user is not.
1045 I want them to stand out from the rest of the text, hence the use of
1048 \begin_inset space ~
1058 \begin_layout Standard
1059 Seasoned LyX Team Members: Are there other terms that require this special
1060 status? On the other hand, should we eliminate this style completely?
1063 \begin_layout Description
1064 Terminology Note the following:
1067 \begin_layout Itemize
1068 \begin_inset Quotes eld
1072 \begin_inset Quotes erd
1076 \begin_inset Quotes eld
1080 \begin_inset Quotes erd
1084 \begin_inset Quotes eld
1088 \begin_inset Quotes erd
1093 \begin_inset Quotes eld
1097 \begin_inset Quotes erd
1101 \begin_inset Quotes eld
1105 \begin_inset Quotes erd
1111 \begin_layout Itemize
1112 PostScript® is a registered trademark of Adobe Corp.
1115 You must put the ® after it or we'll get sued!
1117 I also want it written as seen here, always capitalized.
1119 \begin_inset Quotes eld
1123 \begin_inset Quotes erd
1127 \begin_inset Quotes eld
1131 \begin_inset Quotes erd
1135 \begin_inset Quotes eld
1139 \begin_inset Quotes erd
1142 - both of them capitalized, in the default font (i.
1143 \begin_inset space ~
1147 \begin_inset space \thinspace{}
1151 \begin_inset space ~
1155 If you must, cut and paste it from here.
1159 \begin_layout Standard
1160 I am going to say this again:
1163 \begin_layout Standard
1164 \begin_inset VSpace 0.37cm
1170 \begin_layout Standard
1175 You must put the ® after PostScript® or we'll get sued!
1178 \begin_layout Standard
1179 \begin_inset VSpace 0.51cm
1185 \begin_layout Standard
1186 I mean it! American companies like to sue anything that moves.
1191 by forgetting that ®.
1197 \begin_layout Itemize
1198 Similarly, if you use any other registered trademark in any documentation,
1199 put the ® after it, too.
1202 \begin_layout Description
1204 \begin_inset space ~
1207 Items When quick-referencing an item in a menu, use the menu separator:
1209 \begin_inset Quotes eld
1212 \SpecialChar \menuseparator
1214 \begin_inset Quotes erd
1220 File\SpecialChar \menuseparator
1224 Notice that there are
1229 \begin_inset Quotes eld
1232 \SpecialChar \menuseparator
1234 \begin_inset Quotes erd
1240 \begin_inset space ~
1245 , just like the menu and item names.
1249 \begin_layout Enumerate
1250 The reason why I want no spaces around the
1251 \begin_inset Quotes eld
1254 \SpecialChar \menuseparator
1256 \begin_inset Quotes erd
1259 is to prevent LyX from splitting terms across lines.
1260 The same goes for using
1263 \begin_inset space ~
1268 s between multi-word terms.
1269 The split would be visually disruptive.
1272 \begin_layout Enumerate
1274 \begin_inset Quotes eld
1277 \SpecialChar \menuseparator
1279 \begin_inset Quotes erd
1282 goes between menu names and item names
1287 (Yes, submenus are okay, too).
1290 \begin_layout Enumerate
1296 \begin_inset Quotes eld
1299 \SpecialChar \menuseparator
1301 \begin_inset Quotes erd
1304 between menu items and dialog names.
1306 \begin_inset Quotes eld
1314 ayout\SpecialChar \menuseparator
1319 per\SpecialChar \menuseparator
1321 \begin_inset space ~
1327 \begin_inset Quotes erd
1332 IS STRICTLY FORBIDDEN!
1338 \begin_layout Standard
1344 \begin_inset Quotes eld
1347 \SpecialChar \menuseparator
1349 \begin_inset Quotes erd
1352 between popup names and any dialog.
1354 \begin_inset Quotes eld
1360 \begin_inset space ~
1363 Dialog\SpecialChar \menuseparator
1371 \begin_inset Quotes erd
1376 IS STRICTLY FORBIDDEN!
1379 \begin_layout Standard
1385 \begin_inset Quotes eld
1388 \SpecialChar \menuseparator
1390 \begin_inset Quotes erd
1393 between menu items and any dialog.
1395 \begin_inset Quotes eld
1403 ayout\SpecialChar \menuseparator
1408 per\SpecialChar \menuseparator
1416 \begin_inset Quotes erd
1421 IS STRICTLY FORBIDDEN!
1424 \begin_layout Standard
1425 Either write out the description, or use context to eliminate any need to
1426 repeat menu items, dialog names, etc.
1431 \begin_layout Description
1433 \begin_inset space ~
1436 Boxes LyX has a feature for adding comments that appear only within the
1439 \begin_inset Note Note
1442 \begin_layout Plain Layout
1443 These should NEVER appear in the manuals.
1449 You will see nothing in a printout of the Style Sheet.
1450 Therefore, they have no place in the manuals.
1456 \begin_layout Standard
1457 If you have a parenthetical comment you want to make, the reader should
1458 see it too, even in the printed version.
1459 Use an Author's Note (see section
1460 \begin_inset CommandInset ref
1462 reference "sec:author-notes"
1466 ) in place of the Note-Boxes.
1470 \begin_layout Description
1471 \begin_inset Quotes eld
1474 (\SpecialChar \ldots{}
1476 \begin_inset Quotes erd
1480 \begin_inset space ~
1484 \begin_inset Quotes eld
1487 [\SpecialChar \ldots{}
1489 \begin_inset Quotes erd
1493 \begin_inset space ~
1497 \begin_inset space ~
1501 \begin_inset Quotes eld
1504 {\SpecialChar \ldots{}
1506 \begin_inset Quotes erd
1509 I have recently been corrected about the use of parentheses.
1510 Standard English typesetting uses the normal parentheses,
1511 \begin_inset Quotes eld
1514 (\SpecialChar \ldots{}
1516 \begin_inset Quotes erd
1519 , around any aside, remark, or parenthetical expression.
1521 \begin_inset Quotes eld
1524 [\SpecialChar \ldots{}
1526 \begin_inset Quotes erd
1529 , is used only within quotations (see section
1530 \begin_inset space ~
1534 \begin_inset CommandInset ref
1536 reference "sec:quote"
1542 \begin_inset Quotes eld
1545 {\SpecialChar \ldots{}
1547 \begin_inset Quotes erd
1551 Therefore, never use
1552 \begin_inset Quotes eld
1555 [\SpecialChar \ldots{}
1557 \begin_inset Quotes erd
1561 \begin_inset Quotes eld
1564 {\SpecialChar \ldots{}
1566 \begin_inset Quotes erd
1569 unless otherwise specified by this Style Sheet.
1572 \begin_layout Description
1573 Dashes: Be sure to use the correct one.
1575 \begin_inset Quotes eld
1583 \begin_inset Quotes erd
1586 character is not a dash, it's a hyphen.
1587 Use it only as a hyphen.
1592 \begin_layout Standard
1594 \begin_inset Quotes eld
1598 \begin_inset Quotes erd
1602 \begin_inset Quotes eld
1606 \begin_inset Quotes erd
1610 \begin_inset Quotes eld
1618 \begin_inset Quotes erd
1621 characters form the en-dash.
1623 \begin_inset Quotes eld
1631 \begin_inset Quotes erd
1634 characters create an em-dash, which is slightly longer than the en-dash.
1635 In the printed version of any document, LyX will combine the two or three
1637 \begin_inset Quotes eld
1645 \begin_inset Quotes erd
1648 characters into a single, unbroken line.
1652 \begin_layout Section
1653 Cross-References and Labels
1656 \begin_layout Standard
1657 Use the following labelling conventions:
1660 \begin_layout Labeling
1661 \labelwidthstring 00.00.0000
1662 sec:xxx Use this for
1681 \begin_layout Labeling
1682 \labelwidthstring 00.00.0000
1683 eqn:xxx Use this for Equations, should you need to create any.
1686 \begin_layout Labeling
1687 \labelwidthstring 00.00.0000
1688 tbl:xxxx Use this for tables inside of a table float.
1691 \begin_layout Labeling
1692 \labelwidthstring 00.00.0000
1693 fig:xxx Use this for figures inside of figure floats.
1696 \begin_layout Standard
1697 Additionally, you should put the label at one of two locations:
1700 \begin_layout Enumerate
1703 beginning of the paragraph
1705 , after a section heading, or at the beginning of captions, etc.
1706 It should be the first thing on the first line.
1707 Don't put a space betweeen it and the first word.
1710 \begin_layout Enumerate
1711 If there is no paragraph after a section heading, put it at the
1713 end of the last line.
1720 \begin_layout Standard
1725 which is immediately followed by a
1730 This is a case where you need to put the label at the end of the
1735 I know it looks ugly; not much we can do about that, though.
1739 \begin_layout Section
1740 Content --- What Goes Where
1743 \begin_layout Standard
1748 important to anyone documenting a new feature.
1749 If you need to add new documentation, pay attention.
1753 \begin_layout Standard
1754 In the dim and distant past, whenever someone wanted to document a new feature
1755 they added, they either wrote a mini-doc and stuck it into the documentation
1756 directory, or they added a new section to the lone manual.
1757 No one paid much attention to organization in those days, either.
1758 The result was a totally bloated, totally unnavigable, and incomplete manual
1759 orbitted by a swarm of tiny, incomplete mini-docs.
1760 I don't want the docs to fall back into that mess.
1763 \begin_layout Standard
1764 With that in mind, I have some instructions for how to keep things organized:
1767 \begin_layout Labeling
1768 \labelwidthstring 00.00.0000
1773 Please, don't touch this file.
1774 It's essentially complete, anyhow.
1775 Only the editor(s) should make changes to this, as this file contains info
1776 about how to contribute to the doc project.
1777 That's really the only stuff that should need to change, and even then,
1778 only when a new maintainer comes along.
1781 \begin_layout Labeling
1782 \labelwidthstring 00.00.0000
1787 This file is complete.
1788 Any changes should be for updates
1793 DO NOT ADD new features to here willy-nilly.
1794 Let the editor decide if --- and when --- new sections go in here.
1795 Place any new features in\SpecialChar \ldots{}
1799 \begin_layout Labeling
1800 \labelwidthstring 00.00.0000
1805 This is where all new features go from now on.
1806 It's in the style of a bound journal --- each section is an
1807 \begin_inset Quotes eld
1811 \begin_inset Quotes erd
1814 from the author of the feature.
1815 Also, anyone who writes a
1819 file for a new document class should write a section describing that new
1820 class and how to use it.
1821 That also goes here.
1825 \begin_layout Standard
1826 Note, however, that you are
1830 excused from following this Style Sheet just because the sections of
1834 are in the form of a journal article.
1838 \begin_layout Labeling
1839 \labelwidthstring 00.00.0000
1844 This file is complete.
1845 Do not change or add to without permission of the Documenation Project
1849 \begin_layout Labeling
1850 \labelwidthstring 00.00.0000
1855 This document describes advanced features, most of which alter the look,
1856 feel, and behavior of LyX.
1857 This manual is still a bit incomplete, although that may change soon.
1858 Check for updates often.
1862 \begin_layout Standard
1863 If you are unsure whether or not something belongs in
1867 , then, most-likely, it
1876 Again, let the current editor of the LyX documentation decide if your new
1877 section should be migrated to
1885 \begin_layout Labeling
1886 \labelwidthstring 00.00.0000
1891 I'd prefer to completely finish this one before doing anything else, but
1893 LyX keeps changing so much that I think the
1897 will be the last one completed.
1898 However, I'd like it if the developer's would add entries anytime they
1899 create a new function or popup.
1900 That would help things immensely!
1904 \begin_layout Standard
1909 follows this Style Sheet for the most part.
1910 There are, however, additional rules to follow when making new entries.
1911 At the top of this manual, there are examples of and a template for
1920 \begin_layout Section
1921 Writing Style: The Primary Manuals
1924 \begin_layout Standard
1925 While I want to make contributing to the Documentation Project as painless
1926 as possible for newcomers, I also want the newcomers to be painless on
1927 the existing Documentation Team! Ergo, I've written this section to give
1928 some flavor to guide everyone's individual style.
1932 \begin_layout Subsection
1936 \begin_layout Standard
1937 All contributions to the
1941 LyX documentation must be in English.
1942 I don't care if it's British, Australian, or American English.
1943 The DocTeam editor will proofread for glaring mistakes and fix them.
1946 \begin_layout Standard
1947 Don't get hung up on semantics.
1948 English is a flexible language, and just because your Mothertongue-to-English
1949 dictionary gives only one translation for a word doesn't necessarily mean
1951 We've had some discussions and misunderstandings on the Developers' List
1952 because of this very problem.
1953 If something is unclear (or just plain weird) due to a translation problem,
1954 one of the American/British/Australian developers can fix it.
1957 \begin_layout Standard
1962 documentation, I exclude the translations.
1963 We usually don't have enough people to cover the manuals in one language,
1964 let alone more than one.
1965 Subsequently, the tranlsations are just that --- translations of the English
1966 version of the LyX manuals.
1967 The translation efforts require have their own set of guidelines.
1969 \begin_inset CommandInset ref
1971 reference "sec:translations"
1978 \begin_layout Subsection
1980 \begin_inset Newline newline
1983 Commentary from the Author (i.
1984 \begin_inset space ~
1990 \begin_layout Standard
1991 \begin_inset CommandInset label
1993 name "sec:author-notes"
1997 I want to make it easy for everyone when it comes to documenting things.
1998 Some features are incomplete.
1999 Some, you might not know everything about.
2000 Sometimes, you may want to comminucate something to me or the reader or
2001 other DocTeam members.
2002 Sometimes, you may want to
2003 \begin_inset Quotes eld
2007 \begin_inset Quotes erd
2010 you want to say something that is your personal opinion and using
2011 \begin_inset Quotes eld
2015 \begin_inset Quotes erd
2018 would be inappropriate.
2021 \begin_layout Standard
2022 In short, when you contribute to the LyX Docs, you wear many hats.
2025 \begin_layout Standard
2026 For occasions when you need to switch hats, I've designed some special mechanism
2030 \begin_layout Subsubsection
2032 \begin_inset space ~
2036 \begin_inset Quotes eld
2040 \begin_inset Quotes erd
2046 \begin_layout Standard
2047 These are footnotes.
2048 They begin with the following:
2059 \begin_layout Standard
2060 \SpecialChar \ldots{}
2065 for the person's name and without the quotes.
2066 The rest of the footnote is the actual comment.
2070 \begin_layout Standard
2071 Use these when you need to quote a comment by someone (usually yourself),
2072 and need to identify that person.
2073 This includes occasions when you need wear the
2074 \begin_inset Quotes eld
2078 \begin_inset Quotes erd
2082 \begin_inset space ~
2086 \begin_inset space ~
2089 to speak for yourself instead of for the LyX Team.
2092 \begin_layout Standard
2093 If the comment is too large to put in a footnote, don't use a Personal Note.
2094 When quoting more than about 3 sentences or 5 lines of text, use a bona
2096 Don't use any leading
2097 \begin_inset Quotes eld
2105 \begin_inset Quotes erd
2109 In a real quote, you'll give credit to the original speaker in either the
2110 paragraph before or after the body of the
2117 \begin_layout Subsubsection
2119 \begin_inset space ~
2123 \begin_inset Quotes eld
2127 \begin_inset Quotes erd
2133 \begin_layout Standard
2134 There will be times when you are not speaking for the LyX Team, yet you
2135 are not entirely speaking for yourself.
2136 Instead, you are speaking on behalf of the manual itself, as the author
2138 Some examples of when you might need to do this are:
2141 \begin_layout Itemize
2142 You need to contradict something you just wrote because the feature isn't
2143 quite ready yet, but you wanted to document what it will do.
2146 \begin_layout Itemize
2147 You need to leave a note for yourself.
2150 \begin_layout Itemize
2151 You need to leave a note for the editor or the other DocTeam members.
2154 \begin_layout Itemize
2155 You need to point out something about the manuals to the reader, something
2156 that doesn't fit into the context of the current paragraph.
2159 \begin_layout Standard
2160 At such times, you are wearing your
2161 \begin_inset Quotes eld
2165 \begin_inset Quotes erd
2171 \begin_layout Standard
2172 The typography for an
2173 \begin_inset Quotes eld
2177 \begin_inset Quotes erd
2183 \begin_layout Itemize
2184 They go in the body of the text, in brackets,
2185 \begin_inset Quotes eld
2189 \begin_inset Quotes erd
2192 , not any other form of parentheses.
2193 The bracket are in the default character style.
2196 \begin_layout Itemize
2197 The text of the note itself, however, is emphasized.
2201 \begin_layout Itemize
2202 Begin with the words,
2203 \begin_inset Quotes eld
2211 \begin_inset Quotes erd
2214 and end with an em-dash,
2215 \begin_inset Quotes eld
2219 \begin_inset Quotes erd
2222 , followed by your initials.
2226 \begin_layout Standard
2227 Here's an example: [
2229 Author's Note: This is an example note.
2235 \begin_layout Standard
2236 The form of the Author's Note, by the way, isn't a suggestion or request.
2242 All Author's Notes must begin with this text, verbatim:
2243 \begin_inset Quotes eld
2251 \begin_inset Quotes erd
2256 \begin_inset Quotes eld
2260 \begin_inset Quotes erd
2263 are or any other variant are forbidden.
2264 The Author's Note must end with an em-dash, which is 3
2265 \begin_inset Quotes eld
2269 \begin_inset Quotes erd
2273 \begin_inset Quotes eld
2277 \begin_inset Quotes erd
2282 \begin_inset Quotes eld
2286 \begin_inset Quotes erd
2289 ; you must use 3 (and 5 is right out).
2292 \begin_layout Standard
2293 \begin_inset Quotes eld
2297 \begin_inset Quotes erd
2300 are inherently transient, and should disapear as a manual matures.
2303 \begin_layout Subsubsection
2307 \begin_layout Standard
2308 You are also free to use footnotes on their own in addition to the Personal
2309 Notes and/or Author's Notes.
2310 I've frequently used footnotes to \SpecialChar \ldots{}
2311 well, to comment on parts of a section
2312 without putting the commentary into the body of the text.
2315 \begin_layout Paragraph*
2316 Mixing Footnotes and Personal Notes
2319 \begin_layout Standard
2320 Personal Notes always go in footnotes, and should be 5 lines or fewer.
2321 Any larger quotation should be quoted properly, using the rules of standard
2327 paragraph environment.
2330 \begin_layout Paragraph*
2331 Mixing Footnotes and Author's Notes
2334 \begin_layout Standard
2335 Author's Notes should
2343 \begin_layout Paragraph*
2344 Mixing Personal Notes and Author's Notes
2347 \begin_layout Standard
2348 Forbidden; these two are mutually exclusive.
2351 \begin_layout Subsubsection
2355 \begin_layout Itemize
2357 \begin_inset Newline newline
2364 opinion --- yours or another LyX developer's --- about anything.
2365 Anywhere in the manuals you wish to speak for yourself instead the the
2367 If you have a long rant, however, quote yourself (see section
2368 \begin_inset space ~
2372 \begin_inset CommandInset ref
2374 reference "sec:quote"
2381 \begin_layout Itemize
2383 \begin_inset Newline newline
2386 Use this to describe things in LyX (or the manuals) that may change in the
2387 future or are somehow incomplete.
2388 Author's Notes are supposed to disappear as a manual matures.
2391 \begin_layout Itemize
2393 \begin_inset Newline newline
2396 Used for text fragments that almost fit into the flow of the text\SpecialChar \ldots{}
2401 \begin_layout Standard
2402 When using these three mechanisms, in addition to rigorously following their
2403 descriptions, please use them properly.
2404 I listed some additional restrictions previously.
2405 Some of you may balk at these restrictions.
2406 Nevertheless, there is a reason for them: if you have an overwhemling desire
2407 to mix or modify footnotes, Personal Notes, and Author's Notes, you shouldn't
2408 be using any of them.
2409 More specifically, you're trying to use a hammer to drive in a screw.
2410 What you want to say probably needs to go into the main body of the text.
2413 \begin_layout Subsection
2414 General Stylistic Guidelines
2417 \begin_layout Standard
2418 Everything in this section is
2420 mandatory to all documenters
2422 , regardless the language you're writing in.
2426 \begin_layout Subsubsection
2430 \begin_layout Enumerate
2431 Use the typography rules outlined in the beginning sections of this document.
2434 \begin_layout Enumerate
2435 Don't, however, mimic the typography of this file.
2436 Yes, the Style Sheet doesn't follow the Style Sheet (grin).
2439 \begin_layout Enumerate
2440 There is some typographic freedom in those rules in earlier sections.
2441 Use that freedom wisely.
2442 Most importanly, never sacrifice the online appearance for the printed
2443 appearance and vice versa.
2447 \begin_layout Standard
2448 An example is in the
2453 There is a footnote using the
2457 command to divide a long
2461 environment into 3 columns.
2462 It adds some LaTeX commands to the online version, the so-called
2463 \begin_inset Quotes eld
2467 \begin_inset Quotes erd
2470 that some so vehemently oppose.
2471 Without it, however, that footnote takes up over two pages, most of which
2473 This is an example of permitting a little ugliness in the online version
2474 to get the printed version to look right.
2478 \begin_layout Enumerate
2479 When in doubt, compromise.
2483 \begin_layout Standard
2484 When in doubt, use good judgement.
2488 \begin_layout Subsubsection
2492 \begin_layout Enumerate
2494 \begin_inset Quotes eld
2498 \begin_inset Quotes erd
2505 \begin_layout Standard
2506 When you speak, you speak for the entire LyX Team, so use
2507 \begin_inset Quotes eld
2511 \begin_inset Quotes erd
2515 \begin_inset Quotes eld
2519 \begin_inset Quotes erd
2526 \begin_layout Enumerate
2528 \begin_inset Quotes eld
2532 \begin_inset Quotes erd
2539 \begin_layout Standard
2540 Whenever you want to say something to the reader, use
2541 \begin_inset Quotes eld
2545 \begin_inset Quotes erd
2548 not some contorted construction to avoid being too informal.
2553 \begin_layout Enumerate
2555 \begin_inset Quotes eld
2559 \begin_inset Quotes erd
2562 for both the physical pointing object (mouse, joystick, touch pad, track
2563 ball, etc.) and the mouse cursor which the physical object moves about the
2567 \begin_layout Enumerate
2569 \begin_inset Quotes eld
2573 \begin_inset Quotes erd
2576 for the little blinking vertical bar that indicates where text can/will
2580 \begin_layout Enumerate
2581 When in doubt, compromise.
2585 \begin_layout Standard
2586 When in doubt, use good judgement.
2590 \begin_layout Subsubsection
2591 \begin_inset CommandInset label
2597 Quoting Yourself and Others
2600 \begin_layout Standard
2601 In some cases, you'll have something to say, an opinion of yours.
2602 Since this is your opinion, you're not speaking for the LyX Team.
2603 You have so much to say, in fact, that it won't fit into a Personal Note
2604 or an Author's Note.
2605 In these cases you want to quote yourself.
2608 \begin_layout Standard
2609 Any time you wish to quote someone, be it yourself or someone else, there
2610 are standard rules one follows.
2611 Every language has its own rules.
2612 You should follow the rules that apply to the language of the document
2613 to which you are contributing.
2617 \begin_layout Standard
2618 This creates a problem for the primary documentation.
2619 The primary documentation is written in English, yet the contributors come
2620 from many countries.
2621 The quoting rules for English (well, American English, at least) are outlined
2625 \begin_inset space ~
2630 , for your convenience.
2631 Read them if you need to.
2634 \begin_layout Standard
2635 \begin_inset Float figure
2641 \begin_layout Plain Layout
2642 Quoting rules for English:
2645 \begin_layout Itemize
2646 The body of the quote belongs in a
2653 \begin_layout Itemize
2654 The sentences prior to the quote should flow logically and smoothly into
2658 \begin_layout Itemize
2659 The sentences immediately following the quote should continue the flow of
2663 \begin_layout Itemize
2668 credit the original author of the quote in the sentences immediately before
2672 \begin_layout Itemize
2673 Crediting the original author of the quote should not, however, disrupt
2674 the flow of the text.
2677 \begin_layout Itemize
2678 If you omit text from the beginning of the first sentence in the quote,
2679 the quote must start with the text
2680 \begin_inset Quotes eld
2683 [\SpecialChar \ldots{}
2685 \begin_inset Quotes erd
2689 This is an ellipsis in square brackets.
2692 \begin_layout Itemize
2693 If you omit text from the end of the last sentence in the quote, the quote
2694 must end with the text
2695 \begin_inset Quotes eld
2698 [\SpecialChar \ldots{}
2700 \begin_inset Quotes erd
2703 followed by the sentence's punctuation mark.
2706 \begin_layout Itemize
2707 If you omit any text from the middle of the quote, be it whole sentences
2708 or parts of sentences, replace it with the text
2709 \begin_inset Quotes eld
2712 [\SpecialChar \ldots{}
2714 \begin_inset Quotes erd
2720 \begin_layout Itemize
2721 The quote must be grammatically correct.
2726 \begin_layout Itemize
2727 If the original is wrong, you must correct it.
2730 \begin_layout Itemize
2731 If omitting part of the quote
2732 \begin_inset Quotes eld
2736 \begin_inset Quotes erd
2739 it, you must correct the problem.
2742 \begin_layout Itemize
2743 For missing words (e.
2744 \begin_inset space ~
2748 \begin_inset space ~
2752 \begin_inset Quotes eld
2756 \begin_inset Quotes erd
2759 goes missing), place the word in square brackets,
2760 \begin_inset Quotes eld
2763 [\SpecialChar \ldots{}
2765 \begin_inset Quotes erd
2768 and insert in the quote where needed.
2771 \begin_layout Itemize
2772 For mangled word order, correct the mangled text, following it with the
2774 \begin_inset Quotes eld
2778 \begin_inset Quotes erd
2785 \begin_layout Itemize
2786 Spelling in the quote must be correct.
2787 Correct any misspelled words and place the text
2788 \begin_inset Quotes eld
2792 \begin_inset Quotes erd
2795 after the corrected word.
2798 \begin_layout Itemize
2799 Back-to-back bracket blocks merge together.
2801 \begin_inset Quotes eld
2804 [\SpecialChar \ldots{}
2806 \begin_inset Quotes erd
2811 \begin_inset Quotes eld
2814 [\SpecialChar \ldots{}
2816 \begin_inset Quotes erd
2822 \begin_layout Itemize
2823 If you correct the spelling in 2 or more consecutive words, you can get
2825 \begin_inset Quotes eld
2829 \begin_inset Quotes erd
2832 after the last mistake.
2840 \begin_layout Subsubsection
2844 \begin_layout Standard
2845 When describing a new feature or
2852 \begin_layout Enumerate
2863 \begin_inset Quotes eld
2866 Keep It Short and Sweet
2867 \begin_inset Quotes erd
2871 \begin_inset Quotes eld
2874 Keep It Simple, Stupid!
2875 \begin_inset Quotes erd
2882 \begin_layout Itemize
2887 write paragraph after paragraph of verbage.
2891 \begin_layout Itemize
2895 \begin_layout Itemize
2896 Take a look at the manual for a commercial word processor --- it's a fine
2901 to write documentation.
2902 It's all pithy, substanceless verbage, and its
2910 \begin_layout Enumerate
2911 Avoid being pedantic like The Plague!
2914 \begin_layout Enumerate
2915 In the same vein, don't write more than you have to.
2916 You're not working in a vacuum --- refer freely to other parts of the manual
2917 (and other parts of other manuals).
2919 \begin_inset Quotes eld
2922 other part of the manual
2923 \begin_inset Quotes erd
2926 is incomplete or empty, refer to it.
2927 Someone will fill it in eventually.
2930 \begin_layout Enumerate
2931 On the other hand, BE THOROUGH!
2935 \begin_layout Enumerate
2940 , not widgets, not how the source code is organized.
2943 \begin_layout Enumerate
2944 Group by feature, not by widget.
2947 \begin_layout Enumerate
2948 Stay on topic --- one
2961 s and further subdivisions to group things if you're documenting several
2962 related features in a single
2969 \begin_layout Enumerate
2970 Describe EVERYTHING related to that feature, no matter where it is.
2974 \begin_layout Enumerate
2975 Example: Paragraph Indenting.
2976 Several popups control its behavior.
2981 of this: which popups control it, when you use which setting on which popup
2982 to do which operation, et cetera.
2985 \begin_layout Enumerate
2991 \begin_inset Newline newline
2994 I've had people only document one popup --- literally.
2995 This added off-topic information and only described half of the feature,
2996 since other menus, popups, and even unbound functions contained additional
2998 \begin_inset Newline newline
3005 cranky when that happens, because it means
3010 Bad help is worse than no help at all.
3014 \begin_layout Standard
3015 These remarks still hold true: you'll piss of the DocTeam editor if you
3016 do things wrong, because he'll have to fix your mistakes.
3021 \begin_layout Enumerate
3022 Remember, there are people who will reference
3026 section, just as you're referencing someone else's.
3027 You do want what you write to be useful, don't you?
3031 \begin_layout Enumerate
3032 When in doubt, compromise.
3036 \begin_layout Standard
3037 When in doubt, use good judgement.
3041 \begin_layout Subsubsection
3046 Treat the Reader as if She is Stupid
3049 \begin_layout Enumerate
3053 \begin_layout Enumerate
3054 No talking down to the reader.
3057 \begin_layout Enumerate
3058 The reader is smart enough to know what a mouse is.
3061 \begin_layout Enumerate
3062 The reader is smart enough to know how to use a keyboard, including the
3076 (The introduction of most of the manuals takes care of the
3077 \begin_inset Quotes eld
3089 \begin_inset Quotes erd
3092 issue, so you don't need to.)
3095 \begin_layout Enumerate
3096 The reader is smart enough to know that
3097 \begin_inset Quotes eld
3101 \begin_inset Quotes erd
3105 \begin_inset Quotes eld
3108 where the text cursor is sitting right now, in the buffer currently visible.
3109 \begin_inset Quotes erd
3114 (Anything more than the word
3115 \begin_inset Quotes eld
3119 \begin_inset Quotes erd
3122 is, IMO, superfluous and wll be deleted .
3123 So, save yourself the typing, save the editor the cutting, and save the
3124 reader the strain of sifting through extra verbage that adds no content.)
3127 \begin_layout Enumerate
3128 Rule of thumb: the reader is not an imbecile.
3129 The reader is merely lost; point them in the right direction, and they
3130 can take it from there.
3133 \begin_layout Subsection
3134 Tips for the English Version
3137 \begin_layout Standard
3138 \begin_inset CommandInset label
3140 name "sec:english-only"
3144 When contributing to the primary --- i.
3145 \begin_inset space ~
3149 \begin_inset space ~
3152 the English language version --- of the LyX manuals, keep the following
3156 \begin_layout Subsubsection
3157 Write as if You're Talking with a Friend.
3161 \begin_layout Enumerate
3162 Think that way when you write.
3163 Play the dialogue in your mind.
3166 \begin_layout Enumerate
3167 Be as informal as you please (without being rude).
3170 \begin_layout Subsubsection
3171 AVOID the Passive Voice
3174 \begin_layout Enumerate
3176 \begin_inset Quotes eld
3179 It is felt that this name best explains the command's purpose.
3180 \begin_inset Quotes erd
3183 We know full well who wrote the command:
3184 \begin_inset Quotes eld
3187 The LyX Team felt ...
3188 \begin_inset Quotes erd
3192 \begin_inset Quotes eld
3196 \begin_inset Quotes erd
3202 \begin_layout Enumerate
3203 Things don't happen by magic - somebody or something did it.
3204 Only politicians use the passive voice to cover up who did something.
3205 If LyX reformats a paragraph, write,
3206 \begin_inset Quotes eld
3209 LyX reformatted the paragraph.
3210 \begin_inset Quotes erd
3217 makes changes, write,
3218 \begin_inset Quotes eld
3225 changes the document.
3226 \begin_inset Quotes erd
3233 \begin_layout Standard
3234 Rule of thumb: any sentence you can express as,
3235 \begin_inset Quotes eld
3239 \begin_inset Quotes erd
3243 \begin_inset Quotes eld
3247 \begin_inset Quotes erd
3254 \begin_layout Enumerate
3256 We all hear way, way too much garbage English on the TV every day in the
3258 Some people think it makes speech better.
3260 It makes speech baroque, if not outright byzantine.
3261 With a little effort, you can wean yourself off of it.
3264 \begin_layout Enumerate
3267 will make you rewrite
3269 anything in the passive voice.
3270 It's awkward and hard to read.
3273 \begin_layout Enumerate
3274 Note to non-Americans:
3278 \begin_layout Standard
3279 Using passive voice is generally considered bad style in the U.
3280 \begin_inset space ~
3284 \begin_inset space ~
3287 as it is too easy to obfuscate your words with it.
3288 It also bloats sentences, often unnecessarily.
3292 \begin_layout Subsubsection
3297 \begin_layout Standard
3298 In English, there is a grammatical error known as the
3299 \begin_inset Quotes eld
3303 \begin_inset Quotes erd
3306 The classic example of a run-on sentence is 7 clauses strung together with
3308 \begin_inset Quotes eld
3312 \begin_inset Quotes erd
3315 There are, however, less obvious run-on sentences, ones using too many
3316 subordinate clauses.
3317 Such sentences may look elegant because they are complex.
3318 However, they are also extremely difficult to read because they are so
3322 \begin_layout Standard
3323 In general, stick to short sentences in written English.
3324 Getting rid of passive voice (
3325 \begin_inset Quotes eld
3328 \SpecialChar \ldots{}
3329 was done by\SpecialChar \ldots{}
3331 \begin_inset Quotes erd
3334 ) shortens and simplifies them.
3335 Hacking apart sentences with many dependent clauses is another way to shorten
3337 There are ways to do this yet still have a smooth-flowing paragraph.
3340 \begin_layout Standard
3341 While I'm talking about paragraphs, I'll apply the
3342 \begin_inset Quotes eld
3346 \begin_inset Quotes erd
3349 motto to them, as well.
3350 At the time I started with the manuals (and this Style Sheet), I didn't
3351 pay too much attention to paragraph size.
3352 I've since become a big proponent of short paragraphs, with one idea per
3354 While long, flowing, multi-concept paragraphs can be nice in novels, we're
3356 Our goal is rapid information location and comprehension, not a literary
3360 \begin_layout Standard
3361 There is a single exception to the short sentence, short paragraph rule.
3362 Particularly complex ideas may need more
3363 \begin_inset Quotes eld
3367 \begin_inset Quotes erd
3370 However, you shouldn't encounter such complex ideas often when documenting
3372 Try to keep things short, and use your judgement as needed.
3375 \begin_layout Standard
3376 To reiterate, yet again, something I said before:
3380 When in doubt, compromise.
3384 When in doubt, use good judgement.
3387 \begin_layout Standard
3388 Hopefully, you've got the idea (grin).
3391 \begin_layout Section
3395 \begin_layout Subsection
3396 Rules of the Translating Trade
3399 \begin_layout Standard
3400 While translating anything, there are certain
3401 \begin_inset Quotes eld
3405 \begin_inset Quotes erd
3409 They will help you greatly.
3412 \begin_layout Subsubsection
3413 Translate one paragraph at a time.
3416 \begin_layout Standard
3417 Most people translate word by word.
3418 Clearly, you lose all context if you do that.
3419 A word may have multiple meanings.
3420 You can't tell which unless you look at the rest of the sentence.
3423 \begin_layout Standard
3424 There is another level to the context issue, however.
3425 Your dictionary may translate multiple English words the same way.
3426 All those words mean
3431 Each one, however, covers a different shade of meaning, a different mood
3433 It is often difficult to resolve those shades of meaning in the context
3434 of even one sentence.
3435 A paragraph, however, will provide that context.
3438 \begin_layout Subsubsection
3439 You will not translate it correctly on the first try.
3442 \begin_layout Standard
3443 Alright, I admit that you may be able to translate some of the sentences
3445 If you know a language well, you may even understand over half of the text.
3446 Nevertheless, overconfidence can lead you astray.
3447 There will be some sentences, no matter how few, that will simply confound
3451 \begin_layout Standard
3452 It is generally a good idea to make multiple passes over a paragraph you're
3454 Even if you translate the entire paragraph on the first pass, make a second
3456 You'll often improve upon your first attempt.
3459 \begin_layout Subsubsection
3460 When in doubt, write down all of the meanings for a word.
3463 \begin_layout Standard
3464 You can often translate tricky parts of a text using the context of the
3465 surrounding sentences.
3466 So, if you hit a word or phrase you don't know, translate it more than
3468 Picking the most likely translations, summarize them in one to three words
3470 \begin_inset Quotes eld
3474 \begin_inset Quotes erd
3481 \begin_layout Subsubsection
3482 Using context, fix the meanings on the next pass.
3485 \begin_layout Standard
3486 This is where your multiple translations of a single word become useful.
3487 Using the other sentences you translated, you can now translate that mystery--s
3488 entence without reconsulting your dictionary.
3491 \begin_layout Subsubsection
3492 Fix the grammar only after you've finished translating the sentence.
3495 \begin_layout Standard
3496 If there's a mystery phrase in the middle of a sentence, you can't translate
3497 the entire sentence.
3498 Why grammatically rearrange the words you translated already? You may need
3499 to restructure the sentence a second time once you figure out how to translate
3500 that mystery phrase.
3501 Better to wait until you've completely translated the sentence to clean
3503 That way, you do so only once.
3506 \begin_layout Subsubsection
3507 If you can't translate it, skip it and come back to it on the next pass.
3510 \begin_layout Standard
3511 Remember the earlier discussion of context and its immense usefulness? There
3512 is no sin in making multiple passes over a tricky passage.
3515 \begin_layout Subsubsection
3516 Translate the meaning first.
3520 \begin_layout Standard
3521 The information content of the text under translation is the most important
3523 This is especially important for a manual, where the information
3527 important part of the original document.
3528 Lose that, and you lose the very point of performing the translation.
3531 \begin_layout Subsection
3532 Tips for the Translators
3535 \begin_layout Standard
3536 Those of you contributing to a translation of the LyX manuals must follow
3537 a modified set of rules.
3538 The first few rules are analogous to those in section
3539 \begin_inset space ~
3543 \begin_inset CommandInset ref
3545 reference "sec:english-only"
3550 There are additional rules and regulations that follow those first few.
3554 \begin_layout Subsubsection
3555 Write as if you are explaining LyX to a colleague you know well.
3558 \begin_layout Enumerate
3559 Think that way when you write.
3560 Play the dialogue in your mind.
3563 \begin_layout Enumerate
3564 Use a conversational style in your writing.
3565 Pretend you are teaching LyX to a colleague you know well.
3568 \begin_layout Enumerate
3569 Use a style that is polite without being too formal.
3570 If, in your culture, informal language is appropriate to use with a colleague,
3571 use informal speech in the translation of the manual.
3574 \begin_layout Subsubsection
3575 AVOID Snobby, Academic, Specialized, or
3576 \begin_inset Quotes eld
3580 \begin_inset Quotes erd
3587 \begin_layout Standard
3588 In English, the passive voice appears formal, dry, barren.
3589 It also often adds unnecessary complexity.
3590 In other langauges, however, this is not the case.
3591 There is nothing wrong with passive voice, and people use it frequently
3592 in everyday conversation.
3593 Nevertheless, your translation of the LyX manuals must avoid
3594 \begin_inset Quotes eld
3598 \begin_inset Quotes erd
3604 \begin_layout Standard
3605 In Germany, there is a magazine known as
3606 \begin_inset Quotes gld
3610 \begin_inset Quotes grd
3613 The writing in it is so complex, it is extremely difficult for non-native
3614 German speakers to understand.
3615 While sophisticated, the writing style of
3616 \begin_inset Quotes gld
3620 \begin_inset Quotes grd
3623 is not what a German uses in everyday conversation.
3624 Nor is the writing style for a Russian mathematics journal.
3625 Such specialized or overly-sophisticated styles are
3626 \begin_inset Quotes eld
3630 \begin_inset Quotes erd
3633 in the sense that they are seldom used by normal people in everyday speech.
3636 \begin_layout Standard
3637 We who write the LyX manuals, original or translated, seek to
3642 If we write in a style only a few people use, and use seldomly, we will
3644 Use a writing style that mirrors everyday speech (without being vulgar,
3649 \begin_layout Subsubsection
3650 Keep the Writing Simple.
3653 \begin_layout Standard
3654 For the English version, I wrote,
3655 \begin_inset Quotes eld
3658 Use short sentences and short paragraphs.
3659 \begin_inset Quotes erd
3662 What if, however, short sentences and paragraphs are something only children
3663 use in your language? What if, in yet another language, short sentences
3664 imply rudeness? Naturally, you would not want to use them in your translation.
3667 \begin_layout Standard
3668 Nevertheless, the translations of the LyX manuals should be as clear as
3670 So, for our international colleagues, we apply this rule: Keep your sentences
3671 and paragraphs as short as makes sense.
3674 \begin_layout Standard
3675 Remember: we're translating manuals here, folks.
3676 Our goal is rapid information location and comprehension, not a literary
3678 Try to keep your writing concise yet smooth-flowing.
3679 And use your judgement as needed:
3683 When in doubt, compromise.
3687 When in doubt, use good judgement.
3690 \begin_layout Subsubsection
3691 Translators must follow the Style Sheet, too!
3694 \begin_layout Standard
3695 Everything in this manual ---
3698 \begin_inset space ~
3702 \begin_inset CommandInset ref
3704 reference "sec:english-only"
3710 --- applies to every LyX documenter, no matter what the language.
3713 \begin_layout Subsubsection
3714 Translators must read the Style Sheet Supplement for their language.
3717 \begin_layout Standard
3718 For every translation project, there is a Supplement to the Style Sheet.
3725 DocStyle_Supplement_<cn>.lyx
3728 \begin_layout Standard
3729 \SpecialChar \ldots{}
3731 \begin_inset Quotes eld
3739 \begin_inset Quotes erd
3742 is your language's two-letter locale code.
3743 The Translation Project Chief for your language wrote this.
3744 If he hasn't, pester him to do so! <
3751 \begin_layout Subsubsection
3752 The English versions of the manuals are not Sacred Text.
3755 \begin_layout Standard
3756 You do not need to translate everything word for word.
3757 In fact, you shouldn't.
3758 Keep to the spirit of the originals, not the letter.
3759 Be as creative as you want, as long as you
3767 convey all of the information contained in the English versions.
3770 \begin_layout Subsubsection
3771 Any information in the LyX manuals must also be in the translations.
3774 \begin_layout Standard
3775 \begin_inset CommandInset label
3781 This falls under translating the orignals accurately and completely.
3785 \begin_layout Itemize
3786 Omitting any feature description is
3793 \begin_layout Itemize
3794 Misrepresenting or misdescribing any LyX feature or operation
3801 \begin_layout Itemize
3806 outpace the original.
3807 \begin_inset Newline newline
3810 If no one has documented new feature in the primary LyX manuals (i.
3811 \begin_inset space ~
3815 \begin_inset space ~
3818 the English versions), do not do so in the translations.
3819 If you're really looking for something to do, either:
3823 \begin_layout Itemize
3824 \SpecialChar \ldots{}
3825 focus on translating something you haven't yet,
3826 \begin_inset Newline newline
3832 \begin_layout Itemize
3833 \SpecialChar \ldots{}
3834 update or repair the primary manual.
3837 \begin_layout Standard
3838 If you cannot or do not want to do one of the above, then take a break.
3840 Wait for the main manuals to catch up before translating anything else.
3844 \begin_layout Subsubsection
3845 What you cannot translate, you may omit (usually).
3848 \begin_layout Standard
3849 Prepositions, idioms, metaphors, slang, Oh My! There's a jungle of potentially
3850 untranslatable text you may face.
3851 Happily, none of these untranslatables are essential to the original text\SpecialChar \ldots{}
3854 If you can't translate a phrase or two, try omitting them.
3855 If the rest of the paragraph still makes sense, then don't worry about
3859 \begin_layout Standard
3860 There may be special cases where omitting part of a sentence or paragraph
3862 \begin_inset space ~
3866 \begin_inset CommandInset ref
3868 reference "sec:accuracy"
3877 You must try and translate those tricky spots.
3880 \begin_layout Subsubsection
3881 Translators may add their own fluff to the information content.
3884 \begin_layout Standard
3885 After you do strip away all of the idioms, metaphors, slang, humor, and
3887 \begin_inset Quotes eld
3891 \begin_inset Quotes erd
3894 you may find that your translated manual is dull and dry.
3895 Why not add your own fluff? Add text that makes the manual a pleasure to
3896 read, that engages the reader.
3897 It may take the form of humor, or metaphors, or sayings.
3898 Whatever you add, it should be
3899 \begin_inset Quotes eld
3903 \begin_inset Quotes erd
3906 It should not clash with the explanation of LyX features and functions.
3909 \begin_layout Subsection
3910 For Translation Project Chiefs
3913 \begin_layout Subsubsection
3914 The First Is In Charge
3917 \begin_layout Standard
3918 If you were the first person to start translating the manuals, you're the
3919 LyXDoc Translation Project Chief for your language.
3924 person translating the LyXDocs, that automatically makes you the Translation
3928 \begin_layout Standard
3929 Amongst other things, that means that you must read this section and perform
3930 the tasks described here.
3933 \begin_layout Standard
3934 If you are a member of a LyX Documentation Translation Team, but
3938 its Chief, you may stop reading.
3939 The remainder of this section will be of no interest to you.
3940 If you came to the Style Sheet from the Supplement for your language, you
3944 \begin_layout Standard
3945 If you have not read the Style Sheet Supplement for your language, you should
3950 \begin_layout Subsubsection
3951 Read the Style Sheet
3954 \begin_layout Standard
3955 No documenter is excused from following the Style Sheet, not even a Translation
3959 \begin_layout Standard
3964 important that the Translation Project Chiefs read the Style Sheet.
3967 \begin_layout Subsubsection
3968 Make your translators read the Style Sheet
3971 \begin_layout Standard
3972 No documenter is excused from following the Style Sheet.
3975 \begin_layout Standard
3976 Since your translation team is translating, they know
3981 Therefore, they should be able to read the Style Sheet.
3984 \begin_layout Subsubsection
3986 \begin_inset Quotes eld
3990 \begin_inset Quotes erd
3996 \begin_layout Standard
3997 There are parts of this Style Sheet that are English-specific.
3998 I have tried to provide a general, language-independent description of
3999 certain details in this section.
4000 Unfortunately, that general description doesn't cover the specifics of
4005 \begin_layout Standard
4006 That's where you, as head of a LyXDoc Translation Team, come in.
4009 \begin_layout Standard
4010 Every Translation Team Chief is
4014 to write a Supplement to the official Documentation Style Sheet, with specifics
4015 issues affecting your language.
4016 (You are, after all, the LyX Team expert on your native tongue.) Follow
4017 these guidelines when writing the Supplement:
4020 \begin_layout Enumerate
4022 \begin_inset Newline newline
4027 DocStyle_Supplement_<cn>.lyx
4030 \begin_inset Newline newline
4033 \SpecialChar \ldots{}
4035 \begin_inset Quotes eld
4043 \begin_inset Quotes erd
4046 is the two-letter code for your language.
4047 This is the same two-letter code that is part of the filenames for the
4050 \begin_inset Quotes eld
4058 \begin_inset Quotes erd
4062 \begin_inset Quotes eld
4070 \begin_inset Quotes erd
4074 \begin_inset Quotes eld
4082 \begin_inset Quotes erd
4088 \begin_layout Enumerate
4089 Do not worry about where the file goes.
4090 The CVS maintainers will locate all documentation and Style Sheet Supplements
4091 in an appropriate place.
4094 \begin_layout Enumerate
4095 Document Properties:
4099 \begin_layout Itemize
4100 For consistency, use the same document class and other document properties
4105 \begin_layout Plain Layout
4106 Specifically, check the settings in the
4111 Use those in your Supplement.
4119 \begin_layout Itemize
4120 Exceptions: Use margins, indentation/paragraph separation, language, and
4121 encoding appropriate for your language.
4125 \begin_layout Enumerate
4126 The title of the Supplement:
4130 \begin_layout Itemize
4131 The title will use the
4132 \begin_inset Quotes eld
4140 \begin_inset Quotes erd
4143 paragraph environment.
4144 In your native tongue, the title will read:
4148 \begin_layout Standard
4151 Documentation Project Style Sheet:
4152 \begin_inset Newline newline
4155 Supplement for the <foo> Translation Project
4158 \begin_layout Standard
4160 \begin_inset Quotes eld
4168 \begin_inset Quotes erd
4171 with the name of your language.)
4175 \begin_layout Itemize
4176 If, in your language,
4177 \begin_inset Quotes eld
4181 \begin_inset Quotes erd
4185 \begin_inset Quotes eld
4189 \begin_inset Quotes erd
4194 \begin_inset Quotes eld
4198 \begin_inset Quotes erd
4202 \begin_inset Quotes eld
4206 \begin_inset Quotes erd
4209 have somewhat different meanings.
4210 An appendix is an extra part of a document.
4211 A supplement is an extra document.
4216 \begin_layout Standard
4217 Choose a replacement word accordingly.
4218 Whatever you choose to replace
4219 \begin_inset Quotes eld
4223 \begin_inset Quotes erd
4226 it must not have the same translation as the word
4227 \begin_inset Quotes eld
4231 \begin_inset Quotes erd
4239 \begin_layout Enumerate
4240 Below the title, in the
4241 \begin_inset Quotes eld
4249 \begin_inset Quotes erd
4252 paragraph environment, place your name.
4256 \begin_layout Standard
4257 There will be no abstract.
4261 \begin_layout Enumerate
4270 \begin_layout Standard
4271 The first thing you will do is strongly yet politely encourage the reader
4273 \begin_inset Quotes eld
4277 \begin_inset Quotes erd
4280 and go read the Style Sheet.
4281 The reader should not return to the
4282 \begin_inset Quotes eld
4286 \begin_inset Quotes erd
4293 understood the Style Sheet proper.
4297 \begin_layout Subsubsection
4298 Keep the Supplement Succinct
4301 \begin_layout Standard
4302 This Style Sheet is already very detailed.
4303 DocTeam members all have a lot to read.
4304 We don't want to place an extra burden on translators.
4305 Therefore, keep the Supplement as short as you can without losing information.
4308 \begin_layout Subsubsection
4312 \begin_layout Standard
4317 will be about font issues\SpecialChar \ldots{}
4319 Not all Translation Project Chiefs will need to deal with this issue.
4323 \begin_layout Itemize
4329 \begin_layout Itemize
4335 \begin_layout Itemize
4337 \begin_inset Newline newline
4342 Emphasized (actually Italics)
4345 \begin_layout Itemize
4351 \begin_layout Itemize
4357 \begin_layout Itemize
4360 Noun (actually Small Caps)
4363 \begin_layout Standard
4364 \SpecialChar \ldots{}
4365 certainly exist for all languages that use the Roman alphabet.
4366 Do they exist, however, for Greek? How about Cyrillic? These different
4367 fonts almost certainly do not exist for Devanagri, Chinese, Korean, Japanese,
4368 Hebrew, Arabic, and other scripts.
4372 \begin_layout Standard
4373 There will be some languages for which following the font-scheme specified
4374 in this Style Sheet may not be possible.
4375 If you are the Translation Project Chief for such a language, you have
4379 \begin_layout Standard
4380 In the font section of the Supplement, you will provide a new typographic
4381 style, designed specifically for your writing system.
4382 For consistency, the title of this section in every Supplement should translate
4384 \begin_inset Quotes eld
4388 \begin_inset Quotes erd
4391 Before adding anything to this section, however, determine what this new
4392 typographic style will look like.
4393 Stick to the font specifications in this Style Sheet as best you can, whenever
4395 When you cannot, use the following suggestions:
4398 \begin_layout Itemize
4400 \begin_inset Quotes eld
4404 \begin_inset Quotes erd
4408 \begin_inset Newline newline
4412 \begin_inset Newline newline
4415 What to do when a font doesn't exist:
4419 \begin_layout Labeling
4420 \labelwidthstring MMMMMMMM
4421 Roman Use the font that typesetters in your language use for printing books,
4423 This will typically be the default font LyX (and LaTeX) uses in your language.
4426 \begin_layout Labeling
4427 \labelwidthstring MMMMMMMM
4431 \begin_inset space ~
4436 This is for people's names.
4437 If there is special font for names in your alphabet/writing system, use
4438 it in place of this.
4439 Otherwise, write names in the default font, typeset according to the rules
4443 \begin_layout Labeling
4444 \labelwidthstring MMMMMMMM
4449 Use the font with which your language normally emphasizes text.
4453 \begin_layout Standard
4454 Use a font that is different from your language's equivalent of
4459 In other words, your
4467 and similar headers will be in one typeface, perhaps
4472 Whatever that font is, avoid using it for
4480 \begin_layout Labeling
4481 \labelwidthstring MMMMMMMM
4486 Pick up a computer program manual written in your language.
4487 It will use a special typeface for filenames, for command names, program
4489 Use that same font in place of
4496 \begin_layout Labeling
4497 \labelwidthstring MMMMMMMM
4501 \begin_inset space ~
4506 Pick any other font that is different from the ones you're using in place
4520 If you're unlucky, and your language's writing system doesn't have enough
4521 fonts, use the same font you picked to replace
4526 Only do this, however, if your alphabet/writing system has very few fonts
4530 \begin_layout Labeling
4531 \labelwidthstring MMMMMMMM
4538 \begin_inset space ~
4542 \begin_inset space ~
4547 Don't worry about this one.
4551 \begin_layout Standard
4552 If you use some special font on-screen to highlight the accelerator keys
4553 for menus, buttons, and other widgets, you might want to mimic that in
4555 It is not required, however.
4556 Therefore, if you can't mimic this typographic convention in your native
4557 writing system, don't.
4562 \begin_layout Standard
4563 Note that you may also want to describe fonts that your Translation Team
4569 For example, no contributer to the English/European versions may ever use
4574 , as this is used for section-headings.
4575 Since there are enough other fonts, we who use the Roman alphabet and its
4576 variants can afford to omit
4584 \begin_layout Standard
4585 Once you have determined which fonts in your native writing system will
4586 replace one or more of the above, propose it to the LyX Developer's Mailing
4588 You may receive valuable feedback this way.
4589 If not, that's okay.
4590 If no one can read your writing system, and therefore cannot comment, that's
4592 Go ahead and describe the typographic standard you created in the Supplement.
4596 \begin_layout Standard
4597 Remember: stick to the font specifications in this Style Sheet as best you
4598 can, whenever you can.
4601 \begin_layout Subsubsection
4602 Quoting Style and the
4614 \begin_layout Standard
4615 The next section of the Supplement will cover the issue of quoting.
4616 Give it an appropriate title.
4619 \begin_layout Standard
4620 One of the first things you should do in that section is resolve the following
4624 \begin_layout Itemize
4633 is the correct paragraph environment for your language.
4636 \begin_layout Itemize
4637 In the Supplement, specify which one to use.
4640 \begin_layout Standard
4641 English has its own typography and style for quoting others.
4642 The Style Sheet describes that typography in section
4643 \begin_inset space ~
4647 \begin_inset CommandInset ref
4649 reference "sec:quote"
4654 Your language also has a specific typography and style for quotations.
4655 Describe that style in this section of the Supplement, too.
4656 Naturally, you do not need to go overboard.
4658 \begin_inset space ~
4662 \begin_inset CommandInset ref
4664 reference "sec:quote"
4668 of this Style Sheet is overly detailed for a good reason.
4669 Authors of the primary LyX manuals are not necessarily native English speakers.
4670 The members of your Translation Team, however, will all likely be native
4671 speakers of your language.
4672 Therefore, discuss proper quoting style of your native tongue to an appropriate
4676 \begin_layout Subsubsection
4677 Translations of Style Sheet Terminology
4680 \begin_layout Standard
4681 In the Supplement, you must provide a standard translation of certain key
4682 phrases for the members of your Translation Team.
4683 Place this in a section following the one about quotations.
4686 \begin_layout Standard
4687 In particular, standardize the translations of the phrases:
4690 \begin_layout Itemize
4696 \begin_layout Itemize
4702 \begin_layout Standard
4707 change the typography of the
4708 \begin_inset Quotes eld
4712 \begin_inset Quotes erd
4716 \begin_inset Quotes eld
4720 \begin_inset Quotes erd
4724 Only provide a translation for the opening phrases.
4725 Insist that the members of your Translation Team use these two tools correctly.
4728 \begin_layout Standard
4729 While we are discussing proper use of the
4730 \begin_inset Quotes eld
4734 \begin_inset Quotes erd
4738 \begin_inset Quotes eld
4742 \begin_inset Quotes erd
4745 in translations, let's talk about a related problem.
4747 \begin_inset Quotes eld
4751 \begin_inset Quotes erd
4754 is meant to be a note from the author of a manual to the reader.
4755 In the case of a translation, however, the translator is
4759 the author! How then should a translator translate an
4760 \begin_inset Quotes eld
4764 \begin_inset Quotes erd
4770 \begin_layout Standard
4771 You, as Translation Project Chief, must decide.
4772 You can forbid translation of pre-existing
4773 \begin_inset Quotes eld
4777 \begin_inset Quotes erd
4780 omitting them entirely instead.
4781 You could tell your translators to read any
4782 \begin_inset Quotes eld
4786 \begin_inset Quotes erd
4789 they may encounter, understand it, then write their own
4790 \begin_inset Quotes eld
4794 \begin_inset Quotes erd
4797 about the situation, not as a translation but as a personal opinion.
4798 You may decide on some other policy.
4801 \begin_layout Standard
4802 Whatever you decide, codify your policy in its own
4811 Place it near the section where you translated
4812 \begin_inset Quotes eld
4816 \begin_inset Quotes erd
4820 \begin_inset Quotes eld
4824 \begin_inset Quotes erd
4830 \begin_layout Subsubsection
4834 \begin_layout Standard
4835 After describing all of the previous issues, create a new
4841 \begin_inset Quotes eld
4844 Lost in Translation,
4845 \begin_inset Quotes erd
4848 or something similar.
4851 \begin_layout Standard
4852 In this section you will discuss any common English metaphors, humor, connotatio
4853 n, or other difficult to translate text.
4854 Try to balance brevity and completeness.
4863 s --- to each specific issue.
4866 \begin_layout Subsubsection
4867 \SpecialChar \ldots{}
4869 \begin_inset Quotes eld
4873 \begin_inset Quotes erd
4876 \SpecialChar \ldots{}
4880 \begin_layout Standard
4881 Throughout the manuals, the DocTeam has used the following sentences:
4885 If you haven't read the <
4889 > manual, go read it.
4893 \begin_layout Standard
4894 This sentence will be tricky to translate, since it contains non-translatable
4900 for this issue in your
4901 \begin_inset Quotes eld
4905 \begin_inset Quotes erd
4910 \begin_inset Quotes eld
4913 \SpecialChar \ldots{}
4914 Yes, we mean now\SpecialChar \ldots{}
4916 \begin_inset Quotes erd
4919 sentences, then present a translation, along with any explanation you feel
4923 \begin_layout Standard
4924 Here's what those two sentences, sitting alone in their own paragraph, mean:
4927 \begin_layout Standard
4928 The first sentence uses the English conditional followed by an imperative.
4929 We, as the LyX team, are commanding the reader to go back to another manual.
4934 manual is a prerequisite for all of the other manuals.
4935 The conditional clause preceeding the command means,
4936 \begin_inset Quotes eld
4939 You do not need to perform this command twice.
4940 \begin_inset Quotes erd
4946 \begin_layout Standard
4947 The second sentence adds force to the command.
4948 Culturally, the imperative tense of a verb in English is not necessarily
4950 The way we wrote that command,
4951 \begin_inset Quotes eld
4955 \begin_inset Quotes erd
4958 is firm, yet polite.
4959 The reader may choose to ignore it.
4961 \begin_inset Quotes eld
4965 \begin_inset Quotes erd
4968 we imply two things.
4970 \begin_inset Quotes eld
4974 \begin_inset Quotes erd
4978 That second sentence reinforces the command, making it a bit harder to
4980 Second, the sentence itself implies a certain sense of urgency.
4981 You cannot merely wait until later to fulfill that command.
4982 The brief pragraph, and its sudden end, add still further subtle reinforcement
4984 \begin_inset Quotes eld
4987 go do the required reading before using this manual.
4988 \begin_inset Quotes erd
4994 \begin_layout Standard
4995 Note that all of this commanding and reinforcing is nevertheless in a polite
4997 Furthermore, it is in a subtle form.
4998 We are commanding the reader to do something, but in an indirect fashion.
4999 This way, the reader does not feel like we are bullying him.
5002 \begin_layout Subsubsection
5007 \begin_layout Standard
5008 In the same part of the Supplement that you place the
5009 \begin_inset Quotes eld
5012 \SpecialChar \ldots{}
5013 Yes, we mean now\SpecialChar \ldots{}
5015 \begin_inset Quotes erd
5018 translation, discuss the English version's use of
5019 \begin_inset Quotes eld
5023 \begin_inset Quotes erd
5029 \begin_layout Standard
5030 You see, here in America, we often say that everything is permitted unless
5031 explicitly banned by law.
5032 As a result, manuals for computer software are frequently ignored and the
5033 software subsequently blamed for not being
5034 \begin_inset Quotes eld
5038 \begin_inset Quotes erd
5041 This is where the use of
5042 \begin_inset Quotes eld
5046 \begin_inset Quotes erd
5053 \begin_layout Standard
5054 We who wrote the manuals added sentences insisting that the reader not ignore
5055 certain parts of the documentation.
5056 We wrote in a manner that was polite, yet firmly asserted that the user
5057 was misusing the software if he did not read the manual correctly.
5058 We did not, however, want to sound threatening, coercive, or bullying.
5061 \begin_layout Standard
5062 In your culture, cajoling the reader into using the manuals correctly may
5064 It may, in fact, be outright rude.
5065 Additionally, translating the firm-but-convincing bits may not work.
5066 The translation may sound weird, or rude, or hostile.
5067 Therefore, you and your translation team will face many sentences that
5068 you cannot translate.
5071 \begin_layout Standard
5072 You, the Translation Project Chief, must discuss this issue.
5073 Try and find parts of the original manuals where some friendly but firm
5074 convincing does not translate properly.
5075 Use these cases as the basis for examples of the problem.
5076 Be sure to then offer a solution (i.
5077 \begin_inset space ~
5081 \begin_inset space ~
5084 how you want such sentences translated.) If stumped, ask for help on the
5085 LyX Developer's List.
5088 \begin_layout Subsubsection
5092 \begin_layout Standard
5093 You can add more sections to the Supplement if you need to discuss other
5095 There may be policies or guidelines that you want to set for your Translation
5097 Be careful, however! Keep the Supplement