Differential D37381 Diff 113105 documentation/content/en/books/fdp-primer/writing-style/_index.adoc

Changeset View

Standalone View

documentation/content/en/books/fdp-primer/writing-style/_index.adoc

Context not available.
	[[writing-style-linting-vale]]	[[writing-style-linting-vale]]
	== Linting with Vale	== Linting with Vale

	To maintain clarity and consistency across all documentation and website link:https://vale.sh[Vale] styles has been introduced in the documentation tree.	To maintain clarity and consistency across all documentation and the website link:https://vale.sh[Vale] styles have been introduced in the documentation tree.
		ceriUnsubmitted Done Inline Actions Have ceri: Have
		ceriUnsubmitted Done Inline Actions and the website, ceri: and the website,
	link:https://vale.sh[Vale] is a powerful linter for writing customized rules and can be used in multiple scenarios.	link:https://vale.sh[Vale] is a powerful linter for writing customized rules and can be used in multiple scenarios.
	At this moment link:https://vale.sh[Vale] can be used as a command line tool, for CI/CD pipeline and integrated into editor of choice.	At this moment link:https://vale.sh[Vale] can be used as a command line tool, in a CI/CD pipeline, or integrated into editor of choice.
		ceriUnsubmitted Done Inline Actions in a ceri: in a
		ceriUnsubmitted Done Inline Actions , or integrated into your editor of choice ceri: , or integrated into your editor of choice
		bofhAuthorUnsubmitted Not Done Inline Actions I am not sure whether if we are allowed to use any of "you/your/they/their" bofh: I am not sure whether if we are allowed to use any of "you/your/they/their"
		bcrUnsubmitted Not Done Inline Actions I am not sure whether if we are allowed to use any of "you/your/they/their" We're discouraging the use of "you" in the documentation. "into an editor of choice" solves this... bcr: > I am not sure whether if we are allowed to use any of "you/your/they/their" We're…

	The following table describes the current rule names and respective severity.	The following table describes the current rule names and their respective severity.
		ceriUnsubmitted Done Inline Actions and their respective ceri: and their respective

	[.informaltable]	[.informaltable]
	[cols="1,1", frame="none", options="header"]	[cols="1,1", frame="none", options="header"]
