Date: Mon, 14 Nov 2022 16:56:54 +0100 From: Moin Rahman <bofh@freebsd.org> To: "doc-committers@freebsd.org" <doc-committers@FreeBSD.org>, "dev-commits-doc-all@freebsd.org" <dev-commits-doc-all@FreeBSD.org> Subject: Re: git: eb6c0b65b8 - main - books/fdp-primer: Vale introducation in FDP Message-ID: <8AF34223-7076-443A-8044-A1D7571BFA74@freebsd.org> In-Reply-To: <202211141504.2AEF4oer054652@gitrepo.freebsd.org> References: <202211141504.2AEF4oer054652@gitrepo.freebsd.org>
next in thread | previous in thread | raw e-mail | index | archive | help
--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 <bofh@freebsd.org> = 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 <bofh@FreeBSD.org> > AuthorDate: 2022-11-14 15:03:18 +0000 > Commit: Muhammad Moinur Rahman <bofh@FreeBSD.org> > 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--
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?8AF34223-7076-443A-8044-A1D7571BFA74>