tidy-html5/build/documentation/README.md
2015-03-04 23:36:33 +00:00

102 lines
3.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Documentation HOW-TO
**HTML Tidy** provides several types of documentation to suit different purposes. This
document describes how to generate the following:
- `tidylib_api/` (directory)
- This collection of documents describes the **TidyLib** API and is generated from the
comments and code in the **Tidy** source code.
- `quickref.html`
- This document provides a nice, readable HTML document describing all of the options and
settings that you can use with **Tidy** and internally in **TidyLib**.
- `tidy.1`
- This document is a Mac/Linux/Unix standard `man` page.
## The easy way
In this directory you can find the shell script `build_docs.sh`, and that will build all
of the documentation into the `temp/` directory (i.e., `{tidy}/build/documentation/temp`).
Please note these prerequisites:
- It's a Mac/Linux/Unix shell script.
- Doxygen is required to generate the API documentation.
- xsltproc is required to generate the man page and the `quickref.html` file.
If you prefer to understand how to do this manually (for example, for integration into
other scripts, build systems, or IDEs), read on.
## Manually
### `tidylib_api/` (directory)
If you want to build the API documentation you must have [doxygen][1] installed.
You can clone the [repository from github][2] if it is not currently installed.
Building as simple as:
~~~
cd {tidy}/build/documentation/
doxygen doxygen.cfg
~~~
This will result in a document set in `{tidy}/build/documentation/temp/tidylib_api`,
where you can find the main `index.html` file.
### `quickref.html`
Note that these instructions require the standard `xsltproc` utility to build the file,
but any XSLT processor of your choice should work, too.
- `tidy -xml-config > "tidy-config.xml"`
- This uses your up-to-date version of **Tidy** to generate an XML file containing all
of **Tidy**s built-in settings and their descriptions. This file is only temporary,
as it will be transformed in the next step.
- `xsltproc "quickref.xsl" "tidy-config.xml" > "quickref.html"`
- This examples uses the `xsltproc` command to transform `tidy-config.xml` using the
rules in the `quickref.xsl` stylesheet, and output it to `quickref.html`.
### `tidy.1`
Note that these instructions require the standard `xsltproc` utility to build the file,
but any XSLT processor of your choice should work, too.
- `tidy -xml-config > "tidy-config.xml"`
- This uses your up-to-date version of **Tidy** to generate an XML file containing all
of **Tidy**s built-in settings and their descriptions. This file is only temporary,
as it will be transformed in the third step.
- `tidy -xml-help > "tidy-help.xml"`
- This uses your up-to-date version of **Tidy** to generate an XML file containing all
of **Tidy**s built-in help information. This file is only temporary,
as it will be transformed in the next step.
- `xsltproc "tidy1.xsl" "tidy-help.xml" > "tidy.1"`
- This examples uses the `xsltproc` command to transform `tidy-help.xml` using the
rules in the `tidy1.xsl` stylesheet, and output it to `tidy.1`.
\note Note that `tidy1.xls` includes the file `tidy-config.xml` as part of the stylesheet,
and so although it does not appear in the command invocation, it is indeed required.
[1]: http://www.stack.nl/~dimitri/doxygen/
[2]: https://github.com/doxygen/doxygen