From c8506c3095002662787c5ae4f9603c51518e4fe1 Mon Sep 17 00:00:00 2001 From: Pedro Date: Wed, 4 Mar 2015 22:36:10 +0000 Subject: [PATCH 01/15] Read doxygen version from version.txt file --- build/documentation/build_docs.sh | 4 +++- build/documentation/doxygen.cfg | 10 +++++----- 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/build/documentation/build_docs.sh b/build/documentation/build_docs.sh index a378471..7d2dcc2 100755 --- a/build/documentation/build_docs.sh +++ b/build/documentation/build_docs.sh @@ -9,6 +9,8 @@ TIDY_PATH="./tidy5" # Current directory. +TIDY_VERSION=`cat ../../version.txt` + cat << HEREDOC @@ -104,7 +106,7 @@ 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" - doxygen "$DOXY_CFG" > /dev/null + ( cat "$DOXY_CFG"; echo "PROJECT_NUMBER=$TIDY_VERSION" ) | doxygen - > /dev/null echo "\nTidyLib API documentation has been built." else echo "* $OUTP_DIR/tidylib_api/ was skipped because not all dependencies were satisfied." diff --git a/build/documentation/doxygen.cfg b/build/documentation/doxygen.cfg index 6aee6f7..847b5f1 100644 --- a/build/documentation/doxygen.cfg +++ b/build/documentation/doxygen.cfg @@ -475,14 +475,14 @@ INLINE_INFO = YES # alphabetically by member name. If set to NO the members will appear in # declaration order. -SORT_MEMBER_DOCS = NO +SORT_MEMBER_DOCS = YES # If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the # brief documentation of file, namespace and class members alphabetically # by member name. If set to NO (the default) the members will appear in # declaration order. -SORT_BRIEF_DOCS = NO +SORT_BRIEF_DOCS = YES # If the SORT_MEMBERS_CTORS_1ST tag is set to YES then doxygen # will sort the (brief and detailed) documentation of class members so that @@ -498,7 +498,7 @@ SORT_MEMBERS_CTORS_1ST = NO # hierarchy of group names into alphabetical order. If set to NO (the default) # the group names will appear in their defined order. -SORT_GROUP_NAMES = NO +SORT_GROUP_NAMES = YES # If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be # sorted by fully-qualified names, including namespaces. If set to @@ -508,7 +508,7 @@ SORT_GROUP_NAMES = NO # Note: This option applies only to the class list, not to the # alphabetical list. -SORT_BY_SCOPE_NAME = NO +SORT_BY_SCOPE_NAME = YES # If the STRICT_PROTO_MATCHING option is enabled and doxygen fails to # do proper type resolution of all parameters of a function it will reject a @@ -624,7 +624,7 @@ WARNINGS = YES # for undocumented members. If EXTRACT_ALL is set to YES then this flag will # automatically be disabled. -WARN_IF_UNDOCUMENTED = NO +WARN_IF_UNDOCUMENTED = YES # If WARN_IF_DOC_ERROR is set to YES, doxygen will generate warnings for # potential errors in the documentation, such as not documenting some From 9488c2fdb761d8344b08f5129b6cda52f09343f8 Mon Sep 17 00:00:00 2001 From: Pedro Date: Wed, 4 Mar 2015 22:38:56 +0000 Subject: [PATCH 02/15] Read doxygen version from version.txt file --- build/documentation/doxygen.cfg | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/build/documentation/doxygen.cfg b/build/documentation/doxygen.cfg index 847b5f1..1f0cd58 100644 --- a/build/documentation/doxygen.cfg +++ b/build/documentation/doxygen.cfg @@ -1171,7 +1171,7 @@ ECLIPSE_DOC_ID = org.doxygen.Project # top of each HTML page. The value NO (the default) enables the index and # the value YES disables it. -DISABLE_INDEX = YES +DISABLE_INDEX = NO # The GENERATE_TREEVIEW tag is used to specify whether a tree-like index # structure should be generated to display hierarchical information. From 1e60415120a82c6429c61a2250fd2b002cfbae44 Mon Sep 17 00:00:00 2001 From: Pedro Date: Wed, 4 Mar 2015 22:58:32 +0000 Subject: [PATCH 03/15] Add layout dile for doxygen with links to websites --- build/documentation/DoxygenLayout.xml | 197 ++++++++++++++++++++++++++ build/documentation/doxygen.cfg | 6 +- 2 files changed, 200 insertions(+), 3 deletions(-) create mode 100644 build/documentation/DoxygenLayout.xml diff --git a/build/documentation/DoxygenLayout.xml b/build/documentation/DoxygenLayout.xml new file mode 100644 index 0000000..1e11b43 --- /dev/null +++ b/build/documentation/DoxygenLayout.xml @@ -0,0 +1,197 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/build/documentation/doxygen.cfg b/build/documentation/doxygen.cfg index 1f0cd58..dbe2e22 100644 --- a/build/documentation/doxygen.cfg +++ b/build/documentation/doxygen.cfg @@ -594,7 +594,7 @@ FILE_VERSION_FILTER = # You can optionally specify a file name after the option, if omitted # DoxygenLayout.xml will be used as the name of the layout file. -LAYOUT_FILE = +LAYOUT_FILE = DoxygenLayout.xml # The CITE_BIB_FILES tag can be used to specify one or more bib files # containing the references data. This must be a list of .bib files. The @@ -978,7 +978,7 @@ HTML_COLORSTYLE_HUE = 220 # the colors in the HTML output. For a value of 0 the output will use # grayscales only. A value of 255 will produce the most vivid colors. -HTML_COLORSTYLE_SAT = 100 +HTML_COLORSTYLE_SAT = 10 # The HTML_COLORSTYLE_GAMMA tag controls the gamma correction applied to # the luminance component of the colors in the HTML output. Values below @@ -987,7 +987,7 @@ HTML_COLORSTYLE_SAT = 100 # so 80 represents a gamma of 0.8, The value 220 represents a gamma of 2.2, # and 100 does not change the gamma. -HTML_COLORSTYLE_GAMMA = 80 +HTML_COLORSTYLE_GAMMA = 220 # If the HTML_TIMESTAMP tag is set to YES then the footer of each generated HTML # page will contain the date and time when the page was generated. Setting From 334a09b1cf7586bc76fe8e1ef7e1c20baafb5f5c Mon Sep 17 00:00:00 2001 From: Pedro Date: Wed, 4 Mar 2015 23:36:33 +0000 Subject: [PATCH 04/15] Add quickref.html to doxygen build site --- build/documentation/DoxygenLayout.xml | 3 ++- build/documentation/README.md | 4 ++-- build/documentation/build_docs.sh | 5 ++++- build/documentation/doxygen.cfg | 4 ++-- 4 files changed, 10 insertions(+), 6 deletions(-) diff --git a/build/documentation/DoxygenLayout.xml b/build/documentation/DoxygenLayout.xml index 1e11b43..e437cdd 100644 --- a/build/documentation/DoxygenLayout.xml +++ b/build/documentation/DoxygenLayout.xml @@ -3,7 +3,8 @@ - + + diff --git a/build/documentation/README.md b/build/documentation/README.md index fb83b9d..3a74b36 100644 --- a/build/documentation/README.md +++ b/build/documentation/README.md @@ -1,4 +1,4 @@ -# DOCUMENTATION HOW-TO +# Documentation HOW-TO **HTML Tidy** provides several types of documentation to suit different purposes. This document describes how to generate the following: @@ -92,7 +92,7 @@ but any XSLT processor of your choice should work, too. - This examples uses the `xsltproc` command to transform `tidy-help.xml` using the rules in the `tidy1.xsl` stylesheet, and output it to `tidy.1`. - Note that `tidy1.xls` includes the file `tidy-config.xml` as part of the stylesheet, + \note Note that `tidy1.xls` includes the file `tidy-config.xml` as part of the stylesheet, and so although it does not appear in the command invocation, it is indeed required. diff --git a/build/documentation/build_docs.sh b/build/documentation/build_docs.sh index 7d2dcc2..6106ac0 100755 --- a/build/documentation/build_docs.sh +++ b/build/documentation/build_docs.sh @@ -106,7 +106,10 @@ 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" - ( cat "$DOXY_CFG"; echo "PROJECT_NUMBER=$TIDY_VERSION" ) | doxygen - > /dev/null + ( cat "$DOXY_CFG"; \ + echo "PROJECT_NUMBER=$TIDY_VERSION"; \ + echo "HTML_EXTRA_FILES=$OUTP_DIR/quickref.html"; ) \ + | doxygen - > /dev/null echo "\nTidyLib API documentation has been built." else echo "* $OUTP_DIR/tidylib_api/ was skipped because not all dependencies were satisfied." diff --git a/build/documentation/doxygen.cfg b/build/documentation/doxygen.cfg index dbe2e22..7d046c5 100644 --- a/build/documentation/doxygen.cfg +++ b/build/documentation/doxygen.cfg @@ -624,7 +624,7 @@ WARNINGS = YES # for undocumented members. If EXTRACT_ALL is set to YES then this flag will # automatically be disabled. -WARN_IF_UNDOCUMENTED = YES +WARN_IF_UNDOCUMENTED = NO # If WARN_IF_DOC_ERROR is set to YES, doxygen will generate warnings for # potential errors in the documentation, such as not documenting some @@ -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 From f62049e4d250265d3e02c8424cfa123e8c7175a8 Mon Sep 17 00:00:00 2001 From: Pedro Date: Thu, 5 Mar 2015 01:19:03 +0000 Subject: [PATCH 05/15] 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 From 1af91f985c3a5e301bc18648f03ed08e6f134bd1 Mon Sep 17 00:00:00 2001 From: Pedro Date: Thu, 5 Mar 2015 02:03:48 +0000 Subject: [PATCH 06/15] add example --- build/documentation/README.md | 2 +- build/documentation/tidy_docs.dox | 63 +++++++++++++++++++++++++++++++ 2 files changed, 64 insertions(+), 1 deletion(-) diff --git a/build/documentation/README.md b/build/documentation/README.md index 3a74b36..96359e8 100644 --- a/build/documentation/README.md +++ b/build/documentation/README.md @@ -1,4 +1,4 @@ -# Documentation HOW-TO +# Documentation HOWTO **HTML Tidy** provides several types of documentation to suit different purposes. This document describes how to generate the following: diff --git a/build/documentation/tidy_docs.dox b/build/documentation/tidy_docs.dox index a08fece..cb9f62f 100644 --- a/build/documentation/tidy_docs.dox +++ b/build/documentation/tidy_docs.dox @@ -17,16 +17,79 @@ \section content Contents - \ref tidy5_cmd +- \ref tidy5_lib - \ref building_tidy - \ref history + + \page tidy5_cmd `tidy5` command 
 \htmlinclude tidy5.cmd.txt
