1 #LyX 1.3 created this file. For more info see http://www.lyx.org/
15 \use_numerical_citations 0
16 \paperorientation portrait
19 \paragraph_separation indent
21 \quotes_language english
29 Documentation Project Style Sheet
35 This article is a style sheet.
36 It describes, with examples, how the documentation should look and sound.
37 The first few sections explain the font conventions and typography conventions
38 all documentation writers should follow.
39 Those sections also contain examples.
40 It also explains the purpose of each of the different manuals.
41 Follow it not merely to the letter, but also in spirit.
44 The Style Sheet for LyX documentation (hereafter known as the Style Sheet)
49 forms of LyX documenation, regardless of language.
50 There is a section for translators in the Style Sheet, towards the end.
53 Read the entire Style Sheet!
55 Even if you are a translator, I assume you know enough English to comprehend
59 Questions and Clarifications
62 After the second version of this Style Sheet grew uncomfortably large, the
63 LyX DocTeam decided it needed to lose some excess weight.
64 It seems the Style Sheet began to specify too many special cases, too many
65 points of clarification.
66 On the other hand, contributors to the documents were discovering many
67 creative ways of misinterpreting the Style Sheet specifications.
71 If you have any questions about anything in the Style Sheet,
73 ask first, write second!
76 Field all questions to the LyX Developer's Mailing List.
77 There are seasoned DocTeam members who can answer your questions.
78 If you have any problems with the Style Sheet itself, also contact the
85 We'll start with the easiest section, yet also the most important.
88 This is how you should fontify text in the manuals:
90 \labelwidthstring MMMMMMMM
96 general emphasis, generic arguments, titles of books, names the other manuals
97 and of their sections, and notes from the authors
101 Do not overemphasize your text.
104 \labelwidthstring MMMMMMMM
110 program names, file names,
114 -page names, LaTeX code, LaTeX commands, LaTeX package names, and LyX code
117 \labelwidthstring MMMMMMMM
124 menu, button, or popup names, the names/lables of all widgets in a popup,
125 the names of keyboard keys, and certain
126 \begin_inset Quotes eld
130 \begin_inset Quotes erd
135 \labelwidthstring MMMMMMMM
144 \labelwidthstring MMMMMMMM
151 nderlined\SpecialChar ~
155 Rich Fields added this to mimick the underlining of letters in the menus
157 It helps to highlight the accelerator keys, and human brains store information
158 best when they see it frequently.
162 WARNING! --- When you do this, make sure you
166 shut off the underlining.
167 Too many people send in things that look like:
177 \SpecialChar \ldots{}
180 they not only shut off underlining, they turned off
189 Make sure the entire word is still in
194 after you shut off the underlining.
197 \labelwidthstring MMMMMMMM
207 If you want to emphasize any text, use
212 LaTeX will put many things boldface on its own, such as
216 s, certain parts of equations, et cetera.
219 Repeat: do not use boldface.
223 Here are some examples:
230 appears in configuration files and in the LyX source.
231 Therefore, it (and all other LyX function names) count as code and is set
247 is a menu item in the
254 menu, so it appears in
265 nderlined\SpecialChar ~
269 for the accelerator keys.
272 Consider the following excerpt from the introduction of one of the manuals:
284 both refer to the same key.
285 Some keyboards label the
290 \begin_inset Quotes eld
294 \begin_inset Quotes erd
298 \begin_inset Quotes eld
302 \begin_inset Quotes erd
305 still others have two keys.
306 LyX treats all of them as the same key, so we'll use
317 Notice that the key name,
330 when it references the key itself! When I described how the manufacturer
331 chose to label its keyboard, I used Roman and put the word in quotes.
332 There is a semantic difference.
336 Take the following command:
348 Notice that the argument to the
358 This is a case where you don't use
362 for code, because you want the generic argument label to stand out.
363 On the other hand, if you were specifying an argument, for example,
364 \begin_inset Quotes eld
372 \begin_inset Quotes erd
384 Any LaTeX commands and code, and any
388 LaTeX package names get set in
394 \begin_inset Quotes eld
402 \begin_inset Quotes erd
405 is the name of an unsupported LaTeX package, but
406 \begin_inset Quotes eld
414 \begin_inset Quotes erd
417 is a supported LaTeX class.
423 The canonical keyboard contains these keys:
463 use the abbreviations
471 F1 F2 F3 F4 F5 F6 F7 F8 F9 F10 F11 F12
476 Most modern keyboards have all 12.
489 \begin_inset Quotes eld
493 \begin_inset Quotes erd
526 These are the 6 keys that appear above the cursor keys on many PC keyboards.
527 Consider them as part of the standard motion keys.
537 The four standard motion keys.
538 There is no need to put the word
539 \begin_inset Quotes eld
543 \begin_inset Quotes erd
546 anywhere, since that's obvious.
553 \begin_inset Quotes eld
557 \begin_inset Quotes erd
562 \begin_inset Quotes eld
566 \begin_inset Quotes erd
569 after one of these may be redundant in certain situations.
588 I won't throw a hissy fit if you use one instead of the other.
589 I'd prefer if you used
597 , but it's okay if you slip up and forget.
598 Since these two keys are bound to the same function in LyX, it doesn't
603 You do not need to explain everywhere what the
612 The user isn't stupid.
613 Also, someone will document anything that isn't clear (e.\SpecialChar ~
624 problem) someplace in the introduction.
625 No need for you to repeat someone else's work.
628 LyX does not support keyboards missing any of the keys described above,
630 LyX can support a keyboard missing
639 There is a keyboard accelerator for
643 , but this is the only function key LyX assumes exists.
644 Nevertheless, these details are of minor, if any, concern for the documentation.
645 Assume the aforementioned keys exist.
652 \begin_inset Quotes eld
656 \begin_inset Quotes erd
659 and any description of the 3 mouse buttons have no special handling.
660 Don't typeset them in any other font than the default, which is Roman.
664 Exception: you're writing an Author's Note (see section
665 \begin_inset LatexCommand \ref{sec:author-notes}
669 ) and you need to mention something about the mouse.
670 Since the rest of the note is in
674 , your description of
675 \begin_inset Quotes eld
679 \begin_inset Quotes erd
682 should be emphasized, as well.
683 There are a couple of other cases like this one; use your judgement.
686 There are only 3 mouse buttons.
687 The use of them and of the mouse itself is obvious.
688 There are few --- if any --- nonstandard things we do with the mouse.
689 Therefore, there's no need to make the word
690 \begin_inset Quotes eld
694 \begin_inset Quotes erd
698 \begin_inset Quotes eld
702 \begin_inset Quotes erd
714 Multi-word\SpecialChar ~
717 Protected\SpecialChar ~
720 between the words for menu and widget names.
736 This holds for things in
746 If you have a long code example, one that can't simply be inlined and put
761 Protected\SpecialChar ~
764 so that the name doesn't get split between two lines, which is visually
768 Protected\SpecialChar ~
771 is near the end of a line and overflows the margin, use a
777 in that parargraph (consult a LaTeX book for more about
778 \begin_inset Quotes eld
788 \begin_inset Quotes erd
791 ) or manually add a hypenation point.
795 Special\SpecialChar ~
796 Terms These are things like the following:
832 font and, in the case of
840 , capitalize the first two letters.
843 Why are these terms special? They are concepts which the seasoned LaTeX-pert
844 is familiar with, but which the new LyX user is not.
845 I want them to stand out from the rest of the text, hence the use of
855 Seasoned LyX Team Members: Are there other terms that require this special
856 status? On the other hand, should we eliminate this style completely?
859 Terminology Note the following:
863 \begin_inset Quotes eld
867 \begin_inset Quotes erd
871 \begin_inset Quotes eld
875 \begin_inset Quotes erd
879 \begin_inset Quotes eld
883 \begin_inset Quotes erd
888 \begin_inset Quotes eld
892 \begin_inset Quotes erd
896 \begin_inset Quotes eld
900 \begin_inset Quotes erd
906 PostScript® is a registered trademark of Adobe Corp.
909 You must put the ® after it or we'll get sued!
911 I also want it written as seen here, always capitalized.
913 \begin_inset Quotes eld
917 \begin_inset Quotes erd
921 \begin_inset Quotes eld
925 \begin_inset Quotes erd
929 \begin_inset Quotes eld
933 \begin_inset Quotes erd
936 - both of them capitalized, in the default font (i.\SpecialChar ~
939 If you must, cut and paste it from here.
943 I am going to say this again:
945 \added_space_top 0.37cm \added_space_bottom 0.51cm \align center
949 You must put the ® after PostScript® or we'll get sued!
952 I mean it! American companies like to sue anything that moves.
957 by forgetting that ®.
963 Similarly, if you use any other registered trademark in any documentation,
964 put the ® after it, too.
968 Items When quick-referencing an item in a menu, use the menu separator:
970 \begin_inset Quotes eld
973 \SpecialChar \menuseparator
975 \begin_inset Quotes erd
981 File\SpecialChar \menuseparator
985 Notice that there are
990 \begin_inset Quotes eld
993 \SpecialChar \menuseparator
995 \begin_inset Quotes erd
1003 , just like the menu and item names.
1007 The reason why I want no spaces around the
1008 \begin_inset Quotes eld
1011 \SpecialChar \menuseparator
1013 \begin_inset Quotes erd
1016 is to prevent LyX from splitting terms across lines.
1017 The same goes for using
1019 Protected\SpecialChar ~
1022 s between multi-word terms.
1023 The split would be visually disruptive.
1027 \begin_inset Quotes eld
1030 \SpecialChar \menuseparator
1032 \begin_inset Quotes erd
1035 goes between menu names and item names
1040 (Yes, submenus are okay, too).
1048 \begin_inset Quotes eld
1051 \SpecialChar \menuseparator
1053 \begin_inset Quotes erd
1056 between menu items and dialog names.
1058 \begin_inset Quotes eld
1066 ayout\SpecialChar \menuseparator
1071 per\SpecialChar \menuseparator
1076 \begin_inset Quotes erd
1081 IS STRICTLY FORBIDDEN!
1092 \begin_inset Quotes eld
1095 \SpecialChar \menuseparator
1097 \begin_inset Quotes erd
1100 between popup names and any dialog.
1102 \begin_inset Quotes eld
1108 Dialog\SpecialChar \menuseparator
1116 \begin_inset Quotes erd
1121 IS STRICTLY FORBIDDEN!
1129 \begin_inset Quotes eld
1132 \SpecialChar \menuseparator
1134 \begin_inset Quotes erd
1137 between menu items and any dialog.
1139 \begin_inset Quotes eld
1147 ayout\SpecialChar \menuseparator
1152 per\SpecialChar \menuseparator
1160 \begin_inset Quotes erd
1165 IS STRICTLY FORBIDDEN!
1168 Either write out the description, or use context to eliminate any need to
1169 repeat menu items, dialog names, etc.
1175 Boxes LyX has a feature for adding comments that appear only within
1183 These should NEVER appear in the manuals.
1187 You will see nothing in a printout of the Style Sheet.
1188 Therefore, they have no place in the manuals.
1194 If you have a parenthetical comment you want to make, the reader should
1195 see it too, even in the printed version.
1196 Use an Author's Note (see section
1197 \begin_inset LatexCommand \ref{sec:author-notes}
1201 ) in place of the Note-Boxes.
1206 \begin_inset Quotes eld
1209 (\SpecialChar \ldots{}
1211 \begin_inset Quotes erd
1216 \begin_inset Quotes eld
1219 [\SpecialChar \ldots{}
1221 \begin_inset Quotes erd
1227 \begin_inset Quotes eld
1230 {\SpecialChar \ldots{}
1232 \begin_inset Quotes erd
1235 I have recently been corrected about the use of parentheses.
1236 Standard English typesetting uses the normal parentheses,
1237 \begin_inset Quotes eld
1240 (\SpecialChar \ldots{}
1242 \begin_inset Quotes erd
1245 , around any aside, remark, or parenthetical expression.
1247 \begin_inset Quotes eld
1250 [\SpecialChar \ldots{}
1252 \begin_inset Quotes erd
1255 , is used only within quotations (see section\SpecialChar ~
1257 \begin_inset LatexCommand \ref{sec:quote}
1263 \begin_inset Quotes eld
1266 {\SpecialChar \ldots{}
1268 \begin_inset Quotes erd
1272 Therefore, never use
1273 \begin_inset Quotes eld
1276 [\SpecialChar \ldots{}
1278 \begin_inset Quotes erd
1282 \begin_inset Quotes eld
1285 {\SpecialChar \ldots{}
1287 \begin_inset Quotes erd
1290 unless otherwise specified by this Style Sheet.
1293 Dashes: Be sure to use the correct one.
1295 \begin_inset Quotes eld
1303 \begin_inset Quotes erd
1306 character is not a dash, it's a hyphen.
1307 Use it only as a hyphen.
1313 \begin_inset Quotes eld
1317 \begin_inset Quotes erd
1321 \begin_inset Quotes eld
1325 \begin_inset Quotes erd
1329 \begin_inset Quotes eld
1337 \begin_inset Quotes erd
1340 characters form the en-dash.
1342 \begin_inset Quotes eld
1350 \begin_inset Quotes erd
1353 characters create an em-dash, which is slightly longer than the en-dash.
1354 In the printed version of any document, LyX will combine the two or three
1356 \begin_inset Quotes eld
1364 \begin_inset Quotes erd
1367 characters into a single, unbroken line.
1371 Cross-References and Labels
1374 Use the following labelling conventions:
1376 \labelwidthstring 00.00.0000
1378 sec:xxx Use this for
1396 \labelwidthstring 00.00.0000
1398 eqn:xxx Use this for Equations, should you need to create any.
1400 \labelwidthstring 00.00.0000
1402 tbl:xxxx Use this for tables inside of a table float.
1404 \labelwidthstring 00.00.0000
1406 fig:xxx Use this for figures inside of figure floats.
1409 Additionally, you should put the label at one of two locations:
1414 beginning of the paragraph
1416 , after a section heading, or at the beginning of captions, etc.
1417 It should be the first thing on the first line.
1418 Don't put a space betweeen it and the first word.
1421 If there is no paragraph after a section heading, put it at the
1423 end of the last line.
1434 which is immediately followed by a
1439 This is a case where you need to put the label at the end of the
1444 I know it looks ugly; not much we can do about that, though.
1448 Content --- What Goes Where
1455 important to anyone documenting a new feature.
1456 If you need to add new documentation, pay attention.
1460 In the dim and distant past, whenever someone wanted to document a new feature
1461 they added, they either wrote a mini-doc and stuck it into the documentation
1462 directory, or they added a new section to the lone manual.
1463 No one paid much attention to organization in those days, either.
1464 The result was a totally bloated, totally unnavigable, and incomplete manual
1465 orbitted by a swarm of tiny, incomplete mini-docs.
1466 I don't want the docs to fall back into that mess.
1469 With that in mind, I have some instructions for how to keep things organized:
1471 \labelwidthstring 00.00.0000
1477 Please, don't touch this file.
1478 It's essentially complete, anyhow.
1479 Only the editor(s) should make changes to this, as this file contains info
1480 about how to contribute to the doc project.
1481 That's really the only stuff that should need to change, and even then,
1482 only when a new maintainer comes along.
1484 \labelwidthstring 00.00.0000
1490 This file is complete.
1491 Any changes should be for updates
1496 DO NOT ADD new features to here willy-nilly.
1497 Let the editor decide if --- and when --- new sections go in here.
1498 Place any new features in\SpecialChar \ldots{}
1501 \labelwidthstring 00.00.0000
1507 This is where all new features go from now on.
1508 It's in the style of a bound journal --- each section is an
1509 \begin_inset Quotes eld
1513 \begin_inset Quotes erd
1516 from the author of the feature.
1517 Also, anyone who writes a
1521 file for a new document class should write a section describing that new
1522 class and how to use it.
1523 That also goes here.
1527 Note, however, that you are
1531 excused from following this Style Sheet just because the sections of
1535 are in the form of a journal article.
1538 \labelwidthstring 00.00.0000
1544 This file is complete.
1545 Do not change or add to without permission of the Documenation Project
1548 \labelwidthstring 00.00.0000
1554 This document describes advanced features, most of which alter the look,
1555 feel, and behavior of LyX.
1556 This manual is still a bit incomplete, although that may change soon.
1557 Check for updates often.
1561 If you are unsure whether or not something belongs in
1565 , then, most-likely, it
1574 Again, let the current editor of the LyX documentation decide if your new
1575 section should be migrated to
1582 \labelwidthstring 00.00.0000
1588 I'd prefer to completely finish this one before doing anything else, but
1590 LyX keeps changing so much that I think the
1594 will be the last one completed.
1595 However, I'd like it if the developer's would add entries anytime they
1596 create a new function or popup.
1597 That would help things immensely!
1605 follows this Style Sheet for the most part.
1606 There are, however, additional rules to follow when making new entries.
1607 At the top of this manual, there are examples of and a template for
1616 Writing Style: The Primary Manuals
1619 While I want to make contributing to the Documentation Project as painless
1620 as possible for newcomers, I also want the newcomers to be painless on
1621 the existing Documentation Team! Ergo, I've written this section to give
1622 some flavor to guide everyone's individual style.
1629 All contributions to the
1633 LyX documentation must be in English.
1634 I don't care if it's British, Australian, or American English.
1635 The DocTeam editor will proofread for glaring mistakes and fix them.
1638 Don't get hung up on semantics.
1639 English is a flexible language, and just because your Mothertongue-to-English
1640 dictionary gives only one translation for a word doesn't necessarily mean
1642 We've had some discussions and misunderstandings on the Developers' List
1643 because of this very problem.
1644 If something is unclear (or just plain weird) due to a translation problem,
1645 one of the American/British/Australian developers can fix it.
1652 documentation, I exclude the translations.
1653 We usually don't have enough people to cover the manuals in one language,
1654 let alone more than one.
1655 Subsequently, the tranlsations are just that --- translations of the English
1656 version of the LyX manuals.
1657 The translation efforts require have their own set of guidelines.
1659 \begin_inset LatexCommand \ref{sec:translations}
1668 Commentary from the Author (i.\SpecialChar ~
1673 \begin_inset LatexCommand \label{sec:author-notes}
1677 I want to make it easy for everyone when it comes to documenting things.
1678 Some features are incomplete.
1679 Some, you might not know everything about.
1680 Sometimes, you may want to comminucate something to me or the reader or
1681 other DocTeam members.
1682 Sometimes, you may want to
1683 \begin_inset Quotes eld
1687 \begin_inset Quotes erd
1690 you want to say something that is your personal opinion and using
1691 \begin_inset Quotes eld
1695 \begin_inset Quotes erd
1698 would be inappropriate.
1701 In short, when you contribute to the LyX Docs, you wear many hats.
1704 For occasions when you need to switch hats, I've designed some special mechanism
1706 \layout Subsubsection
1708 Personal\SpecialChar ~
1710 \begin_inset Quotes eld
1714 \begin_inset Quotes erd
1720 These are footnotes.
1721 They begin with the following:
1731 \SpecialChar \ldots{}
1736 for the person's name and without the quotes.
1737 The rest of the footnote is the actual comment.
1741 Use these when you need to quote a comment by someone (usually yourself),
1742 and need to identify that person.
1743 This includes occasions when you need wear the
1744 \begin_inset Quotes eld
1748 \begin_inset Quotes erd
1751 hat, i.\SpecialChar ~
1753 to speak for yourself instead of for the LyX Team.
1756 If the comment is too large to put in a footnote, don't use a Personal Note.
1757 When quoting more than about 3 sentences or 5 lines of text, use a bona
1759 Don't use any leading
1760 \begin_inset Quotes eld
1768 \begin_inset Quotes erd
1772 In a real quote, you'll give credit to the original speaker in either the
1773 paragraph before or after the body of the
1778 \layout Subsubsection
1780 Author's\SpecialChar ~
1782 \begin_inset Quotes eld
1786 \begin_inset Quotes erd
1792 There will be times when you are not speaking for the LyX Team, yet you
1793 are not entirely speaking for yourself.
1794 Instead, you are speaking on behalf of the manual itself, as the author
1796 Some examples of when you might need to do this are:
1799 You need to contradict something you just wrote because the feature isn't
1800 quite ready yet, but you wanted to document what it will do.
1803 You need to leave a note for yourself.
1806 You need to leave a note for the editor or the other DocTeam members.
1809 You need to point out something about the manuals to the reader, something
1810 that doesn't fit into the context of the current paragraph.
1813 At such times, you are wearing your
1814 \begin_inset Quotes eld
1818 \begin_inset Quotes erd
1824 The typography for an
1825 \begin_inset Quotes eld
1829 \begin_inset Quotes erd
1835 They go in the body of the text, in brackets,
1836 \begin_inset Quotes eld
1840 \begin_inset Quotes erd
1843 , not any other form of parentheses.
1844 The bracket are in the default character style.
1847 The text of the note itself, however, is emphasized.
1851 Begin with the words,
1852 \begin_inset Quotes eld
1860 \begin_inset Quotes erd
1863 and end with an em-dash,
1864 \begin_inset Quotes eld
1868 \begin_inset Quotes erd
1871 , followed by your initials.
1875 Here's an example: [
1877 Author's Note: This is an example note.
1883 The form of the Author's Note, by the way, isn't a suggestion or request.
1889 All Author's Notes must begin with this text, verbatim:
1890 \begin_inset Quotes eld
1898 \begin_inset Quotes erd
1903 \begin_inset Quotes eld
1907 \begin_inset Quotes erd
1910 are or any other variant are forbidden.
1911 The Author's Note must end with an em-dash, which is 3
1912 \begin_inset Quotes eld
1916 \begin_inset Quotes erd
1920 \begin_inset Quotes eld
1924 \begin_inset Quotes erd
1929 \begin_inset Quotes eld
1933 \begin_inset Quotes erd
1936 ; you must use 3 (and 5 is right out).
1940 \begin_inset Quotes eld
1944 \begin_inset Quotes erd
1947 are inherently transient, and should disapear as a manual matures.
1948 \layout Subsubsection
1953 You are also free to use footnotes on their own in addition to the Personal
1954 Notes and/or Author's Notes.
1955 I've frequently used footnotes to \SpecialChar \ldots{}
1956 well, to comment on parts of a section
1957 without putting the commentary into the body of the text.
1960 Mixing Footnotes and Personal Notes
1963 Personal Notes always go in footnotes, and should be 5 lines or fewer.
1964 Any larger quotation should be quoted properly, using the rules of standard
1970 paragraph environment.
1973 Mixing Footnotes and Author's Notes
1976 Author's Notes should
1984 Mixing Personal Notes and Author's Notes
1987 Forbidden; these two are mutually exclusive.
1988 \layout Subsubsection
1999 opinion --- yours or another LyX developer's --- about anything.
2000 Anywhere in the manuals you wish to speak for yourself instead the the
2002 If you have a long rant, however, quote yourself (see section\SpecialChar ~
2004 \begin_inset LatexCommand \ref{sec:quote}
2013 Use this to describe things in LyX (or the manuals) that may change in the
2014 future or are somehow incomplete.
2015 Author's Notes are supposed to disappear as a manual matures.
2020 Used for text fragments that almost fit into the flow of the text\SpecialChar \ldots{}
2025 When using these three mechanisms, in addition to rigorously following their
2026 descriptions, please use them properly.
2027 I listed some additional restrictions previously.
2028 Some of you may balk at these restrictions.
2029 Nevertheless, there is a reason for them: if you have an overwhemling desire
2030 to mix or modify footnotes, Personal Notes, and Author's Notes, you shouldn't
2031 be using any of them.
2032 More specifically, you're trying to use a hammer to drive in a screw.
2033 What you want to say probably needs to go into the main body of the text.
2036 General Stylistic Guidelines
2039 Everything in this section is
2041 mandatory to all documenters
2043 , regardless the language you're writing in.
2045 \layout Subsubsection
2050 Use the typography rules outlined in the beginning sections of this document.
2053 Don't, however, mimic the typography of this file.
2054 Yes, the Style Sheet doesn't follow the Style Sheet (grin).
2057 There is some typographic freedom in those rules in earlier sections.
2058 Use that freedom wisely.
2059 Most importanly, never sacrifice the online appearance for the printed
2060 appearance and vice versa.
2064 An example is in the
2069 There is a footnote using the
2073 command to divide a long
2077 environment into 3 columns.
2078 It adds some LaTeX commands to the online version, the so-called
2079 \begin_inset Quotes eld
2083 \begin_inset Quotes erd
2086 that some so vehemently oppose.
2087 Without it, however, that footnote takes up over two pages, most of which
2089 This is an example of permitting a little ugliness in the online version
2090 to get the printed version to look right.
2094 When in doubt, compromise.
2098 When in doubt, use good judgement.
2100 \layout Subsubsection
2106 \begin_inset Quotes eld
2110 \begin_inset Quotes erd
2117 When you speak, you speak for the entire LyX Team, so use
2118 \begin_inset Quotes eld
2122 \begin_inset Quotes erd
2126 \begin_inset Quotes eld
2130 \begin_inset Quotes erd
2138 \begin_inset Quotes eld
2142 \begin_inset Quotes erd
2149 Whenever you want to say something to the reader, use
2150 \begin_inset Quotes eld
2154 \begin_inset Quotes erd
2157 not some contorted construction to avoid being too informal.
2163 \begin_inset Quotes eld
2167 \begin_inset Quotes erd
2170 for both the physical pointing object (mouse, joystick, touch pad, track
2171 ball, etc.) and the mouse cursor which the physical object moves about the
2176 \begin_inset Quotes eld
2180 \begin_inset Quotes erd
2183 for the little blinking vertical bar that indicates where text can/will
2187 When in doubt, compromise.
2191 When in doubt, use good judgement.
2193 \layout Subsubsection
2196 \begin_inset LatexCommand \label{sec:quote}
2200 Quoting Yourself and Others
2203 In some cases, you'll have something to say, an opinion of yours.
2204 Since this is your opinion, you're not speaking for the LyX Team.
2205 You have so much to say, in fact, that it won't fit into a Personal Note
2206 or an Author's Note.
2207 In these cases you want to quote yourself.
2210 Any time you wish to quote someone, be it yourself or someone else, there
2211 are standard rules one follows.
2212 Every language has its own rules.
2213 You should follow the rules that apply to the language of the document
2214 to which you are contributing.
2218 This creates a problem for the primary documentation.
2219 The primary documentation is written in English, yet the contributors come
2220 from many countries.
2221 The quoting rules for English (well, American English, at least) are outlined
2224 Figure\SpecialChar ~
2227 , for your convenience.
2228 Read them if you need to.
2232 \begin_inset Float figure
2239 Quoting rules for English:
2242 The body of the quote belongs in a
2249 The sentences prior to the quote should flow logically and smoothly into
2253 The sentences immediately following the quote should continue the flow of
2261 credit the original author of the quote in the sentences immediately before
2265 Crediting the original author of the quote should not, however, disrupt
2266 the flow of the text.
2269 If you omit text from the beginning of the first sentence in the quote,
2270 the quote must start with the text
2271 \begin_inset Quotes eld
2274 [\SpecialChar \ldots{}
2276 \begin_inset Quotes erd
2280 This is an ellipsis in square brackets.
2283 If you omit text from the end of the last sentence in the quote, the quote
2284 must end with the text
2285 \begin_inset Quotes eld
2288 [\SpecialChar \ldots{}
2290 \begin_inset Quotes erd
2293 followed by the sentence's punctuation mark.
2296 If you omit any text from the middle of the quote, be it whole sentences
2297 or parts of sentences, replace it with the text
2298 \begin_inset Quotes eld
2301 [\SpecialChar \ldots{}
2303 \begin_inset Quotes erd
2309 The quote must be grammatically correct.
2314 If the original is wrong, you must correct it.
2317 If omitting part of the quote
2318 \begin_inset Quotes eld
2322 \begin_inset Quotes erd
2325 it, you must correct the problem.
2328 For missing words (e.\SpecialChar ~
2331 \begin_inset Quotes eld
2335 \begin_inset Quotes erd
2338 goes missing), place the word in square brackets,
2339 \begin_inset Quotes eld
2342 [\SpecialChar \ldots{}
2344 \begin_inset Quotes erd
2347 and insert in the quote where needed.
2350 For mangled word order, correct the mangled text, following it with the
2352 \begin_inset Quotes eld
2356 \begin_inset Quotes erd
2363 Spelling in the quote must be correct.
2364 Correct any misspelled words and place the text
2365 \begin_inset Quotes eld
2369 \begin_inset Quotes erd
2372 after the corrected word.
2375 Back-to-back bracket blocks merge together.
2377 \begin_inset Quotes eld
2380 [\SpecialChar \ldots{}
2382 \begin_inset Quotes erd
2387 \begin_inset Quotes eld
2390 [\SpecialChar \ldots{}
2392 \begin_inset Quotes erd
2398 If you correct the spelling in 2 or more consecutive words, you can get
2400 \begin_inset Quotes eld
2404 \begin_inset Quotes erd
2407 after the last mistake.
2411 \layout Subsubsection
2416 When describing a new feature or
2433 \begin_inset Quotes eld
2436 Keep It Short and Sweet
2437 \begin_inset Quotes erd
2441 \begin_inset Quotes eld
2444 Keep It Simple, Stupid!
2445 \begin_inset Quotes erd
2456 write paragraph after paragraph of verbage.
2463 Take a look at the manual for a commercial word processor --- it's a fine
2468 to write documentation.
2469 It's all pithy, substanceless verbage, and its
2477 Avoid being pedantic like The Plague!
2480 In the same vein, don't write more than you have to.
2481 You're not working in a vacuum --- refer freely to other parts of the manual
2482 (and other parts of other manuals).
2484 \begin_inset Quotes eld
2487 other part of the manual
2488 \begin_inset Quotes erd
2491 is incomplete or empty, refer to it.
2492 Someone will fill it in eventually.
2495 On the other hand, BE THOROUGH!
2503 , not widgets, not how the source code is organized.
2506 Group by feature, not by widget.
2509 Stay on topic --- one
2522 s and further subdivisions to group things if you're documenting several
2523 related features in a single
2530 Describe EVERYTHING related to that feature, no matter where it is.
2534 Example: Paragraph Indenting.
2535 Several popups control its behavior.
2540 of this: which popups control it, when you use which setting on which popup
2541 to do which operation, et cetera.
2550 I've had people only document one popup --- literally.
2551 This added off-topic information and only described half of the feature,
2552 since other menus, popups, and even unbound functions contained additional
2559 cranky when that happens, because it means
2564 Bad help is worse than no help at all.
2568 These remarks still hold true: you'll piss of the DocTeam editor if you
2569 do things wrong, because he'll have to fix your mistakes.
2574 Remember, there are people who will reference
2578 section, just as you're referencing someone else's.
2579 You do want what you write to be useful, don't you?
2583 When in doubt, compromise.
2587 When in doubt, use good judgement.
2589 \layout Subsubsection
2595 Treat the Reader as if She is Stupid
2601 No talking down to the reader.
2604 The reader is smart enough to know what a mouse is.
2607 The reader is smart enough to know how to use a keyboard, including the
2621 (The introduction of most of the manuals takes care of the
2622 \begin_inset Quotes eld
2634 \begin_inset Quotes erd
2637 issue, so you don't need to.)
2640 The reader is smart enough to know that
2641 \begin_inset Quotes eld
2645 \begin_inset Quotes erd
2649 \begin_inset Quotes eld
2652 where the text cursor is sitting right now, in the buffer currently visible.
2653 \begin_inset Quotes erd
2658 (Anything more than the word
2659 \begin_inset Quotes eld
2663 \begin_inset Quotes erd
2666 is, IMO, superfluous and wll be deleted .
2667 So, save yourself the typing, save the editor the cutting, and save the
2668 reader the strain of sifting through extra verbage that adds no content.)
2671 Rule of thumb: the reader is not an imbecile.
2672 The reader is merely lost; point them in the right direction, and they
2673 can take it from there.
2676 Tips for the English Version
2680 \begin_inset LatexCommand \label{sec:english-only}
2684 When contributing to the primary --- i.\SpecialChar ~
2686 the English language version ---
2687 of the LyX manuals, keep the following in mind.
2688 \layout Subsubsection
2690 Write as if You're Talking with a Friend.
2694 Think that way when you write.
2695 Play the dialogue in your mind.
2698 Be as informal as you please (without being rude).
2699 \layout Subsubsection
2701 AVOID the Passive Voice
2705 \begin_inset Quotes eld
2708 It is felt that this name best explains the command's purpose.
2709 \begin_inset Quotes erd
2712 We know full well who wrote the command:
2713 \begin_inset Quotes eld
2716 The LyX Team felt ...
2717 \begin_inset Quotes erd
2721 \begin_inset Quotes eld
2725 \begin_inset Quotes erd
2731 Things don't happen by magic - somebody or something did it.
2732 Only politicians use the passive voice to cover up who did something.
2733 If LyX reformats a paragraph, write,
2734 \begin_inset Quotes eld
2737 LyX reformatted the paragraph.
2738 \begin_inset Quotes erd
2745 makes changes, write,
2746 \begin_inset Quotes eld
2753 changes the document.
2754 \begin_inset Quotes erd
2761 Rule of thumb: any sentence you can express as,
2762 \begin_inset Quotes eld
2766 \begin_inset Quotes erd
2770 \begin_inset Quotes eld
2774 \begin_inset Quotes erd
2782 We all hear way, way too much garbage English on the TV every day in the
2784 Some people think it makes speech better.
2786 It makes speech baroque, if not outright byzantine.
2787 With a little effort, you can wean yourself off of it.
2792 will make you rewrite
2794 anything in the passive voice.
2795 It's awkward and hard to read.
2798 Note to non-Americans:
2802 Using passive voice is generally considered bad style in the U.\SpecialChar ~
2805 too easy to obfuscate your words with it.
2806 It also bloats sentences, often unnecessarily.
2808 \layout Subsubsection
2814 In English, there is a grammatical error known as the
2815 \begin_inset Quotes eld
2819 \begin_inset Quotes erd
2822 The classic example of a run-on sentence is 7 clauses strung together with
2824 \begin_inset Quotes eld
2828 \begin_inset Quotes erd
2831 There are, however, less obvious run-on sentences, ones using too many
2832 subordinate clauses.
2833 Such sentences may look elegant because they are complex.
2834 However, they are also extremely difficult to read because they are so
2838 In general, stick to short sentences in written English.
2839 Getting rid of passive voice (
2840 \begin_inset Quotes eld
2843 \SpecialChar \ldots{}
2844 was done by\SpecialChar \ldots{}
2846 \begin_inset Quotes erd
2849 ) shortens and simplifies them.
2850 Hacking apart sentences with many dependent clauses is another way to shorten
2852 There are ways to do this yet still have a smooth-flowing paragraph.
2855 While I'm talking about paragraphs, I'll apply the
2856 \begin_inset Quotes eld
2860 \begin_inset Quotes erd
2863 motto to them, as well.
2864 At the time I started with the manuals (and this Style Sheet), I didn't
2865 pay too much attention to paragraph size.
2866 I've since become a big proponent of short paragraphs, with one idea per
2868 While long, flowing, multi-concept paragraphs can be nice in novels, we're
2870 Our goal is rapid information location and comprehension, not a literary
2874 There is a single exception to the short sentence, short paragraph rule.
2875 Particularly complex ideas may need more
2876 \begin_inset Quotes eld
2880 \begin_inset Quotes erd
2883 However, you shouldn't encounter such complex ideas often when documenting
2885 Try to keep things short, and use your judgement as needed.
2888 To reiterate, yet again, something I said before:
2891 When in doubt, compromise.
2894 When in doubt, use good judgement.
2897 Hopefully, you've got the idea (grin).
2903 Rules of the Translating Trade
2906 While translating anything, there are certain
2907 \begin_inset Quotes eld
2911 \begin_inset Quotes erd
2915 They will help you greatly.
2916 \layout Subsubsection
2918 Translate one paragraph at a time.
2921 Most people translate word by word.
2922 Clearly, you lose all context if you do that.
2923 A word may have multiple meanings.
2924 You can't tell which unless you look at the rest of the sentence.
2927 There is another level to the context issue, however.
2928 Your dictionary may translate multiple English words the same way.
2929 All those words mean
2934 Each one, however, covers a different shade of meaning, a different mood
2936 It is often difficult to resolve those shades of meaning in the context
2937 of even one sentence.
2938 A paragraph, however, will provide that context.
2939 \layout Subsubsection
2941 You will not translate it correctly on the first try.
2944 Alright, I admit that you may be able to translate some of the sentences
2946 If you know a language well, you may even understand over half of the text.
2947 Nevertheless, overconfidence can lead you astray.
2948 There will be some sentences, no matter how few, that will simply confound
2952 It is generally a good idea to make multiple passes over a paragraph you're
2954 Even if you translate the entire paragraph on the first pass, make a second
2956 You'll often improve upon your first attempt.
2957 \layout Subsubsection
2959 When in doubt, write down all of the meanings for a word.
2962 You can often translate tricky parts of a text using the context of the
2963 surrounding sentences.
2964 So, if you hit a word or phrase you don't know, translate it more than
2966 Picking the most likely translations, summarize them in one to three words
2968 \begin_inset Quotes eld
2972 \begin_inset Quotes erd
2977 \layout Subsubsection
2979 Using context, fix the meanings on the next pass.
2982 This is where your multiple translations of a single word become useful.
2983 Using the other sentences you translated, you can now translate that mystery--s
2984 entence without reconsulting your dictionary.
2985 \layout Subsubsection
2987 Fix the grammar only after you've finished translating the sentence.
2990 If there's a mystery phrase in the middle of a sentence, you can't translate
2991 the entire sentence.
2992 Why grammatically rearrange the words you translated already? You may need
2993 to restructure the sentence a second time once you figure out how to translate
2994 that mystery phrase.
2995 Better to wait until you've completely translated the sentence to clean
2997 That way, you do so only once.
2998 \layout Subsubsection
3000 If you can't translate it, skip it and come back to it on the next pass.
3003 Remember the earlier discussion of context and its immense usefulness? There
3004 is no sin in making multiple passes over a tricky passage.
3005 \layout Subsubsection
3007 Translate the meaning first.
3011 The information content of the text under translation is the most important
3013 This is especially important for a manual, where the information
3017 important part of the original document.
3018 Lose that, and you lose the very point of performing the translation.
3021 Tips for the Translators
3024 Those of you contributing to a translation of the LyX manuals must follow
3025 a modified set of rules.
3026 The first few rules are analogous to those in section\SpecialChar ~
3028 \begin_inset LatexCommand \ref{sec:english-only}
3033 There are additional rules and regulations that follow those first few.
3035 \layout Subsubsection
3037 Write as if you are explaining LyX to a colleague you know well.
3040 Think that way when you write.
3041 Play the dialogue in your mind.
3044 Use a conversational style in your writing.
3045 Pretend you are teaching LyX to a colleague you know well.
3048 Use a style that is polite without being too formal.
3049 If, in your culture, informal language is appropriate to use with a colleague,
3050 use informal speech in the translation of the manual.
3051 \layout Subsubsection
3053 AVOID Snobby, Academic, Specialized, or
3054 \begin_inset Quotes eld
3058 \begin_inset Quotes erd
3065 In English, the passive voice appears formal, dry, barren.
3066 It also often adds unnecessary complexity.
3067 In other langauges, however, this is not the case.
3068 There is nothing wrong with passive voice, and people use it frequently
3069 in everyday conversation.
3070 Nevertheless, your translation of the LyX manuals must avoid
3071 \begin_inset Quotes eld
3075 \begin_inset Quotes erd
3081 In Germany, there is a magazine known as
3082 \begin_inset Quotes gld
3086 \begin_inset Quotes grd
3089 The writing in it is so complex, it is extremely difficult for non-native
3090 German speakers to understand.
3091 While sophisticated, the writing style of
3092 \begin_inset Quotes gld
3096 \begin_inset Quotes grd
3099 is not what a German uses in everyday conversation.
3100 Nor is the writing style for a Russian mathematics journal.
3101 Such specialized or overly-sophisticated styles are
3102 \begin_inset Quotes eld
3106 \begin_inset Quotes erd
3109 in the sense that they are seldom used by normal people in everyday speech.
3112 We who write the LyX manuals, original or translated, seek to
3117 If we write in a style only a few people use, and use seldomly, we will
3119 Use a writing style that mirrors everyday speech (without being vulgar,
3122 \layout Subsubsection
3124 Keep the Writing Simple.
3127 For the English version, I wrote,
3128 \begin_inset Quotes eld
3131 Use short sentences and short paragraphs.
3132 \begin_inset Quotes erd
3135 What if, however, short sentences and paragraphs are something only children
3136 use in your language? What if, in yet another language, short sentences
3137 imply rudeness? Naturally, you would not want to use them in your translation.
3140 Nevertheless, the translations of the LyX manuals should be as clear as
3142 So, for our international colleagues, we apply this rule: Keep your sentences
3143 and paragraphs as short as makes sense.
3146 Remember: we're translating manuals here, folks.
3147 Our goal is rapid information location and comprehension, not a literary
3149 Try to keep your writing concise yet smooth-flowing.
3150 And use your judgement as needed:
3153 When in doubt, compromise.
3156 When in doubt, use good judgement.
3157 \layout Subsubsection
3159 Translators must follow the Style Sheet, too!
3162 Everything in this manual ---
3164 except section\SpecialChar ~
3166 \begin_inset LatexCommand \ref{sec:english-only}
3172 --- applies to every LyX documenter, no matter what the language.
3173 \layout Subsubsection
3175 Translators must read the Style Sheet Supplement for their language.
3178 For every translation project, there is a Supplement to the Style Sheet.
3184 DocStyle_Supplement_<cn>.lyx
3187 \SpecialChar \ldots{}
3189 \begin_inset Quotes eld
3197 \begin_inset Quotes erd
3200 is your language's two-letter locale code.
3201 The Translation Project Chief for your language wrote this.
3202 If he hasn't, pester him to do so! <
3207 \layout Subsubsection
3209 The English versions of the manuals are not Sacred Text.
3212 You do not need to translate everything word for word.
3213 In fact, you shouldn't.
3214 Keep to the spirit of the originals, not the letter.
3215 Be as creative as you want, as long as you
3223 convey all of the information contained in the English versions.
3224 \layout Subsubsection
3226 Any information in the LyX manuals must also be in the translations.
3230 \begin_inset LatexCommand \label{sec:accuracy}
3234 This falls under translating the orignals accurately and completely.
3238 Omitting any feature description is
3245 Misrepresenting or misdescribing any LyX feature or operation
3256 outpace the original.
3258 If no one has documented new feature in the primary LyX manuals (i.\SpecialChar ~
3261 versions), do not do so in the translations.
3262 If you're really looking for something to do, either:
3266 \SpecialChar \ldots{}
3267 focus on translating something you haven't yet,
3272 \SpecialChar \ldots{}
3273 update or repair the primary manual.
3276 If you cannot or do not want to do one of the above, then take a break.
3278 Wait for the main manuals to catch up before translating anything else.
3280 \layout Subsubsection
3282 What you cannot translate, you may omit (usually).
3285 Prepositions, idioms, metaphors, slang, Oh My! There's a jungle of potentially
3286 untranslatable text you may face.
3287 Happily, none of these untranslatables are essential to the original text\SpecialChar \ldots{}
3290 If you can't translate a phrase or two, try omitting them.
3291 If the rest of the paragraph still makes sense, then don't worry about
3295 There may be special cases where omitting part of a sentence or paragraph
3296 violates rule\SpecialChar ~
3298 \begin_inset LatexCommand \ref{sec:accuracy}
3307 You must try and translate those tricky spots.
3308 \layout Subsubsection
3310 Translators may add their own fluff to the information content.
3313 After you do strip away all of the idioms, metaphors, slang, humor, and
3315 \begin_inset Quotes eld
3319 \begin_inset Quotes erd
3322 you may find that your translated manual is dull and dry.
3323 Why not add your own fluff? Add text that makes the manual a pleasure to
3324 read, that engages the reader.
3325 It may take the form of humor, or metaphors, or sayings.
3326 Whatever you add, it should be
3327 \begin_inset Quotes eld
3331 \begin_inset Quotes erd
3334 It should not clash with the explanation of LyX features and functions.
3337 For Translation Project Chiefs
3338 \layout Subsubsection
3340 The First Is In Charge
3343 If you were the first person to start translating the manuals, you're the
3344 LyXDoc Translation Project Chief for your language.
3349 person translating the LyXDocs, that automatically makes you the Translation
3353 Amongst other things, that means that you must read this section and perform
3354 the tasks described here.
3357 If you are a member of a LyX Documentation Translation Team, but
3361 its Chief, you may stop reading.
3362 The remainder of this section will be of no interest to you.
3363 If you came to the Style Sheet from the Supplement for your language, you
3367 If you have not read the Style Sheet Supplement for your language, you should
3370 \layout Subsubsection
3372 Read the Style Sheet
3375 No documenter is excused from following the Style Sheet, not even a Translation
3383 important that the Translation Project Chiefs read the Style Sheet.
3384 \layout Subsubsection
3386 Make your translators read the Style Sheet
3389 No documenter is excused from following the Style Sheet.
3392 Since your translation team is translating, they know
3397 Therefore, they should be able to read the Style Sheet.
3398 \layout Subsubsection
3401 \begin_inset Quotes eld
3405 \begin_inset Quotes erd
3411 There are parts of this Style Sheet that are English-specific.
3412 I have tried to provide a general, language-independent description of
3413 certain details in this section.
3414 Unfortunately, that general description doesn't cover the specifics of
3419 That's where you, as head of a LyXDoc Translation Team, come in.
3422 Every Translation Team Chief is
3426 to write a Supplement to the official Documentation Style Sheet, with specifics
3427 issues affecting your language.
3428 (You are, after all, the LyX Team expert on your native tongue.) Follow
3429 these guidelines when writing the Supplement:
3436 DocStyle_Supplement_<cn>.lyx
3440 \SpecialChar \ldots{}
3442 \begin_inset Quotes eld
3450 \begin_inset Quotes erd
3453 is the two-letter code for your language.
3454 This is the same two-letter code that is part of the filenames for the
3457 \begin_inset Quotes eld
3465 \begin_inset Quotes erd
3469 \begin_inset Quotes eld
3477 \begin_inset Quotes erd
3481 \begin_inset Quotes eld
3489 \begin_inset Quotes erd
3495 Do not worry about where the file goes.
3496 The CVS maintainers will locate all documentation and Style Sheet Supplements
3497 in an appropriate place.
3500 Document Properties:
3504 For consistency, use the same document class and other document properties
3511 Specifically, check the settings in the
3516 Use those in your Supplement.
3522 Exceptions: Use margins, indentation/paragraph separation, language, and
3523 encoding appropriate for your language.
3527 The title of the Supplement:
3531 The title will use the
3532 \begin_inset Quotes eld
3540 \begin_inset Quotes erd
3543 paragraph environment.
3544 In your native tongue, the title will read:
3550 Documentation Project Style Sheet:
3552 Supplement for the <foo> Translation Project
3556 \begin_inset Quotes eld
3564 \begin_inset Quotes erd
3567 with the name of your language.)
3571 If, in your language,
3572 \begin_inset Quotes eld
3576 \begin_inset Quotes erd
3580 \begin_inset Quotes eld
3584 \begin_inset Quotes erd
3589 \begin_inset Quotes eld
3593 \begin_inset Quotes erd
3597 \begin_inset Quotes eld
3601 \begin_inset Quotes erd
3604 have somewhat different meanings.
3605 An appendix is an extra part of a document.
3606 A supplement is an extra document.
3611 Choose a replacement word accordingly.
3612 Whatever you choose to replace
3613 \begin_inset Quotes eld
3617 \begin_inset Quotes erd
3620 it must not have the same translation as the word
3621 \begin_inset Quotes eld
3625 \begin_inset Quotes erd
3633 Below the title, in the
3634 \begin_inset Quotes eld
3642 \begin_inset Quotes erd
3645 paragraph environment, place your name.
3649 There will be no abstract.
3661 The first thing you will do is strongly yet politely encourage the reader
3663 \begin_inset Quotes eld
3667 \begin_inset Quotes erd
3670 and go read the Style Sheet.
3671 The reader should not return to the
3672 \begin_inset Quotes eld
3676 \begin_inset Quotes erd
3683 understood the Style Sheet proper.
3685 \layout Subsubsection
3687 Keep the Supplement Succinct
3690 This Style Sheet is already very detailed.
3691 DocTeam members all have a lot to read.
3692 We don't want to place an extra burden on translators.
3693 Therefore, keep the Supplement as short as you can without losing information.
3694 \layout Subsubsection
3703 will be about font issues\SpecialChar \ldots{}
3705 Not all Translation Project Chiefs will need to deal with this issue.
3723 Emphasized (actually Italics)
3738 Noun (actually Small Caps)
3741 \SpecialChar \ldots{}
3742 certainly exist for all languages that use the Roman alphabet.
3743 Do they exist, however, for Greek? How about Cyrillic? These different
3744 fonts almost certainly do not exist for Devanagri, Chinese, Korean, Japanese,
3745 Hebrew, Arabic, and other scripts.
3749 There will be some languages for which following the font-scheme specified
3750 in this Style Sheet may not be possible.
3751 If you are the Translation Project Chief for such a language, you have
3755 In the font section of the Supplement, you will provide a new typographic
3756 style, designed specifically for your writing system.
3757 For consistency, the title of this section in every Supplement should translate
3759 \begin_inset Quotes eld
3763 \begin_inset Quotes erd
3766 Before adding anything to this section, however, determine what this new
3767 typographic style will look like.
3768 Stick to the font specifications in this Style Sheet as best you can, whenever
3770 When you cannot, use the following suggestions:
3774 \begin_inset Quotes eld
3778 \begin_inset Quotes erd
3785 What to do when a font doesn't exist:
3788 \labelwidthstring MMMMMMMM
3790 Roman Use the font that typesetters in your language use for printing books,
3792 This will typically be the default font LyX (and LaTeX) uses in your language.
3794 \labelwidthstring MMMMMMMM
3801 This is for people's names.
3802 If there is special font for names in your alphabet/writing system, use
3803 it in place of this.
3804 Otherwise, write names in the default font, typeset according to the rules
3807 \labelwidthstring MMMMMMMM
3813 Use the font with which your language normally emphasizes text.
3817 Use a font that is different from your language's equivalent of
3822 In other words, your
3830 and similar headers will be in one typeface, perhaps
3835 Whatever that font is, avoid using it for
3842 \labelwidthstring MMMMMMMM
3848 Pick up a computer program manual written in your language.
3849 It will use a special typeface for filenames, for command names, program
3851 Use that same font in place of
3857 \labelwidthstring MMMMMMMM
3864 Pick any other font that is different from the ones you're using in place
3878 If you're unlucky, and your language's writing system doesn't have enough
3879 fonts, use the same font you picked to replace
3884 Only do this, however, if your alphabet/writing system has very few fonts
3887 \labelwidthstring MMMMMMMM
3894 nderlined\SpecialChar ~
3898 Don't worry about this one.
3902 If you use some special font on-screen to highlight the accelerator keys
3903 for menus, buttons, and other widgets, you might want to mimic that in
3905 It is not required, however.
3906 Therefore, if you can't mimic this typographic convention in your native
3907 writing system, don't.
3912 Note that you may also want to describe fonts that your Translation Team
3918 For example, no contributer to the English/European versions may ever use
3923 , as this is used for section-headings.
3924 Since there are enough other fonts, we who use the Roman alphabet and its
3925 variants can afford to omit
3933 Once you have determined which fonts in your native writing system will
3934 replace one or more of the above, propose it to the LyX Developer's Mailing
3936 You may receive valuable feedback this way.
3937 If not, that's okay.
3938 If no one can read your writing system, and therefore cannot comment, that's
3940 Go ahead and describe the typographic standard you created in the Supplement.
3944 Remember: stick to the font specifications in this Style Sheet as best you
3945 can, whenever you can.
3946 \layout Subsubsection
3948 Quoting Style and the
3960 The next section of the Supplement will cover the issue of quoting.
3961 Give it an appropriate title.
3964 One of the first things you should do in that section is resolve the following
3976 is the correct paragraph environment for your language.
3979 In the Supplement, specify which one to use.
3982 English has its own typography and style for quoting others.
3983 The Style Sheet describes that typography in section\SpecialChar ~
3985 \begin_inset LatexCommand \ref{sec:quote}
3990 Your language also has a specific typography and style for quotations.
3991 Describe that style in this section of the Supplement, too.
3992 Naturally, you do not need to go overboard.
3993 Section\SpecialChar ~
3995 \begin_inset LatexCommand \ref{sec:quote}
3999 of this Style Sheet is overly detailed for a good reason.
4000 Authors of the primary LyX manuals are not necessarily native English speakers.
4001 The members of your Translation Team, however, will all likely be native
4002 speakers of your language.
4003 Therefore, discuss proper quoting style of your native tongue to an appropriate
4005 \layout Subsubsection
4007 Translations of Style Sheet Terminology
4010 In the Supplement, you must provide a standard translation of certain key
4011 phrases for the members of your Translation Team.
4012 Place this in a section following the one about quotations.
4015 In particular, standardize the translations of the phrases:
4032 change the typography of the
4033 \begin_inset Quotes eld
4037 \begin_inset Quotes erd
4041 \begin_inset Quotes eld
4045 \begin_inset Quotes erd
4049 Only provide a translation for the opening phrases.
4050 Insist that the members of your Translation Team use these two tools correctly.
4053 While we are discussing proper use of the
4054 \begin_inset Quotes eld
4058 \begin_inset Quotes erd
4062 \begin_inset Quotes eld
4066 \begin_inset Quotes erd
4069 in translations, let's talk about a related problem.
4071 \begin_inset Quotes eld
4075 \begin_inset Quotes erd
4078 is meant to be a note from the author of a manual to the reader.
4079 In the case of a translation, however, the translator is
4083 the author! How then should a translator translate an
4084 \begin_inset Quotes eld
4088 \begin_inset Quotes erd
4094 You, as Translation Project Chief, must decide.
4095 You can forbid translation of pre-existing
4096 \begin_inset Quotes eld
4100 \begin_inset Quotes erd
4103 omitting them entirely instead.
4104 You could tell your translators to read any
4105 \begin_inset Quotes eld
4109 \begin_inset Quotes erd
4112 they may encounter, understand it, then write their own
4113 \begin_inset Quotes eld
4117 \begin_inset Quotes erd
4120 about the situation, not as a translation but as a personal opinion.
4121 You may decide on some other policy.
4124 Whatever you decide, codify your policy in its own
4133 Place it near the section where you translated
4134 \begin_inset Quotes eld
4138 \begin_inset Quotes erd
4142 \begin_inset Quotes eld
4146 \begin_inset Quotes erd
4150 \layout Subsubsection
4155 After describing all of the previous issues, create a new
4161 \begin_inset Quotes eld
4164 Lost in Translation,
4165 \begin_inset Quotes erd
4168 or something similar.
4171 In this section you will discuss any common English metaphors, humor, connotatio
4172 n, or other difficult to translate text.
4173 Try to balance brevity and completeness.
4182 s --- to each specific issue.
4183 \layout Subsubsection
4185 \SpecialChar \ldots{}
4187 \begin_inset Quotes eld
4191 \begin_inset Quotes erd
4194 \SpecialChar \ldots{}
4198 Throughout the manuals, the DocTeam has used the following sentences:
4201 If you haven't read the <
4205 > manual, go read it.
4209 This sentence will be tricky to translate, since it contains non-translatable
4215 for this issue in your
4216 \begin_inset Quotes eld
4220 \begin_inset Quotes erd
4225 \begin_inset Quotes eld
4228 \SpecialChar \ldots{}
4229 Yes, we mean now\SpecialChar \ldots{}
4231 \begin_inset Quotes erd
4234 sentences, then present a translation, along with any explanation you feel
4238 Here's what those two sentences, sitting alone in their own paragraph, mean:
4241 The first sentence uses the English conditional followed by an imperative.
4242 We, as the LyX team, are commanding the reader to go back to another manual.
4247 manual is a prerequisite for all of the other manuals.
4248 The conditional clause preceeding the command means,
4249 \begin_inset Quotes eld
4252 You do not need to perform this command twice.
4253 \begin_inset Quotes erd
4259 The second sentence adds force to the command.
4260 Culturally, the imperative tense of a verb in English is not necessarily
4262 The way we wrote that command,
4263 \begin_inset Quotes eld
4267 \begin_inset Quotes erd
4270 is firm, yet polite.
4271 The reader may choose to ignore it.
4273 \begin_inset Quotes eld
4277 \begin_inset Quotes erd
4280 we imply two things.
4282 \begin_inset Quotes eld
4286 \begin_inset Quotes erd
4290 That second sentence reinforces the command, making it a bit harder to
4292 Second, the sentence itself implies a certain sense of urgency.
4293 You cannot merely wait until later to fulfill that command.
4294 The brief pragraph, and its sudden end, add still further subtle reinforcement
4296 \begin_inset Quotes eld
4299 go do the required reading before using this manual.
4300 \begin_inset Quotes erd
4306 Note that all of this commanding and reinforcing is nevertheless in a polite
4308 Furthermore, it is in a subtle form.
4309 We are commanding the reader to do something, but in an indirect fashion.
4310 This way, the reader does not feel like we are bullying him.
4311 \layout Subsubsection
4317 In the same part of the Supplement that you place the
4318 \begin_inset Quotes eld
4321 \SpecialChar \ldots{}
4322 Yes, we mean now\SpecialChar \ldots{}
4324 \begin_inset Quotes erd
4327 translation, discuss the English version's use of
4328 \begin_inset Quotes eld
4332 \begin_inset Quotes erd
4338 You see, here in America, we often say that everything is permitted unless
4339 explicitly banned by law.
4340 As a result, manuals for computer software are frequently ignored and the
4341 software subsequently blamed for not being
4342 \begin_inset Quotes eld
4346 \begin_inset Quotes erd
4349 This is where the use of
4350 \begin_inset Quotes eld
4354 \begin_inset Quotes erd
4361 We who wrote the manuals added sentences insisting that the reader not ignore
4362 certain parts of the documentation.
4363 We wrote in a manner that was polite, yet firmly asserted that the user
4364 was misusing the software if he did not read the manual correctly.
4365 We did not, however, want to sound threatening, coercive, or bullying.
4368 In your culture, cajoling the reader into using the manuals correctly may
4370 It may, in fact, be outright rude.
4371 Additionally, translating the firm-but-convincing bits may not work.
4372 The translation may sound weird, or rude, or hostile.
4373 Therefore, you and your translation team will face many sentences that
4374 you cannot translate.
4377 You, the Translation Project Chief, must discuss this issue.
4378 Try and find parts of the original manuals where some friendly but firm
4379 convincing does not translate properly.
4380 Use these cases as the basis for examples of the problem.
4381 Be sure to then offer a solution (i.\SpecialChar ~
4383 how you want such sentences translated.)
4384 If stumped, ask for help on the LyX Developer's List.
4385 \layout Subsubsection
4390 You can add more sections to the Supplement if you need to discuss other
4392 There may be policies or guidelines that you want to set for your Translation
4394 Be careful, however! Keep the Supplement