Simplified document build system to single file. Updated README.

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
+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"`
 
@@ -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"`
 

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"
+

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').

build/documentation/quickref.sh

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

build/documentation/tidy1.sh

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