Context not available.
	[[writing-style-linting-vale-rules]]	[[writing-style-linting-vale-rules]]
	=== Current Vale Rules	=== Current Vale Rules

	. BrandTerms: Like The FreeBSD Project every major vendors and Companies have specific rules on writing their Brand Name. according to the Copyright rules of The FreeBSD Foundation freebsd should be written as FreeBSD.	. BrandTerms: Like the FreeBSD Project every major vendor and company have specific rules on how to write their Brand Name.
		ceriUnsubmitted Done Inline Actions the ceri: the
		ceriUnsubmitted Done Inline Actions vendor ceri: vendor
		ceriUnsubmitted Done Inline Actions company ceri: company
		ceriUnsubmitted Done Inline Actions how to write ceri: how to write
		ceriUnsubmitted Done Inline Actions According ceri: According
		ceriUnsubmitted Done Inline Actions copyright ceri: copyright
		ceriUnsubmitted Done Inline Actions the ceri: the
	Similar to that care should be taken to be respective to other's brand value and write PostgreSQL, Node.js, Let's Encrypt etc.	According to the copyright rules of the FreeBSD Foundation freebsd should be written as FreeBSD.
		ceriUnsubmitted Done Inline Actions Similarly, ceri: Similarly,
		ceriUnsubmitted Done Inline Actions be respectful of other brands' ceri: be respectful of other brands'
		ceriUnsubmitted Done Inline Actions and one should write ceri: and one should write
	Missing brand names should be added to the [.filename]#.vale/styles/FreeBSD/BrandTerms.yml#" in the `doc` repository.	Similarly, care should be taken to be respectful of other brands' value and one should write PostgreSQL, Node.js, Let's Encrypt etc.
		ceriUnsubmitted Done Inline Actions either "the file", or "" ceri: either "the file", or ""
		Missing brand names should be added to [.filename]#.vale/styles/FreeBSD/BrandTerms.yml#" in the `doc` repository.

	. Contractions: Contracted words should not be used. This rule avoids all contractions and suggests full words.	. Contractions: Contracted words should not be used. This rule avoids all contractions and suggests full words.

	. Hang: `Hang` is often used to convey the meaning that the application has stopped responding.	. Hang: `Hang` is often used to convey the meaning that the application has stopped responding.
	This rule proposes better wording.	This rule proposes better wording.

		ceriUnsubmitted Done Inline Actions Some ceri: Some
		ceriUnsubmitted Done Inline Actions resuming ceri: resuming
	. Repetition: Same words are often typed twice when leaving the keyboard and rejoining the work again.	. Repetition: Some words are often typed twice when leaving the keyboard and resuming the work again.
		ceriUnsubmitted Done Inline Actions author ceri: author
	This rule finds repeated words and warns the users.	This rule finds repeated words and warns the author.

		ceriUnsubmitted Done Inline Actions aims to avoid ceri: aims to avoid
	. Weasel: This rule handles avoiding weasel words.	. Weasel: This rule aims to avoid weasel words.
		ceriUnsubmitted Done Inline Actions use ceri: use
		ceriUnsubmitted Not Done Inline Actions I don't know what this is supposed to mean. ceri: I don't know what this is supposed to mean.
		bofhAuthorUnsubmitted Done Inline Actions Was a typo. Let me know if it is clear now. bofh: Was a typo. Let me know if it is clear now.
	The uses of weasel words is controversial so at the moment the list of words are being evaluated and the severity level is marked as warning on.	The use of weasel words is controversial so at the moment the list of words are being evaluated and the severity level is marked as warning only.
		ceriUnsubmitted Done Inline Actions as a weasel word, ceri: as a weasel word,
	In case a frequently used word is marked as weasel word it should be removed from [.filename]#.vale/styles/FreeBSD/Weasel.yml#" in the `doc` repository.	In case a frequently used word is marked as a weasel word, it should be removed from [.filename]#.vale/styles/FreeBSD/Weasel.yml#" in the `doc` repository.

		ceriUnsubmitted Done Inline Actions use of conscious language ceri: use of conscious language
	. ConsciousLanguage: This rule proposes uses of conscious languages like avoiding the words white/black/master/slave.	. ConsciousLanguage: This rule proposes use of conscious language like avoiding the words white/black/master/slave.

		ceriUnsubmitted Done Inline Actions Attempts to avoid whitespace at the end of lines. ceri: Attempts to avoid whitespace at the end of lines.
	. EOLSpacing: In most of the documents EOL spacing is present which is not the desirable situation.	. EOLSpacing: Attempts to avoid whitespace at the end of lines.

	. Hyphens: Often adverbs ending with 'ly' are being added with a hyphen which is wrong.	. Hyphens: Often adverbs ending with 'ly' are being added with a hyphen which is wrong.

		ceriUnsubmitted Done Inline Actions notice ceri: notice
	. Spacing: Often double spaces are hard to catch on plain eye which is addressed here.	. Spacing: Often double spaces are hard to notice which is addressed here.

		ceriUnsubmitted Done Inline Actions en_GB ceri: en_GB
	. Spelling: At the moment there is a mix of en_US and en_UK spellings in the documentation and website.	. Spelling: At the moment there is a mix of en_US and en_GB spellings in the documentation and website.
		ceriUnsubmitted Done Inline Actions en_GB ceri: en_GB
	A custom dictionary from link:https://wordlist.aspell.net[Aspell] has been added which uses strictly en_US and do not accept the en_UK variant of any words.	A custom dictionary from link:https://wordlist.aspell.net[Aspell] has been added which uses strictly en_US and do not accept the en_GB variant of any words.
	It has also an exception list to ignore the FreeBSD specific terms.	It has also an exception list to ignore the FreeBSD specific terms.
	At the moment the list is a basic one with minimal words just as a proof of concept but if any word is found to be correct and not available in the dictionary the word should be added to the [.filename]#.vale/styles/FreeBSD/spelling-exceptions.txt#" in the `doc` repository.	At the moment the list is a basic one with minimal words just as a proof of concept but if any word is found to be correct and not available in the dictionary the word should be added to the [.filename]#.vale/styles/FreeBSD/spelling-exceptions.txt#" in the `doc` repository.

		ceriUnsubmitted Done Inline Actions future ceri: future
		ceriUnsubmitted Not Done Inline Actions Who decides? ceri: Who decides?
		bofhAuthorUnsubmitted Not Done Inline Actions Let me know if the scenario is well described or requires more clarification. bofh: Let me know if the scenario is well described or requires more clarification.
	More rules will be introduced in the upcoming days when and where required.	More rules will be introduced in the future when and where doceng team feels fusible.

	[[writing-style-using-vale]]	[[writing-style-using-vale]]
	=== Using Vale	=== Using Vale

		ceriUnsubmitted Done Inline Actions within an editor ceri: within an editor
	link:https://vale.sh[Vale] can be used from command line and from within editor or IDE.	link:https://vale.sh[Vale] can be used from command line and from within an editor or IDE.
		ceriUnsubmitted Done Inline Actions by typing ceri: by typing
	package:textproc/vale[] can be installed as following:	package:textproc/vale[] can be installed by typing following:

	[source, shell]	[source, shell]
	....	....
