.. | ||
examples | ||
pages | ||
.gitignore | ||
build_docs.sh | ||
doxygen.cfg | ||
DoxygenLayout.xml | ||
quickref.include.xsl | ||
quickref.xsl | ||
README.md | ||
style.css | ||
tidy1.xsl |
Documentation HOWTO
Instructions for generating documentation
\note For linking to these docs, the doxygen tag file is tidy.tags
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 installed. You can clone the repository from github 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 transformtidy-config.xml
using the rules in thequickref.xsl
stylesheet, and output it toquickref.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 transformtidy-help.xml
using the rules in thetidy1.xsl
stylesheet, and output it totidy.1
.\note Note that
tidy1.xls
includes the filetidy-config.xml
as part of the stylesheet, and so although it does not appear in the command invocation, it is indeed required.