### Install Standardebooks via pipx on macOS (Alternative)

Source: https://github.com/standardebooks/tools/blob/master/README.md

Installs Standardebooks using pipx on macOS, with manual dependency management via Homebrew. This method allows for more granular control over the installation.

```shell
# Install some pre-flight dependencies.
brew install cairo git openjdk pipx python@3.12
pipx ensurepath
sudo ln -sfn $(brew --prefix)/opt/openjdk/libexec/openjdk.jdk /Library/Java/JavaVirtualMachines/openjdk.jdk

# Install the toolset.
pipx install --python "$(brew --prefix)"/bin/python3.12 standardebooks

# Optional: Bash users who have set up bash-completion via brew can install tab completion.
ln -s $(pipx environment --value PIPX_LOCAL_VENVS)/standardebooks/lib/python3.*/site-packages/se/completions/bash/se $(brew --prefix)/etc/bash_completion.d/se

# Optional: Fish users can install tab completion.
ln -s $(pipx environment --value PIPX_LOCAL_VENVS)/standardebooks/lib/python3.*/site-packages/se/completions/fish/se $HOME/.config/fish/completions/se.fish
```

--------------------------------

### Install Standard Ebooks Toolset with Pipx

Source: https://github.com/standardebooks/tools/blob/master/README.md

Install the `standardebooks` package using `pipx` after setting up dependencies and ensuring `~/.local/bin` is in your PATH.

```shell
pip install --user pipx
```

```shell
pipx install standardebooks
```

--------------------------------

### Install Standardebooks on Fedora

Source: https://github.com/standardebooks/tools/blob/master/README.md

Installs the Standardebooks toolset and its dependencies on Fedora systems using pipx. Ensure pipx is correctly configured in your PATH.

```shell
# Install some pre-flight dependencies.
sudo dnf install pipx python3-devel gcc libxslt-devel git java-25-openjdk-headless

# Ensure $PATH environment variable is correctly set up for pipx.
pipx ensurepath

# Install the toolset.
pipx install standardebooks
```

--------------------------------

### Install ZSH Shell Completions

Source: https://github.com/standardebooks/tools/blob/master/README.md

Installs ZSH shell completions for the 'se' command by creating a symbolic link.

```shell
# Install ZSH completions.
sudo ln -s $(pipx environment --value PIPX_LOCAL_VENVS)/standardebooks/lib/python3.*/site-packages/se/completions/zsh/_se /usr/share/zsh/vendor-completions/_se && hash -rf && compinit
```

--------------------------------

### Install Standard Ebooks Packages on OpenBSD

Source: https://github.com/standardebooks/tools/blob/master/README.md

Create a package list file for `pkg_add` to install necessary dependencies. Ensure you follow linking instructions if multiple Python versions are present.

```shell
py3-pip--
py3-virtualenv--
py3-gitdb--
jdk--%11
git--
```

```shell
doas pkg_add -ivl ~/standard-ebooks-packages
```

```shell
doas ln -sf /usr/local/bin/pip3.7 /usr/local/bin/pip
```

--------------------------------

### Install Standardebooks with Homebrew on macOS

Source: https://github.com/standardebooks/tools/blob/master/README.md

Installs the Standardebooks toolset using the Homebrew package manager on macOS.

```shell
brew install standardebooks
```

--------------------------------

### Install Toolset on Ubuntu 24.04

Source: https://github.com/standardebooks/tools/blob/master/README.md

Installs necessary dependencies and the Standard Ebooks toolset using pipx on Ubuntu 24.04.

```shell
# Install some pre-flight dependencies.
sudo apt install -y default-jre git python3-dev python3-pip python3-venv pipx

# Install the toolset.
pipx install standardebooks
```

--------------------------------

### Install Bash Shell Completions

Source: https://github.com/standardebooks/tools/blob/master/README.md

Installs Bash shell completions for the 'se' command by creating a symbolic link in the user's bash-completion directory.

```shell
# Install Bash completions.
mkdir -p $HOME/.local/share/bash-completion/completions/
ln -s $(pipx environment --value PIPX_LOCAL_VENVS)/standardebooks/lib/python3.*/site-packages/se/completions/bash/se $HOME/.local/share/bash-completion/completions/se
```

