Simplified document build system to single file. Updated README.
This commit is contained in:
Jim Derry
parent
07f90ccc81
commit
96349aedd5
|
|
@ -3,7 +3,7 @@
|
|||
**HTML Tidy** provides several types of documentation to suit different purposes. This
|
||||
document describes how to generate the following:
|
||||
|
||||
`htmldoc/api/` (directory)
|
||||
`tidylib_api/` (directory)
|
||||
|
||||
: This collection of documents describes the **TidyLib** API and is generated from the
|
||||
comments and code in the **Tidy** source code.
|
||||
|
|
@ -18,27 +18,44 @@ document describes how to generate the following:
|
|||
: This document is a Mac/Linux/Unix standard `man` page.
|
||||
|
||||
|
||||
## htmldoc/api/ (directory)
|
||||
## The easy way
|
||||
|
||||
If you want to build the API documentation locally you must have [doxygen][1] installed.
|
||||
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 {your-tidy-html5-source}/htmldoc/doxygen doxygen.cfg`
|
||||
~~~
|
||||
cd {tidy}/build/documentation/
|
||||
doxygen doxygen.cfg
|
||||
~~~
|
||||
|
||||
This will result in a document set in `{your-tidy-html5-source}/htmldoc/doxygen/api/`,
|
||||
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
|
||||
### `quickref.html`
|
||||
|
||||
For convenience you can use the `quickref.sh` shell script on Unix-like systems to
|
||||
build the `quickref.html` file. Note that it depends on the standard `xsltproc` utility
|
||||
to build the file.
|
||||
|
||||
If you are using a non-Unix operating system or have a different XSLT processor then the
|
||||
following section describes how the file can be built easily.
|
||||
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"`
|
||||
|
||||
|
|
@ -53,14 +70,10 @@ following section describes how the file can be built easily.
|
|||
|
||||
|
||||
|
||||
## tidy.1
|
||||
### `tidy.1`
|
||||
|
||||
For convenience you can use the `tidy1.sh` shell script on Unix-like systems to
|
||||
build the `tidy.1` file. Note that it depends on the standard `xsltproc` utility
|
||||
to build the file.
|
||||
|
||||
If you are using a non-Unix operating system or have a different XSLT processor then the
|
||||
following section describes how the file can be built easily.
|
||||
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"`
|
||||
|
||||
|
|
@ -85,4 +98,4 @@ following section describes how the file can be built easily.
|
|||
|
||||
|
||||
[1]: http://www.stack.nl/~dimitri/doxygen/
|
||||
[2]: https://github.com/doxygen/doxygen
|
||||
[2]: https://github.com/doxygen/doxygen
|
||||
|
|
|
|||
119
build/documentation/build_docs.sh
Executable file
119
build/documentation/build_docs.sh
Executable file
|
|
@ -0,0 +1,119 @@
|
|||
#!/bin/sh
|
||||
|
||||
# See cat << HEREDOC for file description.
|
||||
|
||||
|
||||
# Set this to the complete path of the tidy for which you want to generate
|
||||
# documentation. Relative path is okay. You shouldn't have to change this
|
||||
# too often if your compiler always puts tidy in the same place.
|
||||
|
||||
TIDY_PATH="./tidy5" # Current directory.
|
||||
|
||||
|
||||
cat << HEREDOC
|
||||
|
||||
Build 'tidy.1', which is a man page suitable for installation
|
||||
in all Unix-like operating systems. This script will build
|
||||
it, but not install it.
|
||||
|
||||
Build 'quickref.html'. This is distributed with the
|
||||
the Tidy source code and also used on Tidy's website.
|
||||
Be sure to distribute it with 'quickref.css' as well.
|
||||
|
||||
Build the 'tidylib_api' directory, which contains a website
|
||||
with the documentation for TidyLib’s headers.
|
||||
|
||||
These files will be built into '{current_dir}/temp'.
|
||||
|
||||
HEREDOC
|
||||
|
||||
|
||||
# Output and flags' declarations.
|
||||
DOXY_CFG="doxygen.cfg"
|
||||
OUTP_DIR="temp"
|
||||
BUILD_XSLT=1
|
||||
BUILD_API=1
|
||||
|
||||
|
||||
##
|
||||
# Ensure the output dir exists.
|
||||
##
|
||||
if [ ! -d "$OUTP_DIR" ]; then
|
||||
mkdir $OUTP_DIR
|
||||
fi
|
||||
|
||||
|
||||
##
|
||||
# Preflight
|
||||
##
|
||||
|
||||
# Check for a valid tidy.
|
||||
if [ ! -x "$TIDY_PATH" ]; then
|
||||
BUILD_XSLT=0
|
||||
echo "- '$TIDY_PATH' not found. You should set TIDY_PATH in this script."
|
||||
fi
|
||||
|
||||
# Check for xsltproc dependency.
|
||||
hash xsltproc 2>/dev/null || { echo "- xsltproc not found. You require an XSLT processor."; BUILD_XSLT=0; }
|
||||
|
||||
|
||||
##
|
||||
# Build 'quickref.html' and 'tidy.1'.
|
||||
##
|
||||
|
||||
if [ "$BUILD_XSLT" -eq 1 ]; then
|
||||
# Use the designated tidy to get its config and help.
|
||||
# These temporary files will be cleaned up later.
|
||||
$TIDY_PATH -xml-config > "tidy-config.xml"
|
||||
$TIDY_PATH -xml-help > "tidy-help.xml"
|
||||
|
||||
# 'quickref.html'
|
||||
xsltproc "quickref.xsl" "tidy-config.xml" > "$OUTP_DIR/quickref.html"
|
||||
|
||||
# 'tidy.1'
|
||||
xsltproc "tidy1.xsl" "$tidy-help.xml" > "$OUTP_DIR/tidy.1"
|
||||
|
||||
# Cleanup - Note: to avoid issues with the tidy1.xsl finding the tidy-config.xml
|
||||
# document, they are created and read from the source directory instead of temp.
|
||||
rm "tidy-config.xml"
|
||||
rm "tidy-help.xml"
|
||||
|
||||
echo "'quickref.html' and 'tidy.1' have been built.\n"
|
||||
else
|
||||
echo "* tidy.1 was skipped because not all dependencies were satisfied."
|
||||
fi
|
||||
|
||||
|
||||
##
|
||||
# Preflight
|
||||
##
|
||||
|
||||
# Check for the doxygen.cfg file.
|
||||
if [ ! -f "$DOXY_CFG" ]; then
|
||||
BUILD_API=0
|
||||
echo "- 'DOXY_CFG' not found. It is required to configure doxygen."
|
||||
fi
|
||||
|
||||
# Check for doxygen dependency.
|
||||
hash doxygen 2>/dev/null || { echo "- doxygen not found. This script requires doxygen."; BUILD_XSLT=0; }
|
||||
|
||||
|
||||
##
|
||||
# Build the doxygen project.
|
||||
##
|
||||
|
||||
if [ "$BUILD_API" -eq 1 ]; then
|
||||
echo "The following is doxygen's stderr output. It doesn't indicate errors with this script:\n"
|
||||
doxygen "$DOXY_CFG" > /dev/null
|
||||
echo "\nTidyLib API documentation has been built."
|
||||
else
|
||||
echo "* $OUTP_DIR/tidylib_api/ was skipped because not all dependencies were satisfied."
|
||||
fi
|
||||
|
||||
|
||||
##
|
||||
# Done
|
||||
##
|
||||
|
||||
echo "\nDone.\n"
|
||||
|
||||
|
|
@ -52,7 +52,7 @@ PROJECT_LOGO =
|
|||
# If a relative path is entered, it will be relative to the location
|
||||
# where doxygen was started. If left blank the current directory will be used.
|
||||
|
||||
OUTPUT_DIRECTORY =
|
||||
OUTPUT_DIRECTORY = temp
|
||||
|
||||
# If the CREATE_SUBDIRS tag is set to YES, then doxygen will create
|
||||
# 4096 sub-directories (in 2 levels) under the output directory of each output
|
||||
|
|
@ -665,7 +665,7 @@ WARN_LOGFILE =
|
|||
# directories like "/usr/src/myproject". Separate the files or directories
|
||||
# with spaces.
|
||||
|
||||
INPUT = ../include
|
||||
INPUT = "../../include"
|
||||
|
||||
# This tag can be used to specify the character encoding of the source files
|
||||
# that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is
|
||||
|
|
@ -864,7 +864,7 @@ VERBATIM_HEADERS = YES
|
|||
# was compiled with the --with-libclang option.
|
||||
# The default value is: NO.
|
||||
|
||||
CLANG_ASSISTED_PARSING = NO
|
||||
# CLANG_ASSISTED_PARSING = NO
|
||||
|
||||
# If clang assisted parsing is enabled you can provide the compiler with command
|
||||
# line options that you would normally use when invoking the compiler. Note that
|
||||
|
|
@ -872,7 +872,7 @@ CLANG_ASSISTED_PARSING = NO
|
|||
# specified with INPUT and INCLUDE_PATH.
|
||||
# This tag requires that the tag CLANG_ASSISTED_PARSING is set to YES.
|
||||
|
||||
CLANG_OPTIONS =
|
||||
# CLANG_OPTIONS =
|
||||
|
||||
#---------------------------------------------------------------------------
|
||||
# configuration options related to the alphabetical class index
|
||||
|
|
@ -910,7 +910,7 @@ GENERATE_HTML = YES
|
|||
# If a relative path is entered the value of OUTPUT_DIRECTORY will be
|
||||
# put in front of it. If left blank `html' will be used as the default path.
|
||||
|
||||
HTML_OUTPUT = api
|
||||
HTML_OUTPUT = "tidylib_api"
|
||||
|
||||
# The HTML_FILE_EXTENSION tag can be used to specify the file extension for
|
||||
# each generated HTML page (for example: .htm,.php,.asp). If it is left blank
|
||||
|
|
@ -1014,7 +1014,7 @@ HTML_DYNAMIC_SECTIONS = NO
|
|||
# Minimum value: 0, maximum value: 9999, default value: 100.
|
||||
# This tag requires that the tag GENERATE_HTML is set to YES.
|
||||
|
||||
HTML_INDEX_NUM_ENTRIES = YES
|
||||
HTML_INDEX_NUM_ENTRIES =
|
||||
|
||||
# If the GENERATE_DOCSET tag is set to YES, additional index files
|
||||
# will be generated that can be used as input for Apple's Xcode 3
|
||||
|
|
@ -1515,13 +1515,13 @@ XML_OUTPUT = xml
|
|||
# which can be used by a validating XML parser to check the
|
||||
# syntax of the XML files.
|
||||
|
||||
XML_SCHEMA =
|
||||
# XML_SCHEMA =
|
||||
|
||||
# The XML_DTD tag can be used to specify an XML DTD,
|
||||
# which can be used by a validating XML parser to check the
|
||||
# syntax of the XML files.
|
||||
|
||||
XML_DTD =
|
||||
# XML_DTD =
|
||||
|
||||
# If the XML_PROGRAMLISTING tag is set to YES Doxygen will
|
||||
# dump the program listings (including syntax highlighting
|
||||
|
|
@ -1688,7 +1688,7 @@ EXTERNAL_GROUPS = YES
|
|||
# will be listed.
|
||||
# The default value is: YES.
|
||||
|
||||
EXTERNAL_PAGES
|
||||
EXTERNAL_PAGES =
|
||||
|
||||
# The PERL_PATH should be the absolute path and name of the perl script
|
||||
# interpreter (i.e. the result of `which perl').
|
||||
|
|
|
|||
|
|
@ -1,45 +0,0 @@
|
|||
#!/bin/sh
|
||||
|
||||
cat << HEREDOC
|
||||
Build 'quickref.html'. This is distributed with the
|
||||
the Tidy source code and also used on Tidy's website.
|
||||
Be sure to distribute it with 'quickref.css' as well.
|
||||
HEREDOC
|
||||
|
||||
|
||||
# Set this to the complete path of the tidy for which you want to generate
|
||||
# documentation. Relative path is okay. You shouldn't have to change this
|
||||
# too often if your compiler always puts tidy in the same place.
|
||||
TIDY_PATH="./tidy5" # Current directory.
|
||||
#TIDY_PATH="/usr/bin/tidy" # the default on some operating systems.
|
||||
|
||||
|
||||
# Check for a valid tidy.
|
||||
if [ ! -x "$TIDY_PATH" ]; then
|
||||
echo "$TIDY_PATH not found. You should set TIDY_PATH in this script."
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Check for xsltproc dependency.
|
||||
hash xsltproc 2>/dev/null || { echo >&2 "This script requires xsltproc. Aborting."; exit 1; }
|
||||
|
||||
# Use the designated tidy to get its config and help.
|
||||
# These temporary files will be cleaned up later.
|
||||
$TIDY_PATH -xml-config > "tidy-config.xml"
|
||||
#$TIDY_PATH -xml-help > "tidy-help.xml"
|
||||
|
||||
# 'quickref.html'
|
||||
# This file is distributed with tidy and use on the website.
|
||||
xsltproc "quickref.xsl" "tidy-config.xml" > "quickref.html"
|
||||
|
||||
# 'tidy.1'
|
||||
# Build a manpage for *nix systems. Build only, no install.
|
||||
# - requires `tidy-config.xml` (loaded by 'tidy1.xsl' directly)
|
||||
#xsltproc "tidy1.xsl" "tidy-help.xml" > "tidy.1"
|
||||
|
||||
# Cleanup
|
||||
rm "tidy-config.xml"
|
||||
#rm "tidy-help.xml"
|
||||
|
||||
# Done
|
||||
echo Done.
|
||||
|
|
@ -1,45 +0,0 @@
|
|||
#!/bin/sh
|
||||
|
||||
cat << HEREDOC
|
||||
Build 'tidy.1', which is a man page suitable for installation
|
||||
in all Unix-like operating systems. This script will build
|
||||
it, but not install it.
|
||||
HEREDOC
|
||||
|
||||
|
||||
# Set this to the complete path of the tidy for which you want to generate
|
||||
# documentation. Relative path is okay. You shouldn't have to change this
|
||||
# too often if your compiler always puts tidy in the same place.
|
||||
TIDY_PATH="./tidy5" # Current directory.
|
||||
#TIDY_PATH="/usr/bin/tidy" # the default on some operating systems.
|
||||
|
||||
|
||||
# Check for a valid tidy.
|
||||
if [ ! -x "$TIDY_PATH" ]; then
|
||||
echo "$TIDY_PATH not found. You should set TIDY_PATH in this script."
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Check for xsltproc dependency.
|
||||
hash xsltproc 2>/dev/null || { echo >&2 "This script requires xsltproc. Aborting."; exit 1; }
|
||||
|
||||
# Use the designated tidy to get its config and help.
|
||||
# These temporary files will be cleaned up later.
|
||||
$TIDY_PATH -xml-config > "tidy-config.xml"
|
||||
$TIDY_PATH -xml-help > "tidy-help.xml"
|
||||
|
||||
# 'quickref.html'
|
||||
# This file is distributed with tidy and use on the website.
|
||||
#xsltproc "quickref.xsl" "tidy-config.xml" > "quickref.html"
|
||||
|
||||
# 'tidy.1'
|
||||
# Build a manpage for *nix systems. Build only, no install.
|
||||
# - requires `tidy-config.xml` (loaded by 'tidy1.xsl' directly)
|
||||
xsltproc "tidy1.xsl" "tidy-help.xml" > "tidy.1"
|
||||
|
||||
# Cleanup
|
||||
rm "tidy-config.xml"
|
||||
rm "tidy-help.xml"
|
||||
|
||||
# Done
|
||||
echo Done.
|
||||
Loading…
Reference in a new issue