+\page tidy5_lib tidy5lib + +- \b TidyLib is easy to integrate. Because of the near universal adoption of C linkage, a C interface may be called from a great number of programming languages. + +- \b TidyLib was designed to use opaque types in the public interface. This allows the application to just pass an integer around and the need to transform data types in different languages is minimized. As a results it’s straight-forward to write very thin library wrappers for C++, Pascal, and COM/ATL. + +- \b TidyLib eats its own dogfood. HTML Tidy links directly to TidyLib. + +- \b TidyLib is Thread Safe and Re-entrant. Because there are many uses for HTML Tidy - from content validation, content scraping, conversion to XHTML - it was important to make TidyLib run reasonably well within server applications as well as client side. + +- \b TidyLib uses adaptable I/O. As part of the larger integration strategy it was decided to fully abstract all I/O. This means a (relatively) clean separation between character encoding processing and shovelling bytes back and forth. Internally, the library reads from sources and writes to sinks. This abstraction is used for both markup and configuration “files”. Concrete implementations are provided for file and memory I/O, and new sources and sinks may be provided via the public interface. + +\code{.c} +#include ; +#include ; +#include ; +#include ; + +int main(int argc, char **argv ) +{ + const char* input = "Foo

Foo!"; + TidyBuffer output = {0}; + TidyBuffer errbuf = {0}; + int rc = -1; + Bool ok; + + TidyDoc tdoc = tidyCreate(); // Initialize "document" + printf( "Tidying:\t%s\n", input ); + + ok = tidyOptSetBool( tdoc, TidyXhtmlOut, yes ); // Convert to XHTML + if ( ok ) + rc = tidySetErrorBuffer( tdoc, &errbuf ); // Capture diagnostics + if ( rc >= 0 ) + rc = tidyParseString( tdoc, input ); // Parse the input + if ( rc >= 0 ) + rc = tidyCleanAndRepair( tdoc ); // Tidy it up! + if ( rc >= 0 ) + rc = tidyRunDiagnostics( tdoc ); // Kvetch + if ( rc > 1 ) // If error, force output. + rc = ( tidyOptSetBool(tdoc, TidyForceOutput, yes) ? rc : -1 ); + if ( rc >= 0 ) + rc = tidySaveBuffer( tdoc, &output ); // Pretty Print + + if ( rc >= 0 ) + { + if ( rc > 0 ) + printf( "\nDiagnostics:\n\n%s", errbuf.bp ); + printf( "\nAnd here is the result:\n\n%s", output.bp ); + } + else + printf( "A severe error (%d) occurred.\n", rc ); + + tidyBufFree( &output ); + tidyBufFree( &errbuf ); + tidyRelease( tdoc ); + return rc; +} +\endcode + + \page building_tidy Building Tidy \section Prerequisites From 4a5b360847ed4e16680cf5bdec8dfa674a0c8119 Mon Sep 17 00:00:00 2001 From: Pedro Date: Thu, 5 Mar 2015 03:07:36 +0000 Subject: [PATCH 07/15] home sweet home --- build/documentation/DoxygenLayout.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/build/documentation/DoxygenLayout.xml b/build/documentation/DoxygenLayout.xml index e437cdd..a90dcf7 100644 --- a/build/documentation/DoxygenLayout.xml +++ b/build/documentation/DoxygenLayout.xml @@ -2,7 +2,7 @@ - + From 81187629c31c71174e233e082937a066471df911 Mon Sep 17 00:00:00 2001 From: Pedro Date: Thu, 5 Mar 2015 05:14:21 +0000 Subject: [PATCH 08/15] extract more api data via some doxy settings and test to comments --- build/documentation/doxygen.cfg | 24 ++++++++++++------------ build/documentation/tidy_docs.dox | 15 ++++++++------- include/tidy.h | 6 +++--- 3 files changed, 23 insertions(+), 22 deletions(-) diff --git a/build/documentation/doxygen.cfg b/build/documentation/doxygen.cfg index 50c1224..f4f5248 100644 --- a/build/documentation/doxygen.cfg +++ b/build/documentation/doxygen.cfg @@ -113,7 +113,7 @@ ABBREVIATE_BRIEF = # Doxygen will generate a detailed section even if there is only a brief # description. -ALWAYS_DETAILED_SEC = NO +ALWAYS_DETAILED_SEC = YES # If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all # inherited members of a class in the documentation of that class as if those @@ -158,7 +158,7 @@ SHORT_NAMES = NO # comments will behave just like regular Qt-style comments # (thus requiring an explicit @brief command for a brief description.) -JAVADOC_AUTOBRIEF = NO +JAVADOC_AUTOBRIEF = YES # If the QT_AUTOBRIEF tag is set to YES then Doxygen will # interpret the first line (until the first dot) of a Qt-style @@ -166,7 +166,7 @@ JAVADOC_AUTOBRIEF = NO # will behave just like regular Qt-style comments (thus requiring # an explicit \brief command for a brief description.) -QT_AUTOBRIEF = NO +QT_AUTOBRIEF = YES # The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make Doxygen # treat a multi-line C++ special comment block (i.e. a block of //! or /// @@ -174,7 +174,7 @@ QT_AUTOBRIEF = NO # The new default is to treat a multi-line C++ comment block as a detailed # description. Set this tag to YES if you prefer the old behaviour instead. -MULTILINE_CPP_IS_BRIEF = NO +MULTILINE_CPP_IS_BRIEF = YES # If the INHERIT_DOCS tag is set to YES (the default) then an undocumented # member inherits the documentation from any documented member that it @@ -307,7 +307,7 @@ SUBGROUPING = YES # @ingroup) instead of on a separate page (for HTML and Man pages) or # section (for LaTeX and RTF). -INLINE_GROUPED_CLASSES = NO +INLINE_GROUPED_CLASSES = YES # When the INLINE_SIMPLE_STRUCTS tag is set to YES, structs, classes, and # unions with only public data fields will be shown inline in the documentation @@ -316,7 +316,7 @@ INLINE_GROUPED_CLASSES = NO # structs, classes, and unions are shown on a separate page (for HTML and Man # pages) or section (for LaTeX and RTF). -INLINE_SIMPLE_STRUCTS = NO +INLINE_SIMPLE_STRUCTS = YES # When TYPEDEF_HIDES_STRUCT is enabled, a typedef of a struct, union, or enum # is documented as struct, union, or enum with the name of the typedef. So @@ -350,23 +350,23 @@ LOOKUP_CACHE_SIZE = 0 # Private class members and static file members will be hidden unless # the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES -EXTRACT_ALL = NO +EXTRACT_ALL = YES # If the EXTRACT_PRIVATE tag is set to YES all private members of a class # will be included in the documentation. -EXTRACT_PRIVATE = NO +EXTRACT_PRIVATE = YES # If the EXTRACT_PACKAGE tag is set to YES, all members with package or # internal scope will be included in the documentation. # The default value is: NO. -EXTRACT_PACKAGE = NO +EXTRACT_PACKAGE = YES # If the EXTRACT_STATIC tag is set to YES all static members of a file # will be included in the documentation. -EXTRACT_STATIC = NO +EXTRACT_STATIC = YES # If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs) # defined locally in source files will be included in the documentation. @@ -379,7 +379,7 @@ EXTRACT_LOCAL_CLASSES = YES # the interface are included in the documentation. # If set to NO (the default) only methods in the interface are included. -EXTRACT_LOCAL_METHODS = NO +EXTRACT_LOCAL_METHODS = YES # If this flag is set to YES, the members of anonymous namespaces will be # extracted and appear in the documentation as a namespace called @@ -798,7 +798,7 @@ USE_MDFILE_AS_MAINPAGE = # Note: To get rid of all source code in the generated output, make sure also # VERBATIM_HEADERS is set to NO. -SOURCE_BROWSER = NO +SOURCE_BROWSER = YES # Setting the INLINE_SOURCES tag to YES will include the body # of functions and classes directly in the documentation. diff --git a/build/documentation/tidy_docs.dox b/build/documentation/tidy_docs.dox index cb9f62f..304d6a2 100644 --- a/build/documentation/tidy_docs.dox +++ b/build/documentation/tidy_docs.dox @@ -30,18 +30,19 @@ \htmlinclude tidy5.cmd.txt -\page tidy5_lib tidy5lib +\page TidyLib TidyLib -- \b TidyLib is easy to integrate. Because of the near universal adoption of C linkage, a C interface may be called from a great number of programming languages. +- \b TidyLib - is easy to integrate. Because of the near universal adoption of C linkage, a C interface may be called from a great number of programming languages. -- \b TidyLib was designed to use opaque types in the public interface. This allows the application to just pass an integer around and the need to transform data types in different languages is minimized. As a results it’s straight-forward to write very thin library wrappers for C++, Pascal, and COM/ATL. +- \b TidyLib - is designed to use opaque types in the public interface. This allows the application to just pass an integer around and the need to transform data types in different languages is minimized. As a results it’s straight-forward to write very thin library wrappers for C++, Pascal, and COM/ATL. -- \b TidyLib eats its own dogfood. HTML Tidy links directly to TidyLib. +- \b TidyLib - eats its own dogfood. HTML Tidy links directly to TidyLib. -- \b TidyLib is Thread Safe and Re-entrant. Because there are many uses for HTML Tidy - from content validation, content scraping, conversion to XHTML - it was important to make TidyLib run reasonably well within server applications as well as client side. +- \b TidyLib - is Thread Safe and Re-entrant. Because there are many uses for HTML Tidy - from content validation, content scraping, conversion to XHTML - it was important to make TidyLib run reasonably well within server applications as well as client side. -- \b TidyLib uses adaptable I/O. As part of the larger integration strategy it was decided to fully abstract all I/O. This means a (relatively) clean separation between character encoding processing and shovelling bytes back and forth. Internally, the library reads from sources and writes to sinks. This abstraction is used for both markup and configuration “files”. Concrete implementations are provided for file and memory I/O, and new sources and sinks may be provided via the public interface. +- \b TidyLib - uses adaptable I/O. As part of the larger integration strategy it was decided to fully abstract all I/O. This means a (relatively) clean separation between character encoding processing and shovelling bytes back and forth. Internally, the library reads from sources and writes to sinks. This abstraction is used for both markup and configuration “files”. Concrete implementations are provided for file and memory I/O, and new sources and sinks may be provided via the public interface. +\section example_hello Example \code{.c} #include ; #include ; @@ -50,7 +51,7 @@ int main(int argc, char **argv ) { - const char* input = "Foo