Context not available.
	....	....

	[[writing-style-using-vale-commandline]]	[[writing-style-using-vale-commandline]]
		ceriUnsubmitted Done Inline Actions on the command line ceri: on the command line
	==== Using Vale in command line	==== Using Vale on the command line

		ceriUnsubmitted Done Inline Actions Assuming that the `doc` repository... ceri: Assuming that the `doc` repository...
		ceriUnsubmitted Done Inline Actions , the ceri: , the
		ceriUnsubmitted Done Inline Actions will run vale with the project's configuration ceri: will run vale with the project's configuration
	Considering the fact that `doc` repository was cloned into [.filename]#~/doc#" the following commands are required to run:	Assuming that the `doc` repository was cloned into [.filename]#~/doc#", the following commands will run vale with the project's configuration:

	[source, shell]	[source, shell]
	....	....
Context not available.
	[NOTE]	[NOTE]
	======	======
	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.	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.
		ceriUnsubmitted Done Inline Actions A better way ceri: A better way
		ceriUnsubmitted Not Done Inline Actions Not what sure what this is trying to say. ceri: Not what sure what this is trying to say.
		bofhAuthorUnsubmitted Not Done Inline Actions Tried to elaborate more bofh: Tried to elaborate more
	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.	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 project's CI pipeline.
	======	======

	[[writing-style-using-vale-editors]]	[[writing-style-using-vale-editors]]
	==== Using Vale in editors	==== Using Vale in editors

	link:https://vale.sh[Vale] works with major mainstream editors like package:editors/vim[], package:editors/emacs[], package:editors/vscode[].	link:https://vale.sh[Vale] works with major mainstream editors like package:editors/vim[], package:editors/emacs[], package:editors/vscode[].
		ceriUnsubmitted Done Inline Actions configuration ceri: configuration
	At the moment the necessary configurations for package:editors/vim[] is described in crossref:editor-config[editor-config-vim, Vim].	At the moment the necessary configuration for package:editors/vim[] is described in crossref:editor-config[editor-config-vim, Vim].
		ceriUnsubmitted Done Inline Actions An example configuration ceri: An example configuration
	Necessary configurations for package:editors/emacs[] is being worked on.	An example configuration for package:editors/emacs[] is being worked on.
Context not available.