--------------------------------

### Install Fish Shell Completions

Source: https://github.com/standardebooks/tools/blob/master/README.md

Installs Fish shell completions for the 'se' command by creating a symbolic link in the user's Fish configuration directory.

```shell
# Install Fish completions.
ln -s $(pipx environment --value PIPX_LOCAL_VENVS)/standardebooks/lib/python3.*/site-packages/se/completions/fish/se.fish $HOME/.config/fish/completions/
```

--------------------------------

### Editable Installation for Toolset Developers

Source: https://github.com/standardebooks/tools/blob/master/README.md

Clone the toolset repository and install it in editable mode using `pipx` to enable live source code changes.

```shell
git clone https://github.com/standardebooks/tools.git
```

```shell
pipx install --editable ./tools
```

--------------------------------

### Install Toolset on Ubuntu 20.04

Source: https://github.com/standardebooks/tools/blob/master/README.md

Installs necessary dependencies, pipx, and the Standard Ebooks toolset using pipx with a specific Python version on Ubuntu 20.04.

```shell
# Install some pre-flight dependencies.
sudo apt install -y default-jre git python3-dev python3-pip python3-venv

# Install pipx.
python3 -m pip install --user pipx
python3 -m pipx ensurepath

# Install the toolset.
pipx install --python=3.12 --fetch-missing-python standardebooks
```

--------------------------------

### Start Validator Checker Script

Source: https://github.com/standardebooks/tools/blob/master/se/data/vnu/index.html

Starts the validator checker Python script. Requires an internet connection for initial dependency downloads.

```bash
python ./checker.py all
```

--------------------------------

### Install Shell Completions for Standardebooks

Source: https://github.com/standardebooks/tools/blob/master/README.md

Sets up shell completions for Zsh, Bash, and Fish. This requires manual linking of completion scripts to the appropriate system directories.

```shell
# Install ZSH completions.
sudo ln -s $(pipx environment --value PIPX_LOCAL_VENVS)/standardebooks/lib/python3.*/site-packages/se/completions/zsh/_se /usr/share/zsh/vendor-completions/_se && hash -rf && compinit

# Install Bash completions.
mkdir -p $HOME/.local/share/bash-completion/completions/
ln -s $(pipx environment --value PIPX_LOCAL_VENVS)/standardebooks/lib/python3.*/site-packages/se/completions/bash/se $HOME/.local/share/bash-completion/completions/se
# Install Fish completions.
ln -s $(pipx environment --value PIPX_LOCAL_VENVS)/standardebooks/lib/python3.*/site-packages/se/completions/fish/se $HOME/.config/fish/completions/se.fish
```

--------------------------------

### Run EPUBCheck from Command Line

Source: https://github.com/standardebooks/tools/blob/master/se/data/epubcheck/README.txt

Execute EPUBCheck as a standalone command-line tool. Ensure a Java runtime (1.7 or above) is installed. Errors are printed to standard error.

```bash
java -jar epubcheck.jar file.epub
```

--------------------------------

### Checker Script Command-Line Options

Source: https://github.com/standardebooks/tools/blob/master/se/data/vnu/README.md

Examples of using the checker script with different command-line options to control build, test, run, and compilation processes.

```bash
python ./checker.py --help
```

```bash
python ./checker.py build  # to build only
```

```bash
python ./checker.py build  # test to build and test
```

```bash
python ./checker.py run    # to run only
```

```bash
python ./checker.py jar    # to compile vnu.jar
```

```bash
python ./checker.py update-shallow && \
    python ./checker.py dldeps && \
    python ./checker.py jar  # compile vnu.jar faster
```

--------------------------------

### Set JAVA_HOME Environment Variable (Ubuntu/macOS)

Source: https://github.com/standardebooks/tools/blob/master/se/data/vnu/index.html

Sets the JAVA_HOME environment variable, required for building the validator. Examples provided for Ubuntu and macOS.

```bash
export JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64    <-- Ubuntu, etc.
```

```bash
export JAVA_HOME=$(/usr/libexec/java_home)            <-- MacOS
```

--------------------------------

