Made it easier to generate offline documentation.

Documentation can be generated by going to doc/ and running "make".
This requires Python. Before this change, the user had to install the
mistune library, which is used by the generator. The mistune library is
now included in the Better Enums distribution.

The generated docs are available at doc/html/index.html. Note that some
links won't be local (the GitHub repo, the download link, outgoing
links to MSDN, tutorial source in the GitHub repo, and so on). All the
pages belonging to the actual docs will be local, however.

The online version of the docs can be generated by running "make web".
The only difference between the online and offline versions is that the
former includes Google Analytics tracking code, and may include social
communication buttons, comment section, or other useless things in the
future.

Also included errata since the last release.

Resolves #2.

LICENSE

@@ -1,3 +1,7 @@
+Better Enums is distributed under the terms of the 2-clause BSD license. Its
+text is given below.
+
+
 Copyright (c) 2012-2015, Anton Bachin
 All rights reserved.
 
@@ -21,3 +25,44 @@ LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
 ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+
+
+
+
+Better Enums uses the mistune library as part of its documentation generator.
+Its web address and license are given below.
+
+
+http://mistune.readthedocs.org/en/latest/
+
+
+Copyright (c) 2014 - 2015, Hsiaoming Yang
+
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice, this
+list of conditions and the following disclaimer in the documentation and/or
+other materials provided with the distribution.
+
+* Neither the name of the creator nor the names of its contributors may be used
+to endorse or promote products derived from this software without specific prior
+written permission.
+
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

doc/DesignDecisionsFAQ.md

@@ -52,8 +52,6 @@ interesting option, and it has [its own section][traits]. I have tried it, but
 the verbosity increase is much greater than the benefit of dropping underscores,
 so I chose not to do it.
 
-%% description = Better Enums design decisions and tradeoffs.
-
 ### Why does Better Enums use a macro at all?
 
 Better Enums needs to turn the names of declared constants into strings, and I
@@ -248,3 +246,5 @@ generation.
 [underlying]: ${prefix}demo/NonIntegralUnderlyingTypes.html
 [traits-branch]: $repo/tree/traits
 [traits-samples]: $repo/tree/traits/samples
+
+%% description = Better Enums design decisions and tradeoffs.

doc/Makefile

