From nobody Mon Nov 14 15:04:50 2022 X-Original-To: dev-commits-doc-all@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4N9szk2VPrz4hLGn for ; Mon, 14 Nov 2022 15:04:50 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4N9szk1yjbz3xKW; Mon, 14 Nov 2022 15:04:50 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1668438290; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=RYMcpOaCMBCaz10I/oW4dgbFquzAnqLubeHDgKnuw34=; b=uNYTyy1b2lBmjLBwAk5WpsaHlwlQEFE12H3jzBpZiSMAcpzdqa/BJAgIOdqKOARV9dtRuF vUneIgVGxiAFWoymeE1PnJUMniIuz74STop0VlnOh2qWJk/oEWCywpo47E0LtG8/FOhUk8 kMLSrOicIORwW+41PMv0IbcxxlfxR5doMTo1bS8rALNETYN9/dDjrdV7aIe/GDprjEzaZo Pwm79/nc6QvaBVPmU4OTpFcC2EfrRsy/KpJINAHasPPqmhxilfI6LwagADEBu32WVEg+Kw lxvhHZk5RhvQkisGgiPadhtSeDH9quJaFLsPgyUa1/MV0HZRIlxUcAxZtInxVQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1668438290; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=RYMcpOaCMBCaz10I/oW4dgbFquzAnqLubeHDgKnuw34=; b=MtOa82VTDWMXsOXasGPrVHvA3721Qh33ypJ6dkVOK/WJ4RA+uPyKBjFH9RVY1HA9P79Q7N O4d8dqrPwsDCQv+5pRXkUXhpSkxQDRoEjQxvCHCTII02f6sUFuC1BwFGT0HpY5l5cyhJh8 nqlIMyWkzIKnlPufsKJ1l3CbdM0jXVgHtaqqgCWc9jst0Yhm45y1i6V5X4vyoJ0vHImgMe Ost1E3pjUxnB9fI7LksbbZmbhkZ+dtBeCY10RX6+FIqhB6YWcy+7Ejrf7ckOSTBT++cRUY a2+ZRGiMuindyE6sQfKDKV5I7k0ffkWNYzDWPv3EatAnXTIaD0GFRx7xkBZt+w== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1668438290; a=rsa-sha256; cv=none; b=I91zjzuNI4k0Hk7xY+pNWUehP9mW8iwUnbH7Ype6XXDgdgDucLGONJ8Lfbx8++C1j1+Xd8 zQmm4UKC5uix5z7XzdvgTRNoFFcdS2OzRrQMbvHtQl78PlDPyx3p8UmcBPaRrlNb86TJdb 8Q34SdcBDda2uUXRPEldBQ4NXWq3UVF+WFV1u6nmA52ePRf+G8sy07ScfeEpHM1fKYBy/A 9zhcbEjTfy7eTZKubM4Ggp2rLRvkeYH40+bQdEo88YUB6GpEg4lsb/ltgki9pyayxcPRyD c02m3dhIEYvmzRhQyHnipu0f5YneNZqDaEHFP6jA7ctH83WVBJh2xpHxmYwkxw== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 4N9szk10fDzmSC; Mon, 14 Nov 2022 15:04:50 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.16.1/8.16.1) with ESMTP id 2AEF4o3J054653; Mon, 14 Nov 2022 15:04:50 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.16.1/8.16.1/Submit) id 2AEF4oer054652; Mon, 14 Nov 2022 15:04:50 GMT (envelope-from git) Date: Mon, 14 Nov 2022 15:04:50 GMT Message-Id: <202211141504.2AEF4oer054652@gitrepo.freebsd.org> To: doc-committers@FreeBSD.org, dev-commits-doc-all@FreeBSD.org From: Muhammad Moinur Rahman Subject: git: eb6c0b65b8 - main - books/fdp-primer: Vale introducation in FDP List-Id: Commit messages for all branches of the doc repository List-Archive: https://lists.freebsd.org/archives/dev-commits-doc-all List-Help: List-Post: List-Subscribe: List-Unsubscribe: Sender: owner-dev-commits-doc-all@freebsd.org X-BeenThere: dev-commits-doc-all@freebsd.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: bofh X-Git-Repository: doc X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: eb6c0b65b8cce4891bd55c13fd3128ffb15cbd96 Auto-Submitted: auto-generated X-ThisMailContainsUnwantedMimeParts: N The branch main has been updated by bofh: URL: https://cgit.FreeBSD.org/doc/commit/?id=eb6c0b65b8cce4891bd55c13fd3128ffb15cbd96 commit eb6c0b65b8cce4891bd55c13fd3128ffb15cbd96 Author: Muhammad Moinur Rahman AuthorDate: 2022-11-14 15:03:18 +0000 Commit: Muhammad Moinur Rahman 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.