diff --git a/build/documentation/README.md b/build/documentation/README.md index 23de68c..5c559cf 100644 --- a/build/documentation/README.md +++ b/build/documentation/README.md @@ -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 \ No newline at end of file + [2]: https://github.com/doxygen/doxygen diff --git a/build/documentation/build_docs.sh b/build/documentation/build_docs.sh new file mode 100755 index 0000000..a378471 --- /dev/null +++ b/build/documentation/build_docs.sh @@ -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" + diff --git a/build/documentation/doxygen.cfg b/build/documentation/doxygen.cfg index b933679..6aee6f7 100644 --- a/build/documentation/doxygen.cfg +++ b/build/documentation/doxygen.cfg @@ -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'). diff --git a/build/documentation/quickref.sh b/build/documentation/quickref.sh deleted file mode 100755 index 8794441..0000000 --- a/build/documentation/quickref.sh +++ /dev/null @@ -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. diff --git a/build/documentation/tidy1.sh b/build/documentation/tidy1.sh deleted file mode 100755 index 4c12f7a..0000000 --- a/build/documentation/tidy1.sh +++ /dev/null @@ -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.