Foo!"; + const char* input = "Hello

World!"; TidyBuffer output = {0}; TidyBuffer errbuf = {0}; int rc = -1; diff --git a/include/tidy.h b/include/tidy.h index 87d5453..6ef5347 100755 --- a/include/tidy.h +++ b/include/tidy.h @@ -160,7 +160,7 @@ struct _TidyAllocator; /** The allocator **/ typedef struct _TidyAllocator TidyAllocator; -/** An allocator's function table. All functions here must +/** An allocator's function table. All functions here must be provided. */ struct _TidyAllocatorVtbl { @@ -187,7 +187,7 @@ struct _TidyAllocatorVtbl { /** An allocator. To create your own allocator, do something like the following: - + \code typedef struct _MyAllocator { TidyAllocator base; ...other custom allocator state... @@ -213,7 +213,7 @@ struct _TidyAllocatorVtbl { allocator.base.vtbl = &MyAllocatorVtbl; ...initialise allocator specific state... doc = tidyCreateWithAllocator(&allocator); - ... + \endcode Although this looks slightly long winded, the advantage is that to create a custom allocator you simply need to set the vtbl pointer correctly. From 04beaeed0205a716c2703fef07d653efc0ce3e7d Mon Sep 17 00:00:00 2001 From: Pedro Date: Thu, 5 Mar 2015 05:30:48 +0000 Subject: [PATCH 09/15] extract example.c into its own file and include --- build/documentation/example.1.c | 49 +++++++++++++++++++++++++++++++ build/documentation/tidy_docs.dox | 46 +---------------------------- 2 files changed, 50 insertions(+), 45 deletions(-) create mode 100644 build/documentation/example.1.c diff --git a/build/documentation/example.1.c b/build/documentation/example.1.c new file mode 100644 index 0000000..69991ad --- /dev/null +++ b/build/documentation/example.1.c @@ -0,0 +1,49 @@ + + +#include ; +#include ; +#include ; +#include ; + +int main(int argc, char **argv ) +{ + const char* input = "Hello