@@ -1,12 +1,23 @@
 SOURCE_MARKDOWN := $(wildcard tutorial/*) $(wildcard demo/*)
 SOURCE_CXX := $(SOURCE_MARKDOWN:.md=.cc)
 
-.PHONY : all
-all : html examples
-
 .PHONY : html
 html :
 	python docs.py
+	@echo "See html/index.html"
+
+.PHONY : publish
+publish : prepare
+	cp -r html ../doc-publish
+	git commit --amend
+	git push -f
+
+.PHONY : prepare
+prepare : examples web
+
+.PHONY : web
+web : examples
+	python docs.py --web
 
 .PHONY : examples
 examples : clean-examples $(SOURCE_CXX)

doc/better-enums.css

@@ -122,7 +122,6 @@ header {
     background: linear-gradient(#395E7E, #4A79A0);
     color: white;
     padding: 50px 0;
-    margin-bottom: 50px;
 }
 
 h1 {
@@ -226,12 +225,12 @@ footer {
 a {
     text-decoration: none;
     color: white;
-    background-color: red;
+    /*background-color: red;*/
 }
 
 a[href=""] {
     color: white !important;
-    background-color: red !important;
+    /*background-color: red !important;*/
 }
 
 a:hover {
@@ -242,6 +241,10 @@ header a:hover {
     text-decoration: none;
 }
 
+.main {
+    margin-top: 50px;
+}
+
 .main a[href], footer a[href] {
     background-color: #edd;
     color: #844;
@@ -545,3 +548,32 @@ h3.contents {
     margin-top: 0;
     padding-bottom: 1em;
 }
+
+.buttons-bar {
+    background-color: #f4f4f4;
+    padding-top: 0.5em;
+    padding-bottom: 0.5em;
+    height: 20px;
+}
+
+.buttons-bar a img {
+    margin-right: 25px;
+}
+
+.buttons-bar iframe.gh-button {
+    width: 95px;
+}
+
+.buttons-bar .tweet-share,
+.buttons-bar .gh-button {
+    display: none;
+}
+
+.index .buttons-bar .tweet-share,
+.index .buttons-bar .gh-button {
+    display: initial;
+}
+
+.buttons-bar iframe.gh-watch {
+    width: 103px;
+}

doc/demo/102-any-underlying.md

@@ -7,7 +7,15 @@ between `T` and an integral type of your choosing. This also works in $cxx98
 doesn't have to be `constexpr`. In $cxx98, everything involving `T` will simply
 be done by Better Enums at run time.
 
-Here's how to do it.
+This feature is semi-experimental. I am considering relaxing the requirements on
+`T` so that it doesn't have to be literal. I can use a `reinterpret_cast` to
+make a mapping automatically. This will make non-integral underlying types
+easier to use, but will also prevent usage at compile time, which unfortunately
+has structural consequences for the implementation of Better Enums, and
+additional semantic consequences for usage, even at run time.
+
+In the meantime, here's how to have a non-integral underlying type in the
+current version.
 
     #include <iostream>
     #include <enum.h>

doc/docs.py

@@ -7,6 +7,8 @@ import string
 import transform
 import os
 import os.path
+import sys
+import urllib
 
 TEMPLATE_DIRECTORY = "template"
 OUTPUT_DIRECTORY   = "html"
@@ -83,6 +85,9 @@ def compose_page(relative_path, definitions):
     definitions["canonical"] = canonical
     definitions["prefix"] = prefix
 
+    definitions["quoted_url"] = urllib.quote(definitions["canonical"], "")
+    definitions["quoted_title"] = urllib.quote(definitions["title"], "")
+
     if "class" not in definitions:
         definitions["class"] = ""
 
@@ -202,6 +207,9 @@ def generate_sitemap():
 def main():
     load_templates()
 
+    if not (len(sys.argv) >= 2 and sys.argv[1] == "--web"):
+        templates["ga"] = ""
+
     remove_output_directory()
 
     process_threaded(TUTORIAL_DIRECTORY)
@@ -212,6 +220,8 @@ def main():
         compose_general_page(page)
 
     copy_static_file("better-enums.css")
+    copy_static_file("image/twsupport.png")
+    copy_static_file("image/tweet.png")
 
     generate_sitemap()
 

doc/index.md

@@ -61,23 +61,23 @@ Channel     c = <em>Channel::_from_integral(3)</em>;
   <em>reflective</em> enum types.
 </p>
 
-That means you can easily <u>convert enums to and from strings</u>,
-<u>validate</u> them, and <u>loop</u> over them. In $cxx11, you can do it all at
+That means you can easily convert enums to and from strings,
+validate them, and loop over them. In $cxx11, you can do it all at
 compile time.
 
 It's what built-in enums ought to support. Better Enums simply adds the missing
 features. And, it is based on the best known techniques, thoroughly tested,
 fast, portable, and documented exhaustively.
 
-All you have to do to use it is include <a $download><code>enum.h</code></a>.
+To use it, just include <code>enum.h</code>.
 
 Try it live online in
-[Wandbox](http://melpon.org/wandbox/permlink/pdlAAGoxnjqG6FRI), or begin the
+[Wandbox](http://melpon.org/wandbox/permlink/wICNzu2LW2vEgqzh), or begin the
 [tutorial](${prefix}tutorial/HelloWorld.html)!
 
 <div class="hack"></div>
 
-### Features
+### Highlights
 
 <ul class="blurbs">
   <li class="zero-mod-two zero-mod-three">
@@ -218,9 +218,8 @@ Try it live online in
 
 %% title = Clean reflective enums for C++
 
-%% description = Better Enums is a single header C++ library providing
-reflective enums with clean syntax. Better Enums can be converted to and from
-strings, be iterated, counted, and used at run time or for template and
-constexpr metaprogramming. Free and open source under the BSD license.
+%% description = Reflective enums in a single header file, with clean syntax.
+The enums can be converted to string, iterated, and counted, at run time or
+as part of metaprogramming. Free and open source under the BSD license.
 
 %% class = index

doc/template/ga.tmpl

@@ -0,0 +1,10 @@
+<script>
+  (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
+  (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
+  m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
+  })(window,document,'script','//www.google-analytics.com/analytics.js','ga');
+
+  ga('create', 'UA-62962513-1', 'auto');
+  ga('send', 'pageview');
+
+</script>

doc/template/ghfork.tmpl

@@ -0,0 +1 @@
+<iframe src="https://ghbtns.com/github-btn.html?user=aantron&repo=better-enums&type=fork&count=true" frameborder="0" scrolling="0" width="170px" height="20px" class="gh-button"></iframe>

doc/template/ghstar.tmpl

@@ -0,0 +1 @@
+<iframe src="https://ghbtns.com/github-btn.html?user=aantron&repo=better-enums&type=star&count=true" frameborder="0" scrolling="0" width="170px" height="20px" class="gh-button"></iframe>

doc/template/ghwatch.tmpl

@@ -0,0 +1 @@
+<iframe src="https://ghbtns.com/github-btn.html?user=aantron&repo=better-enums&type=watch&count=true&v=2" frameborder="0" scrolling="0" height="20px" class="gh-watch gh-button"></iframe>

doc/template/header.tmpl

@@ -13,6 +13,8 @@
 
 <link rel="stylesheet" href="${prefix}better-enums.css" />
 
+$ga
+
 </head>
 <body class="$class">
 
@@ -41,8 +43,7 @@
       <p>Version $version</p>
       <p>To install, just add <code>enum.h</code> to your project.</p>
       <p>
-        Visit the GitHub repo for issues, feedback, and let me know if you
-        found this library useful!
+        Visit the GitHub repo for issues, feedback, and the latest development.
       </p>
     </section>
 
@@ -53,5 +54,11 @@
   </div>
 </header>
 
+<!-- <div class="buttons-bar">
+  <div class="container">
+    $twsupport
+  </div>
+</div> -->
+
 <div class="main">
   <div class="container">

doc/template/tweet.tmpl

@@ -0,0 +1,3 @@
+<a href="https://twitter.com/intent/tweet?hashtags=cplusplus&text=${quoted_title}&tw_p=tweetbutton&url=${quoted_url}&via=better_enums" class="tweet-share">
+  <img src="${prefix}image/tweet.png" alt="Share this page"></img>
+</a>

doc/template/twsupport.tmpl

@@ -0,0 +1,3 @@
+<a href="https://twitter.com/intent/tweet?related=better_enums&screen_name=better_enums&share_with_retweet=never&tw_p=tweetbutton">
+  <img src="${prefix}image/twsupport.png" alt="Tweet for suport"></img>
+</a>

doc/transform.py

@@ -50,7 +50,7 @@ def camel_case(text):
     components = re.split("[ -]+", text)
     components = map(lambda s: s.capitalize(), components)
     result = "".join(components)
-    result = filter(lambda c: c not in ",!:-$()", result)
+    result = filter(lambda c: c not in ",!:-$()?", result)
     return result
 
 class HtmlRenderer(mistune.Renderer):

example/1-hello-world.cc

@@ -2,7 +2,7 @@
 
 // Hello, World!
 //
-// Download enum.h, then build this program with it:
+// Download enum.h, then compile this program:
 
 #include <iostream>
 #include "enum.h"

example/102-any-underlying.cc

@@ -9,7 +9,15 @@
 // have to be constexpr. In C++98, everything involving T will simply be done by
 // Better Enums at run time.
 //
-// Here's how to do it.
+// This feature is semi-experimental. I am considering relaxing the requirements
+// on T so that it doesn't have to be literal. I can use a reinterpret_cast to
+// make a mapping automatically. This will make non-integral underlying types
+// easier to use, but will also prevent usage at compile time, which
+// unfortunately has structural consequences for the implementation of Better
+// Enums, and additional semantic consequences for usage, even at run time.
+//
+// In the meantime, here's how to have a non-integral underlying type in the
+// current version.
 
 #include <iostream>
 #include <enum.h>

example/5-iostreams.cc

@@ -2,8 +2,9 @@
 
 // Stream operators
 //
-// These work almost as you'd expect. Just make sure you include iostream before
-// enum.h in any translation unit in which you intend to use the operators.
+// These work almost as you'd expect. First, make sure you include iostream
+// before enum.h in any translation unit in which you intend to use the
+// operators:
 
 #include <iostream>
 #include <enum.h>
@@ -25,5 +26,5 @@ int main()
 //
 // Channel     channel = Channel::Blue;
 // std::cin >> channel;    // Expects input such as "Green".
-//
+
 // Only char streams are supported for the time being.