+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 
--OLD--
thumbspage closed issues and developer notes trimmed from the source code
and not added to the later UserGuide.  These are probably of interest to
developers mainly, and were retained as historical context and example.
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++


===========================================================================
CLOSED ISSUES
===========================================================================

This section lists recently closed and current issues, some of 
which are open to user feedback (via lutz@learning-python.com).
This list may not be complete; search for "caveat" in this and
other code files here for additional items, and see section 
"VERSION HISTORY" above for more on version changes noted here.

--CLOSED--

1) Python 3.X assumes local platform's Unicode encoding default
   for header/footer inserts and the output page: change as needed.

   ==> Addressed and resolved in 1.3, per version notes above.

2) This script would probably run on Python 2.X too if the
   viewer_thumbs module didn't import "tkinter" (a book legacy).

   ==> But no longer as is, as of 1.3's Unicode enhancements: 
       punt on trying to maintain 1.2 compatibility.

3) Styling of the table is open ended.  For example, a <table>
   style "border-spacing: 4px;" may help avoid names running into
   each other, though the default (2px?) seems adequate.

   ==> Addressed in version 1.4 with extra CSS styling.

4) The reused viewer_thumbs module skips non-image files by simply
   catching errors; this could use Python's mimetypes module instead.

   ==> See PyPhoto's newer version of this module, which uses 
       mimetypes as described; alas, it's a fork.  Here's the 
       newer code's online link:
          http://learning-python.com/
          pygadgets-products/unzipped/_PyPhoto/PIL/viewer_thumbs.py

   ==> Addressed in version 1.5: incorporated the PyPhoto mods here,
       though PyPhoto's viewer_thumbs may still vary arbitrarily.

5) Relying on browser-specific display of full images isn't ideal,
   because such displays vary in scaling, background color, etc.

   ==> Addressed by version 1.5's image-viewer pages (see above).

6) Desktop Chrome (only) botches <hr>s and <img> borders at some zoom 
   levels: the former may be lighter at some page locations than 
   others, and the latter may drop one or more sides altogether.  

   This was first seen when odd Unicode characters were on-page, but 
   can happen anywhere - at user-zoom levels at or below 90%, all bets 
   are off on <hr>- and <img>-border rendering.  It also happens on both
   index pages and 1.5 viewer pages; the latter's CSS <img> borders may
   drop one or more sides at <= 90% zoom.

   This has been observed on desktop Chrome only, and in versions 66 
   and 68 on Mac OS and Windows.  The only fix seems to be to not use
   <hr> or <img> borders - an extreme workaround.  Styling <hr>s (e.g., 
   style="height: 0.5px; background-color: black;") doesn't fix the 
   issue at all zoom levels.  This is clearly a (temporary?) browser 
   bug, but unfortunate in this site's most widely used browser.

   ==> Addressed <hr>s in 1.5 by replacing them with table borders.
       Chrome borders around <img>s still vanish at zoom <= 90%,
       but they are nice enough to keep, even if only 3 sided.

   ==> Addressed <img>s in 1.6 by using "thin" instead of "1px" for 
       all CSS image border widths.  This fixes <img> borders on both 
       index and viewer pages.  Per above, index-page <hr>s became 
       table borders in 1.5, for which "1px" works correctly.  

7) Viewer-page image scaling in CSS is lousy - there's no way to 
   adjust to changes in window aspect ratio well.  For more details, 
   see [defunct] "USAGE NOTE" above, and code notes below.  JavaScript
   may help, but using Python to generate HTML that embeds both CSS 
   and JavaScript seems a bit much for a simple Python image viewer...

   ==> Addressed by 1.6's JavaScript-based dynamic image scaling.  
       This makes both this script and its output a bit of a tangled
       mess, but such is life in web development today.