World!"; + TidyBuffer output = {0}; + TidyBuffer errbuf = {0}; + int rc = -1; + Bool ok; + + // Initialize "document" + TidyDoc tdoc = tidyCreate(); + printf( "Tidying:\t%s\n", input ); + + // Convert to XHTML + ok = tidyOptSetBool( tdoc, TidyXhtmlOut, yes ); + if ( ok ) + rc = tidySetErrorBuffer( tdoc, &errbuf ); // Capture diagnostics + if ( rc >= 0 ) + rc = tidyParseString( tdoc, input ); // Parse the input + if ( rc >= 0 ) + rc = tidyCleanAndRepair( tdoc ); // Tidy it up! + if ( rc >= 0 ) + rc = tidyRunDiagnostics( tdoc ); // Kvetch + if ( rc > 1 ) // If error, force output. + rc = ( tidyOptSetBool(tdoc, TidyForceOutput, yes) ? rc : -1 ); + if ( rc >= 0 ) + rc = tidySaveBuffer( tdoc, &output ); // Pretty Print + + if ( rc >= 0 ) + { + if ( rc > 0 ) + printf( "\nDiagnostics:\n\n%s", errbuf.bp ); + printf( "\nAnd here is the result:\n\n%s", output.bp ); + } + else + printf( "A severe error (%d) occurred.\n", rc ); + + tidyBufFree( &output ); + tidyBufFree( &errbuf ); + tidyRelease( tdoc ); + return rc; +} + diff --git a/build/documentation/tidy_docs.dox b/build/documentation/tidy_docs.dox index 304d6a2..92b7633 100644 --- a/build/documentation/tidy_docs.dox +++ b/build/documentation/tidy_docs.dox @@ -43,52 +43,8 @@ - \b TidyLib - uses adaptable I/O. As part of the larger integration strategy it was decided to fully abstract all I/O. This means a (relatively) clean separation between character encoding processing and shovelling bytes back and forth. Internally, the library reads from sources and writes to sinks. This abstraction is used for both markup and configuration “files”. Concrete implementations are provided for file and memory I/O, and new sources and sinks may be provided via the public interface. \section example_hello Example -\code{.c} -#include ; -#include ; -#include ; -#include ; -int main(int argc, char **argv ) -{ - const char* input = "Hello

