Re: git: eb6c0b65b8 - main - books/fdp-primer: Vale introducation in FDP

Moin Rahman <[email protected]> Mon, 14 Nov 2022 16:56:54 +0100
Newsgroups	gmane.os.freebsd.devel.cvs.doc
Message-ID	<[email protected]>
Missed some important metatags:

Approved by:    bcr
Differential Revision:  https://reviews.freebsd.org/D37381


> On Nov 14, 2022, at 4:04 PM, Muhammad Moinur Rahman <[email protected]> wrote:
> 
> The branch main has been updated by bofh:
> 
> URL: https://cgit.FreeBSD.org/doc/commit/?id=eb6c0b65b8cce4891bd55c13fd3128ffb15cbd96
> 
> commit eb6c0b65b8cce4891bd55c13fd3128ffb15cbd96
> Author:     Muhammad Moinur Rahman <[email protected]>
> AuthorDate: 2022-11-14 15:03:18 +0000
> Commit:     Muhammad Moinur Rahman <[email protected]>
> CommitDate: 2022-11-14 15:04:22 +0000
> 
>    books/fdp-primer: Vale introducation in FDP
> 
>    Introduction of vale in the fdp-primer. Describes about the current
>    rules and howto use vale from command line or editors.
> ---
> .../en/books/fdp-primer/writing-style/_index.adoc  | 116 +++++++++++++++++++++
> 1 file changed, 116 insertions(+)
> 
> diff --git a/documentation/content/en/books/fdp-primer/writing-style/_index.adoc b/documentation/content/en/books/fdp-primer/writing-style/_index.adoc
> index 1fe5811de1..215d5d30eb 100644
> --- a/documentation/content/en/books/fdp-primer/writing-style/_index.adoc
> +++ b/documentation/content/en/books/fdp-primer/writing-style/_index.adoc
> @@ -252,3 +252,119 @@ If a character is not on this list, ask about it on the {freebsd-doc}.
> | <=
> 
> |===
> +
> +[[writing-style-linting-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.
> +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.
> +
> +The following table describes the current rule names and respective severity.
> +
> +[.informaltable]
> +[cols="1,1", frame="none", options="header"]
> +|===
> +| Name
> +| Severity
> +
> +| BrandTerms
> +| error
> +
> +| ConsciousLanguage
> +| warning
> +
> +| Contractions
> +| suggestions
> +
> +| EOLSpacing
> +| warning
> +
> +| Hang
> +| warning
> +
> +| Hyphens
> +| warning
> +
> +| Repetition
> +| warning
> +
> +| Spacing
> +| error
> +
> +| Spelling
> +| warning
> +
> +| Weasel
> +| warning
> +
> +|===
> +
> +[[writing-style-linting-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*.
> +Similar to that care should be taken to be respective to other's brand value and 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.
> +
> +. 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.
> +This rule proposes better wording.
> +
> +. 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.
> +
> +. Weasel: This rule handles avoiding weasel words.
> +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.
> +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.
> +
> +. ConsciousLanguage: This rule proposes uses of conscious languages like avoiding the words white/black/master/slave.
> +
> +. EOLSpacing: In most of the documents EOL spacing is present which is not the desirable situation.
> +
> +. Hyphens: Often adverbs ending with 'ly' are being added with a hyphen which is wrong.
> +
> +. Spacing: Often double spaces are hard to catch on plain eye which is addressed here.
> +
> +. Spelling: At the moment there is a mix of en_US and en_UK spellings in the documentation and website.
> +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.
> +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.
> +
> +More rules will be introduced in the upcoming days when and where required.
> +
> +[[writing-style-using-vale]]
> +=== Using Vale
> +
> +link:https://vale.sh[Vale] can be used from command line and from within editor or IDE.
> +package:textproc/vale[] can be installed as following:
> +
> +[source, shell]
> +....
> +$ pkg install vale
> +....
> +
> +[[writing-style-using-vale-commandline]]
> +==== Using Vale in command line
> +
> +Considering the fact that `doc` repository was cloned into [.filename]#~/doc#" the following commands are required to run:
> +
> +[source, shell]
> +....
> +% cd ~/doc
> +% vale .
> +....
> +
> +[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.
> +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.
> +======
> +
> +[[writing-style-using-vale-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[].
> +At the moment the necessary configurations for package:editors/vim[] is described in crossref:editor-config[editor-config-vim, Vim].
> +Necessary configurations for package:editors/emacs[] is being worked on.
signature.asc (application/pgp-signature, 963 B)