add basic pages and install

2015-03-05 01:19:03 +00:00 · 2015-03-05 01:19:03 +00:00 · f62049e4d2
parent 334a09b1cf
commit f62049e4d2
3 changed files with 157 additions and 4 deletions
--- 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
--- 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
--- a/build/documentation/tidy_docs.dox
+++ b/build/documentation/tidy_docs.dox
@ -0,0 +1,145 @@
+/*!
+
+\mainpage Tidy home
+
+\note The repository <a href="https://github.com/htacg/tidy-html5">github.com/htacg/tidy-html5</a> and this documentation should be considered  canonical for HTML Tidy as of 2015-January-15.
+
+<h4>What is tidy ?</h4>
+
+-  \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
+
+<pre>
+\htmlinclude tidy5.cmd.txt
+</pre>
+
+\page building_tidy Building Tidy
+
+\section Prerequisites
+
+ - \b git - <a href="http://git-scm.com/book/en/v2/Getting-Started-Installing-Git">git-scm.com/book/en/v2/Getting-Started-Installing-Git</a>
+ - \b cmake - <a href="http://www.cmake.org/download/">cmake.org/download/</a>
+ - 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 <a href="https://github.com/htacg/tidy-html5">github.com/htacg/tidy-html5</a>. 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 <b>Download ZIP</b> 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
+
+<h4>Enter the `build/cmake` directory</h4>
+\code{.sh}
+# *nix
+cd {your-tidy-html5-directory}/build/cmake
+
+# windows
+cd {your-tidy-html5-directory}\build\cmake
+\endcode
+
+<h4>Configure the build</h4>
+\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.
+
+
+<h4>Compile</h4>
+\code{.sh}
+# *nix
+make
+
+# windows
+cmake --build . --config Release
+\endcode
+
+<h4>Install</h4>
+\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 <a href="https://github.com/htacg/tidy-html5">Github</a> from <a href="http://tidy.sourceforge.net/">tidy.sourceforge.net</a>
+
+
+<p><strong>HTML Tidy</strong> was created by the <a href="http://www.w3.org/">W3C’s</a> own  <a href="http://www.w3.org/People/Raggett/">Dave Raggett</a> back in the
+dawn of the Internet age. His original Internet page is still available and
+gives a sense of the early history: <a href="http://www.w3.org/People/Raggett/tidy/">Clean up your Web pages with HTML TIDY</a>.</p>
+
+<p>Satisfied with his work Dave passed the torch to a dedicated group of
+maintainers at <a href="http://tidy.sourceforge.net/">tidy.sourceforge.net</a> where the important tasks of turning
+<strong>Tidy</strong> into a C library and keeping up with developing standards was
+performed.</p>
+
+<p>W3C members took a renewed interest in <strong>Tidy</strong> in 2011 and forked the
+project to <a href="https://github.com/w3c/tidy-html5">github</a> (now redirects to new maintainers), where it featured
+compatibility with HTML5 via a <a href="https://lists.w3.org/Archives/Public/www-archive/2011Nov/0007.html">key contribution</a> from one of the SourceForge
+key members.</p>
+
+<p>In 2015 a group of concerned developers, users, and software integrators formed
+<a href="http://www.htacg.org">HTACG</a> with the goal of revitalizing <strong>Tidy</strong>, 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.</p>
+
+<p>HTACG is also working diligently with the SourceForge maintainers in an effort
+to harmonize <strong>HTML Tidy</strong> into a single, stable, solid release once again.</p>
+
+*/