World!"; - TidyBuffer output = {0}; - TidyBuffer errbuf = {0}; - int rc = -1; - Bool ok; - - TidyDoc tdoc = tidyCreate(); // Initialize "document" - printf( "Tidying:\t%s\n", input ); - - ok = tidyOptSetBool( tdoc, TidyXhtmlOut, yes ); // Convert to XHTML - if ( ok ) - rc = tidySetErrorBuffer( tdoc, &errbuf ); // Capture diagnostics - if ( rc >= 0 ) - rc = tidyParseString( tdoc, input ); // Parse the input - if ( rc >= 0 ) - rc = tidyCleanAndRepair( tdoc ); // Tidy it up! - if ( rc >= 0 ) - rc = tidyRunDiagnostics( tdoc ); // Kvetch - if ( rc > 1 ) // If error, force output. - rc = ( tidyOptSetBool(tdoc, TidyForceOutput, yes) ? rc : -1 ); - if ( rc >= 0 ) - rc = tidySaveBuffer( tdoc, &output ); // Pretty Print - - if ( rc >= 0 ) - { - if ( rc > 0 ) - printf( "\nDiagnostics:\n\n%s", errbuf.bp ); - printf( "\nAnd here is the result:\n\n%s", output.bp ); - } - else - printf( "A severe error (%d) occurred.\n", rc ); - - tidyBufFree( &output ); - tidyBufFree( &errbuf ); - tidyRelease( tdoc ); - return rc; -} -\endcode +\include example.1.c \page building_tidy Building Tidy From 9a5ba3a4e897b9f36724ff6b466b4dd44dbceab7 Mon Sep 17 00:00:00 2001 From: Jim Derry Date: Sun, 8 Mar 2015 11:12:36 +0800 Subject: [PATCH 10/15] Moved generated output to temp --- build/documentation/build_docs.sh | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/build/documentation/build_docs.sh b/build/documentation/build_docs.sh index 9c96961..5961e6f 100755 --- a/build/documentation/build_docs.sh +++ b/build/documentation/build_docs.sh @@ -108,7 +108,7 @@ 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" + $TIDY_PATH -h > "./temp/tidy5.cmd.txt" ## this lot # - echos and catches outputs the doxygen config @@ -116,7 +116,7 @@ if [ "$BUILD_API" -eq 1 ]; then # - 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 ./tidy5.cmd.txt"; ) \ + echo "HTML_EXTRA_FILES=$OUTP_DIR/quickref.html ./temp/tidy5.cmd.txt"; ) \ | doxygen - > /dev/null echo "\nTidyLib API documentation has been built." else From 52ef5f89ce46573f26bffba6fb9cbd1ab1afb4ef Mon Sep 17 00:00:00 2001 From: Jim Derry Date: Sun, 8 Mar 2015 11:34:17 +0800 Subject: [PATCH 11/15] Squelch documentation building errors. --- include/tidy.h | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/include/tidy.h b/include/tidy.h index 6ef5347..945d38b 100755 --- a/include/tidy.h +++ b/include/tidy.h @@ -261,10 +261,10 @@ TIDY_EXPORT Bool TIDY_CALL tidySetPanicCall( TidyPanic fpanic ); The following is a short example program. 

