Updated documentation.

Added changelog.

Bug fixes to the text merged in from PRs getting pushed to official/
; see changelog for details.

CHANGELOG

@@ -0,0 +1,97 @@
+Version 1.1
+###########
+
+This version is the same as the original Red Book (the one with the
+gold lettering), with only errata fixes and the like; no
+substantial content changes.
+
+Prior To 2016-04-12
+===================
+
+BAD VERSIONS!
+
+All copies of the CLL that have a version before 2016-04-12 and
+don't have gold lettering are *BAD*.  You can contact The Logical
+Language Group for a replacement.
+
+2016-04-13 / 2016-04-12
+=======================
+
+Print/PDF
+---------
+
+This is considered the first good/complete PDF/print version.
+
+Changes after this to the PDF/print version are expected to be
+extremely minor/cosmetic.
+
+2016-05-25
+==========
+
+HTML
+----
+
+Revamping of the navigation links in the HTML version.
+
+Print/PDF
+--------
+
+No changes in theory.  In practice, the navigation links invaded the
+PDF file, but we never rolled a new official version at this point
+so it doesn't matter.
+
+2016-06-10
+==========
+
+EPUB
+----
+
+This was the "fix up the EPUB" version; we now roll our own EPUB,
+and it passes EPubCheck 4.0.1 without errors.  Many other changes;
+see HTML section (since the EPUB is just the HTML section chunking
+in a zip file with some modifications, any HTML changes effect the
+EPUB).
+
+This is considered the first good/complete EPUB version.
+
+HTML
+----
+
+The HTML version passes tidy without errors (although it does have
+some bizarre "<a> anchor [blah] already defined" warnings that
+appear to simply be bugs in tidy).
+
+As a side effect of the EPUB work, the html was cleaned up
+considerably, but not in any ways that should have any visual
+effects; there are now no nested "a" elements, all "dt" have "dd".
+
+The links to the glossary now work (they were there but invisible
+before).  The HTML and EPUB indexes now us ":" between items and
+links (before it was a comma, which just looks weird).
+
+This is considerd the first good/complete HTML version.
+
+
+Print/PDF
+---------
+A couple of tiny changes (added a title to section 20.1, changed the
+caption on a chapter picture).
+
+I wouldn't even have stored a new version, except that an unrelated
+CSS change (indeed, a change that should have had no effect) has
+made a tiny difference to where words wrap, and so in some places
+the two PDFs look very different, even though the content has
+changed, so I'm storing this new version for purposes of future
+comparison.
+
+2016-06-12
+==========
+
+All versions: two bug fixes:
+
+https://github.com/lojban/cll/pull/242
+
+https://github.com/lojban/cll/issues/248
+
+This version was pushed everywhere, so there will be print and EPUB
+versions of this available for purchase.

official/CHANGELOG

@@ -0,0 +1,97 @@
+Version 1.1
+###########
+
+This version is the same as the original Red Book (the one with the
+gold lettering), with only errata fixes and the like; no
+substantial content changes.
+
+Prior To 2016-04-12
+===================
+
+BAD VERSIONS!
+
+All copies of the CLL that have a version before 2016-04-12 and
+don't have gold lettering are *BAD*.  You can contact The Logical
+Language Group for a replacement.
+
+2016-04-13 / 2016-04-12
+=======================
+
+Print/PDF
+---------
+
+This is considered the first good/complete PDF/print version.
+
+Changes after this to the PDF/print version are expected to be
+extremely minor/cosmetic.
+
+2016-05-25
+==========
+
+HTML
+----
+
+Revamping of the navigation links in the HTML version.
+
+Print/PDF
+--------
+
+No changes in theory.  In practice, the navigation links invaded the
+PDF file, but we never rolled a new official version at this point
+so it doesn't matter.
+
+2016-06-10
+==========
+
+EPUB
+----
+
+This was the "fix up the EPUB" version; we now roll our own EPUB,
+and it passes EPubCheck 4.0.1 without errors.  Many other changes;
+see HTML section (since the EPUB is just the HTML section chunking
+in a zip file with some modifications, any HTML changes effect the
+EPUB).
+
+This is considered the first good/complete EPUB version.
+
+HTML
+----
+
+The HTML version passes tidy without errors (although it does have
+some bizarre "<a> anchor [blah] already defined" warnings that
+appear to simply be bugs in tidy).
+
+As a side effect of the EPUB work, the html was cleaned up
+considerably, but not in any ways that should have any visual
+effects; there are now no nested "a" elements, all "dt" have "dd".
+
+The links to the glossary now work (they were there but invisible
+before).  The HTML and EPUB indexes now us ":" between items and
+links (before it was a comma, which just looks weird).
+
+This is considerd the first good/complete HTML version.
+
+
+Print/PDF
+---------
+A couple of tiny changes (added a title to section 20.1, changed the
+caption on a chapter picture).
+
+I wouldn't even have stored a new version, except that an unrelated
+CSS change (indeed, a change that should have had no effect) has
+made a tiny difference to where words wrap, and so in some places
+the two PDFs look very different, even though the content has
+changed, so I'm storing this new version for purposes of future
+comparison.
+
+2016-06-12
+==========
+
+All versions: two bug fixes:
+
+https://github.com/lojban/cll/pull/242
+
+https://github.com/lojban/cll/issues/248
+
+This version was pushed everywhere, so there will be print and EPUB
+versions of this available for purchase.

