Simplified document build system to single file. Updated README.

This commit is contained in:
Jim Derry 2015-02-14 13:38:16 +08:00
parent 07f90ccc81
commit 96349aedd5
5 changed files with 161 additions and 119 deletions

View file

@ -3,7 +3,7 @@
**HTML Tidy** provides several types of documentation to suit different purposes. This **HTML Tidy** provides several types of documentation to suit different purposes. This
document describes how to generate the following: 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 : This collection of documents describes the **TidyLib** API and is generated from the
comments and code in the **Tidy** source code. 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. : 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. You can clone the [repository from github][2] if it is not currently installed.
Building as simple as: 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. 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 Note that these instructions require the standard `xsltproc` utility to build the file,
build the `quickref.html` file. Note that it depends on the standard `xsltproc` utility but any XSLT processor of your choice should work, too.
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.
`tidy -xml-config > "tidy-config.xml"` `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 Note that these instructions require the standard `xsltproc` utility to build the file,
build the `tidy.1` file. Note that it depends on the standard `xsltproc` utility but any XSLT processor of your choice should work, too.
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.
`tidy -xml-config > "tidy-config.xml"` `tidy -xml-config > "tidy-config.xml"`

119
build/documentation/build_docs.sh Executable file
View 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 TidyLibs 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"

View file

@ -52,7 +52,7 @@ PROJECT_LOGO =
# If a relative path is entered, it will be relative to the location # 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. # 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 # 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 # 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 # directories like "/usr/src/myproject". Separate the files or directories
# with spaces. # with spaces.
INPUT = ../include INPUT = "../../include"
# This tag can be used to specify the character encoding of the source files # 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 # 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. # was compiled with the --with-libclang option.
# The default value is: NO. # 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 # 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 # 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. # specified with INPUT and INCLUDE_PATH.
# This tag requires that the tag CLANG_ASSISTED_PARSING is set to YES. # 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 # 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 # 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. # 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 # 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 # 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. # Minimum value: 0, maximum value: 9999, default value: 100.
# This tag requires that the tag GENERATE_HTML is set to YES. # 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 # 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 # 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 # which can be used by a validating XML parser to check the
# syntax of the XML files. # syntax of the XML files.
XML_SCHEMA = # XML_SCHEMA =
# The XML_DTD tag can be used to specify an XML DTD, # The XML_DTD tag can be used to specify an XML DTD,
# which can be used by a validating XML parser to check the # which can be used by a validating XML parser to check the
# syntax of the XML files. # syntax of the XML files.
XML_DTD = # XML_DTD =
# If the XML_PROGRAMLISTING tag is set to YES Doxygen will # If the XML_PROGRAMLISTING tag is set to YES Doxygen will
# dump the program listings (including syntax highlighting # dump the program listings (including syntax highlighting
@ -1688,7 +1688,7 @@ EXTERNAL_GROUPS = YES
# will be listed. # will be listed.
# The default value is: YES. # The default value is: YES.
EXTERNAL_PAGES EXTERNAL_PAGES =
# The PERL_PATH should be the absolute path and name of the perl script # The PERL_PATH should be the absolute path and name of the perl script
# interpreter (i.e. the result of `which perl'). # interpreter (i.e. the result of `which perl').

View file

@ -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.

View file

@ -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.