-#include <tidy.h>
-#include <buffio.h>
-#include <stdio.h>
-#include <errno.h>
+\#include <tidy.h>
+\#include <buffio.h>
+\#include <stdio.h>
+\#include <errno.h>
 
 
 int main(int argc, char **argv )

From 424c9d782bf939a067e3826c9a0db0a8bf5cd0ee Mon Sep 17 00:00:00 2001
From: Jim Derry 
Date: Sun, 8 Mar 2015 11:34:49 +0800
Subject: [PATCH 12/15] Removed unused reference causing warnings.

---
 build/documentation/tidy_docs.dox | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/build/documentation/tidy_docs.dox b/build/documentation/tidy_docs.dox
index 92b7633..2f7968f 100644
--- a/build/documentation/tidy_docs.dox
+++ b/build/documentation/tidy_docs.dox
@@ -17,7 +17,6 @@
 \section content Contents
 
 - \ref tidy5_cmd
-- \ref tidy5_lib
 - \ref building_tidy
 - \ref history
     
@@ -162,4 +161,4 @@ 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
+*/

From 817c7752096d444dde07813c38e6dc61806165cc Mon Sep 17 00:00:00 2001
From: Jim Derry 
Date: Sun, 8 Mar 2015 11:35:46 +0800
Subject: [PATCH 13/15] Use the temporary directory variable.

