From f62049e4d250265d3e02c8424cfa123e8c7175a8 Mon Sep 17 00:00:00 2001 From: Pedro Date: Thu, 5 Mar 2015 01:19:03 +0000 Subject: [PATCH] add basic pages and install --- build/documentation/build_docs.sh | 12 ++- build/documentation/doxygen.cfg | 4 +- build/documentation/tidy_docs.dox | 145 ++++++++++++++++++++++++++++++ 3 files changed, 157 insertions(+), 4 deletions(-) create mode 100644 build/documentation/tidy_docs.dox diff --git a/build/documentation/build_docs.sh b/build/documentation/build_docs.sh index 6106ac0..9c96961 100755 --- a/build/documentation/build_docs.sh +++ b/build/documentation/build_docs.sh @@ -106,9 +106,17 @@ hash doxygen 2>/dev/null || { echo "- doxygen not found. This script requires do if [ "$BUILD_API" -eq 1 ]; then echo "The following is doxygen's stderr output. It doesn't indicate errors with this script:\n" + + # echo the output of tidy5 --help so we can include + $TIDY_PATH -h > "./tidy5.cmd.txt" + + ## this lot + # - echos and catches outputs the doxygen config + # - overwrites some vars but appending some to config an end + # - which are then passed to doxygen as stdin (instead of the path to a config.file) ( cat "$DOXY_CFG"; \ - echo "PROJECT_NUMBER=$TIDY_VERSION"; \ - echo "HTML_EXTRA_FILES=$OUTP_DIR/quickref.html"; ) \ + echo "PROJECT_NUMBER=$TIDY_VERSION"; \ + echo "HTML_EXTRA_FILES=$OUTP_DIR/quickref.html ./tidy5.cmd.txt"; ) \ | doxygen - > /dev/null echo "\nTidyLib API documentation has been built." else diff --git a/build/documentation/doxygen.cfg b/build/documentation/doxygen.cfg index 7d046c5..50c1224 100644 --- a/build/documentation/doxygen.cfg +++ b/build/documentation/doxygen.cfg @@ -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 @@ -724,7 +724,7 @@ EXCLUDE_SYMBOLS = # directories that contain example code fragments that are included (see # the \include command). -EXAMPLE_PATH = +EXAMPLE_PATH = "./" # If the value of the EXAMPLE_PATH tag contains directories, you can use the # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp diff --git a/build/documentation/tidy_docs.dox b/build/documentation/tidy_docs.dox new file mode 100644 index 0000000..a08fece --- /dev/null +++ b/build/documentation/tidy_docs.dox @@ -0,0 +1,145 @@ +/*! + +\mainpage Tidy home + +\note The repository github.com/htacg/tidy-html5 and this documentation should be considered canonical for HTML Tidy as of 2015-January-15. + +

What is tidy ?

+ +- \b `tidy` + - is a console application for Mac OS X, Linux, Windows, UNIX, and more. + - It corrects and cleans up HTML and XML documents by fixing markup errors and upgrading legacy code to modern standards. +- \b `tidylib` + - is a C static or dynamic library that developers can integrate into their applications + in order to bring all of Tidy’s power to your favorite tools. + - `tidylib` is used today in desktop applications, web servers, and more. + +\section content Contents + +- \ref tidy5_cmd +- \ref building_tidy +- \ref history + + +\page tidy5_cmd `tidy5` command + +
+\htmlinclude tidy5.cmd.txt
+
+ +\page building_tidy Building Tidy + +\section Prerequisites + + - \b git - git-scm.com/book/en/v2/Getting-Started-Installing-Git + - \b cmake - cmake.org/download/ + - Appropriate build tools for the platform + +CMake comes in two forms - command line and gui. Some installations only install one or the other, but sometimes both. The build +commands below are only for the command line use. + +Also the actual build tools vary for each platform. But that is one of the great features of cmake, it can generate +variuous 'native' build files. Running cmake without any parameters will list the generators +available on that platform. For sure one of the common ones is "Unix Makefiles", which needs autotools +make installed, but many other generators are supported. + +In windows cmake offers various versions of MSVC. Again below only the command line use of MSVC is shown, but the +tidy solution (*.sln) file can be loaded into the MSVC IDE, and the building done in there. + +\section get_source Get the source code + +Tidy’s sourcecode can be found at github.com/htacg/tidy-html5. There are sometimes +several branches, but in general `master` is the most recently updated version. + +\note Note that as “cutting edge,” it may have bugs or other +unstable behavior. If you prefer a stable, officially released version, be sure to have a look +at Releases on the github page. + +In general you can use the Download ZIP button on the github page to download the most recent version of a branch. If you prefer +Git then you can clone the repository to a working machine with: + + +\code{.sh} +git clone git@github.com:htacg/tidy-html5.git +\endcode + +\section compile Compile + +

Enter the `build/cmake` directory

+\code{.sh} +# *nix +cd {your-tidy-html5-directory}/build/cmake + +# windows +cd {your-tidy-html5-directory}\build\cmake +\endcode + +

Configure the build

+\code{.sh} +# *nix +cmake ../../ [-DCMAKE_INSTALL_PREFIX=/path/for/install] + +# windows +cmake ..\..\ +\endcode +By default cmake sets the install path to `/usr/local` in unix. + +If you wanted the binary in say `/usr/bin` instead, then use `-DCMAKE_INSTALL_PREFIX=/usr` + +On windows the default install is to `C:\Program Files\tidy5`, or `C:/Program Files (x86)/tidy5`, which is not very useful. After +the build the `tidy[n].exe` is in the `Release\` directory, and can be copied to any directory in your `PATH` environment variable, for global use. + +If you need the tidy library built as a 'shared' (DLL) library, then in add the command `-DBUILD_SHARED_LIB:BOOL=ON`. +This option is `OFF` by default, so the static library is built and linked with the command line tool for convenience. + + +

Compile

+\code{.sh} +# *nix +make + +# windows +cmake --build . --config Release +\endcode + +

Install

+\code{.sh} +# *nix +[sudo] make install + +# windows +cmake --build . --config Release --target INSTALL +\endcode + + +\page history History + +- This repository originally transferred from w3c.github.com/tidy-html5. + +- First moved to Github from tidy.sourceforge.net + + +

HTML Tidy was created by the W3C’s own Dave Raggett back in the +dawn of the Internet age. His original Internet page is still available and +gives a sense of the early history: Clean up your Web pages with HTML TIDY.

+ +

Satisfied with his work Dave passed the torch to a dedicated group of +maintainers at tidy.sourceforge.net where the important tasks of turning +Tidy into a C library and keeping up with developing standards was +performed.

+ +

W3C members took a renewed interest in Tidy in 2011 and forked the +project to github (now redirects to new maintainers), where it featured +compatibility with HTML5 via a key contribution from one of the SourceForge +key members.

+ +

In 2015 a group of concerned developers, users, and software integrators formed +HTACG with the goal of revitalizing Tidy, which had fallen into a +non-maintained state. As a W3C Community Group, HTACG was deemed worthy by the +W3C, and W3C passed ownership of their project to HTACG, where it is currently +being developed and prepped for a new, stable, and modern release.

+ +

HTACG is also working diligently with the SourceForge maintainers in an effort +to harmonize HTML Tidy into a single, stable, solid release once again.

+ +*/ \ No newline at end of file