diff options
Diffstat (limited to 'documentation/content/en/books/fdp-primer/writing-style/_index.po')
| -rw-r--r-- | documentation/content/en/books/fdp-primer/writing-style/_index.po | 883 |
1 files changed, 883 insertions, 0 deletions
diff --git a/documentation/content/en/books/fdp-primer/writing-style/_index.po b/documentation/content/en/books/fdp-primer/writing-style/_index.po new file mode 100644 index 0000000000..586454bd51 --- /dev/null +++ b/documentation/content/en/books/fdp-primer/writing-style/_index.po @@ -0,0 +1,883 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2023-07-15 16:42-0300\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" +"Language-Team: LANGUAGE <LL@li.org>\n" +"Language: \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#. type: YAML Front Matter: description +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:1 +#, no-wrap +msgid "Writing Style and some conventions used in the FreeBSD Documentation Project" +msgstr "" + +#. type: YAML Front Matter: title +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:1 +#, no-wrap +msgid "Chapter 12. Writing Style" +msgstr "" + +#. type: Title = +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:13 +#, no-wrap +msgid "Writing Style" +msgstr "" + +#. type: Title == +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:51 +#, no-wrap +msgid "Tips" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:57 +msgid "" +"Technical documentation can be improved by consistent use of several " +"principles. Most of these can be classified into three goals: _be clear_, " +"_be complete_, and _be concise_. These goals can conflict with each other. " +"Good writing consists of a balance between them." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:59 +#, no-wrap +msgid "Be Clear" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:64 +msgid "" +"Clarity is extremely important. The reader may be a novice, or reading the " +"document in a second language. Strive for simple, uncomplicated text that " +"clearly explains the concepts." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:68 +msgid "" +"Avoid flowery or embellished speech, jokes, or colloquial expressions. " +"Write as simply and clearly as possible. Simple text is easier to " +"understand and translate." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:73 +msgid "" +"Keep explanations as short, simple, and clear as possible. Avoid empty " +"phrases like \"in order to\", which usually just means \"to\". Avoid " +"potentially patronizing words like \"basically\". Avoid Latin terms like " +"\"i.e.,\" or \"cf.\", which may be unknown outside of academic or scientific " +"groups." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:77 +msgid "" +"Write in a formal style. Avoid addressing the reader as \"you\". For " +"example, say \"copy the file to [.filename]#/tmp#\" rather than \"you can " +"copy the file to [.filename]#/tmp#\"." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:84 +msgid "" +"Give clear, correct, _tested_ examples. A trivial example is better than no " +"example. A good example is better yet. Do not give bad examples, " +"identifiable by apologies or sentences like \"but really it should never be " +"done that way\". Bad examples are worse than no examples. Give good " +"examples, because _even when warned not to use the example as shown_, the " +"reader will usually just use the example as shown." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:87 +msgid "" +"Avoid _weasel words_ like \"should\", \"might\", \"try\", or \"could\". " +"These words imply that the speaker is unsure of the facts, and create doubt " +"in the reader." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:89 +msgid "" +"Similarly, give instructions as imperative commands: not \"you should do " +"this\", but merely \"do this\"." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:91 +#, no-wrap +msgid "Be Complete" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:97 +msgid "" +"Do not make assumptions about the reader's abilities or skill level. Tell " +"them what they need to know. Give links to other documents to provide " +"background information without having to recreate it. Put yourself in the " +"reader's place, anticipate the questions they will ask, and answer them." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:99 +#, no-wrap +msgid "Be Concise" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:104 +msgid "" +"While features should be documented completely, sometimes there is so much " +"information that the reader cannot easily find the specific detail needed. " +"The balance between being complete and being concise is a challenge. One " +"approach is to have an introduction, then a \"quick start\" section that " +"describes the most common situation, followed by an in-depth reference " +"section." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:106 +#, no-wrap +msgid "Guidelines" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:109 +msgid "" +"To promote consistency between the myriad authors of the FreeBSD " +"documentation, some guidelines have been drawn up for authors to follow." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:110 +#, no-wrap +msgid "Use American English Spelling" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:114 +msgid "" +"There are several variants of English, with different spellings for the same " +"word. Where spellings differ, use the American English variant. \"color\", " +"not \"colour\", \"rationalize\", not \"rationalise\", and so on." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:119 +msgid "" +"The use of British English may be accepted in the case of a contributed " +"article, however the spelling must be consistent within the whole document. " +"The other documents such as books, web site, manual pages, etc. must use " +"American English." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:121 +#, no-wrap +msgid "Do not use contractions" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:125 +msgid "" +"Do not use contractions. Always spell the phrase out in full. \"Don't use " +"contractions\" is wrong." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:127 +msgid "" +"Avoiding contractions makes for a more formal tone, is more precise, and is " +"slightly easier for translators." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:128 +#, no-wrap +msgid "Use the serial comma" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:131 +msgid "" +"In a list of items within a paragraph, separate each item from the others " +"with a comma. Separate the last item from the others with a comma and the " +"word \"and\"." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:133 +msgid "For example:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:135 +msgid "This is a list of one, two and three items." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:137 +msgid "" +"Is this a list of three items, \"one\", \"two\", and \"three\", or a list of " +"two items, \"one\" and \"two and three\"?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:139 +msgid "It is better to be explicit and include a serial comma:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:141 +msgid "This is a list of one, two, and three items." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:141 +#, no-wrap +msgid "Avoid redundant phrases" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:144 +msgid "" +"Do not use redundant phrases. In particular, \"the command\", \"the file\", " +"and \"man command\" are often redundant." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:146 +msgid "For example, commands:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:148 +msgid "Wrong: Use the `git` command to update sources." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:150 +msgid "Right: Use `git` to update sources." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:152 +msgid "Filenames:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:154 +msgid "Wrong: ... in the filename [.filename]#/etc/rc.local#..." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:156 +msgid "Right: ... in [.filename]#/etc/rc.local#..." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:158 +msgid "" +"Manual page references (the second example uses `man:[]` with the man:csh[1] " +"entity):" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:160 +msgid "Wrong: See `man csh` for more information." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:162 +msgid "Right: See man:csh[1]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:164 +msgid "" +"For more information about writing style, see http://www.bartleby.com/141/" +"[Elements of Style] by William Strunk." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:166 +#, no-wrap +msgid "Style Guide" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:169 +msgid "" +"To keep the source for the documentation consistent when many different " +"people are editing it, please follow these style conventions." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:171 +#, no-wrap +msgid "One sentence per line" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:176 +msgid "" +"Use Semantic Line Breaks in the documentation, a technique called \"one " +"sentence per line\". The idea of this technique is to help the users to " +"write and read documentation. To get more information about this technique " +"read the link:https://sembr.org/[Semantic Line Breaks] page." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:178 +msgid "This is an example which does not use \"one sentence per line\"." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:181 +#, no-wrap +msgid "All human beings are born free and equal in dignity and rights. They are endowed with reason and conscience and should act towards one another in a spirit of brotherhood.\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:184 +msgid "And this is an example which uses the technique." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:188 +#, no-wrap +msgid "" +"All human beings are born free and equal in dignity and rights.\n" +"They are endowed with reason and conscience and should act towards one another in a spirit of brotherhood.\n" +msgstr "" + +#. type: Title == +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:191 +#, no-wrap +msgid "Acronyms" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:196 +msgid "" +"Acronyms should be defined the first time they appear in a document, as in: " +"\"Network Time Protocol (NTP)\". After the acronym has been defined, use " +"the acronym alone unless it makes more sense contextually to use the whole " +"term. Acronyms are usually defined only once per chapter or per document." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:198 +msgid "All acronyms should be enclosed using the ` character." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:200 +#, no-wrap +msgid "Special Character List" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:204 +msgid "" +"This list of special characters shows the correct syntax and the output when " +"used in FreeBSD documentation. If a character is not on this list, ask " +"about it on the {freebsd-doc}." +msgstr "" + +#. type: Table +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:209 +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:264 +#, no-wrap +msgid "Name" +msgstr "" + +#. type: Table +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:210 +#, no-wrap +msgid "Syntax" +msgstr "" + +#. type: Table +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:213 +#, no-wrap +msgid "Rendered" +msgstr "" + +#. type: Table +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:214 +#, no-wrap +msgid "Copyright" +msgstr "" + +#. type: Table +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:215 +#, no-wrap +msgid "+(C)+" +msgstr "" + +#. type: Table +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:217 +#, no-wrap +msgid "(C)" +msgstr "" + +#. type: Table +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:218 +#, no-wrap +msgid "Registered" +msgstr "" + +#. type: Table +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:219 +#, no-wrap +msgid "+(R)+" +msgstr "" + +#. type: Table +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:221 +#, no-wrap +msgid "(R)" +msgstr "" + +#. type: Table +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:222 +#, no-wrap +msgid "Trademark" +msgstr "" + +#. type: Table +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:223 +#, no-wrap +msgid "+(TM)+" +msgstr "" + +#. type: Table +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:225 +#, no-wrap +msgid "(TM)" +msgstr "" + +#. type: Table +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:226 +#, no-wrap +msgid "Em dash" +msgstr "" + +#. type: Table +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:227 +#, no-wrap +msgid "+--+" +msgstr "" + +#. type: Table +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:229 +#, no-wrap +msgid "--" +msgstr "" + +#. type: Table +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:230 +#, no-wrap +msgid "Ellipses" +msgstr "" + +#. type: Table +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:231 +#, no-wrap +msgid "+...+" +msgstr "" + +#. type: Table +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:233 +#, no-wrap +msgid "..." +msgstr "" + +#. type: Table +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:234 +#, no-wrap +msgid "Single right arrow" +msgstr "" + +#. type: Table +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:235 +#, no-wrap +msgid "+->+" +msgstr "" + +#. type: Table +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:237 +#, no-wrap +msgid "->" +msgstr "" + +#. type: Table +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:238 +#, no-wrap +msgid "Double right arrow" +msgstr "" + +#. type: Table +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:239 +#, no-wrap +msgid "+=>+" +msgstr "" + +#. type: Table +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:241 +#, no-wrap +msgid "=>" +msgstr "" + +#. type: Table +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:242 +#, no-wrap +msgid "Single left arrow" +msgstr "" + +#. type: Table +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:243 +#, no-wrap +msgid "+<-+" +msgstr "" + +#. type: Table +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:245 +#, no-wrap +msgid "<-" +msgstr "" + +#. type: Table +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:246 +#, no-wrap +msgid "Double left arrow" +msgstr "" + +#. type: Table +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:247 +#, no-wrap +msgid "+<=+" +msgstr "" + +#. type: Table +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:249 +#, no-wrap +msgid "<=" +msgstr "" + +#. type: Title == +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:252 +#, no-wrap +msgid "Linting with Vale" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:257 +msgid "" +"To maintain clarity and consistency across all documentation and website " +"pages, link:https://vale.sh[Vale] styles have been introduced in the " +"documentation tree. link:https://vale.sh[Vale] is a powerful linter for " +"writing customized rules and can be used in multiple scenarios. Currently " +"link:https://vale.sh[Vale] can be used as a command line tool, for CI/CD " +"pipelines, and integrated into an editor of choice." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:259 +msgid "" +"The following table describes the current rule names and their respective " +"severity." +msgstr "" + +#. type: Table +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:266 +#, no-wrap +msgid "Severity" +msgstr "" + +#. type: Table +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:267 +#, no-wrap +msgid "FreeBSD.BrandTerms" +msgstr "" + +#. type: Table +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:269 +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:287 +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:293 +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:296 +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:299 +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:302 +#, no-wrap +msgid "error" +msgstr "" + +#. type: Table +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:270 +#, no-wrap +msgid "FreeBSD.ConsciousLanguage" +msgstr "" + +#. type: Table +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:272 +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:278 +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:281 +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:284 +#, no-wrap +msgid "warning" +msgstr "" + +#. type: Table +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:273 +#, no-wrap +msgid "FreeBSD.Contractions" +msgstr "" + +#. type: Table +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:275 +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:290 +#, no-wrap +msgid "suggestion" +msgstr "" + +#. type: Table +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:276 +#, no-wrap +msgid "FreeBSD.EOLSpacing" +msgstr "" + +#. type: Table +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:279 +#, no-wrap +msgid "FreeBSD.Hang" +msgstr "" + +#. type: Table +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:282 +#, no-wrap +msgid "FreeBSD.Hyphens" +msgstr "" + +#. type: Table +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:285 +#, no-wrap +msgid "FreeBSD.Spacing" +msgstr "" + +#. type: Table +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:288 +#, no-wrap +msgid "FreeBSD.SuperfluousOptArgInLinks" +msgstr "" + +#. type: Table +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:291 +#, no-wrap +msgid "Vale.Avoid" +msgstr "" + +#. type: Table +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:294 +#, no-wrap +msgid "Vale.Repetition" +msgstr "" + +#. type: Table +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:297 +#, no-wrap +msgid "Vale.Spelling" +msgstr "" + +#. type: Table +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:300 +#, no-wrap +msgid "Vale.Terms" +msgstr "" + +#. type: Title === +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:305 +#, no-wrap +msgid "Current Vale Rules" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:311 +msgid "" +"FreeBSD.BrandTerms: According to the copyright rules of The FreeBSD " +"Foundation, *freebsd* should be written as *FreeBSD*. Similarly, every " +"major vendor and company has specific rules on writing their brand names and " +"trademarks. Care should be taken to be respectful to the brand value of " +"others and to take time to write PostgreSQL, Node.js, Let's Encrypt etc. " +"Missing brand names should be added to the [.filename]#.vale/styles/FreeBSD/" +"BrandTerms.yml# in the `doc` repository." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:313 +msgid "" +"FreeBSD.ConsciousLanguage: This rule proposes use of conscious language so " +"that sensitive words pointing to the color, age, race, or sexual orientation " +"of people are avoided where possible." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:316 +msgid "" +"FreeBSD.Contractions: Contracted words should not be used. This rule avoids " +"all contractions and suggests full words." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:318 +msgid "" +"FreeBSD.EOLSpacing: In most of the documents EOL spacing is present which is " +"not the desirable situation." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:321 +msgid "" +"FreeBSD.Hang: `Hang` is often used to mean that the application has stopped " +"responding. This rule proposes better wording." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:323 +msgid "" +"FreeBSD.Hyphens: Often adverbs ending with 'ly' are added with a hyphen " +"which is wrong." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:325 +msgid "" +"FreeBSD.Spacing: Often double spaces are hard to catch with the naked eye " +"and this is addressed here." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:327 +msgid "" +"FreeBSD.SuperfluousOptArgInLinks: Suggest to empty square brackets in `link:" +"` macros when the displayed text coincides with the URL." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:331 +msgid "" +"Vale.Avoid: Enforces the *DO NOT USE* vocabulary terms for The FreeBSD " +"Project. If any word is found that should not be in the documentation, the " +"word should be added to [.filename]#.vale/styles/Vocab/Terms/reject.txt# in " +"the `doc` repository. The list is empty at the moment." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:334 +msgid "" +"Vale.Repetition: Same words are often typed twice when leaving the keyboard " +"and rejoining the work again. This rule finds repeated words and warns the " +"users." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:337 +msgid "" +"Vale.Spelling: At the moment there is a mix of en_US and en_GB spellings in " +"the documentation and website. Vale comes with an in built dictionary from " +"which uses strictly en_US and do not accept the en_GB variant of any words." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:341 +msgid "" +"Vale.Terms: Enforces the *PREFERRED* vocabulary terms for The FreeBSD " +"Project. At the moment the list of terms is empty and the FreeBSD specific " +"terms will be added gradually. If any word is found to be correct and not " +"available in the dictionary the word should be added to the [.filename]#." +"vale/styles/Vocab/Terms/accept.txt# in the `doc` repository." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:343 +msgid "" +"More rules will be introduced in the upcoming days when and where required." +msgstr "" + +#. type: Title === +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:345 +#, no-wrap +msgid "Using Vale" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:349 +msgid "" +"link:https://vale.sh[Vale] can be used from the command line and from within " +"an editor or IDE. package:textproc/vale[] can be installed as following:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:353 +#, no-wrap +msgid "$ pkg install vale\n" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:356 +#, no-wrap +msgid "Using Vale on the command line" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:359 +msgid "" +"Assuming that the `doc` repository was cloned into [.filename]#~/doc# the " +"following commands are required to run:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:364 +#, no-wrap +msgid "" +"% cd ~/doc\n" +"% vale .\n" +msgstr "" + +#. type: delimited block = 6 +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:370 +msgid "" +"link:https://vale.sh[Vale] is a CPU and memory intensive program due to the " +"nature of the application and can take a while to show any output on the " +"screen. A better way to run the application is on specific folders or files " +"rather than the entire `doc` repository as that is already done in the CI " +"pipeline." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:373 +#, no-wrap +msgid "Using Vale in editors" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:377 +msgid "" +"link:https://vale.sh[Vale] works with major mainstream editors like package:" +"editors/vim[], package:editors/emacs[], package:editors/vscode[]. At the " +"moment the necessary configuration for package:editors/vim[] is described in " +"crossref:editor-config[editor-config-vim, Vim]. A configuration for package:" +"editors/emacs[] is being worked on." +msgstr "" |