From bb1d62d3bdebcf95a1950d3bb717607012a15f83 Mon Sep 17 00:00:00 2001
From: Evgeniy Yurtaev <evgeniyyurt@gmail.com>
Date: Wed, 22 Feb 2017 14:09:11 +0300
Subject: [PATCH 01/14] Fix leading white spaces trimming

---
 src/lexer.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/lexer.c b/src/lexer.c
index 210c9cf..e625209 100644
--- a/src/lexer.c
+++ b/src/lexer.c
@@ -4096,7 +4096,7 @@ static tmbstr ParseValue( TidyDocImpl* doc, ctmbstr name,
             while (TY_(IsWhite)(lexer->lexbuf[start+len-1]) && (len > 0))
                 --len;
 
-            while (TY_(IsWhite)(lexer->lexbuf[start]) && (start < len) && (len > 0))
+            while (TY_(IsWhite)(lexer->lexbuf[start]) && (len > 0))
             {
                 ++start;
                 --len;

From 569ae4b4350ecbe94e6bcee3d9ed28eff5d3c69b Mon Sep 17 00:00:00 2001
From: Geoff McLane <ubuntu@geoffair.info>
Date: Thu, 23 Feb 2017 15:27:03 +0100
Subject: [PATCH 02/14] Issue #329 - lexer.c - do not discard this newline here

---
 src/lexer.c | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/src/lexer.c b/src/lexer.c
index 210c9cf..fb79e50 100644
--- a/src/lexer.c
+++ b/src/lexer.c
@@ -2986,7 +2986,9 @@ static Node* GetTokenFromStream( TidyDocImpl* doc, GetTokenMode mode )
                 {
                     c = TY_(ReadChar)(doc->docIn);
 
-                    if (c != '\n' && c != '\f')
+                    if ((c == '\n') && (mode != IgnoreWhitespace)) /* Issue #329 - Can NOT afford to lose this newline */
+                        TY_(UngetChar)(c, doc->docIn);  /* Issue #329 - make sure the newline is maintained for now */
+                    else if (c != '\n' && c != '\f')
                         TY_(UngetChar)(c, doc->docIn);
 
                     lexer->waswhite = yes;  /* to swallow leading whitespace */

From b97b2f0d453a9f017d8dd3183f1d57711f212574 Mon Sep 17 00:00:00 2001
From: Geoff McLane <ubuntu@geoffair.info>
Date: Thu, 23 Feb 2017 15:28:40 +0100
Subject: [PATCH 03/14] Issue #329 - version.txt - bump to 5.3.18 for this fix

---
 version.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/version.txt b/version.txt
index e20f7e1..5892180 100644
--- a/version.txt
+++ b/version.txt
@@ -1,2 +1,2 @@
-5.3.17
-2017.02.12
+5.3.18
+2017.02.23

From 27fe0548b9dfe18e6d6f263df9202558acf4c389 Mon Sep 17 00:00:00 2001
From: Geoff McLane <ubuntu@geoffair.info>
Date: Thu, 23 Feb 2017 16:28:19 +0100
Subject: [PATCH 04/14] Issue #468 - config.c - use `RAW` encoding for all
 cases

---
 src/config.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/config.c b/src/config.c
index ddb677c..e4a3ea0 100644
--- a/src/config.c
+++ b/src/config.c
@@ -934,7 +934,7 @@ Bool TY_(ParseConfigValue)( TidyDocImpl* doc, TidyOptionId optId, ctmbstr optval
         if (optId == TidyOutFile)
             doc->config.cfgIn = TY_(BufferInput)( doc, &inbuf, RAW );
         else
-            doc->config.cfgIn = TY_(BufferInput)( doc, &inbuf, ASCII );
+            doc->config.cfgIn = TY_(BufferInput)( doc, &inbuf, RAW ); /* Issue #468 - Was ASCII! */
         doc->config.c = GetC( &doc->config );
 
         status = option->parser( doc, option );

From 13c92bce3855209672b26e86ac9d79db3aea8661 Mon Sep 17 00:00:00 2001
From: Geoff McLane <ubuntu@geoffair.info>
Date: Thu, 23 Feb 2017 16:29:44 +0100
Subject: [PATCH 05/14] Issue #468 - version.txt - Bump to 5.3.19 for this fix

---
 version.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/version.txt b/version.txt
index 5892180..2742ca7 100644
--- a/version.txt
+++ b/version.txt
@@ -1,2 +1,2 @@
-5.3.18
+5.3.19
 2017.02.23

From c4b5904e1c194a01db52be2a4531207a246c12f1 Mon Sep 17 00:00:00 2001
From: Geoff McLane <ubuntu@geoffair.info>
Date: Fri, 24 Feb 2017 14:38:20 +0100
Subject: [PATCH 06/14] Issue #497 - lexer.c - Add comment for this PR @seaburg

---
 src/lexer.c | 1 +
 1 file changed, 1 insertion(+)

diff --git a/src/lexer.c b/src/lexer.c
index aee3e02..efefe74 100644
--- a/src/lexer.c
+++ b/src/lexer.c
@@ -4098,6 +4098,7 @@ static tmbstr ParseValue( TidyDocImpl* doc, ctmbstr name,
             while (TY_(IsWhite)(lexer->lexbuf[start+len-1]) && (len > 0))
                 --len;
 
+            /* Issue #497 - Fix leading space trimming */
             while (TY_(IsWhite)(lexer->lexbuf[start]) && (len > 0))
             {
                 ++start;

From d07134140a404d10dbf8819544424a33818b7bac Mon Sep 17 00:00:00 2001
From: Geoff McLane <ubuntu@geoffair.info>
Date: Fri, 24 Feb 2017 14:39:46 +0100
Subject: [PATCH 07/14] Issue #497 - version.txt - Bump to 5.3.20 for this fix

---
 version.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/version.txt b/version.txt
index 2742ca7..76aab01 100644
--- a/version.txt
+++ b/version.txt
@@ -1,2 +1,2 @@
-5.3.19
-2017.02.23
+5.3.20
+2017.02.24

From a49890ee55025cb4a3097ad63a2fcd79459f2156 Mon Sep 17 00:00:00 2001
From: Geoff McLane <ubuntu@geoffair.info>
Date: Fri, 24 Feb 2017 16:19:58 +0100
Subject: [PATCH 08/14] Issue #498 - parser.c - if a <table> in a <table> just
 close.

The previous action was to discard the second, while it is the second
table that browsers will render.

This conforms to the principle that the html output by tidy should render
in a browser like the original html.
---
 src/parser.c | 17 +++++++++++++++--
 1 file changed, 15 insertions(+), 2 deletions(-)

diff --git a/src/parser.c b/src/parser.c
index 30a9911..6ff2388 100644
--- a/src/parser.c
+++ b/src/parser.c
@@ -3019,9 +3019,22 @@ void TY_(ParseTableTag)(TidyDocImpl* doc, Node *table, GetTokenMode ARG_UNUSED(m
     
     while ((node = TY_(GetToken)(doc, IgnoreWhitespace)) != NULL)
     {
-        if (node->tag == table->tag && node->type == EndTag)
+        if (node->tag == table->tag )
         {
-            TY_(FreeNode)( doc, node);
+            if (node->type == EndTag)
+            {
+                TY_(FreeNode)(doc, node);
+            }
+            else
+            {
+                /* Issue #498 - If a <table> in a <table>
+                 * just close the current table, and issue a 
+                 * warning. The previous action was to discard
+                 * this second <table>
+                 */
+                TY_(UngetToken)(doc);
+                TY_(ReportError)(doc, table, node, TAG_NOT_ALLOWED_IN);
+            }
             lexer->istackbase = istackbase;
             table->closed = yes;
 #if !defined(NDEBUG) && defined(_MSC_VER)

From bb2cb2637223ea3c03edae01ae95be4e84b1b679 Mon Sep 17 00:00:00 2001
From: Jim Derry <balthisar@gmail.com>
Date: Fri, 24 Feb 2017 11:58:30 -0500
Subject: [PATCH 09/14] Update README documents with information for the
 upcoming 5.4.0 release.

---
 README.md              |  99 ++++++++++++++++++++--
 README/ATTRIBUTES.md   |  19 +++--
 README/BRANCHES.md     |  28 +++++++
 README/BUILD.md        |  66 +++++++++++++++
 README/CODESTYLE.md    |  12 +--
 README/CONTRIBUTING.md |  40 +++++----
 README/ELEMENTS.md     |  19 -----
 README/LOCALIZE.md     |   4 +-
 README/MESSAGES.md     |   1 -
 README/OPTIONS.md      |   8 +-
 README/README.html     | 181 +++++++++++++----------------------------
 README/README.md       | 102 -----------------------
 README/TAGS.md         |  19 +++++
 README/VERSION.md      |  14 ++--
 localize/README.md     |   2 +-
 15 files changed, 318 insertions(+), 296 deletions(-)
 create mode 100644 README/BRANCHES.md
 create mode 100644 README/BUILD.md
 delete mode 100644 README/ELEMENTS.md
 delete mode 100644 README/README.md
 create mode 100644 README/TAGS.md

diff --git a/README.md b/README.md
index 8661afe..bf48c56 100644
--- a/README.md
+++ b/README.md
@@ -1,9 +1,96 @@
-# HTML Tidy with HTML5 support
+# HTACG HTML Tidy
 
-All READMEs and related materials can be found in [README/][1].
+All other READMEs and related materials can be found in [README/][100]. Although all of our materials should be linked in this README, be sure to check this directory for documents we’ve not yet added to this document.
 
-For build instructions please see [README/README.md][2].
+## Building HTML Tidy
 
- [1]: https://github.com/htacg/tidy-html5/tree/master/README
- [2]: https://github.com/htacg/tidy-html5/blob/master/README/README.md
- 
\ No newline at end of file
+  - For build instructions please see [README/BUILD.md][115].
+  
+## Branches and Versions
+
+Learn about which branches are available, which branch you should use, and how HTML Tidy’s versioning scheme works.
+
+  - Learn about version numbering in [README/VERSION.md][160].
+  - Learn about our repository branches in [README/BRANCHES.md][110].
+  
+## Contributing and Development Guides
+
+We gladly accept PRs! Read about some of our contribution guidelines, and check out some of the additional explanatory documents that will aid your understanding of how to accomplish certain things in HTML Tidy.
+
+### General Contribution Guidelines
+
+These are some general guidelines that will help you help us when it comes to making your own contributions to HTML Tidy.
+
+  - Learn about our contributing guidelines in [README/CONTRIBUTING.md][125].
+  - Understand HTML Tidy’s source code style in [README/CODESTYLE.md][120].
+
+### Adding Features Guides
+
+When you’re ready to add a great new feature, these write-ups may be useful.
+
+  - Learn how to add new element attributes to HTML Tidy by reading [README/ATTRIBUTES.md][105].
+  - Discover how to add new tags to Tidy in [README/TAGS.md][130].
+  - If you want to add new messages to Tidy, read [README/MESSAGE.md][150].
+  - Configuration options can be added according to [README/OPTIONS.md][155].
+
+### Language Localization Guides
+
+Tidy supports localization, and welcomes translations into various languages. Please read up on how to localize HTML Tidy.
+
+ - The general README for localizing can be found in [/README/LOCALIZE.md][140].
+ - And [/localize/README.md][145] contains specific instructions for localizing.
+
+
+## Other Important Links
+
+ - site: [http://www.html-tidy.org/][4]
+ - source: [https://github.com/htacg/tidy-html5][5]
+ - binaries: [http://binaries.html-tidy.org][6]
+ - bugs: [https://github.com/htacg/tidy-html5/issues][7]
+ - list: [https://lists.w3.org/Archives/Public/html-tidy/][8]
+ - api and quickref: [http://api.html-tidy.org/][9]
+
+  [4]: http://www.html-tidy.org/
+  [5]: https://github.com/htacg/tidy-html5
+  [6]: http://binaries.html-tidy.org
+  [7]: https://github.com/htacg/tidy-html5/issues
+  [8]: https://lists.w3.org/Archives/Public/html-tidy/
+  [9]: http://api.html-tidy.org/
+
+
+## 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][20], now redirected to the current site.
+ 
+ - First moved to Github from [tidy.sourceforge.net][21]. Note, this site is kept only for historic reasons, and is not now well maintained.
+
+**Tidy is the granddaddy of HTML tools, with support for modern standards.** Have fun...
+
+  [20]: http://w3c.github.com/tidy-html5/
+  [21]: http://tidy.sourceforge.net
+
+
+## License
+
+HTML Tidy and LibTidy are free and open source software with a permissive license.
+
+ - You can read the complete license in [README/LICENSE.md][135].
+
+
+
+  [100]: README/
+  [105]: README/ATTRIBUTES.md
+  [110]: README/BRANCHES.md
+  [115]: README/BUILD.md
+  [120]: README/CODESTYLE.md
+  [125]: README/CONTRIBUTING.md
+  [130]: README/TAGS.md
+  [135]: README/LICENSE.md
+  [140]: /README/LOCALIZE.md
+  [145]: /localize/README.md
+  [150]: README/MESSAGE.md
+  [155]: README/OPTIONS.md
+  [160]: README/VERSION.md
+ 
diff --git a/README/ATTRIBUTES.md b/README/ATTRIBUTES.md
index b4ef111..79ec167 100644
--- a/README/ATTRIBUTES.md
+++ b/README/ATTRIBUTES.md
@@ -1,21 +1,26 @@
 # Tidy Element Attributes
 
-This is about adding a **new** `attribute=value` for one or more html `element`, here called `tags`.
+This is about adding a **new** HTML attribute to one or more HTML tags, i.e., a new attribute such as `attribute=value`.
 
-Tidy supports a large number of `attributes`, first defined in `tidyenum.h`, to give it a value, then defined in `attrs.c` to give it a unique **string** name, and a `function` to verify the atrribute **value**. Then in `attrdict.c` the attribute is defined, giving what version(s) of html support this attribute. Finally, what tags support this attrinute, is done in `tags.c`, where each attribute is allowed on that tag, or not, in the `tag_defs[]` table.
+Tidy’s large number of attributes are supported via number of files:
+
+  - `tidyenum.h` is where you first define a new attribute in order to give it an internal value.
+  - `attrs.c` is where you give a unique **string** name to the attribute, as well as a **function** to verify the **value**.
+  - `attrdict.c` further refines the definition of your attribute, specifying which version(s) of HTML support this attribute.
+  - `tags.c`, finally, determines which tags support the attribute, in the `tag_defs[]` table.
 
 So, to add a new `attribute=value`, on one or more existing tags, consists of the following simple steps -
 
- 1. tidyenum.h - Give the attribute an internal name, like `TidyAttr_XXXX`, and thus a value. While there were some initial steps to keep this `TidyAttrId` enumeration alphabetic, now just add the new `TidyAttr_XXXX` just before the last entry 'N_TIDY_ATTRIBS'.
+ 1. `tidyenum.h` - Give the attribute an internal name, like `TidyAttr_XXXX`, and thus a value. While there were some initial steps to keep this `TidyAttrId` enumeration alphabetic, now just add the new `TidyAttr_XXXX` just before the last entry `N_TIDY_ATTRIBS`.
 
- 2. attrs.c - Assign the string value of the attribute. Of course this must be unique. And then assign a `function` to verify the attribute value. There are already a considerable number of defined functions to verify specific attribute values, but maybe this new attribute requires a new function, so that should be written, and defined.
+ 2. `attrs.c` - Assign the string value of the attribute. Of course this must be unique. And then assign a `function` to verify the attribute value. There are already a considerable number of defined functions to verify specific attribute values, but maybe this new attribute requires a new function, so that should be written, and defined.
  
- 3. attrdict.c - If this attribute only relates to specific `tags`, then it should be added to their list. There are some `general` attributes that are allowed on every, or most tags, so this new attribute and value should be added accordingly.
+ 3. `attrdict.c` - If this attribute only relates to specific tags, then it should be added to their list. There are some general attributes that are allowed on every, or most tags, so this new attribute and value should be added accordingly.
  
- 4. tags.c - Now the new attribute will be verified for each tag it is associate with in the `tag_defs[]` table. Like for example the `<button ...>`, `{ TidyTag_BUTTON, ...` has `&TY_(W3CAttrsFor_BUTTON)[0]` assigned.
+ 4. `tags.c` - Now the new attribute will be verified for each tag it is associate with in the `tag_defs[]` table. Like for example the `<button ...>`, `{ TidyTag_BUTTON, ...` has `&TY_(W3CAttrsFor_BUTTON)[0]` assigned.
 
 So, normally, just changing 3 files, `tidyenum.h`, `attrs.c`, and `attrdict.c`, will already adjust `tags.c` to accept a new `attribute=value` for any tag, or all tags. Simple...
 
-Now, one could argue that this is not the **best** way to verify every attribute and value, for every tag, but that is a mute point - that is how tidy does it!
+Now, one could argue that this is not the **best** way to verify every attribute and value, for every tag, but that is a moot point - that is how Tidy does it!
 
 ; eof 20170205
diff --git a/README/BRANCHES.md b/README/BRANCHES.md
new file mode 100644
index 0000000..3ced792
--- /dev/null
+++ b/README/BRANCHES.md
@@ -0,0 +1,28 @@
+# HTML Tidy Branches
+
+## About Branches
+
+Starting with **HTML Tidy** 5.4.0, HTACG will adopt a new branch management strategy utilizing **master** as the _release branch_, and **next** as the active development branch.
+
+As described thoroughly in our [VERSION.md](VERSION.md) document, this means that **master** will always consist of an even-numbered minor version, and activity will remain relatively quiet unless we backport a critical bug fix from **next**.
+
+The **next** branch, then will host the majority of our development activity, and any contributions and PR’s should be again this branch. This means that **next** will always consist of an odd minor version number.
+
+
+## About Versioning
+
+You can read the specifics about version numbers in our [VERSION.md](VERSION.md) document.
+
+
+## FAQs
+
+### Which version or branch should I choose?
+
+As described above, the branch is very strongly correlated with the version. If you require a stable API and relatively stable output and don’t require the features and enhancements of an odd-numbered **next** version, then you should stick to **master**, even-numbered versions.
+
+On the other hand if you are primarily a console application user, then the API isn’t likely as important to you, and you probably want the latest and greatest. If this describes you, you probably want to at least try out **next**.
+
+If you are developing for Tidy, then you _definitely_ want to stick to **next**, even for bug fixes meant for **master**. If it’s a critical enough bug fix, then one of our friendly team will back-port the fix to **master**.
+
+
+
diff --git a/README/BUILD.md b/README/BUILD.md
new file mode 100644
index 0000000..eb426cd
--- /dev/null
+++ b/README/BUILD.md
@@ -0,0 +1,66 @@
+# HTACG HTML Tidy
+
+## Prerequisites
+
+  1. git - [http://git-scm.com/book/en/v2/Getting-Started-Installing-Git][1]
+  
+  2. cmake - [http://www.cmake.org/download/][2]
+  
+  3. appropriate build tools for the platform
+  
+  4. the [xsltproc][3] tool is required to build and install the `tidy.1` man page on Unix-like platforms.
+  
+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 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 --help` should 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 for 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_BUILD_TYPE=Release [-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/bin` 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\tidy`, or `C:/Program Files (x86)/tidy`, which is  not very useful. After the build the `tidy.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.
+
+See the `CMakeLists.txt` file for other CMake **options** offered.
+
+## Build PHP with the tidy-html5 library
+
+Due to API changes in the PHP source, `buffio.h` needs to be renamed to `tidybuffio.h` in the file `ext/tidy/tidy.c` in PHP's source.
+
+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
+```
+
+  [1]: http://git-scm.com/book/en/v2/Getting-Started-Installing-Git
+  [2]: http://www.cmake.org/download/
+  [3]: http://xmlsoft.org/XSLT/xsltproc2.html
+
+  
+; eof
diff --git a/README/CODESTYLE.md b/README/CODESTYLE.md
index 7161104..c6c4aa9 100644
--- a/README/CODESTYLE.md
+++ b/README/CODESTYLE.md
@@ -1,18 +1,18 @@
 # 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.
+The source code of **libTidy** and console app **tidy** mostly 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`.
+Developers adding code to HTML 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...
+There has been a suggestion of using available utilities to make the style consistent, like [Uncrustify](https://github.com/uncrustify/uncrustify) - 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.
+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!
+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...
+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 `//`.
diff --git a/README/CONTRIBUTING.md b/README/CONTRIBUTING.md
index 9ff48b8..788eb18 100644
--- a/README/CONTRIBUTING.md
+++ b/README/CONTRIBUTING.md
@@ -4,17 +4,27 @@ So you want to contribute to Tidy? Fantastic! Here's a brief overview on how bes
 
 ### 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.
+If you are having trouble running console `Tidy`, or using the `LibTidy` 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.
+In either place please start with a short subject to describe the issue. If it involves running Tidy on an html file, or if it’s an API question, make sure to include:
 
-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...
+  - the version: `$ tidy -v`
+  - what was the configuration used
+  - a small sample input
+  - the output
+  - the _expected_ output expected
+  - some sample code (if an API question).
+  
+These data will make replication of your issue much simpler for us.
+
+If you do add sample HTML input, then it can also be very helpful if that sample **passes** the W3C [validator](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 you can find the problem in the source code, then read on about how you can create a Pull Request (“PR”) to share your code and ideas.
 
-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:
+Here are some examples of things you might want to make a PR for:
 
  - New features
  - Bug fixes
@@ -24,36 +34,36 @@ Here are some examples of things you might want to make a pull request for:
 
 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.
+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"...
+ 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.
+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 seperately, otherwise 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 -
+If you are a continuing contributor then you will need to `rebase` your fork, to htacg `next`, **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 git@github.com:htacg/tidy-html5.git # once only
-$ git checkout master
+$ git checkout next
 $ git status
 $ git stash # if not clean
 $ git fetch upstream
-$ git rebase upstream/master
+$ git rebase upstream/next
 $ git stash pop # if required, and fix conflicts
-$ git push      # update the fork master
+$ git push      # update the fork next
 ```
 
-This can be repeated for `branches`.
+This can be repeated for other branches, too.
 
 ### Help Tidy Get Better
 
-It goes without saying **all help is appreciated**. We need to work together to make Tidy! better...
+It goes without saying **all help is appreciated**. We need to work together to make Tidy better!
diff --git a/README/ELEMENTS.md b/README/ELEMENTS.md
deleted file mode 100644
index 7716b54..0000000
--- a/README/ELEMENTS.md
+++ /dev/null
@@ -1,19 +0,0 @@
-# Tidy HTML Elements
-
-This is about adding a new html **element**, or **tag**.
-
-Tidy tries to support all **elements** supported by the W3C. To add a new supported **element**, the defintion begins in `tidyenum.h`, to give it a value. Then it is added to the `tag_defs[]` table in `tags.c`, where it is given a unique string, supported html versions, attributes support, and a bit `type`.
-
-Note, there are a group of configuration options to add **elements** not yet approved by the W3C. These are [new-blocklevel-tags](http://api.html-tidy.org/tidy/quickref_5.2.0.html#new-blocklevel-tags), [new-empty-tags](http://api.html-tidy.org/tidy/quickref_5.2.0.html#new-empty-tags), [new-inline-tags](http://api.html-tidy.org/tidy/quickref_5.2.0.html#new-inline-tags). and [new-pre-tags](http://api.html-tidy.org/tidy/quickref_5.2.0.html#new-pre-tags). This provides a way to extend the `tag_defs[]` table just for that tidy session.
-
-So, to add a new html `element`, consists of the following simple steps -
-
- 1. tidyenum.h - Give the element an internal name, like `TidyTag_XXXX`, and thus a value. While there were some initial steps to keep this `TidyTagId` enumeration alphabetic, now just add the new `TidyTag_XXXX` just before the last entry 'N_TIDY_TAGS'.
-
- 2. tags.c - Add a line to the `tag_defs[]` table. This assigns the unique string value of the element. Then the html versions that support the element, a pointer to the attributes supported by that elelment, and a bit field of the elements characteristics, inline, block, etc.
- 
-So, just changing 2 files, `tidyenum.h` and `tags.c`, and libTidy will now support that element, tag, as W3C approved. Simple... And at times, there is some case for adding **element** that are still in the `Working Draft` stage, especially when there has bee wide spread support in the community, even before it reaches `REC` stage.
-
-Now, one could argue that this is not the **best** way to verify every attribute and value, for every tag, but that is a mute point - that is how tidy does it!
-
-; eof 20170205
diff --git a/README/LOCALIZE.md b/README/LOCALIZE.md
index d38cb66..602fb13 100644
--- a/README/LOCALIZE.md
+++ b/README/LOCALIZE.md
@@ -14,6 +14,6 @@ team you will certainly earn the admiration of fellow Tidy users worldwide.
 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
+ [1]: ../localize
+ [2]: ../localize/README.md
  
diff --git a/README/MESSAGES.md b/README/MESSAGES.md
index 5b775f1..0d0bc46 100644
--- a/README/MESSAGES.md
+++ b/README/MESSAGES.md
@@ -36,6 +36,5 @@ Where to add this seems a bit of a mess, but in general things are grouped by wh
 
 Depending on which of the output routines you use (consult `message.c`) you may be able to use parameters such as `%u` and `%s` in your format strings. The available data is currently limited to the available message output routines, but perhaps generalizing this in order to make more data available will be a nice focus of Tidy 5.5. Please don't use `printf` for message output within **libTidy**.
 
-In this case I want to add showing the code point(s) in hex, so I need to add that also. **(jim --??)**
 
 eof;
diff --git a/README/OPTIONS.md b/README/OPTIONS.md
index 441a9d5..a733e0e 100644
--- a/README/OPTIONS.md
+++ b/README/OPTIONS.md
@@ -6,7 +6,7 @@ The options can also be listed in xml format. `-xml-help` will output each optio
 
 These options can also be used by application linking with **`libtidy`**. For each option there is a `TidyOptionId` enumeration in the `tidyenum.h` file, and get/set functions for each option type.
 
-This file indicates how to add a new option to tidy. Here adding an option `TidyEscapeScripts`. In essence it consists of 4 steps -
+This file indicates how to add a new option to tidy, here adding an option `TidyEscapeScripts`. In essence it consists of 4 steps:
 
  1. Add the option **`ID`** to `tidyenum.h`.
  2. Add to the **`table`** `TidyOptionImpl option_defs[]` in `config.c`
@@ -15,7 +15,7 @@ This file indicates how to add a new option to tidy. Here adding an option `Tidy
  
 #### 1. Option ID
 
-In `tidyenum.h` the `TidyOptionId` can be in any order, but normally a new option would be added just before the last `N_TIDY_OPTIONS`, which must remain the last. Choosing the id name can be any string, but by convention it will commence with `Tidy` followed by brief descriptive like text.
+In `tidyenum.h` the `TidyOptionId` can be in any order, but normally a new option would be added just before the last `N_TIDY_OPTIONS`, which must remain the last. Choosing the id name can be any string, but by convention it will commence with `Tidy` followed by brief descriptive text.
 
 Naturally it can not be the same as any exisitng option. That is, it must be unique. And it will be followed by a brief descriptive special doxygen formatted comment. So for this new option I have chosen -
 
@@ -60,7 +60,7 @@ typedef enum
 
 Care, each of these enumeration strings have been equated to 2 uppercase letters. If you feel there should be another `category` or group then this can be discussed, and added.
 
-The **`name`** can be anything, but should try to be somewhat descriptive of the otpion. Again this string must be unique. It should be lowercase alphanumeric characters, and can contain a `-` separator. Remember this is the name places on the command line, or in a configuration file to set the option.
+The **`name`** can be anything, but should try to be somewhat descriptive of the option. Again this string must be unique. It should be lowercase alphanumeric characters, and can contain a `-` separator. Remember this is the name places on the command line, or in a configuration file to set the option.
 
 The **`type`** is one of the following enumeration items -
 
@@ -73,7 +73,7 @@ typedef enum
 } TidyOptionType;
 ```
 
-Care, each of these enumeration strings have been equated to 2 uppercase letters. If you feel there should be another `type` then this can be discussed, but would require other additional things. And also note the `TidyTriState` is the same as a `TidyInteger` except uses its own parser.
+Care, each of these enumeration strings have been equated to two uppercase letters. If you feel there should be another `type` then this can be discussed, but would require other additional things. And also note the `TidyTriState` is the same as a `TidyInteger` except uses its own parser.
 
 The next item is the **`default`** value for a boolean, tristate or integer. Note tidy set `no=0` and `yes=1` as its own `Bool` enumeration.
 
diff --git a/README/README.html b/README/README.html
index 17590a4..b714301 100644
--- a/README/README.html
+++ b/README/README.html
@@ -1,124 +1,57 @@
-<!DOCTYPE html>
-<html>
- <head>
-  <meta charset="UTF-8">
-  <title>
-  HTML Tidy with HTML5 support
-  </title>
-  <style>
-  h1 {
-    background-color: #6495ed;
-  }
-  code {
-    background-color: #e0ffff;
-  }
-  div {
-    background-color: #b0c4de;
-  }
-  </style>
- </head>
- <body>
-  <h1>
-   HTML Tidy with HTML5 support
-  </h1>
-  <h2>
-   Prerequisites
-  </h2>
-  <ol>
-   <li>
-    <p>
-     git - http://git-scm.com/book/en/v2/Getting-Started-Installing-Git
-    </p>
-   </li>
-   <li>
-    <p>
-     cmake - http://www.cmake.org/download/
-    </p>
-   </li>
-   <li>
-    <p>
-     appropriate build tools for the platform
-    </p>
-   </li>
-  </ol>
-  <p>
-   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.
-  </p>
-  <p>
-   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.
-  </p>
-  <p>
-   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.
-  </p>
-  <h2>
-   Build the tidy library and command line tool
-  </h2>
-  <ol>
-   <li>
-    <p>
-     <code>cd build/cmake</code>
-    </p>
-   </li>
-   <li>
-    <p>
-     <code>cmake ../.. [-DCMAKE_INSTALL_PREFIX=/path/for/install]</code>
-    </p>
-   </li>
-   <li>
-    <p>
-     Windows: <code>cmake --build . --config Release</code>
-     <br>
-     Unix/OS X: <code>make</code>
-    </p>
-   </li>
-   <li>
-    <p>
-     Install, if desired:
-     <br>
-     Windows: <code>cmake --build . --config Release --target INSTALL</code>
-     <br>
-     Unix/OS X: <code>[sudo] make install</code>
-    </p>
-   </li>
-  </ol>
-  <p>
-   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<em>INSTALL</em>PREFIX=/usr
-  </p>
-  <p>
-   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.
-  </p>
-  <p>
-   If you need the tidy library built as a 'shared' (DLL) library, then in 2. add the command
-   -DBUILD<em>SHARED</em>LIB:BOOL=ON. This option is OFF by default, so the static library is
-   built and linked with the command line tool for convenience.
-  </p>
-  <h2>
-   History
-  </h2>
-  <p>
-   This repository should be considered canonical for HTML Tidy as of 2015-January-15.
-  </p>
-  <ul>
-   <li>
-    <p>
-     This repository originally transferred from <a href=
-     "http://w3c.github.com/tidy-html5/">w3c.github.com/tidy-html5</a>.
-    </p>
-   </li>
-   <li>
-    <p>
-     First moved to Github from <a href="http://tidy.sourceforge.net">tidy.sourceforge.net</a>.
-    </p>
-   </li>
-  </ul>
- </body>
-</html>
+<h1 id="htacghtmltidy">HTACG HTML Tidy</h1>
+
+<h2 id="prerequisites">Prerequisites</h2>
+
+<ol>
+<li><p>git - <a href="http://git-scm.com/book/en/v2/Getting-Started-Installing-Git">http://git-scm.com/book/en/v2/Getting-Started-Installing-Git</a></p></li>
+<li><p>cmake - <a href="http://www.cmake.org/download/">http://www.cmake.org/download/</a></p></li>
+<li><p>appropriate build tools for the platform</p></li>
+<li><p>the <a href="http://xmlsoft.org/XSLT/xsltproc2.html">xsltproc</a> tool is required to build and install the <code>tidy.1</code> man page on Unix-like platforms.</p></li>
+</ol>
+
+<p>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 command line use.</p>
+
+<p>Also the actual build tools vary for each platform. But that is one of the great features of CMake, it can generate variuous &#8216;native&#8217; build files. Running <code>cmake --help</code> should list the generators available on that platform. For sure one of the common ones is &#8220;Unix Makefiles&#8221;, which needs autotools make installed, but many other generators are supported.</p>
+
+<p>In Windows CMake offers various versions for 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.</p>
+
+<h2 id="buildthetidylibraryandcommandlinetool">Build the tidy library and command line tool</h2>
+
+<ol>
+<li><p><code>cd build/cmake</code></p></li>
+<li><p><code>cmake ../.. -DCMAKE_BUILD_TYPE=Release [-DCMAKE_INSTALL_PREFIX=/path/for/install]</code></p></li>
+<li><p>Windows: <code>cmake --build . --config Release</code><br/>
+ Unix/OS X: <code>make</code></p></li>
+<li><p>Install, if desired:<br/>
+ Windows: <code>cmake --build . --config Release --target INSTALL</code><br/>
+ Unix/OS X: <code>[sudo] make install</code></p></li>
+</ol>
+
+<p>By default cmake sets the install path to <code>/usr/local/bin</code> in Unix. If you wanted the binary in say <code>/usr/bin</code> instead, then in 2. above use <code>-DCMAKE_INSTALL_PREFIX=/usr</code>.</p>
+
+<p>Also, in Unix if you want to build the release library without any debug <code>assert</code> in the code then add <code>-DCMAKE_BUILD_TYPE=Release</code> in step 2. This adds a <code>-DNDEBUG</code> macro to the compile switches. This is normally added in windows build for the <code>Release</code> config.</p>
+
+<p>In Windows the default install is to <code>C:\Program Files\tidy</code>, or <code>C:/Program Files (x86)/tidy</code>, which is not very useful. After the build the <code>tidy.exe</code> is in the <code>Release</code> directory, and can be copied to any directory in your <code>PATH</code> environment variable for global use.</p>
+
+<p>If you do <strong>not</strong> need the tidy library built as a &#8216;shared&#8217; (DLL) library, then in 2. add the command <code>-DBUILD_SHARED_LIB:BOOL=OFF</code>. This option is <strong>ON</strong> 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.</p>
+
+<p>See the <code>CMakeLists.txt</code> file for other CMake <strong>options</strong> offered.</p>
+
+<h2 id="buildphpwiththetidy-html5library">Build PHP with the tidy-html5 library</h2>
+
+<p>Due to API changes in the PHP source, <code>buffio.h</code> needs to be renamed to <code>tidybuffio.h</code> in the file <code>ext/tidy/tidy.c</code> in PHP&#8217;s source.</p>
+
+<p>That is - prior to configuring PHP run this in the PHP source directory:
+<code>
+sed -i 's/buffio.h/tidybuffio.h/' ext/tidy/*.c
+</code></p>
+
+<p>And then continue with (just an example here, use your own PHP config options):</p>
+
+<pre><code>./configure --with-tidy=/usr/local
+make
+make test
+make install
+</code></pre>
+
+<p>; eof</p>
diff --git a/README/README.md b/README/README.md
deleted file mode 100644
index f583f61..0000000
--- a/README/README.md
+++ /dev/null
@@ -1,102 +0,0 @@
-# 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
-  
-  4. the [xsltproc](http://xmlsoft.org/XSLT/xsltproc2.html) tool is required to build and install the tidy.1 man page.
-  
-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 --help` should 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_BUILD_TYPE=Release [-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/bin` 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\tidy`, or `C:/Program Files (x86)/tidy`, which is  not very useful. After the build the `tidy.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.
-
-See the `CMakeLists.txt` file for other cmake **options** offered.
-
-## 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://binaries.html-tidy.org
- - bugs: https://github.com/htacg/tidy-html5/issues
- - list: https://lists.w3.org/Archives/Public/html-tidy/
- - api and quickref: http://api.html-tidy.org/
-
-## 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).
-
-If you want to add a new configuration **option** to tidy, see [OPTIONS.md](OPTIONS.md).
-
-Tidy is moving towards `localization` of the message string. To help in this effort see [LOCALIZE.md](LOCALIZE.md).
-
-Tidy API documents, and quick reference generation has been moved to its own repo [html-tidy.org.api](https://github.com/htacg/html-tidy.org.api). Likewise, release binary generation has been moved to [html-tidy.org.binaries](https://github.com/htacg/html-tidy.org.binaries). Consult the respective `readmes` there for further details.
-
-## 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](http://w3c.github.com/tidy-html5/), now redirected to the current site.
- 
- - First moved to Github from [tidy.sourceforge.net](http://tidy.sourceforge.net). Note, this site is kept only for historic reasons, and is not now well maintained.
-
-**Tidy is the granddaddy of HTML tools, with support for modern standards.** Have fun...
-
-; eof
diff --git a/README/TAGS.md b/README/TAGS.md
new file mode 100644
index 0000000..d02a8b4
--- /dev/null
+++ b/README/TAGS.md
@@ -0,0 +1,19 @@
+# Tidy HTML Elements
+
+This is about adding a new HTML **tag**.
+
+Tidy tries to support all **tags** supported by the W3C. To add a new supported **tag**, the defintion begins in `tidyenum.h`, to give it a value. Then it is added to the `tag_defs[]` table in `tags.c`, where it is given a unique string, supported html versions, attributes support, and a bit `type`.
+
+Note, there are a group of configuration options to add **tags** not yet approved by the W3C. These are [new-blocklevel-tags](http://api.html-tidy.org/tidy/quickref_5.2.0.html#new-blocklevel-tags), [new-empty-tags](http://api.html-tidy.org/tidy/quickref_5.2.0.html#new-empty-tags), [new-inline-tags](http://api.html-tidy.org/tidy/quickref_5.2.0.html#new-inline-tags). and [new-pre-tags](http://api.html-tidy.org/tidy/quickref_5.2.0.html#new-pre-tags). This provides a way to extend the `tag_defs[]` table just for that tidy session.
+
+So, adding a new HTML **tag** consists of the following simple steps:
+
+ 1. `tidyenum.h` - Give the element an internal name, like `TidyTag_XXXX`, and thus a value. While there were some initial steps to keep this `TidyTagId` enumeration alphabetic, now just add the new `TidyTag_XXXX` just before the last entry `N_TIDY_TAGS`.
+
+ 2. `tags.c` - Add a line to the `tag_defs[]` table. This assigns the unique string value of the element. Then the html versions that support the element, a pointer to the attributes supported by that elelment, and a bit field of the elements characteristics, inline, block, etc.
+ 
+So, just changing 2 files, `tidyenum.h` and `tags.c`, and libTidy will now support that element, tag, as W3C approved. Simple... And at times, there is some case for adding **tags** that are still in the `Working Draft` stage, especially when there has been wide spread support in the community, even before it reaches `REC` stage.
+
+Now, one could argue that this is not the **best** way to verify every attribute and value, for every tag, but that is a moot point - that is how tidy does it!
+
+; eof 20170205
diff --git a/README/VERSION.md b/README/VERSION.md
index eaddced..e16dc52 100644
--- a/README/VERSION.md
+++ b/README/VERSION.md
@@ -32,7 +32,7 @@ The minor version tells a lot more about the true version of Tidy that you have,
 
 - **even numbered minor versions** indicate released versions of **HTML Tidy**. We provide binaries for releases, API documentation, and full support including cherry picking bug fixes back to them. In standard parlance, _released_ versions are _stable_ versions, meaning that the API is stable and you can generally expect Tidy’s output to be the same (other than as a result of bug fixes). 
 
-- **odd numbered minor versions** are development versions, or as is considered in many contexts _bleeding edge_ versions. HTACG do not provide binaries, and API documentation is not usually up to date, but you do have access to the latest bug fixes, newest features, and knowledge of where Tidy is going. The downside, though, is that we make absolutely no guarantees that:
+- **odd numbered minor versions** are development versions, or as is considered in many contexts _bleeding edge_ or _next_ versions. HTACG do not provide binaries, and API documentation is not usually up to date, but you do have access to the latest bug fixes, newest features, and knowledge of where Tidy is going. The downside, though, is that we make absolutely no guarantees that:
 
   - Output remains the same as in previous release versions.
   - Output remains the same as in earlier patch versions in the same development series.
@@ -63,20 +63,20 @@ This file consists of two lines of dot (.) separated items. The first being the
 2017.01.29
 ```
 
-When **cmake** is run, this file is read and two MACROS added to the compile flags:
+When **CMake** is run, this file is read and two macros are 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:
+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 **libTidys**’s internal- only `src/version.h` file:
+These macros are put in `static const char` strings in **libTidys**’s internal- only `src/version.h` file:
 
 ```
 static const char TY_(release_date)[] = RELEASE_DATE;
@@ -96,11 +96,7 @@ TIDY_EXPORT ctmbstr TIDY_CALL     tidyReleaseDate(void);
 
 ### Git branches
 
-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...
+Starting with HTML Tidy 5.4.0 release, our branching scheme aligns nicely with our version numbering scheme. Please consult [BRANCHES.md](BRANCHES.md).
 
 
 Updated: 20170210  
diff --git a/localize/README.md b/localize/README.md
index 09a7b23..dc4339b 100644
--- a/localize/README.md
+++ b/localize/README.md
@@ -259,7 +259,7 @@ localize strings that are actually _different_ from the base language!
 
 ### Positional Parameters
 
-Please note that HTML Tidy does not current support positional parameters. Due
+Please note that HTML Tidy does not currently support positional parameters. Due
 to the nature of most of Tidy's output, it's not expected that they will be
 required. In any case, please translate strings so that substitution values are
 in the same order as the original string.

From c39b1cb42306b5d6c67b4791fcca13fefcbe432d Mon Sep 17 00:00:00 2001
From: Geoff McLane <ubuntu@geoffair.info>
Date: Wed, 1 Mar 2017 14:51:53 +0100
Subject: [PATCH 10/14] Issue #498 - Bump to 5.3.21 for merge #502

---
 version.txt | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/version.txt b/version.txt
index 76aab01..e232944 100644
--- a/version.txt
+++ b/version.txt
@@ -1,2 +1,3 @@
-5.3.20
-2017.02.24
+5.3.21
+2017.03.01
+

From 17b33753aea197e510ce48a93c9f0448c508a474 Mon Sep 17 00:00:00 2001
From: Geoff McLane <ubuntu@geoffair.info>
Date: Wed, 1 Mar 2017 15:04:22 +0100
Subject: [PATCH 11/14] version.txt - Update to 5.4.0 release

---
 version.txt | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/version.txt b/version.txt
index e232944..6cf22d7 100644
--- a/version.txt
+++ b/version.txt
@@ -1,3 +1,2 @@
-5.3.21
+5.4.0
 2017.03.01
-

From 0016e0083505ccee25a5c76dcf64cfe336765128 Mon Sep 17 00:00:00 2001
From: Geoff McLane <ubuntu@geoffair.info>
Date: Wed, 1 Mar 2017 15:06:30 +0100
Subject: [PATCH 12/14] Update verhist.log to 5.4.0 release

---
 README/verhist.log | 61 +++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 60 insertions(+), 1 deletion(-)

diff --git a/README/verhist.log b/README/verhist.log
index 7b084fa..ddc5795 100644
--- a/README/verhist.log
+++ b/README/verhist.log
@@ -1,4 +1,63 @@
-# Version history at 2015/11/23 15:04:00
+# Version history at 2017/03/01
+5.4.0 17b33753ae Geoff McLane Wed Mar 1 15:04:22 2017 +0100
+5.3.21 c39b1cb423 Geoff McLane Wed Mar 1 14:51:53 2017 +0100
+5.3.20 d07134140a Geoff McLane Fri Feb 24 14:39:46 2017 +0100
+5.3.19 13c92bce38 Geoff McLane Thu Feb 23 16:29:44 2017 +0100
+5.3.18 b97b2f0d45 Geoff McLane Thu Feb 23 15:28:40 2017 +0100
+5.3.18 b7c84b1b57 Jim Derry Mon Feb 13 08:49:06 2017 -0500
+5.3.16 73bf561645 Geoff McLane Sun Feb 12 17:40:48 2017 +0100
+5.3.16I483 259d330780 Geoff McLane Wed Feb 1 13:46:25 2017 +0100
+5.3.15 10fd44d101 Geoff McLane Sun Jan 29 19:21:46 2017 +0100
+5.3.14 0cbbd55535 Geoff McLane Mon Jan 9 17:07:13 2017 +0100
+5.3.13 2243510592 Geoff McLane Sun Jan 8 18:24:17 2017 +0100
+5.3.12 fd0ccb2bbf Geoff McLane Sun Oct 30 23:37:31 2016 +0100
+5.3.11 4edbc2424b Geoff McLane Sun Sep 11 17:09:09 2016 +0200
+5.3.10 f1ac2dba58 Geoff McLane Sun Sep 11 15:50:42 2016 +0200
+5.3.9 d2fc252598 Geoff McLane Thu Aug 4 15:54:14 2016 +0200
+5.3.8 09caae3b9c Geoff McLane Fri Jul 29 02:58:24 2016 +0200
+5.3.7 4a483fd066 Geoff McLane Mon Jul 11 15:32:55 2016 +0200
+5.3.6 3b73cc12c5 Geoff McLane Mon Jul 11 00:26:07 2016 +0200
+5.3.5 d332908e5d Geoff McLane Fri Jul 1 15:54:10 2016 +0200
+5.3.4 6b3b1624ea Geoff McLane Thu Jun 30 18:36:10 2016 +0200
+5.3.3 eca7688941 Geoff McLane Sat Jun 18 18:57:09 2016 +0200
+5.3.2 676b36eff5 Geoff McLane Sat Jun 18 18:26:23 2016 +0200
+5.3.1 60c1dd1744 Geoff McLane Sat Apr 16 20:16:50 2016 +0200
+5.3.0 fdf2169ebf Geoff McLane Thu Apr 7 16:36:06 2016 +0200
+5.1.52 0db9b32e22 Geoff McLane Mon Apr 4 18:14:33 2016 +0200
+5.1.51 3e5e07ea18 Geoff McLane Thu Mar 31 14:50:47 2016 +0200
+5.1.50 005f36106a Geoff McLane Wed Mar 30 16:28:45 2016 +0200
+5.1.49 c19d221ddc Geoff McLane Wed Mar 30 14:19:07 2016 +0200
+5.1.48 aa1fc197d5 Geoff McLane Sun Mar 27 19:57:41 2016 +0200
+5.1.47fr fb95ea2ed2 Geoff McLane Wed Mar 23 19:53:51 2016 +0100
+5.1.47 3c8d9bf3f6 Geoff McLane Sun Mar 20 01:03:25 2016 +0100
+5.1.46 8a31aad0e3 Geoff McLane Sat Mar 19 19:32:39 2016 +0100
+5.1.45-Exp3 06215769aa Geoff McLane Fri Mar 18 18:48:08 2016 +0100
+5.1.45-Exp2 98f32ddebb Geoff McLane Sun Mar 6 17:38:48 2016 +0100
+5.1.45-Exp1 b83d5ffb03 Geoff McLane Sat Mar 5 17:40:32 2016 +0100
+5.1.45 b2c591c138 Geoff McLane Fri Mar 4 19:39:21 2016 +0100
+5.1.44 1dd06aa4b2 Geoff McLane Mon Feb 29 19:59:41 2016 +0100
+5.1.43 9a80938246 Geoff McLane Mon Feb 29 18:49:52 2016 +0100
+5.1.42 b41318724c Geoff McLane Wed Feb 24 19:24:46 2016 +0100
+5.1.41issue-373 9ba80b864e Geoff McLane Thu Feb 18 15:12:11 2016 +0100
+5.1.41 be0e5f3a8b Jim Derry Thu Feb 18 10:20:40 2016 +0800
+5.1.40 6c181d5689 Jim Derry Wed Feb 17 12:43:44 2016 +0800
+5.1.40 97abad0c05 Jim Derry Tue Feb 16 11:11:36 2016 +0800
+5.1.38 7df66c45da Jim Derry Tue Feb 16 10:20:34 2016 +0800
+5.1.36_attr_phase2 2ade3357a9 Jim Derry Sat Feb 13 11:31:16 2016 +0800
+5.1.36_attr_phase1 429703dce4 Jim Derry Fri Feb 12 19:34:19 2016 +0800
+5.1.36 0f3cab930a Geoff McLane Mon Feb 1 20:10:23 2016 +0100
+5.1.35 e8ca2aa5f3 Geoff McLane Mon Feb 1 19:45:43 2016 +0100
+5.1.34 dca50d4077 Jim Derry Sat Jan 30 16:02:00 2016 +0800
+5.1.33localizing d505869910 Jim Derry Fri Jan 15 12:06:15 2016 +0800
+5.1.33 ce6c7de2d9 Jim Derry Thu Jan 7 11:52:58 2016 +0800
+5.1.32 9942856164 Geoff McLane Mon Dec 7 12:42:13 2015 +0100
+5.1.31 5f8aac98df Geoff McLane Sat Dec 5 13:02:33 2015 +0100
+5.1.30 121fe86bc6 Geoff McLane Fri Dec 4 18:32:48 2015 +0100
+5.1.29 34eb16b5da Geoff McLane Thu Dec 3 19:38:13 2015 +0100
+5.1.28 4c848c57bc Jim Derry Sun Nov 29 13:24:01 2015 +0800
+5.1.28 501c3fb616 Jim Derry Fri Nov 27 09:47:09 2015 +0800
+5.1.27 db4f6473ed Geoff McLane Thu Nov 26 00:58:07 2015 +0100
+5.1.26 0ef4493ae8 Geoff McLane Tue Nov 24 19:29:52 2015 +0100
 5.1.25 2388fb0175 Geoff McLane Sun Nov 22 18:46:00 2015 +0100
 5.1.24 496c81c48d Geoff McLane Wed Nov 18 20:02:54 2015 +0100
 5.1.23 06e4311189 Geoff McLane Wed Nov 18 17:08:26 2015 +0100

From 3e23225288a9d8e4f332da22711f68a09bc26f48 Mon Sep 17 00:00:00 2001
From: Geoff McLane <ubuntu@geoffair.info>
Date: Wed, 1 Mar 2017 15:33:22 +0100
Subject: [PATCH 13/14] version.txt - Bump to 5.5.0 in next

---
 version.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/version.txt b/version.txt
index 6cf22d7..53c05d8 100644
--- a/version.txt
+++ b/version.txt
@@ -1,2 +1,2 @@
-5.4.0
+5.5.0
 2017.03.01

From 92621d6f99fd724ad4d7168d210b79f05de341a9 Mon Sep 17 00:00:00 2001
From: Jim Derry <balthisar@gmail.com>
Date: Thu, 2 Mar 2017 09:32:02 -0500
Subject: [PATCH 14/14] MSVC Compatibility   - Changed location of pointer
 operator in declarations.   - Updated `CODESTYLE.md` to reflect this.   -
 Updated `API_AND_NAMESPACE.md` to reflect this.

---
 README/API_AND_NAMESPACE.md | 12 ++++++++++++
 README/CODESTYLE.md         |  3 +++
 include/tidy.h              |  2 +-
 src/tidylib.c               |  2 +-
 4 files changed, 17 insertions(+), 2 deletions(-)

diff --git a/README/API_AND_NAMESPACE.md b/README/API_AND_NAMESPACE.md
index 8c97df1..5acb5b9 100644
--- a/README/API_AND_NAMESPACE.md
+++ b/README/API_AND_NAMESPACE.md
@@ -36,6 +36,18 @@ The `TIDY_EXPORT` call clearly indicates that this function prototype is meant t
 
 Although this makes things obvious from the documentation perspective, the truth is a little murkier. In some environments one might define `TIDY_EXPORT` and `TIDY_CALL` differently in order to control compiler behavior, especially in environments that have special requirements for dynamic libraries. In general, though, you shouldn't have to worry about this.
 
+Note that MSVC has issues with macros inserted before pointer operators, and so the preferred use of pointer operators when documenting with macros is this:
+
+~~~
+const tidyLocaleMapItem* TIDY_CALL getNextWindowsLanguage( TidyIterator* iter )
+~~~
+
+…instead of this:
+
+~~~
+const tidyLocaleMapItem TIDY_CALL *getNextWindowsLanguage( TidyIterator* iter )
+~~~
+
 
 # External types are opaque
 
diff --git a/README/CODESTYLE.md b/README/CODESTYLE.md
index 7161104..04f4c53 100644
--- a/README/CODESTYLE.md
+++ b/README/CODESTYLE.md
@@ -18,6 +18,9 @@ From reading of the Tidy source, some things are self evident... in no particula
  - 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.
+ - For compatibility with MSVC, pointer operators in declarations must precede any macro documentation, e.g, `const tidyLocaleMapItem* TIDY_CALL getNextWindowsLanguage( TidyIterator* iter )` instead of `const tidyLocaleMapItem TIDY_CALL *getNextWindowsLanguage( TidyIterator* iter )`.
+
+
 
 Look forward to this document being filled out in detail...
 
diff --git a/include/tidy.h b/include/tidy.h
index 1da8906..58a5fef 100644
--- a/include/tidy.h
+++ b/include/tidy.h
@@ -1173,7 +1173,7 @@ TIDY_EXPORT TidyIterator TIDY_CALL getWindowsLanguageList();
  *  Returns the next record of type `localeMapItem` in
  *  Tidy's structure of Windows<->POSIX local mapping.
  */
-TIDY_EXPORT const tidyLocaleMapItem TIDY_CALL *getNextWindowsLanguage( TidyIterator* iter );
+TIDY_EXPORT const tidyLocaleMapItem* TIDY_CALL getNextWindowsLanguage( TidyIterator* iter );
 
 /**
  *  Given a `tidyLocalMapItem`, return the Windows name.
diff --git a/src/tidylib.c b/src/tidylib.c
index af72cdb..f0457a0 100755
--- a/src/tidylib.c
+++ b/src/tidylib.c
@@ -2428,7 +2428,7 @@ TidyIterator TIDY_CALL getWindowsLanguageList()
 //#define tidyOptionToImpl( topt )    ((const TidyOptionImpl*)(topt))
 //#define tidyImplToOption( option )  ((TidyOption)(option))
 
-const tidyLocaleMapItem TIDY_CALL *getNextWindowsLanguage( TidyIterator* iter )
+const tidyLocaleMapItem* TIDY_CALL getNextWindowsLanguage( TidyIterator* iter )
 {
     /* Get a real structure */
     const tidyLocaleMapItemImpl *item = TY_(getNextWindowsLanguage)( iter );