Merge pull request #2 from mojavelinux/upstream-5_1_36

resolves #1 fast-forward to upstream (v5.1.36) and update Makefile

Author: lovasoa

.gitignore

@@ -31,3 +31,4 @@ temp*
 *.bak
 .DS_Store
 .idea
+*.old

CMakeLists.txt

@@ -1,54 +1,9 @@
 # HTML Tidy with HTML5 support
 
-## Prerequisites
+All READMEs and related materials have been relocated into [README/][1].
 
-  1. git - http://git-scm.com/book/en/v2/Getting-Started-Installing-Git
-  
-  2. cmake - http://www.cmake.org/download/
-  
-  3. 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.
+For build instructions please see [README/README.md][2].
 
-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.
-
-
-## Build the tidy library and command line tool
-
-  1. `cd build/cmake`
-
-  2. `cmake ../.. [-DCMAKE_INSTALL_PREFIX=/path/for/install]`
-
-  3. Windows:  `cmake --build . --config Release`  
-     Unix/OS X: `make`
-
-  4. Install, if desired:  
-     Windows: `cmake --build . --config Release --target INSTALL`  
-     Unix/OS X: `[sudo] make install`
-
-By default cmake sets the install path to /usr/local in unix. If you wanted the binary in say /usr/bin instead, then in 2. above use -DCMAKE_INSTALL_PREFIX=/usr
-
-In 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 2. 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.
-
-## Prebuilt Binaries
-
-An attempt is being made to publish pre-built binaries to http://www.htacg.org/binaries - This is still a work in progress, but getting there..
-
-## History
-
-This repository should be considered canonical for HTML Tidy as of 2015-January-15.
-
- - This repository originally transferred from [w3c.github.com/tidy-html5][1].
- 
- - First moved to Github from [tidy.sourceforge.net][2].
-
-
-   [1]: http://w3c.github.com/tidy-html5/
-
-   [2]: http://tidy.sourceforge.net
-
-; eof
+ [1]: https://github.com/htacg/tidy-html5/tree/master/README
+ [2]:https://github.com/htacg/tidy-html5/blob/master/README/README.md
+ 

README.md