official/README.txt

@@ -1,15 +1,141 @@
+Updating XHTML official/
+------------------------
+
+So you've made changes that you want to push to the world.
+Congratulations!
+
+Start with:
+
+$ cp CHANGELOG official/
 
 Run scripts/diff_official ; confirm that nothing has changed except
 what you want to change.
 
-Put the files in official/
+scripts/diff_official makes copies of both the relevant build/ dir
+and the relevant official/ dir, and massages them to make the output
+easier to review.  In particular, it removes all build-time ID
+numbers, that otherwise would lead to hundreds of thousands of
+apparent changes.
+
+If you have made a complicated change that is hard for a human to
+review, but you can simplify the review process with a script, put
+that script at scripts/diff_official-special ; if that script
+exists, it will be run against every file on *both* sides of the
+diff.
+
+As an example, this mini-script finds anything that looks like a
+navgiation header and removes any newlines inside it; I used this
+when I changed all the nav headers so that each file had ~5 lines of
+changes (easy to review) vs. ~30 lines (not so much).
+
+  ruby -e 'puts ARGF.read.encode("UTF-8", "binary", invalid: :replace, undef: :replace, replace: "").gsub(%r{<div[^>]*(navheader|navfooter|toc-link|back-to-info-link).*?</div>}m) { |x| x.gsub(%r{\s+}," ") }' "$@" 
+
+When you're satisfied that the changes you made are the changes you
+want, put the changes you want is official/ with something like
+this:
+
+$ cp -r build/xhtml_section_chunks official/cll_v1.1_xhtml-section-chunks_2016-05-25
+$ cd official
+$ rm cll_v1.1_xhtml-section-chunks
+$ ln -s cll_v1.1_xhtml-section-chunks_2016-05-25 cll_v1.1_xhtml-section-chunks
+
+(Obviously, update that if we're not on version 1.1 anymore!)
+
+The goal here is to make it so that every currently-relevant
+file/directory has a symlink to it, and that that symlink's name
+only changes when we change CLL versions.
+
+NOTE: The - and _ in the build/ dir do not match what's in the
+official/ dir.  Sorry about that.
+
+Updating PDF official/
+----------------------
+
+Get a PDF diff viewer for your OS and compare them visually.  I'm
+using https://github.com/vslavik/diff-pdf on Windows.
+
+When done, copy and update symlinks as with XHTML.
+
+Updating EPUB official/
+-----------------------
+
+Uh.
+
+I guess if the PDF and XHTML are correct, the EPUB probably is too?
+Review it for obvious errors maybe?
+
+When done, copy and update symlinks as with XHTML.
+
+Pushing official/ To www.lojban.org
+-----------------------------------
+
+In your git directory after you've made official/ look how you want,
+the following script will look for any symlinks under official/ and
+tar up the symlinks and their referents:
+
+$ scripts/tar_official
+
+Then check it:
+
+$ tar -tvf official_cll.tar | less
+
+Then copy it over:
+
+$ scp official_cll.tar jukni:/tmp/
+
+Then on the webserver (currently (Jun 2016) this is jukni):
+
+$ sudo -u apache mv /srv/lojban/static/publications/cll /srv/lojban/static/publications/cll.before-$(date +%Y%m%d)
+$ sudo -u apache mkdir /srv/lojban/static/publications/cll
+$ sudo -u apache tar -xvf /tmp/official_cll.tar -C /srv/lojban/static/publications/cll/
+$ ls -lZd /srv/lojban/static/publications/cll
+drwxr-xr-x. 5 apache apache staff_u:object_r:httpd_user_content_t:s0 4096 Jun  2 17:06 /srv/lojban/static/publications/cll/
+$ ls -lZ /srv/lojban/static/publications/cll
+total 7972
+lrwxrwxrwx. 1 apache apache staff_u:object_r:httpd_user_content_t:s0      24 May 19 23:51 cll_v1.1.epub -> cll_v1.1_2016-04-13.epub
+-rw-r--r--. 1 apache apache staff_u:object_r:httpd_user_content_t:s0 1356591 Apr 13 00:10 cll_v1.1_2016-04-13.epub
+-rw-r--r--. 1 apache apache staff_u:object_r:httpd_user_content_t:s0 6276968 Apr 12 23:47 cll_v1.1_2016-04-13_book.pdf
+-rw-r--r--. 1 apache apache staff_u:object_r:httpd_user_content_t:s0  491834 Apr 19 01:12 cll_v1.1_2016-04-13_cover.pdf
+lrwxrwxrwx. 1 apache apache staff_u:object_r:httpd_user_content_t:s0      28 May 19 23:52 cll_v1.1_book.pdf -> cll_v1.1_2016-04-13_book.pdf
+lrwxrwxrwx. 1 apache apache staff_u:object_r:httpd_user_content_t:s0      29 May 19 23:52 cll_v1.1_cover.pdf -> cll_v1.1_2016-04-13_cover.pdf
+lrwxrwxrwx. 1 apache apache staff_u:object_r:httpd_user_content_t:s0      40 May 28 22:28 cll_v1.1_xhtml-chapter-chunks -> cll_v1.1_xhtml-chapter-chunks_2016-05-25/
+drwxr-xr-x. 3 apache apache staff_u:object_r:httpd_user_content_t:s0    4096 May 25 23:47 cll_v1.1_xhtml-chapter-chunks_2016-05-25/
+lrwxrwxrwx. 1 apache apache staff_u:object_r:httpd_user_content_t:s0      35 May 28 16:27 cll_v1.1_xhtml-no-chunks -> cll_v1.1_xhtml-no-chunks_2016-05-25/
+drwxr-xr-x. 3 apache apache staff_u:object_r:httpd_user_content_t:s0    4096 May 26 00:04 cll_v1.1_xhtml-no-chunks_2016-05-25/
+lrwxrwxrwx. 1 apache apache staff_u:object_r:httpd_user_content_t:s0      40 May 31 18:52 cll_v1.1_xhtml-section-chunks -> cll_v1.1_xhtml-section-chunks_2016-05-25/
+drwxr-xr-x. 3 apache apache staff_u:object_r:httpd_user_content_t:s0   20480 May 31 16:13 cll_v1.1_xhtml-section-chunks_2016-05-25/
+
+Note that the selinux stuff there is important.
+
+Then confirm that all of the following addresses work:
+
+http://lojban.org/publications/cll/cll_v1.1.epub
+http://lojban.org/publications/cll/cll_v1.1_epub-cover.jpg
+http://lojban.org/publications/cll/cll_v1.1_book.pdf
+http://lojban.org/publications/cll/cll_v1.1_cover.pdf
+http://lojban.org/publications/cll/cll_v1.1_xhtml-chapter-chunks/
+http://lojban.org/publications/cll/cll_v1.1_xhtml-no-chunks/
+http://lojban.org/publications/cll/cll_v1.1_xhtml-section-chunks/
+
+(Obviously, update that if we're not on version 1.1 anymore!)
+
+Pushing official/ To Dead Tree Books
+------------------------------------
+
+This is UNTESTED because we *just* switched to Ingram Spark.
+
+Go to https://myaccount.ingramspark.com/Titles/TitleInfo/CSS1956560
+using the LLG's account (Riley or Robin or Bob should have access).
+
+Click "Upload New Files".  Do the obvious.
 
-Update the symlinks there
+Maybe update some of the metadata (such as publication date?) at the
+main book page.
 
-On the main lojban webserver:
+Step 3: Profit?
 
-mkdir /srv/lojban/static/publications/cll/cll_v1.1_2016-04-13
-cd /srv/lojban/static/publications/cll/
-ln -sf cll_v1.1_2016-04-13 cll_v1.1
+Pushing official/ To E-Books
+----------------------------
 
-Copy the files there.
+Go to https://myaccount.ingramspark.com/Titles/TitleInfo/CSS1956560
+using the LLG's account (Riley or Robin or Bob should have access).

official/cll_v1.1.epub

@@ -1 +1 @@
-cll_v1.1_2016-06-10.epub
+cll_v1.1_2016-06-12.epub

official/cll_v1.1_book.pdf

@@ -1 +1 @@
-cll_v1.1_2016-06-10_book.pdf
+cll_v1.1_2016-06-12_book.pdf

official/cll_v1.1_xhtml-chapter-chunks

@@ -1 +1 @@
-cll_v1.1_xhtml-chapter-chunks_2016-06-10
+cll_v1.1_xhtml-chapter-chunks_2016-06-12