8) Assuming UTF-8 for all insert files' Unicode encoding is simple
   (and also works for ASCII, as it's a UTF-8 subset), but requires
   either a minor script change or file conversions for differing
   platform defaults; is this a significant usage factor?

   ==> Addressed in 1.6: insert encoding was made a separately
       and easily configurable setting in user_configs.py.



===========================================================================
DEVELOPER NOTES
===========================================================================

This section provides additional details and musings mostly of 
interest to programmers, not users (but Android users: see #C).
Items are prefixed by the version relevant or current when added.

1) (all) SCOPE: Apart from header/footer inserts, this script makes
   fairly simplistic image and subfolder links only; edit either
   the output HTML page or the code here that creates it as desired.
   [Update: this program has grown less simple but more useful, with
   version 1.4 styling, 1.5 image-viewer pages, and 1.6 image scaling.]

2) (1.1) SUBFOLDERS: Makes a bullet list for any subfolders in the
   images folder (else they cannot be navigated to), but skips all
   other non-image content; put any doctype, readme, font, CSS code,
   etc., in header or footer.  Run on each image tree subfolder manually;
   automating this and other content seems too clever and complex.

3) (1.2) STYLING: Stretching the thumbs table to fill the whole window
   is off by default, as it can appear too spread out for short names in
   large windows.  Enable this via the user_configs.py setting if desired.
   [Update: as of 1.5, stretching is always on, for new table borders.]

4) (1.2) STYLING: A table overflow scrollbar was skipped, as it
   appears only at table bottom, which can be very far away on large
   pages.  Instead, use the browser's automatic general window scroll.
   [Update: changed in 1.4 - now uses CSS autoscroll for thumbs table,
   which is more mobile-friendly, and shows the scrollbar iff needed.]

5) (1.3) UNICODE: The script now fully supports images with non-ASCII
   names, but getting them onto your web server may take special steps.
   On one Linux server, an "unzip" of the WinZip zip package failed on the
   Unicode test images, but GoDaddy's browser-based file upload worked
   (and in later use, Mac OS and cPanel uploads both handle Unicode well).
   See examples/unicode/_README.txt for more on uploading result files.
   See also learning-python.com/ziptools for a Python zip alternative.

6) (1.3) UNICODE: the insertEncoding setting now defaults to UTF-8,
   as this is a general scheme which also works for ASCII files.  To use
   your platform's default encoding instead, set this variable to None;
   this is not required if header/footer inserts are saved as UTF-8.

7) (1.3) UNICODE: If (but only if) file or folder names are non-ASCII,
   custom HEADER.html files must include a <meta> content-type tag with
   a charset matching the outputEncoding (which is UTF-8 by default).
   Default headers include this tag automatically (see code ahead).

8) (all) CSS: Note that index-page styling must be all inline, to 
   avoid asking custom HEADER.html files to code or link to this CSS code.

9) (all) RELATED: See also pixindex, a related tool that adds images
   to a zip file and FTPs them to a sever: learning-python.com/pixindex.

A) (all) DESIGN: As noted in OVERVIEW, this script's results are 
   static.  Although adapting it to produce results dynamically on a 
   server would support changes in server-folder content, this would 
   require a web server, rendering results unusable offline (e.g., in 
   program docs).  Generating results dynamically on a server would 
   also require redesign of thumbnail generation to avoid long delays.

B) (1.6) LOADING INDICATOR: viewer page images are hidden by 
   JavaScript until loaded, to avoid an annoying 'flash' in some
   contexts.  If JavaScript is enabled, a "Loading..." paragraph 
   is also posted temporarily (else the screen is blank on loads).
   Index pages load thumbnails quickly, and require no indicator. 

C) [this was moved to usage notes]
   (1.6) ANDROID "RAW" AND USER SETTINGS: the native image display
   on some Android Chromes may initially render some images oddly and 
   too large in portrait orientation, but if and only if the seemingly 
   unrelated "Force enable zoom" is selected in Accessibility Settings. 

   The "Raw" links of viewer pages trigger this, but it is not caused by 
   this program - it also happens when visiting images' URLs directly,
   completely outside the script's pages.  It's also limited - it occurs
   for some images only, and never when the Setting is cleared.  This is
   sadly typical of browsers' fragility.  Indeed, at times it seems a 
   website could be laid low by a good sneeze...

   Users may be best served by clearing this setting in this use case.
   For more clues, try a search on "android chrome force enable zoom 
   displays images too large", or this possibly related bug report:
   see https://bugs.chromium.org/p/chromium/issues/detail?id=464295.