---
 build/documentation/build_docs.sh | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/build/documentation/build_docs.sh b/build/documentation/build_docs.sh
index 5961e6f..11175e2 100755
--- a/build/documentation/build_docs.sh
+++ b/build/documentation/build_docs.sh
@@ -73,7 +73,7 @@ if [ "$BUILD_XSLT" -eq 1 ]; then
 	xsltproc "quickref.xsl" "tidy-config.xml" > "$OUTP_DIR/quickref.html"
 
 	# 'tidy.1'
-	xsltproc "tidy1.xsl" "$tidy-help.xml" > "$OUTP_DIR/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.
@@ -108,15 +108,15 @@ 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 > "./temp/tidy5.cmd.txt"
+  $TIDY_PATH -h > "./$OUTP_DIR/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 ./temp/tidy5.cmd.txt"; ) \
+    echo "PROJECT_NUMBER=$TIDY_VERSION"; \
+    echo "HTML_EXTRA_FILES=$OUTP_DIR/quickref.html ./$OUTP_DIR/tidy5.cmd.txt"; ) \
     | doxygen - > /dev/null
   echo "\nTidyLib API documentation has been built."
 else

From 6e2411120e1ccf2753406efa23e44f4924c6f676 Mon Sep 17 00:00:00 2001
From: Jim Derry 
Date: Sun, 8 Mar 2015 11:35:59 +0800
Subject: [PATCH 14/15] Add another examples directory.

