1 #LyX 1.4.0cvs created this file. For more info see http://www.lyx.org/
17 \paperorientation portrait
20 \paragraph_separation indent
22 \quotes_language english
27 \tracking_changes false
35 Documentation Project Style Sheet
43 \begin_layout Abstract
45 This article is a style sheet.
46 It describes, with examples, how the documentation should look and sound.
47 The first few sections explain the font conventions and typography conventions
48 all documentation writers should follow.
49 Those sections also contain examples.
50 It also explains the purpose of each of the different manuals.
51 Follow it not merely to the letter, but also in spirit.
54 \begin_layout Abstract
56 The Style Sheet for LyX documentation (hereafter known as the Style Sheet)
61 forms of LyX documenation, regardless of language.
62 There is a section for translators in the Style Sheet, towards the end.
65 Read the entire Style Sheet!
67 Even if you are a translator, I assume you know enough English to comprehend
73 Questions and Clarifications
76 \begin_layout Standard
78 After the second version of this Style Sheet grew uncomfortably large, the
79 LyX DocTeam decided it needed to lose some excess weight.
80 It seems the Style Sheet began to specify too many special cases, too many
81 points of clarification.
82 On the other hand, contributors to the documents were discovering many
83 creative ways of misinterpreting the Style Sheet specifications.
89 If you have any questions about anything in the Style Sheet,
91 ask first, write second!
94 \begin_layout Standard
96 Field all questions to the LyX Developer's Mailing List.
97 There are seasoned DocTeam members who can answer your questions.
98 If you have any problems with the Style Sheet itself, also contact the
102 \begin_layout Section
107 \begin_layout Standard
109 We'll start with the easiest section, yet also the most important.
112 \begin_layout Standard
114 This is how you should fontify text in the manuals:
118 \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
131 Do not overemphasize your text.
135 \labelwidthstring MMMMMMMM
141 program names, file names,
145 -page names, LaTeX code, LaTeX commands, LaTeX package names, and LyX code
150 \labelwidthstring MMMMMMMM
157 menu, button, or popup names, the names/lables of all widgets in a popup,
158 the names of keyboard keys, and certain
159 \begin_inset Quotes eld
163 \begin_inset Quotes erd
170 \labelwidthstring MMMMMMMM
181 \labelwidthstring MMMMMMMM
188 nderlined\InsetSpace ~
192 Rich Fields added this to mimick the underlining of letters in the menus
194 It helps to highlight the accelerator keys, and human brains store information
195 best when they see it frequently.
199 \begin_layout Description
201 WARNING! --- When you do this, make sure you
205 shut off the underlining.
206 Too many people send in things that look like:
216 \SpecialChar \ldots{}
219 they not only shut off underlining, they turned off
228 Make sure the entire word is still in
233 after you shut off the underlining.
237 \labelwidthstring MMMMMMMM
247 \begin_layout Standard
249 If you want to emphasize any text, use
254 LaTeX will put many things boldface on its own, such as
258 s, certain parts of equations, et cetera.
261 \begin_layout Standard
263 Repeat: do not use boldface.
266 \begin_layout Standard
268 Here are some examples:
271 \begin_layout Enumerate
277 appears in configuration files and in the LyX source.
278 Therefore, it (and all other LyX function names) count as code and is set
286 \begin_layout Enumerate
296 is a menu item in the
303 menu, so it appears in
314 nderlined\InsetSpace ~
318 for the accelerator keys.
321 \begin_layout Enumerate
323 Consider the following excerpt from the introduction of one of the manuals:
327 \begin_layout Quotation
337 both refer to the same key.
338 Some keyboards label the
343 \begin_inset Quotes eld
347 \begin_inset Quotes erd
351 \begin_inset Quotes eld
355 \begin_inset Quotes erd
358 still others have two keys.
359 LyX treats all of them as the same key, so we'll use
370 \begin_layout Standard
372 Notice that the key name,
385 when it references the key itself! When I described how the manufacturer
386 chose to label its keyboard, I used Roman and put the word in quotes.
387 There is a semantic difference.
390 \begin_layout Enumerate
392 Take the following command:
396 \begin_layout Standard
406 \begin_layout Standard
408 Notice that the argument to the
418 This is a case where you don't use
422 for code, because you want the generic argument label to stand out.
423 On the other hand, if you were specifying an argument, for example,
424 \begin_inset Quotes eld
432 \begin_inset Quotes erd
443 \begin_layout Enumerate
445 Any LaTeX commands and code, and any
449 LaTeX package names get set in
455 \begin_inset Quotes eld
463 \begin_inset Quotes erd
466 is the name of an unsupported LaTeX package, but
467 \begin_inset Quotes eld
475 \begin_inset Quotes erd
478 is a supported LaTeX class.
481 \begin_layout Section
486 \begin_layout Standard
488 The canonical keyboard contains these keys:
491 \begin_layout Itemize
504 \begin_layout Itemize
517 \begin_layout Itemize
531 \begin_layout Standard
536 use the abbreviations
541 \begin_layout Itemize
545 F1 F2 F3 F4 F5 F6 F7 F8 F9 F10 F11 F12
549 \begin_layout Standard
552 Most modern keyboards have all 12.
555 \begin_layout Itemize
565 \begin_layout Standard
568 \begin_inset Quotes eld
572 \begin_inset Quotes erd
578 \begin_layout Itemize
606 \begin_layout Standard
608 These are the 6 keys that appear above the cursor keys on many PC keyboards.
609 Consider them as part of the standard motion keys.
612 \begin_layout Itemize
620 \begin_layout Standard
622 The four standard motion keys.
623 There is no need to put the word
624 \begin_inset Quotes eld
628 \begin_inset Quotes erd
631 anywhere, since that's obvious.
635 \begin_layout Standard
638 \begin_inset Quotes eld
642 \begin_inset Quotes erd
647 \begin_inset Quotes eld
651 \begin_inset Quotes erd
654 after one of these may be redundant in certain situations.
662 \begin_layout Itemize
676 \begin_layout Standard
678 I won't throw a hissy fit if you use one instead of the other.
679 I'd prefer if you used
687 , but it's okay if you slip up and forget.
688 Since these two keys are bound to the same function in LyX, it doesn't
692 \begin_layout Standard
694 You do not need to explain everywhere what the
703 The user isn't stupid.
704 Also, someone will document anything that isn't clear (e.\InsetSpace ~
715 problem) someplace in the introduction.
716 No need for you to repeat someone else's work.
719 \begin_layout Standard
721 LyX does not support keyboards missing any of the keys described above,
723 LyX can support a keyboard missing
732 There is a keyboard accelerator for
736 , but this is the only function key LyX assumes exists.
737 Nevertheless, these details are of minor, if any, concern for the documentation.
738 Assume the aforementioned keys exist.
741 \begin_layout Section
746 \begin_layout Standard
749 \begin_inset Quotes eld
753 \begin_inset Quotes erd
756 and any description of the 3 mouse buttons have no special handling.
757 Don't typeset them in any other font than the default, which is Roman.
761 \begin_layout Standard
763 Exception: you're writing an Author's Note (see section
764 \begin_inset LatexCommand \ref{sec:author-notes}
768 ) and you need to mention something about the mouse.
769 Since the rest of the note is in
773 , your description of
774 \begin_inset Quotes eld
778 \begin_inset Quotes erd
781 should be emphasized, as well.
782 There are a couple of other cases like this one; use your judgement.
785 \begin_layout Standard
787 There are only 3 mouse buttons.
788 The use of them and of the mouse itself is obvious.
789 There are few --- if any --- nonstandard things we do with the mouse.
790 Therefore, there's no need to make the word
791 \begin_inset Quotes eld
795 \begin_inset Quotes erd
799 \begin_inset Quotes eld
803 \begin_inset Quotes erd
809 \begin_layout Section
814 \begin_layout Standard
819 \begin_layout Description
821 Multi-word\InsetSpace ~
824 Protected\InsetSpace ~
827 between the words for menu and widget names.
843 \begin_layout Standard
845 This holds for things in
855 If you have a long code example, one that can't simply be inlined and put
868 \begin_layout Standard
872 Protected\InsetSpace ~
875 so that the name doesn't get split between two lines, which is visually
879 Protected\InsetSpace ~
882 is near the end of a line and overflows the margin, use a
888 in that parargraph (consult a LaTeX book for more about
889 \begin_inset Quotes eld
899 \begin_inset Quotes erd
902 ) or manually add a hypenation point.
905 \begin_layout Description
908 Terms These are things like the following:
912 \begin_layout Itemize
921 \begin_layout Itemize
930 \begin_layout Itemize
938 \begin_layout Itemize
947 \begin_layout Standard
954 font and, in the case of
962 , capitalize the first two letters.
965 \begin_layout Standard
967 Why are these terms special? They are concepts which the seasoned LaTeX-pert
968 is familiar with, but which the new LyX user is not.
969 I want them to stand out from the rest of the text, hence the use of
978 \begin_layout Standard
980 Seasoned LyX Team Members: Are there other terms that require this special
981 status? On the other hand, should we eliminate this style completely?
984 \begin_layout Description
986 Terminology Note the following:
989 \begin_layout Itemize
992 \begin_inset Quotes eld
996 \begin_inset Quotes erd
1000 \begin_inset Quotes eld
1004 \begin_inset Quotes erd
1008 \begin_inset Quotes eld
1012 \begin_inset Quotes erd
1017 \begin_inset Quotes eld
1021 \begin_inset Quotes erd
1025 \begin_inset Quotes eld
1029 \begin_inset Quotes erd
1035 \begin_layout Itemize
1037 PostScript® is a registered trademark of Adobe Corp.
1040 You must put the ® after it or we'll get sued!
1042 I also want it written as seen here, always capitalized.
1044 \begin_inset Quotes eld
1048 \begin_inset Quotes erd
1052 \begin_inset Quotes eld
1056 \begin_inset Quotes erd
1060 \begin_inset Quotes eld
1064 \begin_inset Quotes erd
1067 - both of them capitalized, in the default font (i.\InsetSpace ~
1070 If you must, cut and paste it from here.
1074 \begin_layout Standard
1076 I am going to say this again:
1080 \begin_layout Standard
1083 \begin_inset VSpace 0.37cm
1089 \begin_layout Standard
1094 You must put the ® after PostScript® or we'll get sued!
1097 \begin_layout Standard
1100 \begin_inset VSpace 0.51cm
1107 \begin_layout Standard
1109 I mean it! American companies like to sue anything that moves.
1114 by forgetting that ®.
1119 \begin_layout Itemize
1121 Similarly, if you use any other registered trademark in any documentation,
1122 put the ® after it, too.
1125 \begin_layout Description
1128 Items When quick-referencing an item in a menu, use the menu separator:
1130 \begin_inset Quotes eld
1133 \SpecialChar \menuseparator
1135 \begin_inset Quotes erd
1141 File\SpecialChar \menuseparator
1145 Notice that there are
1150 \begin_inset Quotes eld
1153 \SpecialChar \menuseparator
1155 \begin_inset Quotes erd
1163 , just like the menu and item names.
1167 \begin_layout Enumerate
1169 The reason why I want no spaces around the
1170 \begin_inset Quotes eld
1173 \SpecialChar \menuseparator
1175 \begin_inset Quotes erd
1178 is to prevent LyX from splitting terms across lines.
1179 The same goes for using
1181 Protected\InsetSpace ~
1184 s between multi-word terms.
1185 The split would be visually disruptive.
1188 \begin_layout Enumerate
1191 \begin_inset Quotes eld
1194 \SpecialChar \menuseparator
1196 \begin_inset Quotes erd
1199 goes between menu names and item names
1204 (Yes, submenus are okay, too).
1207 \begin_layout Enumerate
1214 \begin_inset Quotes eld
1217 \SpecialChar \menuseparator
1219 \begin_inset Quotes erd
1222 between menu items and dialog names.
1224 \begin_inset Quotes eld
1232 ayout\SpecialChar \menuseparator
1237 per\SpecialChar \menuseparator
1242 \begin_inset Quotes erd
1247 IS STRICTLY FORBIDDEN!
1253 \begin_layout Standard
1260 \begin_inset Quotes eld
1263 \SpecialChar \menuseparator
1265 \begin_inset Quotes erd
1268 between popup names and any dialog.
1270 \begin_inset Quotes eld
1276 Dialog\SpecialChar \menuseparator
1284 \begin_inset Quotes erd
1289 IS STRICTLY FORBIDDEN!
1292 \begin_layout Standard
1299 \begin_inset Quotes eld
1302 \SpecialChar \menuseparator
1304 \begin_inset Quotes erd
1307 between menu items and any dialog.
1309 \begin_inset Quotes eld
1317 ayout\SpecialChar \menuseparator
1322 per\SpecialChar \menuseparator
1330 \begin_inset Quotes erd
1335 IS STRICTLY FORBIDDEN!
1338 \begin_layout Standard
1340 Either write out the description, or use context to eliminate any need to
1341 repeat menu items, dialog names, etc.
1345 \begin_layout Description
1348 Boxes LyX has a feature for adding comments that appear only within
1351 \begin_inset Note Note
1354 \begin_layout Standard
1356 These should NEVER appear in the manuals.
1362 You will see nothing in a printout of the Style Sheet.
1363 Therefore, they have no place in the manuals.
1369 \begin_layout Standard
1371 If you have a parenthetical comment you want to make, the reader should
1372 see it too, even in the printed version.
1373 Use an Author's Note (see section
1374 \begin_inset LatexCommand \ref{sec:author-notes}
1378 ) in place of the Note-Boxes.
1381 \begin_layout Description
1384 \begin_inset Quotes eld
1387 (\SpecialChar \ldots{}
1389 \begin_inset Quotes erd
1394 \begin_inset Quotes eld
1397 [\SpecialChar \ldots{}
1399 \begin_inset Quotes erd
1405 \begin_inset Quotes eld
1408 {\SpecialChar \ldots{}
1410 \begin_inset Quotes erd
1413 I have recently been corrected about the use of parentheses.
1414 Standard English typesetting uses the normal parentheses,
1415 \begin_inset Quotes eld
1418 (\SpecialChar \ldots{}
1420 \begin_inset Quotes erd
1423 , around any aside, remark, or parenthetical expression.
1425 \begin_inset Quotes eld
1428 [\SpecialChar \ldots{}
1430 \begin_inset Quotes erd
1433 , is used only within quotations (see section\InsetSpace ~
1435 \begin_inset LatexCommand \ref{sec:quote}
1441 \begin_inset Quotes eld
1444 {\SpecialChar \ldots{}
1446 \begin_inset Quotes erd
1450 Therefore, never use
1451 \begin_inset Quotes eld
1454 [\SpecialChar \ldots{}
1456 \begin_inset Quotes erd
1460 \begin_inset Quotes eld
1463 {\SpecialChar \ldots{}
1465 \begin_inset Quotes erd
1468 unless otherwise specified by this Style Sheet.
1471 \begin_layout Description
1473 Dashes: Be sure to use the correct one.
1475 \begin_inset Quotes eld
1483 \begin_inset Quotes erd
1486 character is not a dash, it's a hyphen.
1487 Use it only as a hyphen.
1492 \begin_layout Standard
1495 \begin_inset Quotes eld
1499 \begin_inset Quotes erd
1503 \begin_inset Quotes eld
1507 \begin_inset Quotes erd
1511 \begin_inset Quotes eld
1519 \begin_inset Quotes erd
1522 characters form the en-dash.
1524 \begin_inset Quotes eld
1532 \begin_inset Quotes erd
1535 characters create an em-dash, which is slightly longer than the en-dash.
1536 In the printed version of any document, LyX will combine the two or three
1538 \begin_inset Quotes eld
1546 \begin_inset Quotes erd
1549 characters into a single, unbroken line.
1552 \begin_layout Section
1554 Cross-References and Labels
1557 \begin_layout Standard
1559 Use the following labelling conventions:
1563 \labelwidthstring 00.00.0000
1565 sec:xxx Use this for
1585 \labelwidthstring 00.00.0000
1587 eqn:xxx Use this for Equations, should you need to create any.
1591 \labelwidthstring 00.00.0000
1593 tbl:xxxx Use this for tables inside of a table float.
1597 \labelwidthstring 00.00.0000
1599 fig:xxx Use this for figures inside of figure floats.
1602 \begin_layout Standard
1604 Additionally, you should put the label at one of two locations:
1607 \begin_layout Enumerate
1611 beginning of the paragraph
1613 , after a section heading, or at the beginning of captions, etc.
1614 It should be the first thing on the first line.
1615 Don't put a space betweeen it and the first word.
1618 \begin_layout Enumerate
1620 If there is no paragraph after a section heading, put it at the
1622 end of the last line.
1629 \begin_layout Standard
1635 which is immediately followed by a
1640 This is a case where you need to put the label at the end of the
1645 I know it looks ugly; not much we can do about that, though.
1648 \begin_layout Section
1650 Content --- What Goes Where
1653 \begin_layout Standard
1659 important to anyone documenting a new feature.
1660 If you need to add new documentation, pay attention.
1664 \begin_layout Standard
1666 In the dim and distant past, whenever someone wanted to document a new feature
1667 they added, they either wrote a mini-doc and stuck it into the documentation
1668 directory, or they added a new section to the lone manual.
1669 No one paid much attention to organization in those days, either.
1670 The result was a totally bloated, totally unnavigable, and incomplete manual
1671 orbitted by a swarm of tiny, incomplete mini-docs.
1672 I don't want the docs to fall back into that mess.
1675 \begin_layout Standard
1677 With that in mind, I have some instructions for how to keep things organized:
1681 \labelwidthstring 00.00.0000
1687 Please, don't touch this file.
1688 It's essentially complete, anyhow.
1689 Only the editor(s) should make changes to this, as this file contains info
1690 about how to contribute to the doc project.
1691 That's really the only stuff that should need to change, and even then,
1692 only when a new maintainer comes along.
1696 \labelwidthstring 00.00.0000
1702 This file is complete.
1703 Any changes should be for updates
1708 DO NOT ADD new features to here willy-nilly.
1709 Let the editor decide if --- and when --- new sections go in here.
1710 Place any new features in\SpecialChar \ldots{}
1715 \labelwidthstring 00.00.0000
1721 This is where all new features go from now on.
1722 It's in the style of a bound journal --- each section is an
1723 \begin_inset Quotes eld
1727 \begin_inset Quotes erd
1730 from the author of the feature.
1731 Also, anyone who writes a
1735 file for a new document class should write a section describing that new
1736 class and how to use it.
1737 That also goes here.
1741 \begin_layout Standard
1743 Note, however, that you are
1747 excused from following this Style Sheet just because the sections of
1751 are in the form of a journal article.
1755 \labelwidthstring 00.00.0000
1761 This file is complete.
1762 Do not change or add to without permission of the Documenation Project
1767 \labelwidthstring 00.00.0000
1773 This document describes advanced features, most of which alter the look,
1774 feel, and behavior of LyX.
1775 This manual is still a bit incomplete, although that may change soon.
1776 Check for updates often.
1780 \begin_layout Standard
1782 If you are unsure whether or not something belongs in
1786 , then, most-likely, it
1795 Again, let the current editor of the LyX documentation decide if your new
1796 section should be migrated to
1804 \labelwidthstring 00.00.0000
1810 I'd prefer to completely finish this one before doing anything else, but
1812 LyX keeps changing so much that I think the
1816 will be the last one completed.
1817 However, I'd like it if the developer's would add entries anytime they
1818 create a new function or popup.
1819 That would help things immensely!
1823 \begin_layout Standard
1829 follows this Style Sheet for the most part.
1830 There are, however, additional rules to follow when making new entries.
1831 At the top of this manual, there are examples of and a template for
1839 \begin_layout Section
1841 Writing Style: The Primary Manuals
1844 \begin_layout Standard
1846 While I want to make contributing to the Documentation Project as painless
1847 as possible for newcomers, I also want the newcomers to be painless on
1848 the existing Documentation Team! Ergo, I've written this section to give
1849 some flavor to guide everyone's individual style.
1853 \begin_layout Subsection
1858 \begin_layout Standard
1860 All contributions to the
1864 LyX documentation must be in English.
1865 I don't care if it's British, Australian, or American English.
1866 The DocTeam editor will proofread for glaring mistakes and fix them.
1869 \begin_layout Standard
1871 Don't get hung up on semantics.
1872 English is a flexible language, and just because your Mothertongue-to-English
1873 dictionary gives only one translation for a word doesn't necessarily mean
1875 We've had some discussions and misunderstandings on the Developers' List
1876 because of this very problem.
1877 If something is unclear (or just plain weird) due to a translation problem,
1878 one of the American/British/Australian developers can fix it.
1881 \begin_layout Standard
1887 documentation, I exclude the translations.
1888 We usually don't have enough people to cover the manuals in one language,
1889 let alone more than one.
1890 Subsequently, the tranlsations are just that --- translations of the English
1891 version of the LyX manuals.
1892 The translation efforts require have their own set of guidelines.
1894 \begin_inset LatexCommand \ref{sec:translations}
1901 \begin_layout Subsection
1905 Commentary from the Author (i.\InsetSpace ~
1909 \begin_layout Standard
1912 \begin_inset LatexCommand \label{sec:author-notes}
1916 I want to make it easy for everyone when it comes to documenting things.
1917 Some features are incomplete.
1918 Some, you might not know everything about.
1919 Sometimes, you may want to comminucate something to me or the reader or
1920 other DocTeam members.
1921 Sometimes, you may want to
1922 \begin_inset Quotes eld
1926 \begin_inset Quotes erd
1929 you want to say something that is your personal opinion and using
1930 \begin_inset Quotes eld
1934 \begin_inset Quotes erd
1937 would be inappropriate.
1940 \begin_layout Standard
1942 In short, when you contribute to the LyX Docs, you wear many hats.
1945 \begin_layout Standard
1947 For occasions when you need to switch hats, I've designed some special mechanism
1951 \begin_layout Subsubsection
1953 Personal\InsetSpace ~
1955 \begin_inset Quotes eld
1959 \begin_inset Quotes erd
1965 \begin_layout Standard
1967 These are footnotes.
1968 They begin with the following:
1980 \begin_layout Standard
1982 \SpecialChar \ldots{}
1987 for the person's name and without the quotes.
1988 The rest of the footnote is the actual comment.
1992 \begin_layout Standard
1994 Use these when you need to quote a comment by someone (usually yourself),
1995 and need to identify that person.
1996 This includes occasions when you need wear the
1997 \begin_inset Quotes eld
2001 \begin_inset Quotes erd
2004 hat, i.\InsetSpace ~
2006 to speak for yourself instead of for the LyX Team.
2009 \begin_layout Standard
2011 If the comment is too large to put in a footnote, don't use a Personal Note.
2012 When quoting more than about 3 sentences or 5 lines of text, use a bona
2014 Don't use any leading
2015 \begin_inset Quotes eld
2023 \begin_inset Quotes erd
2027 In a real quote, you'll give credit to the original speaker in either the
2028 paragraph before or after the body of the
2035 \begin_layout Subsubsection
2037 Author's\InsetSpace ~
2039 \begin_inset Quotes eld
2043 \begin_inset Quotes erd
2049 \begin_layout Standard
2051 There will be times when you are not speaking for the LyX Team, yet you
2052 are not entirely speaking for yourself.
2053 Instead, you are speaking on behalf of the manual itself, as the author
2055 Some examples of when you might need to do this are:
2058 \begin_layout Itemize
2060 You need to contradict something you just wrote because the feature isn't
2061 quite ready yet, but you wanted to document what it will do.
2064 \begin_layout Itemize
2066 You need to leave a note for yourself.
2069 \begin_layout Itemize
2071 You need to leave a note for the editor or the other DocTeam members.
2074 \begin_layout Itemize
2076 You need to point out something about the manuals to the reader, something
2077 that doesn't fit into the context of the current paragraph.
2080 \begin_layout Standard
2082 At such times, you are wearing your
2083 \begin_inset Quotes eld
2087 \begin_inset Quotes erd
2093 \begin_layout Standard
2095 The typography for an
2096 \begin_inset Quotes eld
2100 \begin_inset Quotes erd
2106 \begin_layout Itemize
2108 They go in the body of the text, in brackets,
2109 \begin_inset Quotes eld
2113 \begin_inset Quotes erd
2116 , not any other form of parentheses.
2117 The bracket are in the default character style.
2120 \begin_layout Itemize
2122 The text of the note itself, however, is emphasized.
2126 \begin_layout Itemize
2128 Begin with the words,
2129 \begin_inset Quotes eld
2137 \begin_inset Quotes erd
2140 and end with an em-dash,
2141 \begin_inset Quotes eld
2145 \begin_inset Quotes erd
2148 , followed by your initials.
2152 \begin_layout Standard
2154 Here's an example: [
2156 Author's Note: This is an example note.
2162 \begin_layout Standard
2164 The form of the Author's Note, by the way, isn't a suggestion or request.
2170 All Author's Notes must begin with this text, verbatim:
2171 \begin_inset Quotes eld
2179 \begin_inset Quotes erd
2184 \begin_inset Quotes eld
2188 \begin_inset Quotes erd
2191 are or any other variant are forbidden.
2192 The Author's Note must end with an em-dash, which is 3
2193 \begin_inset Quotes eld
2197 \begin_inset Quotes erd
2201 \begin_inset Quotes eld
2205 \begin_inset Quotes erd
2210 \begin_inset Quotes eld
2214 \begin_inset Quotes erd
2217 ; you must use 3 (and 5 is right out).
2220 \begin_layout Standard
2223 \begin_inset Quotes eld
2227 \begin_inset Quotes erd
2230 are inherently transient, and should disapear as a manual matures.
2233 \begin_layout Subsubsection
2238 \begin_layout Standard
2240 You are also free to use footnotes on their own in addition to the Personal
2241 Notes and/or Author's Notes.
2242 I've frequently used footnotes to \SpecialChar \ldots{}
2243 well, to comment on parts of a section
2244 without putting the commentary into the body of the text.
2247 \begin_layout Paragraph*
2249 Mixing Footnotes and Personal Notes
2252 \begin_layout Standard
2254 Personal Notes always go in footnotes, and should be 5 lines or fewer.
2255 Any larger quotation should be quoted properly, using the rules of standard
2261 paragraph environment.
2264 \begin_layout Paragraph*
2266 Mixing Footnotes and Author's Notes
2269 \begin_layout Standard
2271 Author's Notes should
2279 \begin_layout Paragraph*
2281 Mixing Personal Notes and Author's Notes
2284 \begin_layout Standard
2286 Forbidden; these two are mutually exclusive.
2289 \begin_layout Subsubsection
2294 \begin_layout Itemize
2302 opinion --- yours or another LyX developer's --- about anything.
2303 Anywhere in the manuals you wish to speak for yourself instead the the
2305 If you have a long rant, however, quote yourself (see section\InsetSpace ~
2307 \begin_inset LatexCommand \ref{sec:quote}
2314 \begin_layout Itemize
2318 Use this to describe things in LyX (or the manuals) that may change in the
2319 future or are somehow incomplete.
2320 Author's Notes are supposed to disappear as a manual matures.
2323 \begin_layout Itemize
2327 Used for text fragments that almost fit into the flow of the text\SpecialChar \ldots{}
2332 \begin_layout Standard
2334 When using these three mechanisms, in addition to rigorously following their
2335 descriptions, please use them properly.
2336 I listed some additional restrictions previously.
2337 Some of you may balk at these restrictions.
2338 Nevertheless, there is a reason for them: if you have an overwhemling desire
2339 to mix or modify footnotes, Personal Notes, and Author's Notes, you shouldn't
2340 be using any of them.
2341 More specifically, you're trying to use a hammer to drive in a screw.
2342 What you want to say probably needs to go into the main body of the text.
2345 \begin_layout Subsection
2347 General Stylistic Guidelines
2350 \begin_layout Standard
2352 Everything in this section is
2354 mandatory to all documenters
2356 , regardless the language you're writing in.
2360 \begin_layout Subsubsection
2365 \begin_layout Enumerate
2367 Use the typography rules outlined in the beginning sections of this document.
2370 \begin_layout Enumerate
2372 Don't, however, mimic the typography of this file.
2373 Yes, the Style Sheet doesn't follow the Style Sheet (grin).
2376 \begin_layout Enumerate
2378 There is some typographic freedom in those rules in earlier sections.
2379 Use that freedom wisely.
2380 Most importanly, never sacrifice the online appearance for the printed
2381 appearance and vice versa.
2385 \begin_layout Standard
2387 An example is in the
2392 There is a footnote using the
2396 command to divide a long
2400 environment into 3 columns.
2401 It adds some LaTeX commands to the online version, the so-called
2402 \begin_inset Quotes eld
2406 \begin_inset Quotes erd
2409 that some so vehemently oppose.
2410 Without it, however, that footnote takes up over two pages, most of which
2412 This is an example of permitting a little ugliness in the online version
2413 to get the printed version to look right.
2416 \begin_layout Enumerate
2418 When in doubt, compromise.
2422 \begin_layout Standard
2424 When in doubt, use good judgement.
2427 \begin_layout Subsubsection
2432 \begin_layout Enumerate
2435 \begin_inset Quotes eld
2439 \begin_inset Quotes erd
2446 \begin_layout Standard
2448 When you speak, you speak for the entire LyX Team, so use
2449 \begin_inset Quotes eld
2453 \begin_inset Quotes erd
2457 \begin_inset Quotes eld
2461 \begin_inset Quotes erd
2467 \begin_layout Enumerate
2470 \begin_inset Quotes eld
2474 \begin_inset Quotes erd
2481 \begin_layout Standard
2483 Whenever you want to say something to the reader, use
2484 \begin_inset Quotes eld
2488 \begin_inset Quotes erd
2491 not some contorted construction to avoid being too informal.
2495 \begin_layout Enumerate
2498 \begin_inset Quotes eld
2502 \begin_inset Quotes erd
2505 for both the physical pointing object (mouse, joystick, touch pad, track
2506 ball, etc.) and the mouse cursor which the physical object moves about the
2510 \begin_layout Enumerate
2513 \begin_inset Quotes eld
2517 \begin_inset Quotes erd
2520 for the little blinking vertical bar that indicates where text can/will
2524 \begin_layout Enumerate
2526 When in doubt, compromise.
2530 \begin_layout Standard
2532 When in doubt, use good judgement.
2535 \begin_layout Subsubsection
2538 \begin_inset LatexCommand \label{sec:quote}
2542 Quoting Yourself and Others
2545 \begin_layout Standard
2547 In some cases, you'll have something to say, an opinion of yours.
2548 Since this is your opinion, you're not speaking for the LyX Team.
2549 You have so much to say, in fact, that it won't fit into a Personal Note
2550 or an Author's Note.
2551 In these cases you want to quote yourself.
2554 \begin_layout Standard
2556 Any time you wish to quote someone, be it yourself or someone else, there
2557 are standard rules one follows.
2558 Every language has its own rules.
2559 You should follow the rules that apply to the language of the document
2560 to which you are contributing.
2564 \begin_layout Standard
2566 This creates a problem for the primary documentation.
2567 The primary documentation is written in English, yet the contributors come
2568 from many countries.
2569 The quoting rules for English (well, American English, at least) are outlined
2575 , for your convenience.
2576 Read them if you need to.
2579 \begin_layout Standard
2582 \begin_inset Float figure
2588 \begin_layout Standard
2590 Quoting rules for English:
2593 \begin_layout Itemize
2595 The body of the quote belongs in a
2602 \begin_layout Itemize
2604 The sentences prior to the quote should flow logically and smoothly into
2608 \begin_layout Itemize
2610 The sentences immediately following the quote should continue the flow of
2614 \begin_layout Itemize
2620 credit the original author of the quote in the sentences immediately before
2624 \begin_layout Itemize
2626 Crediting the original author of the quote should not, however, disrupt
2627 the flow of the text.
2630 \begin_layout Itemize
2632 If you omit text from the beginning of the first sentence in the quote,
2633 the quote must start with the text
2634 \begin_inset Quotes eld
2637 [\SpecialChar \ldots{}
2639 \begin_inset Quotes erd
2643 This is an ellipsis in square brackets.
2646 \begin_layout Itemize
2648 If you omit text from the end of the last sentence in the quote, the quote
2649 must end with the text
2650 \begin_inset Quotes eld
2653 [\SpecialChar \ldots{}
2655 \begin_inset Quotes erd
2658 followed by the sentence's punctuation mark.
2661 \begin_layout Itemize
2663 If you omit any text from the middle of the quote, be it whole sentences
2664 or parts of sentences, replace it with the text
2665 \begin_inset Quotes eld
2668 [\SpecialChar \ldots{}
2670 \begin_inset Quotes erd
2676 \begin_layout Itemize
2678 The quote must be grammatically correct.
2683 \begin_layout Itemize
2685 If the original is wrong, you must correct it.
2688 \begin_layout Itemize
2690 If omitting part of the quote
2691 \begin_inset Quotes eld
2695 \begin_inset Quotes erd
2698 it, you must correct the problem.
2701 \begin_layout Itemize
2703 For missing words (e.\InsetSpace ~
2706 \begin_inset Quotes eld
2710 \begin_inset Quotes erd
2713 goes missing), place the word in square brackets,
2714 \begin_inset Quotes eld
2717 [\SpecialChar \ldots{}
2719 \begin_inset Quotes erd
2722 and insert in the quote where needed.
2725 \begin_layout Itemize
2727 For mangled word order, correct the mangled text, following it with the
2729 \begin_inset Quotes eld
2733 \begin_inset Quotes erd
2739 \begin_layout Itemize
2741 Spelling in the quote must be correct.
2742 Correct any misspelled words and place the text
2743 \begin_inset Quotes eld
2747 \begin_inset Quotes erd
2750 after the corrected word.
2753 \begin_layout Itemize
2755 Back-to-back bracket blocks merge together.
2757 \begin_inset Quotes eld
2760 [\SpecialChar \ldots{}
2762 \begin_inset Quotes erd
2767 \begin_inset Quotes eld
2770 [\SpecialChar \ldots{}
2772 \begin_inset Quotes erd
2778 \begin_layout Itemize
2780 If you correct the spelling in 2 or more consecutive words, you can get
2782 \begin_inset Quotes eld
2786 \begin_inset Quotes erd
2789 after the last mistake.
2797 \begin_layout Subsubsection
2802 \begin_layout Standard
2804 When describing a new feature or
2811 \begin_layout Enumerate
2823 \begin_inset Quotes eld
2826 Keep It Short and Sweet
2827 \begin_inset Quotes erd
2831 \begin_inset Quotes eld
2834 Keep It Simple, Stupid!
2835 \begin_inset Quotes erd
2842 \begin_layout Itemize
2848 write paragraph after paragraph of verbage.
2852 \begin_layout Itemize
2857 \begin_layout Itemize
2859 Take a look at the manual for a commercial word processor --- it's a fine
2864 to write documentation.
2865 It's all pithy, substanceless verbage, and its
2872 \begin_layout Enumerate
2874 Avoid being pedantic like The Plague!
2877 \begin_layout Enumerate
2879 In the same vein, don't write more than you have to.
2880 You're not working in a vacuum --- refer freely to other parts of the manual
2881 (and other parts of other manuals).
2883 \begin_inset Quotes eld
2886 other part of the manual
2887 \begin_inset Quotes erd
2890 is incomplete or empty, refer to it.
2891 Someone will fill it in eventually.
2894 \begin_layout Enumerate
2896 On the other hand, BE THOROUGH!
2900 \begin_layout Enumerate
2906 , not widgets, not how the source code is organized.
2909 \begin_layout Enumerate
2911 Group by feature, not by widget.
2914 \begin_layout Enumerate
2916 Stay on topic --- one
2929 s and further subdivisions to group things if you're documenting several
2930 related features in a single
2937 \begin_layout Enumerate
2939 Describe EVERYTHING related to that feature, no matter where it is.
2943 \begin_layout Enumerate
2945 Example: Paragraph Indenting.
2946 Several popups control its behavior.
2951 of this: which popups control it, when you use which setting on which popup
2952 to do which operation, et cetera.
2955 \begin_layout Enumerate
2963 I've had people only document one popup --- literally.
2964 This added off-topic information and only described half of the feature,
2965 since other menus, popups, and even unbound functions contained additional
2972 cranky when that happens, because it means
2977 Bad help is worse than no help at all.
2981 \begin_layout Standard
2983 These remarks still hold true: you'll piss of the DocTeam editor if you
2984 do things wrong, because he'll have to fix your mistakes.
2988 \begin_layout Enumerate
2990 Remember, there are people who will reference
2994 section, just as you're referencing someone else's.
2995 You do want what you write to be useful, don't you?
2998 \begin_layout Enumerate
3000 When in doubt, compromise.
3004 \begin_layout Standard
3006 When in doubt, use good judgement.
3009 \begin_layout Subsubsection
3015 Treat the Reader as if She is Stupid
3018 \begin_layout Enumerate
3023 \begin_layout Enumerate
3025 No talking down to the reader.
3028 \begin_layout Enumerate
3030 The reader is smart enough to know what a mouse is.
3033 \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
3070 The reader is smart enough to know that
3071 \begin_inset Quotes eld
3075 \begin_inset Quotes erd
3079 \begin_inset Quotes eld
3082 where the text cursor is sitting right now, in the buffer currently visible.
3083 \begin_inset Quotes erd
3088 (Anything more than the word
3089 \begin_inset Quotes eld
3093 \begin_inset Quotes erd
3096 is, IMO, superfluous and wll be deleted .
3097 So, save yourself the typing, save the editor the cutting, and save the
3098 reader the strain of sifting through extra verbage that adds no content.)
3101 \begin_layout Enumerate
3103 Rule of thumb: the reader is not an imbecile.
3104 The reader is merely lost; point them in the right direction, and they
3105 can take it from there.
3108 \begin_layout Subsection
3110 Tips for the English Version
3113 \begin_layout Standard
3116 \begin_inset LatexCommand \label{sec:english-only}
3120 When contributing to the primary --- i.\InsetSpace ~
3122 the English language version ---
3123 of the LyX manuals, keep the following in mind.
3126 \begin_layout Subsubsection
3128 Write as if You're Talking with a Friend.
3132 \begin_layout Enumerate
3134 Think that way when you write.
3135 Play the dialogue in your mind.
3138 \begin_layout Enumerate
3140 Be as informal as you please (without being rude).
3143 \begin_layout Subsubsection
3145 AVOID the Passive Voice
3148 \begin_layout Enumerate
3151 \begin_inset Quotes eld
3154 It is felt that this name best explains the command's purpose.
3155 \begin_inset Quotes erd
3158 We know full well who wrote the command:
3159 \begin_inset Quotes eld
3162 The LyX Team felt ...
3163 \begin_inset Quotes erd
3167 \begin_inset Quotes eld
3171 \begin_inset Quotes erd
3177 \begin_layout Enumerate
3179 Things don't happen by magic - somebody or something did it.
3180 Only politicians use the passive voice to cover up who did something.
3181 If LyX reformats a paragraph, write,
3182 \begin_inset Quotes eld
3185 LyX reformatted the paragraph.
3186 \begin_inset Quotes erd
3193 makes changes, write,
3194 \begin_inset Quotes eld
3201 changes the document.
3202 \begin_inset Quotes erd
3209 \begin_layout Standard
3211 Rule of thumb: any sentence you can express as,
3212 \begin_inset Quotes eld
3216 \begin_inset Quotes erd
3220 \begin_inset Quotes eld
3224 \begin_inset Quotes erd
3230 \begin_layout Enumerate
3233 We all hear way, way too much garbage English on the TV every day in the
3235 Some people think it makes speech better.
3237 It makes speech baroque, if not outright byzantine.
3238 With a little effort, you can wean yourself off of it.
3241 \begin_layout Enumerate
3245 will make you rewrite
3247 anything in the passive voice.
3248 It's awkward and hard to read.
3251 \begin_layout Enumerate
3253 Note to non-Americans:
3257 \begin_layout Standard
3259 Using passive voice is generally considered bad style in the U.\InsetSpace ~
3262 too easy to obfuscate your words with it.
3263 It also bloats sentences, often unnecessarily.
3266 \begin_layout Subsubsection
3272 \begin_layout Standard
3274 In English, there is a grammatical error known as the
3275 \begin_inset Quotes eld
3279 \begin_inset Quotes erd
3282 The classic example of a run-on sentence is 7 clauses strung together with
3284 \begin_inset Quotes eld
3288 \begin_inset Quotes erd
3291 There are, however, less obvious run-on sentences, ones using too many
3292 subordinate clauses.
3293 Such sentences may look elegant because they are complex.
3294 However, they are also extremely difficult to read because they are so
3298 \begin_layout Standard
3300 In general, stick to short sentences in written English.
3301 Getting rid of passive voice (
3302 \begin_inset Quotes eld
3305 \SpecialChar \ldots{}
3306 was done by\SpecialChar \ldots{}
3308 \begin_inset Quotes erd
3311 ) shortens and simplifies them.
3312 Hacking apart sentences with many dependent clauses is another way to shorten
3314 There are ways to do this yet still have a smooth-flowing paragraph.
3317 \begin_layout Standard
3319 While I'm talking about paragraphs, I'll apply the
3320 \begin_inset Quotes eld
3324 \begin_inset Quotes erd
3327 motto to them, as well.
3328 At the time I started with the manuals (and this Style Sheet), I didn't
3329 pay too much attention to paragraph size.
3330 I've since become a big proponent of short paragraphs, with one idea per
3332 While long, flowing, multi-concept paragraphs can be nice in novels, we're
3334 Our goal is rapid information location and comprehension, not a literary
3338 \begin_layout Standard
3340 There is a single exception to the short sentence, short paragraph rule.
3341 Particularly complex ideas may need more
3342 \begin_inset Quotes eld
3346 \begin_inset Quotes erd
3349 However, you shouldn't encounter such complex ideas often when documenting
3351 Try to keep things short, and use your judgement as needed.
3354 \begin_layout Standard
3356 To reiterate, yet again, something I said before:
3361 When in doubt, compromise.
3366 When in doubt, use good judgement.
3369 \begin_layout Standard
3371 Hopefully, you've got the idea (grin).
3374 \begin_layout Section
3379 \begin_layout Subsection
3381 Rules of the Translating Trade
3384 \begin_layout Standard
3386 While translating anything, there are certain
3387 \begin_inset Quotes eld
3391 \begin_inset Quotes erd
3395 They will help you greatly.
3398 \begin_layout Subsubsection
3400 Translate one paragraph at a time.
3403 \begin_layout Standard
3405 Most people translate word by word.
3406 Clearly, you lose all context if you do that.
3407 A word may have multiple meanings.
3408 You can't tell which unless you look at the rest of the sentence.
3411 \begin_layout Standard
3413 There is another level to the context issue, however.
3414 Your dictionary may translate multiple English words the same way.
3415 All those words mean
3420 Each one, however, covers a different shade of meaning, a different mood
3422 It is often difficult to resolve those shades of meaning in the context
3423 of even one sentence.
3424 A paragraph, however, will provide that context.
3427 \begin_layout Subsubsection
3429 You will not translate it correctly on the first try.
3432 \begin_layout Standard
3434 Alright, I admit that you may be able to translate some of the sentences
3436 If you know a language well, you may even understand over half of the text.
3437 Nevertheless, overconfidence can lead you astray.
3438 There will be some sentences, no matter how few, that will simply confound
3442 \begin_layout Standard
3444 It is generally a good idea to make multiple passes over a paragraph you're
3446 Even if you translate the entire paragraph on the first pass, make a second
3448 You'll often improve upon your first attempt.
3451 \begin_layout Subsubsection
3453 When in doubt, write down all of the meanings for a word.
3456 \begin_layout Standard
3458 You can often translate tricky parts of a text using the context of the
3459 surrounding sentences.
3460 So, if you hit a word or phrase you don't know, translate it more than
3462 Picking the most likely translations, summarize them in one to three words
3464 \begin_inset Quotes eld
3468 \begin_inset Quotes erd
3475 \begin_layout Subsubsection
3477 Using context, fix the meanings on the next pass.
3480 \begin_layout Standard
3482 This is where your multiple translations of a single word become useful.
3483 Using the other sentences you translated, you can now translate that mystery--s
3484 entence without reconsulting your dictionary.
3487 \begin_layout Subsubsection
3489 Fix the grammar only after you've finished translating the sentence.
3492 \begin_layout Standard
3494 If there's a mystery phrase in the middle of a sentence, you can't translate
3495 the entire sentence.
3496 Why grammatically rearrange the words you translated already? You may need
3497 to restructure the sentence a second time once you figure out how to translate
3498 that mystery phrase.
3499 Better to wait until you've completely translated the sentence to clean
3501 That way, you do so only once.
3504 \begin_layout Subsubsection
3506 If you can't translate it, skip it and come back to it on the next pass.
3509 \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
3517 Translate the meaning first.
3521 \begin_layout Standard
3523 The information content of the text under translation is the most important
3525 This is especially important for a manual, where the information
3529 important part of the original document.
3530 Lose that, and you lose the very point of performing the translation.
3533 \begin_layout Subsection
3535 Tips for the Translators
3538 \begin_layout Standard
3540 Those of you contributing to a translation of the LyX manuals must follow
3541 a modified set of rules.
3542 The first few rules are analogous to those in section\InsetSpace ~
3544 \begin_inset LatexCommand \ref{sec:english-only}
3549 There are additional rules and regulations that follow those first few.
3553 \begin_layout Subsubsection
3555 Write as if you are explaining LyX to a colleague you know well.
3558 \begin_layout Enumerate
3560 Think that way when you write.
3561 Play the dialogue in your mind.
3564 \begin_layout Enumerate
3566 Use a conversational style in your writing.
3567 Pretend you are teaching LyX to a colleague you know well.
3570 \begin_layout Enumerate
3572 Use a style that is polite without being too formal.
3573 If, in your culture, informal language is appropriate to use with a colleague,
3574 use informal speech in the translation of the manual.
3577 \begin_layout Subsubsection
3579 AVOID Snobby, Academic, Specialized, or
3580 \begin_inset Quotes eld
3584 \begin_inset Quotes erd
3591 \begin_layout Standard
3593 In English, the passive voice appears formal, dry, barren.
3594 It also often adds unnecessary complexity.
3595 In other langauges, however, this is not the case.
3596 There is nothing wrong with passive voice, and people use it frequently
3597 in everyday conversation.
3598 Nevertheless, your translation of the LyX manuals must avoid
3599 \begin_inset Quotes eld
3603 \begin_inset Quotes erd
3609 \begin_layout Standard
3611 In Germany, there is a magazine known as
3612 \begin_inset Quotes gld
3616 \begin_inset Quotes grd
3619 The writing in it is so complex, it is extremely difficult for non-native
3620 German speakers to understand.
3621 While sophisticated, the writing style of
3622 \begin_inset Quotes gld
3626 \begin_inset Quotes grd
3629 is not what a German uses in everyday conversation.
3630 Nor is the writing style for a Russian mathematics journal.
3631 Such specialized or overly-sophisticated styles are
3632 \begin_inset Quotes eld
3636 \begin_inset Quotes erd
3639 in the sense that they are seldom used by normal people in everyday speech.
3642 \begin_layout Standard
3644 We who write the LyX manuals, original or translated, seek to
3649 If we write in a style only a few people use, and use seldomly, we will
3651 Use a writing style that mirrors everyday speech (without being vulgar,
3656 \begin_layout Subsubsection
3658 Keep the Writing Simple.
3661 \begin_layout Standard
3663 For the English version, I wrote,
3664 \begin_inset Quotes eld
3667 Use short sentences and short paragraphs.
3668 \begin_inset Quotes erd
3671 What if, however, short sentences and paragraphs are something only children
3672 use in your language? What if, in yet another language, short sentences
3673 imply rudeness? Naturally, you would not want to use them in your translation.
3676 \begin_layout Standard
3678 Nevertheless, the translations of the LyX manuals should be as clear as
3680 So, for our international colleagues, we apply this rule: Keep your sentences
3681 and paragraphs as short as makes sense.
3684 \begin_layout Standard
3686 Remember: we're translating manuals here, folks.
3687 Our goal is rapid information location and comprehension, not a literary
3689 Try to keep your writing concise yet smooth-flowing.
3690 And use your judgement as needed:
3695 When in doubt, compromise.
3700 When in doubt, use good judgement.
3703 \begin_layout Subsubsection
3705 Translators must follow the Style Sheet, too!
3708 \begin_layout Standard
3710 Everything in this manual ---
3712 except section\InsetSpace ~
3714 \begin_inset LatexCommand \ref{sec:english-only}
3720 --- applies to every LyX documenter, no matter what the language.
3723 \begin_layout Subsubsection
3725 Translators must read the Style Sheet Supplement for their language.
3728 \begin_layout Standard
3730 For every translation project, there is a Supplement to the Style Sheet.
3738 DocStyle_Supplement_<cn>.lyx
3741 \begin_layout Standard
3743 \SpecialChar \ldots{}
3745 \begin_inset Quotes eld
3753 \begin_inset Quotes erd
3756 is your language's two-letter locale code.
3757 The Translation Project Chief for your language wrote this.
3758 If he hasn't, pester him to do so! <
3765 \begin_layout Subsubsection
3767 The English versions of the manuals are not Sacred Text.
3770 \begin_layout Standard
3772 You do not need to translate everything word for word.
3773 In fact, you shouldn't.
3774 Keep to the spirit of the originals, not the letter.
3775 Be as creative as you want, as long as you
3783 convey all of the information contained in the English versions.
3786 \begin_layout Subsubsection
3788 Any information in the LyX manuals must also be in the translations.
3791 \begin_layout Standard
3794 \begin_inset LatexCommand \label{sec:accuracy}
3798 This falls under translating the orignals accurately and completely.
3802 \begin_layout Itemize
3804 Omitting any feature description is
3811 \begin_layout Itemize
3813 Misrepresenting or misdescribing any LyX feature or operation
3820 \begin_layout Itemize
3826 outpace the original.
3828 If no one has documented new feature in the primary LyX manuals (i.\InsetSpace ~
3831 versions), do not do so in the translations.
3832 If you're really looking for something to do, either:
3836 \begin_layout Itemize
3838 \SpecialChar \ldots{}
3839 focus on translating something you haven't yet,
3844 \begin_layout Itemize
3846 \SpecialChar \ldots{}
3847 update or repair the primary manual.
3850 \begin_layout Standard
3852 If you cannot or do not want to do one of the above, then take a break.
3854 Wait for the main manuals to catch up before translating anything else.
3857 \begin_layout Subsubsection
3859 What you cannot translate, you may omit (usually).
3862 \begin_layout Standard
3864 Prepositions, idioms, metaphors, slang, Oh My! There's a jungle of potentially
3865 untranslatable text you may face.
3866 Happily, none of these untranslatables are essential to the original text\SpecialChar \ldots{}
3869 If you can't translate a phrase or two, try omitting them.
3870 If the rest of the paragraph still makes sense, then don't worry about
3874 \begin_layout Standard
3876 There may be special cases where omitting part of a sentence or paragraph
3877 violates rule\InsetSpace ~
3879 \begin_inset LatexCommand \ref{sec:accuracy}
3888 You must try and translate those tricky spots.
3891 \begin_layout Subsubsection
3893 Translators may add their own fluff to the information content.
3896 \begin_layout Standard
3898 After you do strip away all of the idioms, metaphors, slang, humor, and
3900 \begin_inset Quotes eld
3904 \begin_inset Quotes erd
3907 you may find that your translated manual is dull and dry.
3908 Why not add your own fluff? Add text that makes the manual a pleasure to
3909 read, that engages the reader.
3910 It may take the form of humor, or metaphors, or sayings.
3911 Whatever you add, it should be
3912 \begin_inset Quotes eld
3916 \begin_inset Quotes erd
3919 It should not clash with the explanation of LyX features and functions.
3922 \begin_layout Subsection
3924 For Translation Project Chiefs
3927 \begin_layout Subsubsection
3929 The First Is In Charge
3932 \begin_layout Standard
3934 If you were the first person to start translating the manuals, you're the
3935 LyXDoc Translation Project Chief for your language.
3940 person translating the LyXDocs, that automatically makes you the Translation
3944 \begin_layout Standard
3946 Amongst other things, that means that you must read this section and perform
3947 the tasks described here.
3950 \begin_layout Standard
3952 If you are a member of a LyX Documentation Translation Team, but
3956 its Chief, you may stop reading.
3957 The remainder of this section will be of no interest to you.
3958 If you came to the Style Sheet from the Supplement for your language, you
3962 \begin_layout Standard
3964 If you have not read the Style Sheet Supplement for your language, you should
3969 \begin_layout Subsubsection
3971 Read the Style Sheet
3974 \begin_layout Standard
3976 No documenter is excused from following the Style Sheet, not even a Translation
3980 \begin_layout Standard
3986 important that the Translation Project Chiefs read the Style Sheet.
3989 \begin_layout Subsubsection
3991 Make your translators read the Style Sheet
3994 \begin_layout Standard
3996 No documenter is excused from following the Style Sheet.
3999 \begin_layout Standard
4001 Since your translation team is translating, they know
4006 Therefore, they should be able to read the Style Sheet.
4009 \begin_layout Subsubsection
4012 \begin_inset Quotes eld
4016 \begin_inset Quotes erd
4022 \begin_layout Standard
4024 There are parts of this Style Sheet that are English-specific.
4025 I have tried to provide a general, language-independent description of
4026 certain details in this section.
4027 Unfortunately, that general description doesn't cover the specifics of
4032 \begin_layout Standard
4034 That's where you, as head of a LyXDoc Translation Team, come in.
4037 \begin_layout Standard
4039 Every Translation Team Chief is
4043 to write a Supplement to the official Documentation Style Sheet, with specifics
4044 issues affecting your language.
4045 (You are, after all, the LyX Team expert on your native tongue.) Follow
4046 these guidelines when writing the Supplement:
4049 \begin_layout Enumerate
4055 DocStyle_Supplement_<cn>.lyx
4059 \SpecialChar \ldots{}
4061 \begin_inset Quotes eld
4069 \begin_inset Quotes erd
4072 is the two-letter code for your language.
4073 This is the same two-letter code that is part of the filenames for the
4076 \begin_inset Quotes eld
4084 \begin_inset Quotes erd
4088 \begin_inset Quotes eld
4096 \begin_inset Quotes erd
4100 \begin_inset Quotes eld
4108 \begin_inset Quotes erd
4114 \begin_layout Enumerate
4116 Do not worry about where the file goes.
4117 The CVS maintainers will locate all documentation and Style Sheet Supplements
4118 in an appropriate place.
4121 \begin_layout Enumerate
4123 Document Properties:
4127 \begin_layout Itemize
4129 For consistency, use the same document class and other document properties
4134 \begin_layout Standard
4136 Specifically, check the settings in the
4141 Use those in your Supplement.
4149 \begin_layout Itemize
4151 Exceptions: Use margins, indentation/paragraph separation, language, and
4152 encoding appropriate for your language.
4155 \begin_layout Enumerate
4157 The title of the Supplement:
4161 \begin_layout Itemize
4163 The title will use the
4164 \begin_inset Quotes eld
4172 \begin_inset Quotes erd
4175 paragraph environment.
4176 In your native tongue, the title will read:
4180 \begin_layout Standard
4184 Documentation Project Style Sheet:
4186 Supplement for the <foo> Translation Project
4189 \begin_layout Standard
4192 \begin_inset Quotes eld
4200 \begin_inset Quotes erd
4203 with the name of your language.)
4206 \begin_layout Itemize
4208 If, in your language,
4209 \begin_inset Quotes eld
4213 \begin_inset Quotes erd
4217 \begin_inset Quotes eld
4221 \begin_inset Quotes erd
4226 \begin_inset Quotes eld
4230 \begin_inset Quotes erd
4234 \begin_inset Quotes eld
4238 \begin_inset Quotes erd
4241 have somewhat different meanings.
4242 An appendix is an extra part of a document.
4243 A supplement is an extra document.
4248 \begin_layout Standard
4250 Choose a replacement word accordingly.
4251 Whatever you choose to replace
4252 \begin_inset Quotes eld
4256 \begin_inset Quotes erd
4259 it must not have the same translation as the word
4260 \begin_inset Quotes eld
4264 \begin_inset Quotes erd
4271 \begin_layout Enumerate
4273 Below the title, in the
4274 \begin_inset Quotes eld
4282 \begin_inset Quotes erd
4285 paragraph environment, place your name.
4289 \begin_layout Standard
4291 There will be no abstract.
4294 \begin_layout Enumerate
4304 \begin_layout Standard
4306 The first thing you will do is strongly yet politely encourage the reader
4308 \begin_inset Quotes eld
4312 \begin_inset Quotes erd
4315 and go read the Style Sheet.
4316 The reader should not return to the
4317 \begin_inset Quotes eld
4321 \begin_inset Quotes erd
4328 understood the Style Sheet proper.
4331 \begin_layout Subsubsection
4333 Keep the Supplement Succinct
4336 \begin_layout Standard
4338 This Style Sheet is already very detailed.
4339 DocTeam members all have a lot to read.
4340 We don't want to place an extra burden on translators.
4341 Therefore, keep the Supplement as short as you can without losing information.
4344 \begin_layout Subsubsection
4349 \begin_layout Standard
4355 will be about font issues\SpecialChar \ldots{}
4357 Not all Translation Project Chiefs will need to deal with this issue.
4361 \begin_layout Itemize
4368 \begin_layout Itemize
4375 \begin_layout Itemize
4381 Emphasized (actually Italics)
4384 \begin_layout Itemize
4391 \begin_layout Itemize
4398 \begin_layout Itemize
4402 Noun (actually Small Caps)
4405 \begin_layout Standard
4407 \SpecialChar \ldots{}
4408 certainly exist for all languages that use the Roman alphabet.
4409 Do they exist, however, for Greek? How about Cyrillic? These different
4410 fonts almost certainly do not exist for Devanagri, Chinese, Korean, Japanese,
4411 Hebrew, Arabic, and other scripts.
4415 \begin_layout Standard
4417 There will be some languages for which following the font-scheme specified
4418 in this Style Sheet may not be possible.
4419 If you are the Translation Project Chief for such a language, you have
4423 \begin_layout Standard
4425 In the font section of the Supplement, you will provide a new typographic
4426 style, designed specifically for your writing system.
4427 For consistency, the title of this section in every Supplement should translate
4429 \begin_inset Quotes eld
4433 \begin_inset Quotes erd
4436 Before adding anything to this section, however, determine what this new
4437 typographic style will look like.
4438 Stick to the font specifications in this Style Sheet as best you can, whenever
4440 When you cannot, use the following suggestions:
4443 \begin_layout Itemize
4446 \begin_inset Quotes eld
4450 \begin_inset Quotes erd
4457 What to do when a font doesn't exist:
4462 \labelwidthstring MMMMMMMM
4464 Roman Use the font that typesetters in your language use for printing books,
4466 This will typically be the default font LyX (and LaTeX) uses in your language.
4470 \labelwidthstring MMMMMMMM
4477 This is for people's names.
4478 If there is special font for names in your alphabet/writing system, use
4479 it in place of this.
4480 Otherwise, write names in the default font, typeset according to the rules
4485 \labelwidthstring MMMMMMMM
4491 Use the font with which your language normally emphasizes text.
4495 \begin_layout Standard
4497 Use a font that is different from your language's equivalent of
4502 In other words, your
4510 and similar headers will be in one typeface, perhaps
4515 Whatever that font is, avoid using it for
4523 \labelwidthstring MMMMMMMM
4529 Pick up a computer program manual written in your language.
4530 It will use a special typeface for filenames, for command names, program
4532 Use that same font in place of
4540 \labelwidthstring MMMMMMMM
4547 Pick any other font that is different from the ones you're using in place
4561 If you're unlucky, and your language's writing system doesn't have enough
4562 fonts, use the same font you picked to replace
4567 Only do this, however, if your alphabet/writing system has very few fonts
4572 \labelwidthstring MMMMMMMM
4579 nderlined\InsetSpace ~
4583 Don't worry about this one.
4587 \begin_layout Standard
4589 If you use some special font on-screen to highlight the accelerator keys
4590 for menus, buttons, and other widgets, you might want to mimic that in
4592 It is not required, however.
4593 Therefore, if you can't mimic this typographic convention in your native
4594 writing system, don't.
4598 \begin_layout Standard
4600 Note that you may also want to describe fonts that your Translation Team
4606 For example, no contributer to the English/European versions may ever use
4611 , as this is used for section-headings.
4612 Since there are enough other fonts, we who use the Roman alphabet and its
4613 variants can afford to omit
4621 \begin_layout Standard
4623 Once you have determined which fonts in your native writing system will
4624 replace one or more of the above, propose it to the LyX Developer's Mailing
4626 You may receive valuable feedback this way.
4627 If not, that's okay.
4628 If no one can read your writing system, and therefore cannot comment, that's
4630 Go ahead and describe the typographic standard you created in the Supplement.
4634 \begin_layout Standard
4636 Remember: stick to the font specifications in this Style Sheet as best you
4637 can, whenever you can.
4640 \begin_layout Subsubsection
4642 Quoting Style and the
4654 \begin_layout Standard
4656 The next section of the Supplement will cover the issue of quoting.
4657 Give it an appropriate title.
4660 \begin_layout Standard
4662 One of the first things you should do in that section is resolve the following
4666 \begin_layout Itemize
4676 is the correct paragraph environment for your language.
4679 \begin_layout Itemize
4681 In the Supplement, specify which one to use.
4684 \begin_layout Standard
4686 English has its own typography and style for quoting others.
4687 The Style Sheet describes that typography in section\InsetSpace ~
4689 \begin_inset LatexCommand \ref{sec:quote}
4694 Your language also has a specific typography and style for quotations.
4695 Describe that style in this section of the Supplement, too.
4696 Naturally, you do not need to go overboard.
4697 Section\InsetSpace ~
4699 \begin_inset LatexCommand \ref{sec:quote}
4703 of this Style Sheet is overly detailed for a good reason.
4704 Authors of the primary LyX manuals are not necessarily native English speakers.
4705 The members of your Translation Team, however, will all likely be native
4706 speakers of your language.
4707 Therefore, discuss proper quoting style of your native tongue to an appropriate
4711 \begin_layout Subsubsection
4713 Translations of Style Sheet Terminology
4716 \begin_layout Standard
4718 In the Supplement, you must provide a standard translation of certain key
4719 phrases for the members of your Translation Team.
4720 Place this in a section following the one about quotations.
4723 \begin_layout Standard
4725 In particular, standardize the translations of the phrases:
4728 \begin_layout Itemize
4735 \begin_layout Itemize
4742 \begin_layout Standard
4748 change the typography of the
4749 \begin_inset Quotes eld
4753 \begin_inset Quotes erd
4757 \begin_inset Quotes eld
4761 \begin_inset Quotes erd
4765 Only provide a translation for the opening phrases.
4766 Insist that the members of your Translation Team use these two tools correctly.
4769 \begin_layout Standard
4771 While we are discussing proper use of the
4772 \begin_inset Quotes eld
4776 \begin_inset Quotes erd
4780 \begin_inset Quotes eld
4784 \begin_inset Quotes erd
4787 in translations, let's talk about a related problem.
4789 \begin_inset Quotes eld
4793 \begin_inset Quotes erd
4796 is meant to be a note from the author of a manual to the reader.
4797 In the case of a translation, however, the translator is
4801 the author! How then should a translator translate an
4802 \begin_inset Quotes eld
4806 \begin_inset Quotes erd
4812 \begin_layout Standard
4814 You, as Translation Project Chief, must decide.
4815 You can forbid translation of pre-existing
4816 \begin_inset Quotes eld
4820 \begin_inset Quotes erd
4823 omitting them entirely instead.
4824 You could tell your translators to read any
4825 \begin_inset Quotes eld
4829 \begin_inset Quotes erd
4832 they may encounter, understand it, then write their own
4833 \begin_inset Quotes eld
4837 \begin_inset Quotes erd
4840 about the situation, not as a translation but as a personal opinion.
4841 You may decide on some other policy.
4844 \begin_layout Standard
4846 Whatever you decide, codify your policy in its own
4855 Place it near the section where you translated
4856 \begin_inset Quotes eld
4860 \begin_inset Quotes erd
4864 \begin_inset Quotes eld
4868 \begin_inset Quotes erd
4874 \begin_layout Subsubsection
4879 \begin_layout Standard
4881 After describing all of the previous issues, create a new
4887 \begin_inset Quotes eld
4890 Lost in Translation,
4891 \begin_inset Quotes erd
4894 or something similar.
4897 \begin_layout Standard
4899 In this section you will discuss any common English metaphors, humor, connotatio
4900 n, or other difficult to translate text.
4901 Try to balance brevity and completeness.
4910 s --- to each specific issue.
4913 \begin_layout Subsubsection
4915 \SpecialChar \ldots{}
4917 \begin_inset Quotes eld
4921 \begin_inset Quotes erd
4924 \SpecialChar \ldots{}
4928 \begin_layout Standard
4930 Throughout the manuals, the DocTeam has used the following sentences:
4935 If you haven't read the <
4939 > manual, go read it.
4943 \begin_layout Standard
4945 This sentence will be tricky to translate, since it contains non-translatable
4951 for this issue in your
4952 \begin_inset Quotes eld
4956 \begin_inset Quotes erd
4961 \begin_inset Quotes eld
4964 \SpecialChar \ldots{}
4965 Yes, we mean now\SpecialChar \ldots{}
4967 \begin_inset Quotes erd
4970 sentences, then present a translation, along with any explanation you feel
4974 \begin_layout Standard
4976 Here's what those two sentences, sitting alone in their own paragraph, mean:
4979 \begin_layout Standard
4981 The first sentence uses the English conditional followed by an imperative.
4982 We, as the LyX team, are commanding the reader to go back to another manual.
4987 manual is a prerequisite for all of the other manuals.
4988 The conditional clause preceeding the command means,
4989 \begin_inset Quotes eld
4992 You do not need to perform this command twice.
4993 \begin_inset Quotes erd
4999 \begin_layout Standard
5001 The second sentence adds force to the command.
5002 Culturally, the imperative tense of a verb in English is not necessarily
5004 The way we wrote that command,
5005 \begin_inset Quotes eld
5009 \begin_inset Quotes erd
5012 is firm, yet polite.
5013 The reader may choose to ignore it.
5015 \begin_inset Quotes eld
5019 \begin_inset Quotes erd
5022 we imply two things.
5024 \begin_inset Quotes eld
5028 \begin_inset Quotes erd
5032 That second sentence reinforces the command, making it a bit harder to
5034 Second, the sentence itself implies a certain sense of urgency.
5035 You cannot merely wait until later to fulfill that command.
5036 The brief pragraph, and its sudden end, add still further subtle reinforcement
5038 \begin_inset Quotes eld
5041 go do the required reading before using this manual.
5042 \begin_inset Quotes erd
5048 \begin_layout Standard
5050 Note that all of this commanding and reinforcing is nevertheless in a polite
5052 Furthermore, it is in a subtle form.
5053 We are commanding the reader to do something, but in an indirect fashion.
5054 This way, the reader does not feel like we are bullying him.
5057 \begin_layout Subsubsection
5063 \begin_layout Standard
5065 In the same part of the Supplement that you place the
5066 \begin_inset Quotes eld
5069 \SpecialChar \ldots{}
5070 Yes, we mean now\SpecialChar \ldots{}
5072 \begin_inset Quotes erd
5075 translation, discuss the English version's use of
5076 \begin_inset Quotes eld
5080 \begin_inset Quotes erd
5086 \begin_layout Standard
5088 You see, here in America, we often say that everything is permitted unless
5089 explicitly banned by law.
5090 As a result, manuals for computer software are frequently ignored and the
5091 software subsequently blamed for not being
5092 \begin_inset Quotes eld
5096 \begin_inset Quotes erd
5099 This is where the use of
5100 \begin_inset Quotes eld
5104 \begin_inset Quotes erd
5111 \begin_layout Standard
5113 We who wrote the manuals added sentences insisting that the reader not ignore
5114 certain parts of the documentation.
5115 We wrote in a manner that was polite, yet firmly asserted that the user
5116 was misusing the software if he did not read the manual correctly.
5117 We did not, however, want to sound threatening, coercive, or bullying.
5120 \begin_layout Standard
5122 In your culture, cajoling the reader into using the manuals correctly may
5124 It may, in fact, be outright rude.
5125 Additionally, translating the firm-but-convincing bits may not work.
5126 The translation may sound weird, or rude, or hostile.
5127 Therefore, you and your translation team will face many sentences that
5128 you cannot translate.
5131 \begin_layout Standard
5133 You, the Translation Project Chief, must discuss this issue.
5134 Try and find parts of the original manuals where some friendly but firm
5135 convincing does not translate properly.
5136 Use these cases as the basis for examples of the problem.
5137 Be sure to then offer a solution (i.\InsetSpace ~
5139 how you want such sentences translated.)
5140 If stumped, ask for help on the LyX Developer's List.
5143 \begin_layout Subsubsection
5148 \begin_layout Standard
5150 You can add more sections to the Supplement if you need to discuss other
5152 There may be policies or guidelines that you want to set for your Translation
5154 Be careful, however! Keep the Supplement