Path: blob/main/documentation/content/en/books/fdp-primer/writing-style/_index.po
18099 views
# 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: 2025-05-01 19:56-0300\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" "Language-Team: LANGUAGE <[email protected]>\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:14 #, no-wrap msgid "Writing Style" msgstr "" #. type: Title == #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:52 #, no-wrap msgid "Tips" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:58 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:60 #, no-wrap msgid "Be Clear" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:65 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:69 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:74 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:78 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:85 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:88 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:90 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:92 #, no-wrap msgid "Be Complete" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:98 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:100 #, no-wrap msgid "Be Concise" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:105 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:107 #, no-wrap msgid "Guidelines" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:110 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:111 #, no-wrap msgid "Use American English Spelling" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:115 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:120 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:122 #, no-wrap msgid "Do not use contractions" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:126 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:128 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:129 #, no-wrap msgid "Use the serial comma" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:132 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:134 msgid "For example:" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:136 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:138 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:140 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:142 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:142 #, no-wrap msgid "Avoid redundant phrases" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:145 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:147 msgid "For example, commands:" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:149 msgid "Wrong: Use the `git` command to update sources." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:151 msgid "Right: Use `git` to update sources." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:153 msgid "Filenames:" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:155 msgid "Wrong: ... in the filename [.filename]#/etc/rc.local#..." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:157 msgid "Right: ... in [.filename]#/etc/rc.local#..." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:159 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:161 msgid "Wrong: See `man csh` for more information." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:163 msgid "Right: See man:csh[1]." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:165 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:167 #, no-wrap msgid "Style Guide" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:170 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:172 #, no-wrap msgid "One sentence per line" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:177 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:179 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:182 #, 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:185 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:189 #, 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:192 #, no-wrap msgid "Acronyms" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:197 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:199 msgid "All acronyms should be enclosed using the ` character." msgstr "" #. type: Title == #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:201 #, no-wrap msgid "Special Character List" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:205 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:210 #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:265 #, no-wrap msgid "Name" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:211 #, no-wrap msgid "Syntax" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:214 #, no-wrap msgid "Rendered" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:215 #, no-wrap msgid "Copyright" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:216 #, no-wrap msgid "+(C)+" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:218 #, no-wrap msgid "(C)" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:219 #, no-wrap msgid "Registered" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:220 #, no-wrap msgid "+(R)+" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:222 #, no-wrap msgid "(R)" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:223 #, no-wrap msgid "Trademark" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:224 #, no-wrap msgid "+(TM)+" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:226 #, no-wrap msgid "(TM)" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:227 #, no-wrap msgid "Em dash" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:228 #, no-wrap msgid "+--+" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:230 #, no-wrap msgid "--" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:231 #, no-wrap msgid "Ellipses" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:232 #, no-wrap msgid "+...+" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:234 #, no-wrap msgid "..." msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:235 #, no-wrap msgid "Single right arrow" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:236 #, no-wrap msgid "+->+" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:238 #, no-wrap msgid "->" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:239 #, no-wrap msgid "Double right arrow" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:240 #, no-wrap msgid "+=>+" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:242 #, no-wrap msgid "=>" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:243 #, no-wrap msgid "Single left arrow" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:244 #, no-wrap msgid "+<-+" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:246 #, no-wrap msgid "<-" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:247 #, no-wrap msgid "Double left arrow" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:248 #, no-wrap msgid "+<=+" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:250 #, no-wrap msgid "<=" msgstr "" #. type: Title == #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:253 #, no-wrap msgid "Linting with Vale" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:258 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:260 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:267 #, no-wrap msgid "Severity" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:268 #, no-wrap msgid "FreeBSD.BrandTerms" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:270 #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:288 #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:294 #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:297 #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:300 #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:303 #, no-wrap msgid "error" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:271 #, no-wrap msgid "FreeBSD.ConsciousLanguage" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:273 #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:279 #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:282 #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:285 #, no-wrap msgid "warning" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:274 #, no-wrap msgid "FreeBSD.Contractions" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:276 #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:291 #, no-wrap msgid "suggestion" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:277 #, no-wrap msgid "FreeBSD.EOLSpacing" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:280 #, no-wrap msgid "FreeBSD.Hang" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:283 #, no-wrap msgid "FreeBSD.Hyphens" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:286 #, no-wrap msgid "FreeBSD.Spacing" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:289 #, no-wrap msgid "FreeBSD.SuperfluousOptArgInLinks" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:292 #, no-wrap msgid "Vale.Avoid" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:295 #, no-wrap msgid "Vale.Repetition" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:298 #, no-wrap msgid "Vale.Spelling" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:301 #, no-wrap msgid "Vale.Terms" msgstr "" #. type: Title === #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:306 #, no-wrap msgid "Current Vale Rules" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:312 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:314 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:317 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:319 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:322 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:324 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:326 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:328 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:332 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:335 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:338 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:342 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:344 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:346 #, no-wrap msgid "Using Vale" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:350 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:354 #, no-wrap msgid "$ pkg install vale\n" msgstr "" #. type: Title ==== #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:357 #, no-wrap msgid "Using Vale on the command line" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:360 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:365 #, no-wrap msgid "" "% cd ~/doc\n" "% vale .\n" msgstr "" #. type: delimited block = 6 #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:371 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:374 #, no-wrap msgid "Using Vale in editors" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:378 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 ""