---
 build/documentation/doxygen.cfg | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/build/documentation/doxygen.cfg b/build/documentation/doxygen.cfg
index f4f5248..7cf2385 100644
--- a/build/documentation/doxygen.cfg
+++ b/build/documentation/doxygen.cfg
@@ -724,7 +724,7 @@ EXCLUDE_SYMBOLS        =
 # directories that contain example code fragments that are included (see
 # the \include command).
 
-EXAMPLE_PATH           = "./"
+EXAMPLE_PATH           = "./" "./temp/"
 
 # 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

From 6099f132e758c975b8d8878fbbabc89a05d1f028 Mon Sep 17 00:00:00 2001
From: Jim Derry 
Date: Sun, 8 Mar 2015 11:51:54 +0800
Subject: [PATCH 15/15] Tweaked the colors a bit to eliminate the illegible
 text shadow effect.

---
 build/documentation/doxygen.cfg | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/build/documentation/doxygen.cfg b/build/documentation/doxygen.cfg
index 7cf2385..21ba5a1 100644
--- a/build/documentation/doxygen.cfg
+++ b/build/documentation/doxygen.cfg
@@ -978,7 +978,7 @@ HTML_COLORSTYLE_HUE    = 220
 # the colors in the HTML output. For a value of 0 the output will use
 # grayscales only. A value of 255 will produce the most vivid colors.
 
-HTML_COLORSTYLE_SAT    = 10
+HTML_COLORSTYLE_SAT    = 50
 
 # The HTML_COLORSTYLE_GAMMA tag controls the gamma correction applied to
 # the luminance component of the colors in the HTML output. Values below
@@ -987,7 +987,7 @@ HTML_COLORSTYLE_SAT    = 10
 # so 80 represents a gamma of 0.8, The value 220 represents a gamma of 2.2,
 # and 100 does not change the gamma.
 
-HTML_COLORSTYLE_GAMMA  = 220
+HTML_COLORSTYLE_GAMMA  = 100
 
 # If the HTML_TIMESTAMP tag is set to YES then the footer of each generated HTML
 # page will contain the date and time when the page was generated. Setting