### Deploy VNU WAR to Servlet Container

Source: https://github.com/standardebooks/tools/blob/master/se/data/vnu/index.html

Example log message indicating successful deployment of the vnu.war file to a servlet container like Apache Tomcat.

```log
May 7, 2014 4:42:04 PM org.apache.catalina.startup.HostConfig deployWAR
INFO: Deploying web application archive /var/lib/tomcat7/webapps/vnu.war
```

--------------------------------

### Install Nu Html Checker via Homebrew

Source: https://github.com/standardebooks/tools/blob/master/se/data/vnu/index.html

Install the vnu command-line tool using Homebrew on macOS. This provides a convenient way to access the checker from your terminal.

```bash
brew install vnu
```

--------------------------------

### Run VNU Checker as Standalone Server

Source: https://github.com/standardebooks/tools/blob/master/se/data/vnu/index.html

Start the VNU checker as a standalone service using the built-in Jetty server. Specify the port to listen on. Future releases may default to 127.0.0.1, so consider using bind-address.

```bash
java -cp ~/vnu.jar              nu.validator.servlet.Main 8888
```

```bash
vnu-runtime-image/bin/java      nu.validator.servlet.Main 8888
```

```bash
vnu-runtime-image\bin\java.exe  nu.validator.servlet.Main 8888
```

--------------------------------

### Install Nu Html Checker via npm

Source: https://github.com/standardebooks/tools/blob/master/se/data/vnu/index.html

Install the vnu-jar package, which provides the Nu Html Checker, using npm. This is useful for integrating HTML checking into Node.js projects.

```bash
npm install vnu-jar
```

--------------------------------

### Set Java System Properties for VNU Checker

Source: https://github.com/standardebooks/tools/blob/master/se/data/vnu/README.md

Configures the VNU checker with specific Java system properties using the `JAVA_TOOL_OPTIONS` environment variable. This example sets `nu.validator.client.asciiquotes` to `yes`.

```bash
docker run -it --rm \
         -e JAVA_TOOL_OPTIONS=-Dnu.validator.client.asciiquotes=yes  \
         -p 8888:8888 \
         validator/validator
```

--------------------------------

### Inject pytest into standardebooks package

Source: https://github.com/standardebooks/tools/blob/master/tests/README.md

Injects the pytest testing framework into the pipx-created virtual environment for the standardebooks package. Ensure pytest is installed in the correct version.

```shell
pipx inject standardebooks pytest==9.0.2
```

--------------------------------

### XML Glossary Entry Match Example

Source: https://github.com/standardebooks/tools/blob/master/tests/lint/metadata/m-070/golden/m-070-out.txt

This XML snippet shows a `<match>` element within a glossary configuration. Ensure that the 'value' attribute corresponds to an actual entry in the text to avoid 'Glossary entry not found' errors.

```xml
<match value="foo"/>
```

--------------------------------

### Run VNU Checker with Java JAR

Source: https://github.com/standardebooks/tools/blob/master/se/data/vnu/index.html

Invoke the VNU checker using the Java JAR file. Ensure Java 8+ is installed. Replace `~/vnu.jar` with the actual path to your JAR file.

```bash
java -jar ~/vnu.jar OPTIONS FILES
```

--------------------------------

### Display EPUBCheck Command Line Help

Source: https://github.com/standardebooks/tools/blob/master/se/data/epubcheck/README.txt

View the available command-line options and usage instructions for EPUBCheck by using the --help argument.

```bash
java -jar epubcheck.jar --help
```

--------------------------------

### Install Nu Html Checker via pip

Source: https://github.com/standardebooks/tools/blob/master/se/data/vnu/index.html

Install the html5validator Python package, which integrates the Nu Html Checker. This is useful for automated checking in CI environments or Python projects.

```bash
pip install html5validator
```

--------------------------------

### Run Validator Only

Source: https://github.com/standardebooks/tools/blob/master/se/data/vnu/index.html

Starts only the validator service without performing build or test operations.

```bash
python ./checker.py run
```

--------------------------------

### Run Pylint and Pyright from Pipx Venv

Source: https://github.com/standardebooks/tools/blob/master/README.md

