dmpop / techpubstyle

Vale-based style guide for technical publications

Tech pub style style guide

A Vale-compatible style for technical writers documenting open-source software and for anyone writing about Open Source.

Checks

The supplied rules perform the following checks:

• common language usage errors
• punctuation
• editorializing
• wordiness
• terminology
• corporate speak
• inclusive language

Installation on Linux

The following installation procedure has been tested on Linux Mint and openSUSE.

Option 1. Install precompiled binary

1. Check the available tags at https://github.com/errata-ai/vale/tags
2. Use wget to download the latest tag, for example:

wget https://github.com/errata-ai/vale/releases/download/v2.20.0/vale_2.20.0_Linux_64-bit.tar.gz

3. Extract the downloaded archive:

tar xvf vale_2.20.0_Linux_64-bit.tar.gz vale

4. Move the vale binary to the /usr/local/bin directory:

sudo mv ./vale /usr/local/bin

Instead of /usr/local/bin, you can move the binary to any directory that is in $PATH.

Option 2. Install via Brew

1. Install Brew:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2. Install Vale:

brew install vale

Install Tech pub style

1. Create the styles directory: mkdir $HOME/styles
2. Clone the Git repository: cd $HOME/styles && git clone https://github.com/dmpop/techpubstyle.git

Create configuration file

Create a configuration file in your home directory:

nano $HOME/.vale.ini

Add the following configuration:

StylesPath = styles
MinAlertLevel = suggestion
[asciidoctor]
experimental = YES
[*.{md,txt,adoc}]
BasedOnStyles = techpubstyle

Save the changes.

Add XML support (openSUSE)

1. Install the libxslt-tools and docbook-xsl-stylesheets packages.
2. Open the .vale.ini file for editing and update the existing configuration as follows:

StylesPath = styles
MinAlertLevel = suggestion
[asciidoctor]
experimental = YES
[*.xml]
Transform = /usr/share/xml/docbook/stylesheet/suse2022-ns/xhtml/docbook.xsl
BasedOnStyles = techpubstyle
[*.{md,txt,adoc}]
BasedOnStyles = techpubstyle

3. Save the changes.

Add XML support (Linux Mint)

1. Install the docbook5-xml and docbook-xsl packages.
2. Open the .vale.ini file for editing and update the existing configuration as follows:

StylesPath = styles
MinAlertLevel = suggestion
[asciidoctor]
experimental = YES
[*.xml]
Transform = /usr/share/xml/docbook/stylesheet/nwalsh/html/docbook.xsl
BasedOnStyles = techpubstyle
[*.{md,txt,adoc}]
BasedOnStyles = techpubstyle

3. Save the changes.

Add VS Code and VSCodium integration

In VS Code, install the Vale +VS Code extension. In VSCodium, install Vale +VS Code extension.

Source code

In VS Code or VSCodium, choose File > Preferences > Settings and specify the path to the Vale binary (for example, /usr/local/bin/vale) under Vale > Vale CLI: Path.

Updating Tech pub style

Switch to the techpubstyle directory and run the git pull command.

Problems?

Please report bugs and issues in the Issues section.

Contribute

If you've found an error, or you have a suggestion for improvement, open an issue in the Issues section.

To add a new feature or fix issues yourself, proceed as follows.

1. Fork the project's repository.
2. Create a feature branch using the git checkout -b new-feature command.
3. Add your new feature or fix bugs and run the git commit -am 'Add a new feature' command to commit changes.
4. Push changes using the git push origin new-feature command.
5. Submit a pull request.

Author

Dmitri Popov [e-mail]

License

The GNU General Public License version 3