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
26 \tracking_changes false
33 Documentation Project Style Sheet
40 \begin_layout Abstract
41 This article is a style sheet.
42 It describes, with examples, how the documentation should look and sound.
43 The first few sections explain the font conventions and typography conventions
44 all documentation writers should follow.
45 Those sections also contain examples.
46 It also explains the purpose of each of the different manuals.
47 Follow it not merely to the letter, but also in spirit.
50 \begin_layout Abstract
51 The Style Sheet for LyX documentation (hereafter known as the Style Sheet)
56 forms of LyX documenation, regardless of language.
57 There is a section for translators in the Style Sheet, towards the end.
60 Read the entire Style Sheet!
62 Even if you are a translator, I assume you know enough English to comprehend
67 Questions and Clarifications
70 \begin_layout Standard
71 After the second version of this Style Sheet grew uncomfortably large, the
72 LyX DocTeam decided it needed to lose some excess weight.
73 It seems the Style Sheet began to specify too many special cases, too many
74 points of clarification.
75 On the other hand, contributors to the documents were discovering many
76 creative ways of misinterpreting the Style Sheet specifications.
81 If you have any questions about anything in the Style Sheet,
83 ask first, write second!
86 \begin_layout Standard
87 Field all questions to the LyX Developer's Mailing List.
88 There are seasoned DocTeam members who can answer your questions.
89 If you have any problems with the Style Sheet itself, also contact the
97 \begin_layout Standard
98 We'll start with the easiest section, yet also the most important.
101 \begin_layout Standard
102 This is how you should fontify text in the manuals:
106 \labelwidthstring MMMMMMMM
111 general emphasis, generic arguments, titles of books, names the other manuals
112 and of their sections, and notes from the authors
116 \begin_layout Standard
117 Do not overemphasize your text.
122 \labelwidthstring MMMMMMMM
127 program names, file names,
131 -page names, LaTeX code, LaTeX commands, LaTeX package names, and LyX code
136 \labelwidthstring MMMMMMMM
142 menu, button, or popup names, the names/lables of all widgets in a popup,
143 the names of keyboard keys, and certain
144 \begin_inset Quotes eld
148 \begin_inset Quotes erd
155 \labelwidthstring MMMMMMMM
165 \labelwidthstring MMMMMMMM
171 nderlined\InsetSpace ~
175 Rich Fields added this to mimick the underlining of letters in the menus
177 It helps to highlight the accelerator keys, and human brains store information
178 best when they see it frequently.
182 \begin_layout Description
183 WARNING! --- When you do this, make sure you
187 shut off the underlining.
188 Too many people send in things that look like:
198 \SpecialChar \ldots{}
201 they not only shut off underlining, they turned off
210 Make sure the entire word is still in
215 after you shut off the underlining.
220 \labelwidthstring MMMMMMMM
229 \begin_layout Standard
230 If you want to emphasize any text, use
235 LaTeX will put many things boldface on its own, such as
239 s, certain parts of equations, et cetera.
242 \begin_layout Standard
243 Repeat: do not use boldface.
247 \begin_layout Standard
248 Here are some examples:
251 \begin_layout Enumerate
256 appears in configuration files and in the LyX source.
257 Therefore, it (and all other LyX function names) count as code and is set
265 \begin_layout Enumerate
274 is a menu item in the
281 menu, so it appears in
292 nderlined\InsetSpace ~
296 for the accelerator keys.
299 \begin_layout Enumerate
300 Consider the following excerpt from the introduction of one of the manuals:
304 \begin_layout Quotation
313 both refer to the same key.
314 Some keyboards label the
319 \begin_inset Quotes eld
323 \begin_inset Quotes erd
327 \begin_inset Quotes eld
331 \begin_inset Quotes erd
334 still others have two keys.
335 LyX treats all of them as the same key, so we'll use
346 \begin_layout Standard
347 Notice that the key name,
360 when it references the key itself! When I described how the manufacturer
361 chose to label its keyboard, I used Roman and put the word in quotes.
362 There is a semantic difference.
366 \begin_layout Enumerate
367 Take the following command:
371 \begin_layout Standard
380 \begin_layout Standard
381 Notice that the argument to the
391 This is a case where you don't use
395 for code, because you want the generic argument label to stand out.
396 On the other hand, if you were specifying an argument, for example,
397 \begin_inset Quotes eld
405 \begin_inset Quotes erd
417 \begin_layout Enumerate
418 Any LaTeX commands and code, and any
422 LaTeX package names get set in
428 \begin_inset Quotes eld
436 \begin_inset Quotes erd
439 is the name of an unsupported LaTeX package, but
440 \begin_inset Quotes eld
448 \begin_inset Quotes erd
451 is a supported LaTeX class.
454 \begin_layout Section
458 \begin_layout Standard
459 The canonical keyboard contains these keys:
462 \begin_layout Itemize
474 \begin_layout Itemize
486 \begin_layout Itemize
499 \begin_layout Standard
503 use the abbreviations
509 \begin_layout Itemize
512 F1 F2 F3 F4 F5 F6 F7 F8 F9 F10 F11 F12
516 \begin_layout Standard
518 Most modern keyboards have all 12.
522 \begin_layout Itemize
531 \begin_layout Standard
533 \begin_inset Quotes eld
537 \begin_inset Quotes erd
544 \begin_layout Itemize
571 \begin_layout Standard
572 These are the 6 keys that appear above the cursor keys on many PC keyboards.
573 Consider them as part of the standard motion keys.
577 \begin_layout Itemize
584 \begin_layout Standard
585 The four standard motion keys.
586 There is no need to put the word
587 \begin_inset Quotes eld
591 \begin_inset Quotes erd
594 anywhere, since that's obvious.
598 \begin_layout Standard
600 \begin_inset Quotes eld
604 \begin_inset Quotes erd
609 \begin_inset Quotes eld
613 \begin_inset Quotes erd
616 after one of these may be redundant in certain situations.
625 \begin_layout Itemize
638 \begin_layout Standard
639 I won't throw a hissy fit if you use one instead of the other.
640 I'd prefer if you used
648 , but it's okay if you slip up and forget.
649 Since these two keys are bound to the same function in LyX, it doesn't
654 \begin_layout Standard
655 You do not need to explain everywhere what the
664 The user isn't stupid.
665 Also, someone will document anything that isn't clear (e.\InsetSpace ~
676 problem) someplace in the introduction.
677 No need for you to repeat someone else's work.
680 \begin_layout Standard
681 LyX does not support keyboards missing any of the keys described above,
683 LyX can support a keyboard missing
692 There is a keyboard accelerator for
696 , but this is the only function key LyX assumes exists.
697 Nevertheless, these details are of minor, if any, concern for the documentation.
698 Assume the aforementioned keys exist.
701 \begin_layout Section
705 \begin_layout Standard
707 \begin_inset Quotes eld
711 \begin_inset Quotes erd
714 and any description of the 3 mouse buttons have no special handling.
715 Don't typeset them in any other font than the default, which is Roman.
719 \begin_layout Standard
720 Exception: you're writing an Author's Note (see section
721 \begin_inset LatexCommand \ref{sec:author-notes}
725 ) and you need to mention something about the mouse.
726 Since the rest of the note is in
730 , your description of
731 \begin_inset Quotes eld
735 \begin_inset Quotes erd
738 should be emphasized, as well.
739 There are a couple of other cases like this one; use your judgement.
742 \begin_layout Standard
743 There are only 3 mouse buttons.
744 The use of them and of the mouse itself is obvious.
745 There are few --- if any --- nonstandard things we do with the mouse.
746 Therefore, there's no need to make the word
747 \begin_inset Quotes eld
751 \begin_inset Quotes erd
755 \begin_inset Quotes eld
759 \begin_inset Quotes erd
765 \begin_layout Section
769 \begin_layout Standard
773 \begin_layout Description
774 Multi-word\InsetSpace ~
777 Protected\InsetSpace ~
780 between the words for menu and widget names.
796 \begin_layout Standard
797 This holds for things in
807 If you have a long code example, one that can't simply be inlined and put
820 \begin_layout Standard
823 Protected\InsetSpace ~
826 so that the name doesn't get split between two lines, which is visually
830 Protected\InsetSpace ~
833 is near the end of a line and overflows the margin, use a
839 in that parargraph (consult a LaTeX book for more about
840 \begin_inset Quotes eld
850 \begin_inset Quotes erd
853 ) or manually add a hypenation point.
857 \begin_layout Description
859 Terms These are things like the following:
863 \begin_layout Itemize
871 \begin_layout Itemize
879 \begin_layout Itemize
886 \begin_layout Itemize
894 \begin_layout Standard
900 font and, in the case of
908 , capitalize the first two letters.
911 \begin_layout Standard
912 Why are these terms special? They are concepts which the seasoned LaTeX-pert
913 is familiar with, but which the new LyX user is not.
914 I want them to stand out from the rest of the text, hence the use of
924 \begin_layout Standard
925 Seasoned LyX Team Members: Are there other terms that require this special
926 status? On the other hand, should we eliminate this style completely?
929 \begin_layout Description
930 Terminology Note the following:
933 \begin_layout Itemize
934 \begin_inset Quotes eld
938 \begin_inset Quotes erd
942 \begin_inset Quotes eld
946 \begin_inset Quotes erd
950 \begin_inset Quotes eld
954 \begin_inset Quotes erd
959 \begin_inset Quotes eld
963 \begin_inset Quotes erd
967 \begin_inset Quotes eld
971 \begin_inset Quotes erd
977 \begin_layout Itemize
978 PostScript® is a registered trademark of Adobe Corp.
981 You must put the ® after it or we'll get sued!
983 I also want it written as seen here, always capitalized.
985 \begin_inset Quotes eld
989 \begin_inset Quotes erd
993 \begin_inset Quotes eld
997 \begin_inset Quotes erd
1001 \begin_inset Quotes eld
1005 \begin_inset Quotes erd
1008 - both of them capitalized, in the default font (i.\InsetSpace ~
1011 If you must, cut and paste it from here.
1015 \begin_layout Standard
1016 I am going to say this again:
1019 \begin_layout Standard
1020 \begin_inset VSpace 0.37cm
1026 \begin_layout Standard
1031 You must put the ® after PostScript® or we'll get sued!
1034 \begin_layout Standard
1035 \begin_inset VSpace 0.51cm
1041 \begin_layout Standard
1042 I mean it! American companies like to sue anything that moves.
1047 by forgetting that ®.
1053 \begin_layout Itemize
1054 Similarly, if you use any other registered trademark in any documentation,
1055 put the ® after it, too.
1058 \begin_layout Description
1060 Items When quick-referencing an item in a menu, use the menu separator:
1062 \begin_inset Quotes eld
1065 \SpecialChar \menuseparator
1067 \begin_inset Quotes erd
1073 File\SpecialChar \menuseparator
1077 Notice that there are
1082 \begin_inset Quotes eld
1085 \SpecialChar \menuseparator
1087 \begin_inset Quotes erd
1095 , just like the menu and item names.
1099 \begin_layout Enumerate
1100 The reason why I want no spaces around the
1101 \begin_inset Quotes eld
1104 \SpecialChar \menuseparator
1106 \begin_inset Quotes erd
1109 is to prevent LyX from splitting terms across lines.
1110 The same goes for using
1112 Protected\InsetSpace ~
1115 s between multi-word terms.
1116 The split would be visually disruptive.
1119 \begin_layout Enumerate
1121 \begin_inset Quotes eld
1124 \SpecialChar \menuseparator
1126 \begin_inset Quotes erd
1129 goes between menu names and item names
1134 (Yes, submenus are okay, too).
1137 \begin_layout Enumerate
1143 \begin_inset Quotes eld
1146 \SpecialChar \menuseparator
1148 \begin_inset Quotes erd
1151 between menu items and dialog names.
1153 \begin_inset Quotes eld
1161 ayout\SpecialChar \menuseparator
1166 per\SpecialChar \menuseparator
1171 \begin_inset Quotes erd
1176 IS STRICTLY FORBIDDEN!
1182 \begin_layout Standard
1188 \begin_inset Quotes eld
1191 \SpecialChar \menuseparator
1193 \begin_inset Quotes erd
1196 between popup names and any dialog.
1198 \begin_inset Quotes eld
1204 Dialog\SpecialChar \menuseparator
1212 \begin_inset Quotes erd
1217 IS STRICTLY FORBIDDEN!
1220 \begin_layout Standard
1226 \begin_inset Quotes eld
1229 \SpecialChar \menuseparator
1231 \begin_inset Quotes erd
1234 between menu items and any dialog.
1236 \begin_inset Quotes eld
1244 ayout\SpecialChar \menuseparator
1249 per\SpecialChar \menuseparator
1257 \begin_inset Quotes erd
1262 IS STRICTLY FORBIDDEN!
1265 \begin_layout Standard
1266 Either write out the description, or use context to eliminate any need to
1267 repeat menu items, dialog names, etc.
1272 \begin_layout Description
1274 Boxes LyX has a feature for adding comments that appear only within
1277 \begin_inset Note Note
1280 \begin_layout Standard
1281 These should NEVER appear in the manuals.
1287 You will see nothing in a printout of the Style Sheet.
1288 Therefore, they have no place in the manuals.
1294 \begin_layout Standard
1295 If you have a parenthetical comment you want to make, the reader should
1296 see it too, even in the printed version.
1297 Use an Author's Note (see section
1298 \begin_inset LatexCommand \ref{sec:author-notes}
1302 ) in place of the Note-Boxes.
1306 \begin_layout Description
1307 \begin_inset Quotes eld
1310 (\SpecialChar \ldots{}
1312 \begin_inset Quotes erd
1317 \begin_inset Quotes eld
1320 [\SpecialChar \ldots{}
1322 \begin_inset Quotes erd
1328 \begin_inset Quotes eld
1331 {\SpecialChar \ldots{}
1333 \begin_inset Quotes erd
1336 I have recently been corrected about the use of parentheses.
1337 Standard English typesetting uses the normal parentheses,
1338 \begin_inset Quotes eld
1341 (\SpecialChar \ldots{}
1343 \begin_inset Quotes erd
1346 , around any aside, remark, or parenthetical expression.
1348 \begin_inset Quotes eld
1351 [\SpecialChar \ldots{}
1353 \begin_inset Quotes erd
1356 , is used only within quotations (see section\InsetSpace ~
1358 \begin_inset LatexCommand \ref{sec:quote}
1364 \begin_inset Quotes eld
1367 {\SpecialChar \ldots{}
1369 \begin_inset Quotes erd
1373 Therefore, never use
1374 \begin_inset Quotes eld
1377 [\SpecialChar \ldots{}
1379 \begin_inset Quotes erd
1383 \begin_inset Quotes eld
1386 {\SpecialChar \ldots{}
1388 \begin_inset Quotes erd
1391 unless otherwise specified by this Style Sheet.
1394 \begin_layout Description
1395 Dashes: Be sure to use the correct one.
1397 \begin_inset Quotes eld
1405 \begin_inset Quotes erd
1408 character is not a dash, it's a hyphen.
1409 Use it only as a hyphen.
1414 \begin_layout Standard
1416 \begin_inset Quotes eld
1420 \begin_inset Quotes erd
1424 \begin_inset Quotes eld
1428 \begin_inset Quotes erd
1432 \begin_inset Quotes eld
1440 \begin_inset Quotes erd
1443 characters form the en-dash.
1445 \begin_inset Quotes eld
1453 \begin_inset Quotes erd
1456 characters create an em-dash, which is slightly longer than the en-dash.
1457 In the printed version of any document, LyX will combine the two or three
1459 \begin_inset Quotes eld
1467 \begin_inset Quotes erd
1470 characters into a single, unbroken line.
1474 \begin_layout Section
1475 Cross-References and Labels
1478 \begin_layout Standard
1479 Use the following labelling conventions:
1483 \labelwidthstring 00.00.0000
1484 sec:xxx Use this for
1504 \labelwidthstring 00.00.0000
1505 eqn:xxx Use this for Equations, should you need to create any.
1509 \labelwidthstring 00.00.0000
1510 tbl:xxxx Use this for tables inside of a table float.
1514 \labelwidthstring 00.00.0000
1515 fig:xxx Use this for figures inside of figure floats.
1518 \begin_layout Standard
1519 Additionally, you should put the label at one of two locations:
1522 \begin_layout Enumerate
1525 beginning of the paragraph
1527 , after a section heading, or at the beginning of captions, etc.
1528 It should be the first thing on the first line.
1529 Don't put a space betweeen it and the first word.
1532 \begin_layout Enumerate
1533 If there is no paragraph after a section heading, put it at the
1535 end of the last line.
1542 \begin_layout Standard
1547 which is immediately followed by a
1552 This is a case where you need to put the label at the end of the
1557 I know it looks ugly; not much we can do about that, though.
1561 \begin_layout Section
1562 Content --- What Goes Where
1565 \begin_layout Standard
1570 important to anyone documenting a new feature.
1571 If you need to add new documentation, pay attention.
1575 \begin_layout Standard
1576 In the dim and distant past, whenever someone wanted to document a new feature
1577 they added, they either wrote a mini-doc and stuck it into the documentation
1578 directory, or they added a new section to the lone manual.
1579 No one paid much attention to organization in those days, either.
1580 The result was a totally bloated, totally unnavigable, and incomplete manual
1581 orbitted by a swarm of tiny, incomplete mini-docs.
1582 I don't want the docs to fall back into that mess.
1585 \begin_layout Standard
1586 With that in mind, I have some instructions for how to keep things organized:
1590 \labelwidthstring 00.00.0000
1595 Please, don't touch this file.
1596 It's essentially complete, anyhow.
1597 Only the editor(s) should make changes to this, as this file contains info
1598 about how to contribute to the doc project.
1599 That's really the only stuff that should need to change, and even then,
1600 only when a new maintainer comes along.
1604 \labelwidthstring 00.00.0000
1609 This file is complete.
1610 Any changes should be for updates
1615 DO NOT ADD new features to here willy-nilly.
1616 Let the editor decide if --- and when --- new sections go in here.
1617 Place any new features in\SpecialChar \ldots{}
1622 \labelwidthstring 00.00.0000
1627 This is where all new features go from now on.
1628 It's in the style of a bound journal --- each section is an
1629 \begin_inset Quotes eld
1633 \begin_inset Quotes erd
1636 from the author of the feature.
1637 Also, anyone who writes a
1641 file for a new document class should write a section describing that new
1642 class and how to use it.
1643 That also goes here.
1647 \begin_layout Standard
1648 Note, however, that you are
1652 excused from following this Style Sheet just because the sections of
1656 are in the form of a journal article.
1661 \labelwidthstring 00.00.0000
1666 This file is complete.
1667 Do not change or add to without permission of the Documenation Project
1672 \labelwidthstring 00.00.0000
1677 This document describes advanced features, most of which alter the look,
1678 feel, and behavior of LyX.
1679 This manual is still a bit incomplete, although that may change soon.
1680 Check for updates often.
1684 \begin_layout Standard
1685 If you are unsure whether or not something belongs in
1689 , then, most-likely, it
1698 Again, let the current editor of the LyX documentation decide if your new
1699 section should be migrated to
1708 \labelwidthstring 00.00.0000
1713 I'd prefer to completely finish this one before doing anything else, but
1715 LyX keeps changing so much that I think the
1719 will be the last one completed.
1720 However, I'd like it if the developer's would add entries anytime they
1721 create a new function or popup.
1722 That would help things immensely!
1726 \begin_layout Standard
1731 follows this Style Sheet for the most part.
1732 There are, however, additional rules to follow when making new entries.
1733 At the top of this manual, there are examples of and a template for
1742 \begin_layout Section
1743 Writing Style: The Primary Manuals
1746 \begin_layout Standard
1747 While I want to make contributing to the Documentation Project as painless
1748 as possible for newcomers, I also want the newcomers to be painless on
1749 the existing Documentation Team! Ergo, I've written this section to give
1750 some flavor to guide everyone's individual style.
1754 \begin_layout Subsection
1758 \begin_layout Standard
1759 All contributions to the
1763 LyX documentation must be in English.
1764 I don't care if it's British, Australian, or American English.
1765 The DocTeam editor will proofread for glaring mistakes and fix them.
1768 \begin_layout Standard
1769 Don't get hung up on semantics.
1770 English is a flexible language, and just because your Mothertongue-to-English
1771 dictionary gives only one translation for a word doesn't necessarily mean
1773 We've had some discussions and misunderstandings on the Developers' List
1774 because of this very problem.
1775 If something is unclear (or just plain weird) due to a translation problem,
1776 one of the American/British/Australian developers can fix it.
1779 \begin_layout Standard
1784 documentation, I exclude the translations.
1785 We usually don't have enough people to cover the manuals in one language,
1786 let alone more than one.
1787 Subsequently, the tranlsations are just that --- translations of the English
1788 version of the LyX manuals.
1789 The translation efforts require have their own set of guidelines.
1791 \begin_inset LatexCommand \ref{sec:translations}
1798 \begin_layout Subsection
1801 Commentary from the Author (i.\InsetSpace ~
1805 \begin_layout Standard
1806 \begin_inset LatexCommand \label{sec:author-notes}
1810 I want to make it easy for everyone when it comes to documenting things.
1811 Some features are incomplete.
1812 Some, you might not know everything about.
1813 Sometimes, you may want to comminucate something to me or the reader or
1814 other DocTeam members.
1815 Sometimes, you may want to
1816 \begin_inset Quotes eld
1820 \begin_inset Quotes erd
1823 you want to say something that is your personal opinion and using
1824 \begin_inset Quotes eld
1828 \begin_inset Quotes erd
1831 would be inappropriate.
1834 \begin_layout Standard
1835 In short, when you contribute to the LyX Docs, you wear many hats.
1838 \begin_layout Standard
1839 For occasions when you need to switch hats, I've designed some special mechanism
1843 \begin_layout Subsubsection
1844 Personal\InsetSpace ~
1846 \begin_inset Quotes eld
1850 \begin_inset Quotes erd
1856 \begin_layout Standard
1857 These are footnotes.
1858 They begin with the following:
1869 \begin_layout Standard
1870 \SpecialChar \ldots{}
1875 for the person's name and without the quotes.
1876 The rest of the footnote is the actual comment.
1880 \begin_layout Standard
1881 Use these when you need to quote a comment by someone (usually yourself),
1882 and need to identify that person.
1883 This includes occasions when you need wear the
1884 \begin_inset Quotes eld
1888 \begin_inset Quotes erd
1891 hat, i.\InsetSpace ~
1893 to speak for yourself instead of for the LyX Team.
1896 \begin_layout Standard
1897 If the comment is too large to put in a footnote, don't use a Personal Note.
1898 When quoting more than about 3 sentences or 5 lines of text, use a bona
1900 Don't use any leading
1901 \begin_inset Quotes eld
1909 \begin_inset Quotes erd
1913 In a real quote, you'll give credit to the original speaker in either the
1914 paragraph before or after the body of the
1921 \begin_layout Subsubsection
1922 Author's\InsetSpace ~
1924 \begin_inset Quotes eld
1928 \begin_inset Quotes erd
1934 \begin_layout Standard
1935 There will be times when you are not speaking for the LyX Team, yet you
1936 are not entirely speaking for yourself.
1937 Instead, you are speaking on behalf of the manual itself, as the author
1939 Some examples of when you might need to do this are:
1942 \begin_layout Itemize
1943 You need to contradict something you just wrote because the feature isn't
1944 quite ready yet, but you wanted to document what it will do.
1947 \begin_layout Itemize
1948 You need to leave a note for yourself.
1951 \begin_layout Itemize
1952 You need to leave a note for the editor or the other DocTeam members.
1955 \begin_layout Itemize
1956 You need to point out something about the manuals to the reader, something
1957 that doesn't fit into the context of the current paragraph.
1960 \begin_layout Standard
1961 At such times, you are wearing your
1962 \begin_inset Quotes eld
1966 \begin_inset Quotes erd
1972 \begin_layout Standard
1973 The typography for an
1974 \begin_inset Quotes eld
1978 \begin_inset Quotes erd
1984 \begin_layout Itemize
1985 They go in the body of the text, in brackets,
1986 \begin_inset Quotes eld
1990 \begin_inset Quotes erd
1993 , not any other form of parentheses.
1994 The bracket are in the default character style.
1997 \begin_layout Itemize
1998 The text of the note itself, however, is emphasized.
2002 \begin_layout Itemize
2003 Begin with the words,
2004 \begin_inset Quotes eld
2012 \begin_inset Quotes erd
2015 and end with an em-dash,
2016 \begin_inset Quotes eld
2020 \begin_inset Quotes erd
2023 , followed by your initials.
2027 \begin_layout Standard
2028 Here's an example: [
2030 Author's Note: This is an example note.
2036 \begin_layout Standard
2037 The form of the Author's Note, by the way, isn't a suggestion or request.
2043 All Author's Notes must begin with this text, verbatim:
2044 \begin_inset Quotes eld
2052 \begin_inset Quotes erd
2057 \begin_inset Quotes eld
2061 \begin_inset Quotes erd
2064 are or any other variant are forbidden.
2065 The Author's Note must end with an em-dash, which is 3
2066 \begin_inset Quotes eld
2070 \begin_inset Quotes erd
2074 \begin_inset Quotes eld
2078 \begin_inset Quotes erd
2083 \begin_inset Quotes eld
2087 \begin_inset Quotes erd
2090 ; you must use 3 (and 5 is right out).
2093 \begin_layout Standard
2094 \begin_inset Quotes eld
2098 \begin_inset Quotes erd
2101 are inherently transient, and should disapear as a manual matures.
2104 \begin_layout Subsubsection
2108 \begin_layout Standard
2109 You are also free to use footnotes on their own in addition to the Personal
2110 Notes and/or Author's Notes.
2111 I've frequently used footnotes to \SpecialChar \ldots{}
2112 well, to comment on parts of a section
2113 without putting the commentary into the body of the text.
2116 \begin_layout Paragraph*
2117 Mixing Footnotes and Personal Notes
2120 \begin_layout Standard
2121 Personal Notes always go in footnotes, and should be 5 lines or fewer.
2122 Any larger quotation should be quoted properly, using the rules of standard
2128 paragraph environment.
2131 \begin_layout Paragraph*
2132 Mixing Footnotes and Author's Notes
2135 \begin_layout Standard
2136 Author's Notes should
2144 \begin_layout Paragraph*
2145 Mixing Personal Notes and Author's Notes
2148 \begin_layout Standard
2149 Forbidden; these two are mutually exclusive.
2152 \begin_layout Subsubsection
2156 \begin_layout Itemize
2163 opinion --- yours or another LyX developer's --- about anything.
2164 Anywhere in the manuals you wish to speak for yourself instead the the
2166 If you have a long rant, however, quote yourself (see section\InsetSpace ~
2168 \begin_inset LatexCommand \ref{sec:quote}
2175 \begin_layout Itemize
2178 Use this to describe things in LyX (or the manuals) that may
2179 change in the future or are somehow incomplete.
2180 Author's Notes are supposed to disappear as a manual matures.
2183 \begin_layout Itemize
2186 Used for text fragments that almost fit into the flow of
2187 the text\SpecialChar \ldots{}
2191 \begin_layout Standard
2192 When using these three mechanisms, in addition to rigorously following their
2193 descriptions, please use them properly.
2194 I listed some additional restrictions previously.
2195 Some of you may balk at these restrictions.
2196 Nevertheless, there is a reason for them: if you have an overwhemling desire
2197 to mix or modify footnotes, Personal Notes, and Author's Notes, you shouldn't
2198 be using any of them.
2199 More specifically, you're trying to use a hammer to drive in a screw.
2200 What you want to say probably needs to go into the main body of the text.
2203 \begin_layout Subsection
2204 General Stylistic Guidelines
2207 \begin_layout Standard
2208 Everything in this section is
2210 mandatory to all documenters
2212 , regardless the language you're writing in.
2216 \begin_layout Subsubsection
2220 \begin_layout Enumerate
2221 Use the typography rules outlined in the beginning sections of this document.
2224 \begin_layout Enumerate
2225 Don't, however, mimic the typography of this file.
2226 Yes, the Style Sheet doesn't follow the Style Sheet (grin).
2229 \begin_layout Enumerate
2230 There is some typographic freedom in those rules in earlier sections.
2231 Use that freedom wisely.
2232 Most importanly, never sacrifice the online appearance for the printed
2233 appearance and vice versa.
2237 \begin_layout Standard
2238 An example is in the
2243 There is a footnote using the
2247 command to divide a long
2251 environment into 3 columns.
2252 It adds some LaTeX commands to the online version, the so-called
2253 \begin_inset Quotes eld
2257 \begin_inset Quotes erd
2260 that some so vehemently oppose.
2261 Without it, however, that footnote takes up over two pages, most of which
2263 This is an example of permitting a little ugliness in the online version
2264 to get the printed version to look right.
2268 \begin_layout Enumerate
2269 When in doubt, compromise.
2273 \begin_layout Standard
2274 When in doubt, use good judgement.
2278 \begin_layout Subsubsection
2282 \begin_layout Enumerate
2284 \begin_inset Quotes eld
2288 \begin_inset Quotes erd
2295 \begin_layout Standard
2296 When you speak, you speak for the entire LyX Team, so use
2297 \begin_inset Quotes eld
2301 \begin_inset Quotes erd
2305 \begin_inset Quotes eld
2309 \begin_inset Quotes erd
2316 \begin_layout Enumerate
2318 \begin_inset Quotes eld
2322 \begin_inset Quotes erd
2329 \begin_layout Standard
2330 Whenever you want to say something to the reader, use
2331 \begin_inset Quotes eld
2335 \begin_inset Quotes erd
2338 not some contorted construction to avoid being too informal.
2343 \begin_layout Enumerate
2345 \begin_inset Quotes eld
2349 \begin_inset Quotes erd
2352 for both the physical pointing object (mouse, joystick, touch pad, track
2353 ball, etc.) and the mouse cursor which the physical object moves about the
2357 \begin_layout Enumerate
2359 \begin_inset Quotes eld
2363 \begin_inset Quotes erd
2366 for the little blinking vertical bar that indicates where text can/will
2370 \begin_layout Enumerate
2371 When in doubt, compromise.
2375 \begin_layout Standard
2376 When in doubt, use good judgement.
2380 \begin_layout Subsubsection
2381 \begin_inset LatexCommand \label{sec:quote}
2385 Quoting Yourself and Others
2388 \begin_layout Standard
2389 In some cases, you'll have something to say, an opinion of yours.
2390 Since this is your opinion, you're not speaking for the LyX Team.
2391 You have so much to say, in fact, that it won't fit into a Personal Note
2392 or an Author's Note.
2393 In these cases you want to quote yourself.
2396 \begin_layout Standard
2397 Any time you wish to quote someone, be it yourself or someone else, there
2398 are standard rules one follows.
2399 Every language has its own rules.
2400 You should follow the rules that apply to the language of the document
2401 to which you are contributing.
2405 \begin_layout Standard
2406 This creates a problem for the primary documentation.
2407 The primary documentation is written in English, yet the contributors come
2408 from many countries.
2409 The quoting rules for English (well, American English, at least) are outlined
2415 , for your convenience.
2416 Read them if you need to.
2419 \begin_layout Standard
2420 \begin_inset Float figure
2426 \begin_layout Standard
2427 Quoting rules for English:
2430 \begin_layout Itemize
2431 The body of the quote belongs in a
2438 \begin_layout Itemize
2439 The sentences prior to the quote should flow logically and smoothly into
2443 \begin_layout Itemize
2444 The sentences immediately following the quote should continue the flow of
2448 \begin_layout Itemize
2453 credit the original author of the quote in the sentences immediately before
2457 \begin_layout Itemize
2458 Crediting the original author of the quote should not, however, disrupt
2459 the flow of the text.
2462 \begin_layout Itemize
2463 If you omit text from the beginning of the first sentence in the quote,
2464 the quote must start with the text
2465 \begin_inset Quotes eld
2468 [\SpecialChar \ldots{}
2470 \begin_inset Quotes erd
2474 This is an ellipsis in square brackets.
2477 \begin_layout Itemize
2478 If you omit text from the end of the last sentence in the quote, the quote
2479 must end with the text
2480 \begin_inset Quotes eld
2483 [\SpecialChar \ldots{}
2485 \begin_inset Quotes erd
2488 followed by the sentence's punctuation mark.
2491 \begin_layout Itemize
2492 If you omit any text from the middle of the quote, be it whole sentences
2493 or parts of sentences, replace it with the text
2494 \begin_inset Quotes eld
2497 [\SpecialChar \ldots{}
2499 \begin_inset Quotes erd
2505 \begin_layout Itemize
2506 The quote must be grammatically correct.
2511 \begin_layout Itemize
2512 If the original is wrong, you must correct it.
2515 \begin_layout Itemize
2516 If omitting part of the quote
2517 \begin_inset Quotes eld
2521 \begin_inset Quotes erd
2524 it, you must correct the problem.
2527 \begin_layout Itemize
2528 For missing words (e.\InsetSpace ~
2531 \begin_inset Quotes eld
2535 \begin_inset Quotes erd
2538 goes missing), place the word in square brackets,
2539 \begin_inset Quotes eld
2542 [\SpecialChar \ldots{}
2544 \begin_inset Quotes erd
2547 and insert in the quote where needed.
2550 \begin_layout Itemize
2551 For mangled word order, correct the mangled text, following it with the
2553 \begin_inset Quotes eld
2557 \begin_inset Quotes erd
2564 \begin_layout Itemize
2565 Spelling in the quote must be correct.
2566 Correct any misspelled words and place the text
2567 \begin_inset Quotes eld
2571 \begin_inset Quotes erd
2574 after the corrected word.
2577 \begin_layout Itemize
2578 Back-to-back bracket blocks merge together.
2580 \begin_inset Quotes eld
2583 [\SpecialChar \ldots{}
2585 \begin_inset Quotes erd
2590 \begin_inset Quotes eld
2593 [\SpecialChar \ldots{}
2595 \begin_inset Quotes erd
2601 \begin_layout Itemize
2602 If you correct the spelling in 2 or more consecutive words, you can get
2604 \begin_inset Quotes eld
2608 \begin_inset Quotes erd
2611 after the last mistake.
2619 \begin_layout Subsubsection
2623 \begin_layout Standard
2624 When describing a new feature or
2631 \begin_layout Enumerate
2642 \begin_inset Quotes eld
2645 Keep It Short and Sweet
2646 \begin_inset Quotes erd
2650 \begin_inset Quotes eld
2653 Keep It Simple, Stupid!
2654 \begin_inset Quotes erd
2661 \begin_layout Itemize
2666 write paragraph after paragraph of verbage.
2670 \begin_layout Itemize
2674 \begin_layout Itemize
2675 Take a look at the manual for a commercial word processor --- it's a fine
2680 to write documentation.
2681 It's all pithy, substanceless verbage, and its
2689 \begin_layout Enumerate
2690 Avoid being pedantic like The Plague!
2693 \begin_layout Enumerate
2694 In the same vein, don't write more than you have to.
2695 You're not working in a vacuum --- refer freely to other parts of the manual
2696 (and other parts of other manuals).
2698 \begin_inset Quotes eld
2701 other part of the manual
2702 \begin_inset Quotes erd
2705 is incomplete or empty, refer to it.
2706 Someone will fill it in eventually.
2709 \begin_layout Enumerate
2710 On the other hand, BE THOROUGH!
2714 \begin_layout Enumerate
2719 , not widgets, not how the source code is organized.
2722 \begin_layout Enumerate
2723 Group by feature, not by widget.
2726 \begin_layout Enumerate
2727 Stay on topic --- one
2740 s and further subdivisions to group things if you're documenting several
2741 related features in a single
2748 \begin_layout Enumerate
2749 Describe EVERYTHING related to that feature, no matter where it is.
2753 \begin_layout Enumerate
2754 Example: Paragraph Indenting.
2755 Several popups control its behavior.
2760 of this: which popups control it, when you use which setting on which popup
2761 to do which operation, et cetera.
2764 \begin_layout Enumerate
2771 I've had people only document one popup --- literally.
2772 This added off-topic information and only described half of the feature,
2773 since other menus, popups, and even unbound functions contained additional
2780 cranky when that happens, because it means
2785 Bad help is worse than no help at all.
2789 \begin_layout Standard
2790 These remarks still hold true: you'll piss of the DocTeam editor if you
2791 do things wrong, because he'll have to fix your mistakes.
2796 \begin_layout Enumerate
2797 Remember, there are people who will reference
2801 section, just as you're referencing someone else's.
2802 You do want what you write to be useful, don't you?
2806 \begin_layout Enumerate
2807 When in doubt, compromise.
2811 \begin_layout Standard
2812 When in doubt, use good judgement.
2816 \begin_layout Subsubsection
2821 Treat the Reader as if She is Stupid
2824 \begin_layout Enumerate
2828 \begin_layout Enumerate
2829 No talking down to the reader.
2832 \begin_layout Enumerate
2833 The reader is smart enough to know what a mouse is.
2836 \begin_layout Enumerate
2837 The reader is smart enough to know how to use a keyboard, including the
2851 (The introduction of most of the manuals takes care of the
2852 \begin_inset Quotes eld
2864 \begin_inset Quotes erd
2867 issue, so you don't need to.)
2870 \begin_layout Enumerate
2871 The reader is smart enough to know that
2872 \begin_inset Quotes eld
2876 \begin_inset Quotes erd
2880 \begin_inset Quotes eld
2883 where the text cursor is sitting right now, in the buffer currently visible.
2884 \begin_inset Quotes erd
2889 (Anything more than the word
2890 \begin_inset Quotes eld
2894 \begin_inset Quotes erd
2897 is, IMO, superfluous and wll be deleted .
2898 So, save yourself the typing, save the editor the cutting, and save the
2899 reader the strain of sifting through extra verbage that adds no content.)
2902 \begin_layout Enumerate
2903 Rule of thumb: the reader is not an imbecile.
2904 The reader is merely lost; point them in the right direction, and they
2905 can take it from there.
2908 \begin_layout Subsection
2909 Tips for the English Version
2912 \begin_layout Standard
2913 \begin_inset LatexCommand \label{sec:english-only}
2917 When contributing to the primary --- i.\InsetSpace ~
2919 the English language version ---
2920 of the LyX manuals, keep the following in mind.
2923 \begin_layout Subsubsection
2924 Write as if You're Talking with a Friend.
2928 \begin_layout Enumerate
2929 Think that way when you write.
2930 Play the dialogue in your mind.
2933 \begin_layout Enumerate
2934 Be as informal as you please (without being rude).
2937 \begin_layout Subsubsection
2938 AVOID the Passive Voice
2941 \begin_layout Enumerate
2943 \begin_inset Quotes eld
2946 It is felt that this name best explains the command's purpose.
2947 \begin_inset Quotes erd
2950 We know full well who wrote the command:
2951 \begin_inset Quotes eld
2954 The LyX Team felt ...
2955 \begin_inset Quotes erd
2959 \begin_inset Quotes eld
2963 \begin_inset Quotes erd
2969 \begin_layout Enumerate
2970 Things don't happen by magic - somebody or something did it.
2971 Only politicians use the passive voice to cover up who did something.
2972 If LyX reformats a paragraph, write,
2973 \begin_inset Quotes eld
2976 LyX reformatted the paragraph.
2977 \begin_inset Quotes erd
2984 makes changes, write,
2985 \begin_inset Quotes eld
2992 changes the document.
2993 \begin_inset Quotes erd
3000 \begin_layout Standard
3001 Rule of thumb: any sentence you can express as,
3002 \begin_inset Quotes eld
3006 \begin_inset Quotes erd
3010 \begin_inset Quotes eld
3014 \begin_inset Quotes erd
3021 \begin_layout Enumerate
3023 We all hear way, way too much garbage English on the TV every day in the
3025 Some people think it makes speech better.
3027 It makes speech baroque, if not outright byzantine.
3028 With a little effort, you can wean yourself off of it.
3031 \begin_layout Enumerate
3034 will make you rewrite
3036 anything in the passive voice.
3037 It's awkward and hard to read.
3040 \begin_layout Enumerate
3041 Note to non-Americans:
3045 \begin_layout Standard
3046 Using passive voice is generally considered bad style in the U.\InsetSpace ~
3049 too easy to obfuscate your words with it.
3050 It also bloats sentences, often unnecessarily.
3054 \begin_layout Subsubsection
3059 \begin_layout Standard
3060 In English, there is a grammatical error known as the
3061 \begin_inset Quotes eld
3065 \begin_inset Quotes erd
3068 The classic example of a run-on sentence is 7 clauses strung together with
3070 \begin_inset Quotes eld
3074 \begin_inset Quotes erd
3077 There are, however, less obvious run-on sentences, ones using too many
3078 subordinate clauses.
3079 Such sentences may look elegant because they are complex.
3080 However, they are also extremely difficult to read because they are so
3084 \begin_layout Standard
3085 In general, stick to short sentences in written English.
3086 Getting rid of passive voice (
3087 \begin_inset Quotes eld
3090 \SpecialChar \ldots{}
3091 was done by\SpecialChar \ldots{}
3093 \begin_inset Quotes erd
3096 ) shortens and simplifies them.
3097 Hacking apart sentences with many dependent clauses is another way to shorten
3099 There are ways to do this yet still have a smooth-flowing paragraph.
3102 \begin_layout Standard
3103 While I'm talking about paragraphs, I'll apply the
3104 \begin_inset Quotes eld
3108 \begin_inset Quotes erd
3111 motto to them, as well.
3112 At the time I started with the manuals (and this Style Sheet), I didn't
3113 pay too much attention to paragraph size.
3114 I've since become a big proponent of short paragraphs, with one idea per
3116 While long, flowing, multi-concept paragraphs can be nice in novels, we're
3118 Our goal is rapid information location and comprehension, not a literary
3122 \begin_layout Standard
3123 There is a single exception to the short sentence, short paragraph rule.
3124 Particularly complex ideas may need more
3125 \begin_inset Quotes eld
3129 \begin_inset Quotes erd
3132 However, you shouldn't encounter such complex ideas often when documenting
3134 Try to keep things short, and use your judgement as needed.
3137 \begin_layout Standard
3138 To reiterate, yet again, something I said before:
3142 When in doubt, compromise.
3146 When in doubt, use good judgement.
3149 \begin_layout Standard
3150 Hopefully, you've got the idea (grin).
3153 \begin_layout Section
3157 \begin_layout Subsection
3158 Rules of the Translating Trade
3161 \begin_layout Standard
3162 While translating anything, there are certain
3163 \begin_inset Quotes eld
3167 \begin_inset Quotes erd
3171 They will help you greatly.
3174 \begin_layout Subsubsection
3175 Translate one paragraph at a time.
3178 \begin_layout Standard
3179 Most people translate word by word.
3180 Clearly, you lose all context if you do that.
3181 A word may have multiple meanings.
3182 You can't tell which unless you look at the rest of the sentence.
3185 \begin_layout Standard
3186 There is another level to the context issue, however.
3187 Your dictionary may translate multiple English words the same way.
3188 All those words mean
3193 Each one, however, covers a different shade of meaning, a different mood
3195 It is often difficult to resolve those shades of meaning in the context
3196 of even one sentence.
3197 A paragraph, however, will provide that context.
3200 \begin_layout Subsubsection
3201 You will not translate it correctly on the first try.
3204 \begin_layout Standard
3205 Alright, I admit that you may be able to translate some of the sentences
3207 If you know a language well, you may even understand over half of the text.
3208 Nevertheless, overconfidence can lead you astray.
3209 There will be some sentences, no matter how few, that will simply confound
3213 \begin_layout Standard
3214 It is generally a good idea to make multiple passes over a paragraph you're
3216 Even if you translate the entire paragraph on the first pass, make a second
3218 You'll often improve upon your first attempt.
3221 \begin_layout Subsubsection
3222 When in doubt, write down all of the meanings for a word.
3225 \begin_layout Standard
3226 You can often translate tricky parts of a text using the context of the
3227 surrounding sentences.
3228 So, if you hit a word or phrase you don't know, translate it more than
3230 Picking the most likely translations, summarize them in one to three words
3232 \begin_inset Quotes eld
3236 \begin_inset Quotes erd
3243 \begin_layout Subsubsection
3244 Using context, fix the meanings on the next pass.
3247 \begin_layout Standard
3248 This is where your multiple translations of a single word become useful.
3249 Using the other sentences you translated, you can now translate that mystery--s
3250 entence without reconsulting your dictionary.
3253 \begin_layout Subsubsection
3254 Fix the grammar only after you've finished translating the sentence.
3257 \begin_layout Standard
3258 If there's a mystery phrase in the middle of a sentence, you can't translate
3259 the entire sentence.
3260 Why grammatically rearrange the words you translated already? You may need
3261 to restructure the sentence a second time once you figure out how to translate
3262 that mystery phrase.
3263 Better to wait until you've completely translated the sentence to clean
3265 That way, you do so only once.
3268 \begin_layout Subsubsection
3269 If you can't translate it, skip it and come back to it on the next pass.
3272 \begin_layout Standard
3273 Remember the earlier discussion of context and its immense usefulness? There
3274 is no sin in making multiple passes over a tricky passage.
3277 \begin_layout Subsubsection
3278 Translate the meaning first.
3282 \begin_layout Standard
3283 The information content of the text under translation is the most important
3285 This is especially important for a manual, where the information
3289 important part of the original document.
3290 Lose that, and you lose the very point of performing the translation.
3293 \begin_layout Subsection
3294 Tips for the Translators
3297 \begin_layout Standard
3298 Those of you contributing to a translation of the LyX manuals must follow
3299 a modified set of rules.
3300 The first few rules are analogous to those in section\InsetSpace ~
3302 \begin_inset LatexCommand \ref{sec:english-only}
3307 There are additional rules and regulations that follow those first few.
3311 \begin_layout Subsubsection
3312 Write as if you are explaining LyX to a colleague you know well.
3315 \begin_layout Enumerate
3316 Think that way when you write.
3317 Play the dialogue in your mind.
3320 \begin_layout Enumerate
3321 Use a conversational style in your writing.
3322 Pretend you are teaching LyX to a colleague you know well.
3325 \begin_layout Enumerate
3326 Use a style that is polite without being too formal.
3327 If, in your culture, informal language is appropriate to use with a colleague,
3328 use informal speech in the translation of the manual.
3331 \begin_layout Subsubsection
3332 AVOID Snobby, Academic, Specialized, or
3333 \begin_inset Quotes eld
3337 \begin_inset Quotes erd
3344 \begin_layout Standard
3345 In English, the passive voice appears formal, dry, barren.
3346 It also often adds unnecessary complexity.
3347 In other langauges, however, this is not the case.
3348 There is nothing wrong with passive voice, and people use it frequently
3349 in everyday conversation.
3350 Nevertheless, your translation of the LyX manuals must avoid
3351 \begin_inset Quotes eld
3355 \begin_inset Quotes erd
3361 \begin_layout Standard
3362 In Germany, there is a magazine known as
3363 \begin_inset Quotes gld
3367 \begin_inset Quotes grd
3370 The writing in it is so complex, it is extremely difficult for non-native
3371 German speakers to understand.
3372 While sophisticated, the writing style of
3373 \begin_inset Quotes gld
3377 \begin_inset Quotes grd
3380 is not what a German uses in everyday conversation.
3381 Nor is the writing style for a Russian mathematics journal.
3382 Such specialized or overly-sophisticated styles are
3383 \begin_inset Quotes eld
3387 \begin_inset Quotes erd
3390 in the sense that they are seldom used by normal people in everyday speech.
3393 \begin_layout Standard
3394 We who write the LyX manuals, original or translated, seek to
3399 If we write in a style only a few people use, and use seldomly, we will
3401 Use a writing style that mirrors everyday speech (without being vulgar,
3406 \begin_layout Subsubsection
3407 Keep the Writing Simple.
3410 \begin_layout Standard
3411 For the English version, I wrote,
3412 \begin_inset Quotes eld
3415 Use short sentences and short paragraphs.
3416 \begin_inset Quotes erd
3419 What if, however, short sentences and paragraphs are something only children
3420 use in your language? What if, in yet another language, short sentences
3421 imply rudeness? Naturally, you would not want to use them in your translation.
3424 \begin_layout Standard
3425 Nevertheless, the translations of the LyX manuals should be as clear as
3427 So, for our international colleagues, we apply this rule: Keep your sentences
3428 and paragraphs as short as makes sense.
3431 \begin_layout Standard
3432 Remember: we're translating manuals here, folks.
3433 Our goal is rapid information location and comprehension, not a literary
3435 Try to keep your writing concise yet smooth-flowing.
3436 And use your judgement as needed:
3440 When in doubt, compromise.
3444 When in doubt, use good judgement.
3447 \begin_layout Subsubsection
3448 Translators must follow the Style Sheet, too!
3451 \begin_layout Standard
3452 Everything in this manual ---
3454 except section\InsetSpace ~
3456 \begin_inset LatexCommand \ref{sec:english-only}
3462 --- applies to every LyX documenter, no matter what the language.
3465 \begin_layout Subsubsection
3466 Translators must read the Style Sheet Supplement for their language.
3469 \begin_layout Standard
3470 For every translation project, there is a Supplement to the Style Sheet.
3477 DocStyle_Supplement_<cn>.lyx
3480 \begin_layout Standard
3481 \SpecialChar \ldots{}
3483 \begin_inset Quotes eld
3491 \begin_inset Quotes erd
3494 is your language's two-letter locale code.
3495 The Translation Project Chief for your language wrote this.
3496 If he hasn't, pester him to do so! <
3503 \begin_layout Subsubsection
3504 The English versions of the manuals are not Sacred Text.
3507 \begin_layout Standard
3508 You do not need to translate everything word for word.
3509 In fact, you shouldn't.
3510 Keep to the spirit of the originals, not the letter.
3511 Be as creative as you want, as long as you
3519 convey all of the information contained in the English versions.
3522 \begin_layout Subsubsection
3523 Any information in the LyX manuals must also be in the translations.
3526 \begin_layout Standard
3527 \begin_inset LatexCommand \label{sec:accuracy}
3531 This falls under translating the orignals accurately and completely.
3535 \begin_layout Itemize
3536 Omitting any feature description is
3543 \begin_layout Itemize
3544 Misrepresenting or misdescribing any LyX feature or operation
3551 \begin_layout Itemize
3556 outpace the original.
3558 If no one has documented new feature in the primary
3559 LyX manuals (i.\InsetSpace ~
3561 the English versions), do not do so in the translations.
3562 If you're really looking for something to do, either:
3566 \begin_layout Itemize
3567 \SpecialChar \ldots{}
3568 focus on translating something you haven't yet,
3573 \begin_layout Itemize
3574 \SpecialChar \ldots{}
3575 update or repair the primary manual.
3578 \begin_layout Standard
3579 If you cannot or do not want to do one of the above, then take a break.
3581 Wait for the main manuals to catch up before translating anything else.
3585 \begin_layout Subsubsection
3586 What you cannot translate, you may omit (usually).
3589 \begin_layout Standard
3590 Prepositions, idioms, metaphors, slang, Oh My! There's a jungle of potentially
3591 untranslatable text you may face.
3592 Happily, none of these untranslatables are essential to the original text\SpecialChar \ldots{}
3595 If you can't translate a phrase or two, try omitting them.
3596 If the rest of the paragraph still makes sense, then don't worry about
3600 \begin_layout Standard
3601 There may be special cases where omitting part of a sentence or paragraph
3602 violates rule\InsetSpace ~
3604 \begin_inset LatexCommand \ref{sec:accuracy}
3613 You must try and translate those tricky spots.
3616 \begin_layout Subsubsection
3617 Translators may add their own fluff to the information content.
3620 \begin_layout Standard
3621 After you do strip away all of the idioms, metaphors, slang, humor, and
3623 \begin_inset Quotes eld
3627 \begin_inset Quotes erd
3630 you may find that your translated manual is dull and dry.
3631 Why not add your own fluff? Add text that makes the manual a pleasure to
3632 read, that engages the reader.
3633 It may take the form of humor, or metaphors, or sayings.
3634 Whatever you add, it should be
3635 \begin_inset Quotes eld
3639 \begin_inset Quotes erd
3642 It should not clash with the explanation of LyX features and functions.
3645 \begin_layout Subsection
3646 For Translation Project Chiefs
3649 \begin_layout Subsubsection
3650 The First Is In Charge
3653 \begin_layout Standard
3654 If you were the first person to start translating the manuals, you're the
3655 LyXDoc Translation Project Chief for your language.
3660 person translating the LyXDocs, that automatically makes you the Translation
3664 \begin_layout Standard
3665 Amongst other things, that means that you must read this section and perform
3666 the tasks described here.
3669 \begin_layout Standard
3670 If you are a member of a LyX Documentation Translation Team, but
3674 its Chief, you may stop reading.
3675 The remainder of this section will be of no interest to you.
3676 If you came to the Style Sheet from the Supplement for your language, you
3680 \begin_layout Standard
3681 If you have not read the Style Sheet Supplement for your language, you should
3686 \begin_layout Subsubsection
3687 Read the Style Sheet
3690 \begin_layout Standard
3691 No documenter is excused from following the Style Sheet, not even a Translation
3695 \begin_layout Standard
3700 important that the Translation Project Chiefs read the Style Sheet.
3703 \begin_layout Subsubsection
3704 Make your translators read the Style Sheet
3707 \begin_layout Standard
3708 No documenter is excused from following the Style Sheet.
3711 \begin_layout Standard
3712 Since your translation team is translating, they know
3717 Therefore, they should be able to read the Style Sheet.
3720 \begin_layout Subsubsection
3722 \begin_inset Quotes eld
3726 \begin_inset Quotes erd
3732 \begin_layout Standard
3733 There are parts of this Style Sheet that are English-specific.
3734 I have tried to provide a general, language-independent description of
3735 certain details in this section.
3736 Unfortunately, that general description doesn't cover the specifics of
3741 \begin_layout Standard
3742 That's where you, as head of a LyXDoc Translation Team, come in.
3745 \begin_layout Standard
3746 Every Translation Team Chief is
3750 to write a Supplement to the official Documentation Style Sheet, with specifics
3751 issues affecting your language.
3752 (You are, after all, the LyX Team expert on your native tongue.) Follow
3753 these guidelines when writing the Supplement:
3756 \begin_layout Enumerate
3761 DocStyle_Supplement_<cn>.lyx
3765 \SpecialChar \ldots{}
3767 \begin_inset Quotes eld
3775 \begin_inset Quotes erd
3778 is the two-letter code for your language.
3779 This is the same two-letter code that is part of the filenames for the
3782 \begin_inset Quotes eld
3790 \begin_inset Quotes erd
3794 \begin_inset Quotes eld
3802 \begin_inset Quotes erd
3806 \begin_inset Quotes eld
3814 \begin_inset Quotes erd
3820 \begin_layout Enumerate
3821 Do not worry about where the file goes.
3822 The CVS maintainers will locate all documentation and Style Sheet Supplements
3823 in an appropriate place.
3826 \begin_layout Enumerate
3827 Document Properties:
3831 \begin_layout Itemize
3832 For consistency, use the same document class and other document properties
3837 \begin_layout Standard
3838 Specifically, check the settings in the
3843 Use those in your Supplement.
3851 \begin_layout Itemize
3852 Exceptions: Use margins, indentation/paragraph separation, language, and
3853 encoding appropriate for your language.
3857 \begin_layout Enumerate
3858 The title of the Supplement:
3862 \begin_layout Itemize
3863 The title will use the
3864 \begin_inset Quotes eld
3872 \begin_inset Quotes erd
3875 paragraph environment.
3876 In your native tongue, the title will read:
3880 \begin_layout Standard
3883 Documentation Project Style Sheet:
3885 Supplement for the <foo> Translation Project
3888 \begin_layout Standard
3890 \begin_inset Quotes eld
3898 \begin_inset Quotes erd
3901 with the name of your language.)
3905 \begin_layout Itemize
3906 If, in your language,
3907 \begin_inset Quotes eld
3911 \begin_inset Quotes erd
3915 \begin_inset Quotes eld
3919 \begin_inset Quotes erd
3924 \begin_inset Quotes eld
3928 \begin_inset Quotes erd
3932 \begin_inset Quotes eld
3936 \begin_inset Quotes erd
3939 have somewhat different meanings.
3940 An appendix is an extra part of a document.
3941 A supplement is an extra document.
3946 \begin_layout Standard
3947 Choose a replacement word accordingly.
3948 Whatever you choose to replace
3949 \begin_inset Quotes eld
3953 \begin_inset Quotes erd
3956 it must not have the same translation as the word
3957 \begin_inset Quotes eld
3961 \begin_inset Quotes erd
3969 \begin_layout Enumerate
3970 Below the title, in the
3971 \begin_inset Quotes eld
3979 \begin_inset Quotes erd
3982 paragraph environment, place your name.
3986 \begin_layout Standard
3987 There will be no abstract.
3991 \begin_layout Enumerate
4000 \begin_layout Standard
4001 The first thing you will do is strongly yet politely encourage the reader
4003 \begin_inset Quotes eld
4007 \begin_inset Quotes erd
4010 and go read the Style Sheet.
4011 The reader should not return to the
4012 \begin_inset Quotes eld
4016 \begin_inset Quotes erd
4023 understood the Style Sheet proper.
4027 \begin_layout Subsubsection
4028 Keep the Supplement Succinct
4031 \begin_layout Standard
4032 This Style Sheet is already very detailed.
4033 DocTeam members all have a lot to read.
4034 We don't want to place an extra burden on translators.
4035 Therefore, keep the Supplement as short as you can without losing information.
4038 \begin_layout Subsubsection
4042 \begin_layout Standard
4047 will be about font issues\SpecialChar \ldots{}
4049 Not all Translation Project Chiefs will need to deal with this issue.
4053 \begin_layout Itemize
4059 \begin_layout Itemize
4065 \begin_layout Itemize
4070 Emphasized (actually Italics)
4073 \begin_layout Itemize
4079 \begin_layout Itemize
4085 \begin_layout Itemize
4088 Noun (actually Small Caps)
4091 \begin_layout Standard
4092 \SpecialChar \ldots{}
4093 certainly exist for all languages that use the Roman alphabet.
4094 Do they exist, however, for Greek? How about Cyrillic? These different
4095 fonts almost certainly do not exist for Devanagri, Chinese, Korean, Japanese,
4096 Hebrew, Arabic, and other scripts.
4100 \begin_layout Standard
4101 There will be some languages for which following the font-scheme specified
4102 in this Style Sheet may not be possible.
4103 If you are the Translation Project Chief for such a language, you have
4107 \begin_layout Standard
4108 In the font section of the Supplement, you will provide a new typographic
4109 style, designed specifically for your writing system.
4110 For consistency, the title of this section in every Supplement should translate
4112 \begin_inset Quotes eld
4116 \begin_inset Quotes erd
4119 Before adding anything to this section, however, determine what this new
4120 typographic style will look like.
4121 Stick to the font specifications in this Style Sheet as best you can, whenever
4123 When you cannot, use the following suggestions:
4126 \begin_layout Itemize
4128 \begin_inset Quotes eld
4132 \begin_inset Quotes erd
4139 What to do when a font doesn't exist:
4144 \labelwidthstring MMMMMMMM
4145 Roman Use the font that typesetters in your language use for printing books,
4147 This will typically be the default font LyX (and LaTeX) uses in your language.
4151 \labelwidthstring MMMMMMMM
4157 This is for people's names.
4158 If there is special font for names in your alphabet/writing system, use
4159 it in place of this.
4160 Otherwise, write names in the default font, typeset according to the rules
4165 \labelwidthstring MMMMMMMM
4170 Use the font with which your language normally emphasizes text.
4174 \begin_layout Standard
4175 Use a font that is different from your language's equivalent of
4180 In other words, your
4188 and similar headers will be in one typeface, perhaps
4193 Whatever that font is, avoid using it for
4202 \labelwidthstring MMMMMMMM
4207 Pick up a computer program manual written in your language.
4208 It will use a special typeface for filenames, for command names, program
4210 Use that same font in place of
4218 \labelwidthstring MMMMMMMM
4224 Pick any other font that is different from the ones you're using in place
4238 If you're unlucky, and your language's writing system doesn't have enough
4239 fonts, use the same font you picked to replace
4244 Only do this, however, if your alphabet/writing system has very few fonts
4249 \labelwidthstring MMMMMMMM
4255 nderlined\InsetSpace ~
4259 Don't worry about this one.
4263 \begin_layout Standard
4264 If you use some special font on-screen to highlight the accelerator keys
4265 for menus, buttons, and other widgets, you might want to mimic that in
4267 It is not required, however.
4268 Therefore, if you can't mimic this typographic convention in your native
4269 writing system, don't.
4274 \begin_layout Standard
4275 Note that you may also want to describe fonts that your Translation Team
4281 For example, no contributer to the English/European versions may ever use
4286 , as this is used for section-headings.
4287 Since there are enough other fonts, we who use the Roman alphabet and its
4288 variants can afford to omit
4296 \begin_layout Standard
4297 Once you have determined which fonts in your native writing system will
4298 replace one or more of the above, propose it to the LyX Developer's Mailing
4300 You may receive valuable feedback this way.
4301 If not, that's okay.
4302 If no one can read your writing system, and therefore cannot comment, that's
4304 Go ahead and describe the typographic standard you created in the Supplement.
4308 \begin_layout Standard
4309 Remember: stick to the font specifications in this Style Sheet as best you
4310 can, whenever you can.
4313 \begin_layout Subsubsection
4314 Quoting Style and the
4326 \begin_layout Standard
4327 The next section of the Supplement will cover the issue of quoting.
4328 Give it an appropriate title.
4331 \begin_layout Standard
4332 One of the first things you should do in that section is resolve the following
4336 \begin_layout Itemize
4345 is the correct paragraph environment for your language.
4348 \begin_layout Itemize
4349 In the Supplement, specify which one to use.
4352 \begin_layout Standard
4353 English has its own typography and style for quoting others.
4354 The Style Sheet describes that typography in section\InsetSpace ~
4356 \begin_inset LatexCommand \ref{sec:quote}
4361 Your language also has a specific typography and style for quotations.
4362 Describe that style in this section of the Supplement, too.
4363 Naturally, you do not need to go overboard.
4364 Section\InsetSpace ~
4366 \begin_inset LatexCommand \ref{sec:quote}
4370 of this Style Sheet is overly detailed for a good reason.
4371 Authors of the primary LyX manuals are not necessarily native English speakers.
4372 The members of your Translation Team, however, will all likely be native
4373 speakers of your language.
4374 Therefore, discuss proper quoting style of your native tongue to an appropriate
4378 \begin_layout Subsubsection
4379 Translations of Style Sheet Terminology
4382 \begin_layout Standard
4383 In the Supplement, you must provide a standard translation of certain key
4384 phrases for the members of your Translation Team.
4385 Place this in a section following the one about quotations.
4388 \begin_layout Standard
4389 In particular, standardize the translations of the phrases:
4392 \begin_layout Itemize
4398 \begin_layout Itemize
4404 \begin_layout Standard
4409 change the typography of the
4410 \begin_inset Quotes eld
4414 \begin_inset Quotes erd
4418 \begin_inset Quotes eld
4422 \begin_inset Quotes erd
4426 Only provide a translation for the opening phrases.
4427 Insist that the members of your Translation Team use these two tools correctly.
4430 \begin_layout Standard
4431 While we are discussing proper use of the
4432 \begin_inset Quotes eld
4436 \begin_inset Quotes erd
4440 \begin_inset Quotes eld
4444 \begin_inset Quotes erd
4447 in translations, let's talk about a related problem.
4449 \begin_inset Quotes eld
4453 \begin_inset Quotes erd
4456 is meant to be a note from the author of a manual to the reader.
4457 In the case of a translation, however, the translator is
4461 the author! How then should a translator translate an
4462 \begin_inset Quotes eld
4466 \begin_inset Quotes erd
4472 \begin_layout Standard
4473 You, as Translation Project Chief, must decide.
4474 You can forbid translation of pre-existing
4475 \begin_inset Quotes eld
4479 \begin_inset Quotes erd
4482 omitting them entirely instead.
4483 You could tell your translators to read any
4484 \begin_inset Quotes eld
4488 \begin_inset Quotes erd
4491 they may encounter, understand it, then write their own
4492 \begin_inset Quotes eld
4496 \begin_inset Quotes erd
4499 about the situation, not as a translation but as a personal opinion.
4500 You may decide on some other policy.
4503 \begin_layout Standard
4504 Whatever you decide, codify your policy in its own
4513 Place it near the section where you translated
4514 \begin_inset Quotes eld
4518 \begin_inset Quotes erd
4522 \begin_inset Quotes eld
4526 \begin_inset Quotes erd
4532 \begin_layout Subsubsection
4536 \begin_layout Standard
4537 After describing all of the previous issues, create a new
4543 \begin_inset Quotes eld
4546 Lost in Translation,
4547 \begin_inset Quotes erd
4550 or something similar.
4553 \begin_layout Standard
4554 In this section you will discuss any common English metaphors, humor, connotatio
4555 n, or other difficult to translate text.
4556 Try to balance brevity and completeness.
4565 s --- to each specific issue.
4568 \begin_layout Subsubsection
4569 \SpecialChar \ldots{}
4571 \begin_inset Quotes eld
4575 \begin_inset Quotes erd
4578 \SpecialChar \ldots{}
4582 \begin_layout Standard
4583 Throughout the manuals, the DocTeam has used the following sentences:
4587 If you haven't read the <
4591 > manual, go read it.
4595 \begin_layout Standard
4596 This sentence will be tricky to translate, since it contains non-translatable
4602 for this issue in your
4603 \begin_inset Quotes eld
4607 \begin_inset Quotes erd
4612 \begin_inset Quotes eld
4615 \SpecialChar \ldots{}
4616 Yes, we mean now\SpecialChar \ldots{}
4618 \begin_inset Quotes erd
4621 sentences, then present a translation, along with any explanation you feel
4625 \begin_layout Standard
4626 Here's what those two sentences, sitting alone in their own paragraph, mean:
4629 \begin_layout Standard
4630 The first sentence uses the English conditional followed by an imperative.
4631 We, as the LyX team, are commanding the reader to go back to another manual.
4636 manual is a prerequisite for all of the other manuals.
4637 The conditional clause preceeding the command means,
4638 \begin_inset Quotes eld
4641 You do not need to perform this command twice.
4642 \begin_inset Quotes erd
4648 \begin_layout Standard
4649 The second sentence adds force to the command.
4650 Culturally, the imperative tense of a verb in English is not necessarily
4652 The way we wrote that command,
4653 \begin_inset Quotes eld
4657 \begin_inset Quotes erd
4660 is firm, yet polite.
4661 The reader may choose to ignore it.
4663 \begin_inset Quotes eld
4667 \begin_inset Quotes erd
4670 we imply two things.
4672 \begin_inset Quotes eld
4676 \begin_inset Quotes erd
4680 That second sentence reinforces the command, making it a bit harder to
4682 Second, the sentence itself implies a certain sense of urgency.
4683 You cannot merely wait until later to fulfill that command.
4684 The brief pragraph, and its sudden end, add still further subtle reinforcement
4686 \begin_inset Quotes eld
4689 go do the required reading before using this manual.
4690 \begin_inset Quotes erd
4696 \begin_layout Standard
4697 Note that all of this commanding and reinforcing is nevertheless in a polite
4699 Furthermore, it is in a subtle form.
4700 We are commanding the reader to do something, but in an indirect fashion.
4701 This way, the reader does not feel like we are bullying him.
4704 \begin_layout Subsubsection
4709 \begin_layout Standard
4710 In the same part of the Supplement that you place the
4711 \begin_inset Quotes eld
4714 \SpecialChar \ldots{}
4715 Yes, we mean now\SpecialChar \ldots{}
4717 \begin_inset Quotes erd
4720 translation, discuss the English version's use of
4721 \begin_inset Quotes eld
4725 \begin_inset Quotes erd
4731 \begin_layout Standard
4732 You see, here in America, we often say that everything is permitted unless
4733 explicitly banned by law.
4734 As a result, manuals for computer software are frequently ignored and the
4735 software subsequently blamed for not being
4736 \begin_inset Quotes eld
4740 \begin_inset Quotes erd
4743 This is where the use of
4744 \begin_inset Quotes eld
4748 \begin_inset Quotes erd
4755 \begin_layout Standard
4756 We who wrote the manuals added sentences insisting that the reader not ignore
4757 certain parts of the documentation.
4758 We wrote in a manner that was polite, yet firmly asserted that the user
4759 was misusing the software if he did not read the manual correctly.
4760 We did not, however, want to sound threatening, coercive, or bullying.
4763 \begin_layout Standard
4764 In your culture, cajoling the reader into using the manuals correctly may
4766 It may, in fact, be outright rude.
4767 Additionally, translating the firm-but-convincing bits may not work.
4768 The translation may sound weird, or rude, or hostile.
4769 Therefore, you and your translation team will face many sentences that
4770 you cannot translate.
4773 \begin_layout Standard
4774 You, the Translation Project Chief, must discuss this issue.
4775 Try and find parts of the original manuals where some friendly but firm
4776 convincing does not translate properly.
4777 Use these cases as the basis for examples of the problem.
4778 Be sure to then offer a solution (i.\InsetSpace ~
4780 how you want such sentences translated.)
4781 If stumped, ask for help on the LyX Developer's List.
4784 \begin_layout Subsubsection
4788 \begin_layout Standard
4789 You can add more sections to the Supplement if you need to discuss other
4791 There may be policies or guidelines that you want to set for your Translation
4793 Be careful, however! Keep the Supplement