Execute `pylint` and `pyright` using their full paths within the `standardebooks` virtual environment created by `pipx`. Ensure `pyright` is aware of the venv path for correct library resolution.

```shell
cd /path/to/tools/repo
$HOME/.local/share/pipx/venvs/standardebooks/bin/pylint .
```

```shell
# Specify the venv path to `pyright` so that it knows where to look for libraries.
$HOME/.local/share/pipx/venvs/standardebooks/bin/pyright --venvpath=$HOME/.local/share/pipx/venvs/ .
```

--------------------------------

### Update Homebrew on macOS

Source: https://github.com/standardebooks/tools/blob/master/README.md

Updates the Homebrew package manager to the latest version. This is a prerequisite for installing tools with Homebrew.

```shell
brew update
```

--------------------------------

### Comment out VNU Servlet Filter

Source: https://github.com/standardebooks/tools/blob/master/se/data/vnu/index.html

Example of commenting out the inbound-size-limit-filter within the /WEB-INF/web.xml file of the VNU WAR archive to disable it.

```xml
<!--
  <filter>
      <filter-name>inbound-size-limit-filter</filter-name>
      <filter-class>nu.validator.servlet.InboundSizeLimitFilter</filter-class>
  </filter>
  <filter-mapping>
      <filter-name>inbound-size-limit-filter</filter-name>
      <url-pattern>/\*</url-pattern>
  </filter-mapping>
-->
```

--------------------------------

### Clone and Navigate to Validator Repository

Source: https://github.com/standardebooks/tools/blob/master/se/data/vnu/README.md

Clone the validator repository from GitHub and change into the newly created directory. This sets up the project's working directory.

```bash
git clone https://github.com/validator/validator.git
```

```bash
cd validator
```

--------------------------------

### Inject Linters into Standard Ebooks Pipx Environment

Source: https://github.com/standardebooks/tools/blob/master/README.md

Use `pipx inject` to add `pylint` and `pyright`, along with necessary type stubs, to the `standardebooks` virtual environment.

```shell
pipx inject standardebooks pylint==4.0.5 pyright==1.1.410 types-requests==2.33.0.20260518 types-setuptools==80.9.0.20250822 types-lxml==2026.2.16
```

--------------------------------

### Run Nu Html Checker (Windows)

Source: https://github.com/standardebooks/tools/blob/master/se/data/vnu/index.html

Execute the Nu Html Checker from the command line on Windows systems. Replace OPTIONS with desired checker flags and FILES with the paths to the documents to be validated.

```batch
vnu-runtime-image\bin\vnu.bat OPTIONS FILES
```

--------------------------------

### Run Nu Html Checker (Linux/macOS)

Source: https://github.com/standardebooks/tools/blob/master/se/data/vnu/index.html

Execute the Nu Html Checker from the command line on Linux or macOS systems. Replace OPTIONS with desired checker flags and FILES with the paths to the documents to be validated.

```bash
vnu-runtime-image/bin/vnu OPTIONS FILES
```

--------------------------------

### Run Nu Html Checker via Docker

Source: https://github.com/standardebooks/tools/blob/master/se/data/vnu/index.html

Launch an instance of the Nu Html Checker using Docker. This command pulls the latest validator image and maps port 8888 for access.

```bash
docker run -it --rm -p 8888:8888 validator/validator:latest
```

--------------------------------

### XML Glossary Entry Value Example

Source: https://github.com/standardebooks/tools/blob/master/tests/lint/metadata/m-070/golden/m-070-out.txt

This XML snippet defines a `<value>` element for a glossary entry. If this 'value' is not present in the processed text, the m-070 error may occur.

```xml
<value value="pariahsss"/>
```

--------------------------------

### Run VNU HTTP Client Remotely

Source: https://github.com/standardebooks/tools/blob/master/se/data/vnu/README.md

Check documents against a remote VNU instance by specifying the host and port using system properties. This example targets html5.validator.nu on port 80.

```java
java -cp ~/vnu.jar -Dnu.validator.client.port=80 \
        -Dnu.validator.client.host=html5.validator.nu \
        nu.validator.client.HttpClient FILE.html...
```