@@ -0,0 +1,24 @@
+# HTML Tidy Code Style
+
+The source code of **libTidy**, and console app **tidy**, follow the preferences of the original maintainers. Perhaps some of these decisions were arbitrary and based on their sense of aesthetics at the time, but it is good to have all the code looking the same even if it is not exactly what everyone would prefer.
+
+Developers adding code to **Tidy!** are urged to try to follow the existing code style. Code that does not follow these conventions may be accepted, but may be modified as time goes by to best fit the `Tidy Style`.
+
+There has been a suggestion of using available utilities to make the style consistent, like [Uncrusty](https://github/bengardener/uncrusty) - see [issue #245](https://github.com/htacg/tidy-html5/issues/245), and maybe others...
+
+Others have suggested the [AStyle](http://astyle.sourceforge.net/) formatting program with say  '-taOHUKk3 -M8' arguments, to conform, but there are a few bugs in AStyle.
+
+But again these, and other tools, may not produce code that everybody agrees with... and are presently not formally used in Tidy!
+
+#### Known Conventions
+
+From reading of the Tidy source, some things are self evident... in no particular order...
+
+ - Use of 4-space indenting, and no tabs.
+ - No C++ single line comments using `//`.
+ - The openning `{` is indented on the next newline.
+ - While the maximum code line length varies, generally long `if`, `while`, ... statements are wrapped to newlines.
+
+Look forward to this document being filled out in detail...
+
+Date: 20150904

README/CODESTYLE.md

@@ -0,0 +1,59 @@
+# Contributing to HTML Tidy
+
+So you want to contribute to Tidy? Fantastic! Here's a brief overview on how best to do so.
+
+### Support request
+
+If you are having trouble running console `Tidy`, or using the `Tidy Library` API in your own project, then maybe the best places to get help is either via a comment in [Tidy Issues](https://github.com/htacg/tidy-html5/issues), or on the [Tidy Mail Archive](https://lists.w3.org/Archives/Public/html-tidy/) list.
+
+In either place please start with a short subject to describe the issue. If it involves running tidy on a html file, or an API question, make sure to include the version: `$ tidy -v`; what was the configuration used; a small sample input; the output, and the output expected; some sample code, to make quick testing easy.
+
+If you do add a sample html input, then it can also be very helpful if that sample **passes** the W3C [validation](https://validator.w3.org/#validate_by_upload)... tidy attempts to follow all current W3C standards...
+
+If you are able to build tidy from [source](https://github.com/htacg/tidy-html5), requires [CMake](https://cmake.org/download/), and can find the problem in the code, then read on about how you can create a `Pull Request`... share your code, ideas, ....
+
+### What to change
+
+Here are some examples of things you might want to make a pull request for:
+
+ - New features
+ - Bug fixes
+ - Inefficient blocks of code
+ - Memory problems
+ - Language translations
+
+If you have a more deeply-rooted problem with how the program is built or some of the stylistic decisions made in the code, it is best to [create an issue](https://github.com/htacg/tidy-html5/issues/new) before putting the effort into a pull request. The same goes for new features - it might be best to check the project's direction, existing pull requests, and currently open and closed issues first.
+
+Concerning the 'Tidy Code Style', checkout [CODESTYLE.md](CODESTYLE.md), but looking at existing code is the best way to get a good feel for the patterns we use.
+
+### Using Git appropriately
+
+ 1. Fork the repository to your GitHub account.
+ 2. Optionally create a **topical branch** - a branch whose name is succint but explains what
+you're doing, such as "feature/add-new-lines"...
+ 3. Make your changes, committing at logical breaks.
+ 4. Push your work to your personal account.
+ 5. [Create a pull request](https://help.github.com/articles/using-pull-requests).
+ 6. Watch for comments or acceptance.
+
+Please note - if you want to change multiple things that don't depend on each
+other, it is better to use `branches`, and make sure you check the master branch back out before making more changes - that way we can take in each change seperate. Else github has a tendancy to combine your requests into one.
+
+If you are a continuing contributor then you will need to `rebase` your fork, to htacg `master`, **before** doing any more work, and likewise branches, otherwise we may not be able to cleanly merge your PR. This is a simple process -
+
+```
+$ git remote add upstream [email protected]:htacg/tidy-html5.git # once only
+$ git checkout master
+$ git status
+$ git stash # if not clean
+$ git fetch upstream
+$ git rebase upstream/master
+$ git stash pop # if required, and fix conflicts
+$ git push      # update the fork master
+```
+
+This can be repeated for `branches`.
+
+### Help Tidy Get Better
+
+It goes without saying **all help is appreciated**. We need to work together to make Tidy! better...

README/CONTRIBUTING.md

@@ -0,0 +1,19 @@
+# Localize HTML Tidy
+
+HTML Tidy is used worldwide but is not very friendly to non-English speakers.
+The latest versions of HTML Tidy and `libtidy` now support other languages and
+regional variations, but we need your help to make it accessible to these users
+by using your knowledge of other languages to make Tidy better.
+
+Help us translate HTML Tidy into another language and as part of our project
+team you will certainly earn the admiration of fellow Tidy users worldwide.
+
+
+## How to Contribute
+
+All READMEs (including [instructions][2] on how to localize Tidy) and related 
+materials can be found in [localize][1].
+
+ [1]: https://github.com/htacg/tidy-html5/tree/master/localize
+ [2]:https://github.com/htacg/tidy-html5/blob/master/localize/README.md
+ 

LICENSE.md renamed to README/LICENSE.md

@@ -0,0 +1,94 @@
+# HTML Tidy with HTML5 support
+
+## Prerequisites
+
+  1. git - http://git-scm.com/book/en/v2/Getting-Started-Installing-Git
+  
+  2. cmake - http://www.cmake.org/download/
+  
+  3. 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.
+
+
+## Build the tidy library and command line tool
+
+  1. `cd build/cmake`
+
+  2. `cmake ../.. [-DCMAKE_INSTALL_PREFIX=/path/for/install]`
+
+  3. Windows:  `cmake --build . --config Release`  
+     Unix/OS X: `make`
+
+  4. Install, if desired:  
+     Windows: `cmake --build . --config Release --target INSTALL`  
+     Unix/OS X: `[sudo] make install`
+
+By default cmake sets the install path to /usr/local in unix. If you wanted the binary in say /usr/bin instead, then in 2. above use -DCMAKE_INSTALL_PREFIX=/usr
+
+Also, in unix if you want to build the release library without any debug `assert` in the code then add `-DCMAKE_BUILD_TYPE=Release` in step 2. This adds a `-DNDEBUG` macro to the compile switches. This is normally added in windows build for the `Release` config.
+
+In 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 do **not** need the tidy library built as a 'shared' (DLL) library, then in 2. add the command -DBUILD_SHARED_LIB:BOOL=OFF. This option is ON by default. The static library is always built and linked with the command line tool for convenience in windows, and so the binary can be run as part of the man page build without the shared library being installed in unix.
+
+## Build PHP with the tidy-html5 library
+
+Due to API changes in the PHP source, "buffio.h" needs to be changed to "tidybuffio.h" in the file ext/tidy/tidy.c.
+
+That is - prior to configuring php run this in the php source directory:
+```
+sed -i 's/buffio.h/tidybuffio.h/' ext/tidy/*.c
+```
+
+And then continue with (just an example here, use your own php config options):
+
+```
+./configure --with-tidy=/usr/local
+make
+make test
+make install
+```
+
+## Important Links
+
+ - site: http://www.html-tidy.org/
+ - source: https://github.com/htacg/tidy-html5
+ - binaries: http://www.htacg.org/binaries/
+ - bugs: https://github.com/htacg/tidy-html5/issues
+ - list: https://lists.w3.org/Archives/Public/html-tidy/
+ - api: http://www.htacg.org/tidy-html5/tidylib_api/
+ - quickref: http://www.htacg.org/tidy-html5/quickref.html
+
+## Development
+
+The default branch of this repository is `master`. This is the development branch, hopefully always `stable` source.
+
+It will identify as library version X.odd.X. Use it to help us on the forever `bug` quest, addition of new features, options, ..., etc.
+
+However, if you seek **release** code, then do `git branch -r`, and choose one of the `release/X.even.0` branches for your build and install...
+
+This will always be the latest release branch. Important `bug` fixes thought relevant to this release, pushed back, may bump the library version to X.even.1, ..., etc, but will be remain known as `X.even`...
+
+Some more details of the `Tidy Version` can be found in [VERSION.md](VERSION.md).
+
+Concerning the `Tidy Code Style`, some notes can be found in [CODESTYLE.md](CODESTYLE.md).
+
+If you want to contribute to Tidy, then read [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## History
+
+This repository should be considered canonical for HTML Tidy as of 2015-January-15.
+
+ - This repository originally transferred from [w3c.github.com/tidy-html5][1].
+ 
+ - First moved to Github from [tidy.sourceforge.net][2].
+
+
+   [1]: http://w3c.github.com/tidy-html5/
+
+   [2]: http://tidy.sourceforge.net

LICENSE.txt renamed to README/LICENSE.txt

@@ -0,0 +1,65 @@
+# Tidy Library Versioning
+
+The **libTidy** version is controlled by the contents of `version.txt` in the root.
+
+This file consists of two lines of dot (.) separated items. The first being the MAJOR, MINOR, and PATCH version values, and the second string is a date. Example -
+
+```
+5.1.8
+2015.09.04
+```
+
+When cmake is run this file is read and two MACROS added to the compile flags -
+
+```
+add_definitions ( -DLIBTIDY_VERSION="${LIBTIDY_VERSION}" )
+add_definitions ( -DRELEASE_DATE="${tidy_YEAR}/${tidy_MONTH}/${tidy_DAY}" )
+```
+
+And in CMakeLists.txt there is the posibility to define another MACRO, when and if required -
+
+```
+# add_definitions ( -DRC_NUMBER="D231" )
+```
+
+These MACROS are put in static const char strings in **libTidy's** `internal` only src/version.h file -
+
+```
+static const char TY_(release_date)[] = RELEASE_DATE;
+#ifdef RC_NUMBER
+static const char TY_(library_version)[] = LIBTIDY_VERSION "." RC_NUMBER;
+#else
+static const char TY_(library_version)[] = LIBTIDY_VERSION;
+#endif
+```
+
+These strings are returned respectively by the **libTidy** API functions -
+
+```
+TIDY_EXPORT ctmbstr TIDY_CALL     tidyLibraryVersion(void);
+TIDY_EXPORT ctmbstr TIDY_CALL     tidyReleaseDate(void);
+```
+
+**NOTE**: `tidyReleaseDate()` is marked deprecated!
+
+The actual `versioning` of the library more or less follows the [Semantic Versioning](http://semver.org/) style.
+
+When a `release` is done a release/5.0.0 **branch**, and a similar release/5.0.0 **tag** is created.
+
+At that point the version.txt is set to the next, 5.1.0. 
+
+That is the `master` branch will contain the ongoing development. Any subsequent good bug fixes found for some time after that will be carefully tested and push back (cherry picked I think is the correct term) into the release/5.0.0, making it 5.0.1...
+
+And on just about each fix, or feature addition to the `master` will bump the version to 5.1.1, 5.1.2, 5.1.3, and so on... even 5.1.4567 if necessary ;=)).
+
+When ready for the next release, say some 6 months or so later, then a branch `release/5.2.0` would be created, and tagged, and the master version.txt moved on to 5.3.0, and so on...
+
+That is, each `release` will have an `even` second digit, followed by .0, unless any subsequent fixes are pushed back, making it .1, ... probably not many of those... while the `master` develoment HEAD will have an `odd` second digit, followed by .0, incremented for just about each significant code change...
+
+The intial MAJOR digit, 5, will be maintained while the **libTidy** API remains fully compatible, although there may be additions, extensions, as and when these are identified...
+
+And throughout this, every effort will be made to keep `master` **stable** at all times, but would expect package managers to eventually really only pick up on the `release` branches, tags. 
+
+In cases of significant code re-writes, major featues added, these would be done in branches until they are `stable` enought, and tested enough, to be merge back to `master`.
+
+Date: 20150904