From nobody Mon Nov 14 15:56:54 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 4N9v7s428pz4hRKk for ; Mon, 14 Nov 2022 15:56:57 +0000 (UTC) (envelope-from bofh@freebsd.org) Received: from smtp.freebsd.org (smtp.freebsd.org [IPv6:2610:1c1:1:606c::24b:4]) (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 "smtp.freebsd.org", Issuer "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4N9v7s3L2Rz44Gh; Mon, 14 Nov 2022 15:56:57 +0000 (UTC) (envelope-from bofh@freebsd.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1668441417; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: in-reply-to:in-reply-to:references:references; bh=lX+1R9cmVjgIRYNTG+mpOZdPhroqv+XcGyOE3tNjqF0=; b=PBaKc+Ls6L681TtEw0kkdJScDhijeX129xug8W3U/OJPjnNMItL85nITblrd1xlC013hOf CgEQoMJGaQpwZTx4WZtuEcex+RUInwdiMhedhEHmDV/AnIosDl9Vt0hlReoFgYfKpkpPfR Y3zbX0yZEwC5MBh8uW8dcgVioZnJ6v2ujkVQMaXQ2Yz1hUb4KdpDCtKZH36W5OG5wLYVvc jPv6KULUIcwDbL5AwqtMpcIMrefmPNVtkWit47ImcicXLByu4x1eZ9ngmWY/jFfe/bpXo2 zePtuvMWOiPXHJSOVrMoEE97DOl4gJP4Yj3hEzc5fLYNNs7DZlrMTNGIeg/BbQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1668441417; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: in-reply-to:in-reply-to:references:references; bh=lX+1R9cmVjgIRYNTG+mpOZdPhroqv+XcGyOE3tNjqF0=; b=FPZbKd6iVsF8NdPUHBiPAISsNOoD/FrtoNG/M4KRz7cDOJw8JqYndNbW+lLprgLPF0N2Pc S50ZVbd4iFrrS6CRGp6ofXKIQRk7a0P1aQrrlDJmi/+BlphUEwpG6ZyHEjakNw74neCcsP YHR9Qj60vFgYyQagWiNpqRKabFFKbTgwUw7OUUrASfUl9FNhH+2VEbPMhu921E6JCDUwSd 9/DhxH/JTpRqs7A3u+Sa2G1IT17+b43DqDuGinNzUg0tHRJAcLsn8L9JDaUXZNlDKDWkei Rl/JPquNbBL6Ngb62YHj/ICXTsTPxGAJ0JExE4gu3jdt2QvY7Iy36hbnn7M0RA== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1668441417; a=rsa-sha256; cv=none; b=h+xjgCCT3uv15ipGv3pIiq6MdGQcn3xe3a9VDyx//amysvUJN3uqN41IA5nGXQblh/FYAN 0YHUqF43ijEL/6r+1xBu+5MYCwDE1QoKa1TXAuVZuN34d6fSxMhDSMjzT4If4DUXz0CREL 7i9FdL2QJ4Oq28jLNFLa1rL4D3eLAIlsm0VM5buujeOHjzw7AlrsDWGjBSgMkUYfFyOFpP eBxPvjWiir7hGDIZf9s9PnECZRV9chEfXVzcvvxajH45fXI298rvIbaXnTurcGyL1QSRU+ mnOyGf6jkRePPbcpmZWf37KVuRXJZGfilw3rCttPnjo4LDpXe3kEI9n/OHxNTw== Received: from mx.bofh.network (mx.bofh.network [IPv6:2a0d:2787:2::28]) (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 (2048 bits) client-digest SHA256) (Client CN "mx.bofh.network", Issuer "R3" (verified OK)) (Authenticated sender: bofh/mail) by smtp.freebsd.org (Postfix) with ESMTPSA id 4N9v7r6bwwz1Pxp; Mon, 14 Nov 2022 15:56:56 +0000 (UTC) (envelope-from bofh@freebsd.org) Received: from smtpclient.apple (gw.office.cyso.net [95.97.78.194]) by mx.bofh.network (OpenSMTPD) with ESMTPSA id 50ee39df (TLSv1.2:ECDHE-RSA-AES256-GCM-SHA384:256:NO); Mon, 14 Nov 2022 15:56:55 +0000 (UTC) From: Moin Rahman Content-Type: multipart/signed; boundary="Apple-Mail=_477EF0AA-D26E-4D30-ACF7-BEF6C822E44B"; protocol="application/pgp-signature"; micalg=pgp-sha512 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 (Mac OS X Mail 16.0 \(3696.120.41.1.1\)) Subject: Re: git: eb6c0b65b8 - main - books/fdp-primer: Vale introducation in FDP Date: Mon, 14 Nov 2022 16:56:54 +0100 References: <202211141504.2AEF4oer054652@gitrepo.freebsd.org> To: "doc-committers@freebsd.org" , "dev-commits-doc-all@freebsd.org" In-Reply-To: <202211141504.2AEF4oer054652@gitrepo.freebsd.org> Message-Id: <8AF34223-7076-443A-8044-A1D7571BFA74@freebsd.org> X-Mailer: Apple Mail (2.3696.120.41.1.1) X-ThisMailContainsUnwantedMimeParts: N --Apple-Mail=_477EF0AA-D26E-4D30-ACF7-BEF6C822E44B Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset=us-ascii 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 = wrote: >=20 > The branch main has been updated by bofh: >=20 > URL: = https://cgit.FreeBSD.org/doc/commit/?id=3Deb6c0b65b8cce4891bd55c13fd3128ff= b15cbd96 >=20 > 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 >=20 > books/fdp-primer: Vale introducation in FDP >=20 > 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(+) >=20 > 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}. > | <=3D >=20 > |=3D=3D=3D > + > +[[writing-style-linting-vale]] > +=3D=3D 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=3D"1,1", frame=3D"none", options=3D"header"] > +|=3D=3D=3D > +| Name > +| Severity > + > +| BrandTerms > +| error > + > +| ConsciousLanguage > +| warning > + > +| Contractions > +| suggestions > + > +| EOLSpacing > +| warning > + > +| Hang > +| warning > + > +| Hyphens > +| warning > + > +| Repetition > +| warning > + > +| Spacing > +| error > + > +| Spelling > +| warning > + > +| Weasel > +| warning > + > +|=3D=3D=3D > + > +[[writing-style-linting-vale-rules]] > +=3D=3D=3D 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]] > +=3D=3D=3D 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]] > +=3D=3D=3D=3D 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] > +=3D=3D=3D=3D=3D=3D > +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. > +=3D=3D=3D=3D=3D=3D > + > +[[writing-style-using-vale-editors]] > +=3D=3D=3D=3D 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. --Apple-Mail=_477EF0AA-D26E-4D30-ACF7-BEF6C822E44B Content-Transfer-Encoding: 7bit Content-Disposition: attachment; filename=signature.asc Content-Type: application/pgp-signature; name=signature.asc Content-Description: Message signed with OpenPGP -----BEGIN PGP SIGNATURE----- iQKTBAEBCgB9FiEETfdREoUGjQZKBS+fvbm1phfAvJEFAmNyZUZfFIAAAAAALgAo aXNzdWVyLWZwckBub3RhdGlvbnMub3BlbnBncC5maWZ0aGhvcnNlbWFuLm5ldDRE Rjc1MTEyODUwNjhEMDY0QTA1MkY5RkJEQjlCNUE2MTdDMEJDOTEACgkQvbm1phfA vJHZvA//bETWPXSwblhJAucuisrAttFxdBQK6m1OdEW6dQehm/Ua0qhyWKJbefPO PmnHjs37Wp9+J3HQgtMt90FLKqPHKb9Fz94eayI5HzCRz0/9LAHGHtX2Pwh/S2nG oc5wjbPQmCYFjQUH79zQQ148Terqc/SF7QcoUdHdBiMlhr3jcmsGa/+J2HXMcG3G NqBpBY+tT7NZL6CB2Ba2cH9R8WPzCcifbOYjovpWJZtsw9bgFIPxiIzWb+gCgjcr tmowPdz0Kf5TQVoaRjwo9ulft4epKf6/ef7YCB1DY31wQJ9ISVuZ0Z0UT+3M+/Jn r5nlc3xubDeHNsT579fhVBeXB3Q7CXKKqvpHPC7vwf+3biPCd9NJS4iAztxB3jJQ bw2WZBwywy9+VIlqj4ZSEmvs6mDhGhNebn0+Dj9IqrTzWFnOfIY1g1XjNGv05TCz bk2T+0zkag/EbDD6qiKUeoUOvNXHa8vHytVkgmS7Jzsc4QhgEEqsHGr4naJfefwo 8UlOOBYcPMWSpuSdLmMHlmJwpYuoyukt/ULJL9H0U+umMmzOC/eKXn2ytHCTyIec QS4St2TNBuvzSC0E17Dwgrsk14kjQX1E7mh7lXooU3TtN3YfxuLbhpzMa8PnoA53 gGn6WinI/vcMLpmZY602CDVux5ksxuymDoZkEXBqnZASkobSStI= =dl24 -----END PGP SIGNATURE----- --Apple-Mail=_477EF0AA-D26E-4D30-ACF7-BEF6C822E44B--