```java
vnu-runtime-image/bin/java -Dnu.validator.client.port=80 \
        -Dnu.validator.client.host=html5.validator.nu \
        nu.validator.client.HttpClient FILE.html...
```

--------------------------------

### Check Directory as CSS

Source: https://github.com/standardebooks/tools/blob/master/se/data/vnu/index.html

Check all documents within a specified directory specifically as CSS files.

```bash
vnu --css DIRECTORY_PATH
```

--------------------------------

### Check Documents Locally with HTTP Client

Source: https://github.com/standardebooks/tools/blob/master/se/data/vnu/index.html

Use the VNU checker's packaged HTTP client from the command line to check documents against a locally running instance of the checker service.

```bash
java -cp ~/vnu.jar nu.validator.client.HttpClient FILE.html...
```

```bash
vnu-runtime-image/bin/java nu.validator.client.HttpClient FILE.html...
```

--------------------------------

### Check Directory with Mixed HTML and CSS

Source: https://github.com/standardebooks/tools/blob/master/se/data/vnu/index.html

Check all documents in a directory, treating files with a .css extension as CSS and all others as HTML.

```bash
vnu --also-check-css DIRECTORY_PATH
```

--------------------------------

### Execute pytest tests

Source: https://github.com/standardebooks/tools/blob/master/tests/README.md

Navigates to the top level of the tools repository and executes pytest using the path to the virtual environment's pytest executable. This command assumes the virtual environment is already set up.

```shell
cd /path/to/tools/repo
$HOME/.local/share/pipx/venvs/standardebooks/bin/pytest
```

--------------------------------

### Standard Ebooks Source Directory Structure

Source: https://github.com/standardebooks/tools/blob/master/README.md

This is a visual representation of the typical file and directory structure for a Standard Ebooks source project. It details the placement of images, source files, and EPUB-specific content.

```text
.
|__ images/
|   |__ cover.jpg
|   |__ cover.source.jpg
|   |__ cover.svg
|   |__ titlepage.svg
|
|__ src/
|   |__ META-INF/
|   |   |__ container.xml
|
|   |__ epub/
|   |   |__ css/
|   |   |   |__ core.css
|   |   |   |__ local.css
|   |   |   |__ se.css
|   |   |
|   |   |__ images/
|   |   |   |__ cover.svg
|   |   |   |__ logo.svg
|   |   |   |__ titlepage.svg
|   |   |
|   |   |__ text/
|   |   |   |__ colophon.xhtml
|   |   |   |__ imprint.xhtml
|   |   |   |__ titlepage.xhtml
|   |   |   |__ uncopyright.xhtml
|   |   |
|   |   |__ content.opf
|   |   |__ toc.xhtml
|
|   |__ mimetype
|
|__ LICENSE.md
```

--------------------------------

### Run Checker with Bind Address Option

Source: https://github.com/standardebooks/tools/blob/master/se/data/vnu/index.html

Runs the checker script with the --bind-address option to specify a particular IP address, preventing potential reachability issues in future releases.

```bash
python ./checker.py --bind-address=128.30.52.73 all
```

--------------------------------

### Check a Web Document

Source: https://github.com/standardebooks/tools/blob/master/se/data/vnu/index.html

Check a document located at a specific URL. Replace `URL` with the actual web address.

```bash
vnu URL
```

```bash
vnu http://example.com/foo
```

--------------------------------

### VNU Option: --Werror

Source: https://github.com/standardebooks/tools/blob/master/se/data/vnu/index.html

Treat warnings as errors. The checker will exit with a non-zero status if any warnings are encountered.

```bash
java -jar ~/vnu.jar --Werror FILES
```

--------------------------------

### Check HTML Files from Command Line

Source: https://github.com/standardebooks/tools/blob/master/se/data/vnu/index.html

Check one or more HTML files using the VNU command-line tool. You can use the direct executable or the Java JAR.

```bash
vnu-runtime-image/bin/vnu      FILE.html FILE2.html FILE3.html...
```

```bash
vnu-runtime-image\bin\vnu.bat  FILE.html FILE2.html FILE3.html...
```

```bash
java -jar ~/vnu.jar            FILE.html FILE2.html FILE3.html...
```