//******************************************************************************
//* Infodoc-styles - Version History                                           *
//*                                                                            *
//* Author     : Mahlon R. Smith                                               *
//*              Copyright (c) 2014-2025 Mahlon R. Smith, The Software Samurai *
//*                  CSS definitions, source code and binaries released under  *
//*                    GNU GPL version 3.                                      *
//*                  Documentation released under GNU FDL version 1.3          *
//* Date       : 02-Aug-2025                                                   *
//*                                                                            *
//* -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  *
//* Copyright Notice:                                                          *
//* This program is free software: you can redistribute it and/or modify it    *
//* under the terms of the GNU General Public License as published by the Free *
//* Software Foundation, either version 3 of the License, or (at your option)  *
//* any later version.                                                         *
//*                                                                            *
//* This program is distributed in the hope that it will be useful, but        *
//* WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY *
//* or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License   *
//* for more details.                                                          *
//*                                                                            *
//* You should have received a copy of the GNU General Public License along    *
//* with this program.  If not, see <http://www.gnu.org/licenses/>.            *
//*                                                                            *
//* -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  *
//* Description:                                                               *
//* Please see the description of package components in the 'README' file      *
//*                                                                            *
//******************************************************************************

Version History (most recent first):
- - - - - - - - - - - - - - - - - -
v: 0.0.16 13-Jan-2025
  -- Redefine the style class "cjk" to use the "letter-spacing" style 
     element instead of relying upon manual insertion of &hairsp; elements.
  -- Define the "ulin" style class. This class applies the text underline 
     modifier to the enclosed text data. This is useful for documenting 
     the underlined character which identifies the so-called hotkey used 
     to access window controls. It may also be useful for underlined text 
     generally.
  -- In the "tscap" <div> tag, adjust the "line-height" style value 
     to reduce (ugly) spacing between lines in screenshots.
  -- Update comments in infodoc-styles.css.
  -- Posted to website: 02-Aug-2025

v: 0.0.15 02-Apr-2024
  -- The folks who maintan the Texinfo project have made some design 
     decisions which have impacted our documentation; specifically: 
     1) The 'texi2any' processor now outputs an warning message if a 
        @xref, @pxref, @ref reference is inside a @w{} sequence.
        This does not affect the output; however, it does spew hundreds 
        of warning messages across our terminal window. This has cost us 
        several days to update the documentation to eliminate those warnings.
     2) Section menus now call out a "mini-toc" class.
     3) <ul> lists: These lists are now constructed to declare either two(2) 
        class names, OR one(1) class name followed by a style element
        indicating the bullet character to be used. All declared classes are 
        now defined, along with a group of classes for additional characters.
     4) <ol> lists: HTML source syntax has undergone minor adjustments, and 
        idpp has been updated in those areas.
        -- Important Change: The interactive prompt for enumerated lists has 
           been modified: the order of secondary options has changed.
           Therefore, existing response files which specify multiple options 
           for configuring enumerated lists will need to be verified.
           The new order of options is: enumeration_type, initial_value, 
           font_size, and sequence_direction.
     5) The syntax of data following the index table has changed which caused 
        our 'idpp' post-processing utility to see a syntax error. This does not 
        affect the output, but again, it annoyed our sense of order in the 
        universe.
     6) The HTML <tt> tag is no longer used within the HTML markup generated 
        by texi2any. This change was expected because <tt> is no longer 
        supported in the HTML5 specification.
        The tag has been replaced by 
        the <code class="verb">...</code> tag.
        This affects two major makeinfo commands: @t{...} and @verb{|...|}
        which are now encoded as: <code class="t"></code> and 
        <code class="verb"></code>, respectively. These new classes have been 
        defined in 'infodoc-styles.css' to support for these changes in the 
        HTML syntax.
     7) For "quotation" block objects, the HTML syntax for the @author 
        sub-command has changed, and idpp has been updated in that area.
     8) Due to enhancements to the texi-2-HTML output, the "--up_target" and 
        "--no_uplink" command-line options are no longer necessary and therefore 
        deprecated. Currently, these options are recognized, but ignored, and 
        may be removed in a future release. By default, texi2any now removes the 
        up-target link of the first page and replaces it with a reference to 
        the top of the document. This behavior can be controlled by a Texinfo 
        build option. The application now assumes that if the build options 
        TOP_NODE_UP_URL or TOP_FILE or TOP_NODE_FILE_TARGET are used, then the 
        developer must know what he/she/they is/are doing. (We realized that 
        this is a dangerous assumption, but we have faith in you! :-)
     9) Due to enhancements in the texi-2-HTML output, which now declares a 
        standard HTML5 MIME type, the "--no_html5" option is now obsolete.
        If specified, this option will be ignored, and will be removed from 
        the application for the next release.
    10) Due to enhancements to the texi-2-HTML output, the "--fixed_list" option 
        now has limited usefulness because all unordered lists now declare a 
        CSS class. Currently, this option is recognized, but ignored, and may 
        be removed in a future release.
    11) Several new CSS classes have been declared for the generated HTML, 
        so the 'infodoc-style.css' file has been updated to fully implement 
        most, if not all these newly-declared classes.
  -- Significant enhancements have been made in the area of selecting the 
     relative font size for all the major objects (what the makeinfo 
     documentation calls "environments"). This includes block environments, 
     itemized lists, enumerated lists, multitables, the cartouche, _and_ 
     text outside of any environment object. These enhancements include 
     interactive-processing options, as well as an expanded support for 
     invisible styling tokens embedded within the Texi source.
  -- Significant improvements have been made in the configuration of style 
     options for enumerated lists. Again, these enhancements include 
     interactive-processing options, as well as an expanded support for 
     invisible styling tokens embedded within the Texi source.
     -- A number of new Texinfo macros have been defined to support these 
        styling enhancements and to reduce the likelihood of syntax errors 
        when creating the Texinfo source document. 
        See the documentation chapter on "Macros In Infodoc" and the file
        'texi-macros.texi' for details.
  -- Add the "--cartouche" command-line option to give direct control over 
     text flow within a cartouche object. The "--no_cartouche" option was a 
     binary switch and is now deprecated.
  -- Bug Fix: If user specified to process a file for the second time, the 
     'multiPass' flag was not being set, so a second copy of the container 
     class was being written to target. (Bad programmer! Go to your room!)
  -- Bug Fix: If -v (verbose) option specified, number of line items in 
     itemized lists was not being counted correctly.
  -- Due to enhancements in the texi-2-HTML output, the "--fixed_list" option 
     now has limited usefulness because all unordered lists now declare a 
     CSS class. Currently, this option is recognized, but ignored, and may 
     be removed in a future release.
  -- In the prompt for enumerated lists, replace the 'c' (custom) enumerated 
     type with 'G' upper-case Greek type. The 'c' option is still available; 
     however, it is not displayed in the prompt.
     -- Note that at this time (2024) not all browsers can handle upper-case 
        Greek enumerations, and will output the default decimal enumeration instead.
  -- Cleaned up receipt of the ABORT token from either the response file or 
     directly within interactive mode. Formerly, the abort signal was not always 
     recognized.
  -- If an invalid response is read from a response file i.e. the file responses 
     are out-of-synch, the application will now immediately terminate 
     post-processing. This makes it easier for the developer to find where 
     in the sequence the error occurred.
  -- Implement the '--step' command-line option to assist in debugging the 
     scan of source data.
  -- Implement the '--skip' command-line option to assist in debugging the 
     user prompts.
  -- Update the output generated by the '--version' option.
  -- Update command-line help to allow either '--help' or '--helpless' 
     (-h or -hl). This functionality was imported from the author's AnsiCmd 
     library, and optionally pipes the help data through the 'less' utility.
     Thus, helpless :-)
  -- Import the nsleep() method from our AnsiCmd library. This allows for 
     inserting a small delay in processing tokens read from the response file.
  -- Parsing the source now about 5-8% faster. (It wasn't slow before :-)
  -- Major documentation update. Note that the documentation may still be 
     a bit rough in places, which will be addressed soon.
  -- Posted to website: 24-May-2024


v: 0.0.14 04-Jun-2021
   -- 'infodoc-styles.css' (CSS style definitions)
      Define additional heading styles: "p.h[5|6|7|8]heading". 
      These provide a series of sub-heading levels.
   -- 'idpp' (post-processing utility)
      -- Update: Recent changes to the HTML output formatting generated by
         makeinfo (texi2any v:6.8) have required updates to the parsing algorithm
         of idpp. The major differences relate to changing various constructs
         to be "classes" instead of simple "<span> etc.
         -- The HTML format which begins the main section of the data just below
            the <body> was changed from: <span id="TOP">
                                     to: <div class="top" id="Top">
         -- The HTML format which begins the table of contents was changed
            from: "<span id=\"SEC_Contents\"></span>"
              to: "<div class=\"Contents_element\" id=\"SEC_Contents\">"
         -- The 'info' style top menu is no longer included in the HTML document.
         -- The Title page is now located _above_ the Table of Contents.
            This is actually a more logical placement, but it required updating
            the post-processor to scan for blocks of formatted text _above_
            the Table of Contents.
         -- The HTML format for the seldom-used "lisp" block has been modified:
            from: "<div class=\"lisp\">
              to: "<div class=\"example lisp\">
                  "<pre class=\"lisp\">"
            We can see why this was done: the Lisp and Example blocks actually
            use the same format; however, it was a poor design decision.
      -- Update the gString-class code from v:0.0.30 to v:0.0.32. Note that the 
         changes to gString are unrelated to that way the utility is used in this
         application.
      -- Consolidate some redundant code e.g. ppfFormattedBlock().
      -- Reorganize the messages generated by the '--book' option.
      -- Update copyright dates.
      -- Correct a statement which generated a compiler warning about comparing
         signed and unsigned integers. (no actual functionality change)
   -- Documentation update.
   -- Posted to website 26-Jun-2023

v: 0.0.13 01-Aug-2020
   -- 'infodoc-styles.css' (CSS style definitions)
      Update version number only.

   -- 'idpp' (post-processing utility)
      -- Modifications to post-processing for a second or subsequent pass on 
         the same file. While a second pass on a previously-processed HTML 
         file is allowed, our goal is to do as little _unintentional_ 
         modification as practical during the second pass.
         For this reason, we have made the following adjustments:
         -- If a second pass is performed with automatic processing:
            -- Bug Fix: In ppfProcGNU(), two redundant "<br>" tokens were 
               being inserted after the version-number declaration.
            -- Bug Fix: When pushing an empty source line into the FIFO object, 
               the corresponding pull of that line from the FIFO object was 
               seeing no data. Refer to ppfUnReadSrcLine() and ppfReadSrcLine() 
               for details.
            -- Bug Fix: In ppfProcOL(), if the source file contained a 
               descending <ol> list, (example: 10, 9, 8, ...) the "reversed" 
               token was being discarded.
            -- Bug Fix: The table-border prompts were being skipped on the 
               second pass because there was no test for previously-processed 
               tables.
         -- If a second pass is performed with interactive processing via a 
            response file:
            -- The "no-mods" flag is set to prevent all modifications during 
               the second pass. This is necessary to avoid unintended responses 
               due to the response file tokens very likely becomming 
               out-of-synch with the actual promots.
               Note: The user can override the "no_mods" flag (for the first 
               source file in the list only) by invoking the application with 
               the '-V' (verify) flag.
      -- Bug Fix: When scanning for <ul> and <ol> tags, there was a hidden 
         bug which accidentally parsed the tag correctly in all known cases.
         It now does the same parsing intentionally, eliminating the potential 
         error.
      -- Documentation update.
      -- Posted to website 14-Aug-2020


v: 0.0.12 16-Dec-2019
   -- 'infodoc-styles.css' (CSS style definitions)
      Update version number only.

   -- 'idpp' (post-processing utility)
      - Bug Fix: If formatted text blocks are present between the Table Of 
        Contents and the top-level menu, they were not always recognized.
      - Enhance user prompt for UL and OL lists by displaying cleaner 
        "first line item" text.
      - Cartouche objects are now recognized within UL and OL lists so long 
        as it is preceded by a blank line.
   -- Documentation
      - Update version numbers.
   -- Posted to website 03-Jul-2020

v: 0.0.11 12-Dec-2019
   -- 'infodoc-styles.css' (CSS style definitions)
      - Integrate the color attributes and styles which support documentation 
        of the NcDialog API. These styles were formerly found in a version 
        of this file which was developed along a separate track.
        The two development tracks have now been merged.

   -- 'idpp' (post-processing utility)
      - Bug Fix: Application exit code was sometimes not being set correctly.
        Application should exit with either OK ( 0 ) or ERR ( -1 ).
      - Enhance processing of the document chapters which contain the 
        GNU General Public License and the Free Documentation License. As stated 
        elsewhere (ppfProcGNU() method), these are legal documents and therefore 
        should resemble as closely as possible the lawyers' intended format.

   -- Documentation
      - Update version numbers.
   -- Posted to website 15-Dec-2019

v: 0.0.10 26-Sep-2019
   -- 'infodoc-styles.css' (CSS style definitions)
      - Add "small..." and "large..." versions of all block constructs.
      - Additional minor updates.

   -- 'idpp' (post-processing utility, version:0.0.10)
      - Skip v:6 through v:9 to synchronize with 'infodoc-styles.css'
      - Complete rewrite of parsing routines to support the changes in 
        the way makeinfo/texi2any formats the HTML output.
      - Direct support for smaller-font and larger-font block definitions.
        This was made necessary because texi2any no longer supports 
        "@small..." versions of block definitions for HTML output.
      - Significant changes in invocation options:
        - Remove options:
          -t               text-only mode (obsolete)
          -o               ordered-list processing (see "--bullet_list)
          -p               ordered-list sequencing (see "--enum_list)
          --no_bullet      no bullet-list processing (see "--bullet_list)
          --css_mods       dynamic modification of CSS definitions (not yet implemented)
        - Redefine:
          -i               interactive mode (includes the four sub-categories, see below)
          --no_cartouche   enable "flowing" text within @cartouche blocks
                           (cartouche text is preformatted by default)
        - Add new options:
          --bullet_list    interactive bullet-list processing
          --enum_list      interactive enumeration-list processing
          --table_border   interactive table formatting options
          --block_font     interactive text-block font size selection
          - V              verify that source has not already been processed
          --fixed_list     prevent browsers from automatically reformatting bullet lists
          --response       specify a interactive-response file
                           (formerly, this file was accessed via redirection of stdin)
          --no_special     disable automatic "special-case" list formatting
          --no_html5       disable automatic update of HTML v:3 and v:4 constructs
          --scan           fully define the existing debugging option
          --book           fully define the existing debugging option
      - Minor changes to the source code to accomodate updates made in the
        GCC/G++ compiler. Previous: v:4.8.3 (gnu++11). Current: v:9.2.1.

   -- Documentation
      - Update for new and modified 'idpp' invocation options.
      - Create detailed response file, "apply_response.txt" to exercise all 
        'idpp' interactive processing options.
      - Remove most references to makeinfo v:5.x bugs. (These have _mostly_ been addressed)
      - Update all formatting tests and verify 'idpp' functionality.

v: 0.0.09 07-Apr-2017
   -- Update to website only. No public release.

v: 0.0.08 13-Jun-2015
   -- 'infodoc-styles.css' (CSS style definitions)
      - Add foreground/background color styles to support NcDialog API 
        screen capture. These styles are specific to screen captures 
        of terminal-window dialogs written using the NcDialog API, and are
        not necessary for standard Texinfo documents.
        Located below the message: "Styles specific to SoftwareSam's website."

   -- 'idpp' (post-processing utility, version:0.0.05)
      - Update text-formatting utility (gString class).

   -- 'infodoc.texi' (test and documentation source document)
      - Minor changes only.

   -- Posted on website dd-Mmm-2015.

v: 0.0.07 21-Feb-2015
   -- 'infodoc-styles.css' (CSS style definitions)
      - Bug fix: Correct the 'list-style-type' element in the 
       'enum-decimal-zero' class.

   -- 'idpp' (post-processing utility, version:0.0.04)
      - Create a more robust test for end-of-block markers. This reduces the
        chance that really strange constructs will hide the end-of-block tag,
        causing a processing error. See ppfEndBlock().
      - Create a more robust test for the beginning of <ul> and <ol> lists.
        Occasional strange constructs were sometimes causing the opening tag
        to be missed, and therefore the list to be unprocessed.
        See ppfTestUlistBegin() and ppfTestOlistBegin().
      - Bug fix: In ppfProcFormattedBlock(), if source contained one
        preformatted block nested inside another preformatted block, then
        processing of the block terminated too soon.
      - Lists inside pre-formatted blocks. In the previous release we did not
        process anything inside a preformatted block. In fact, lists
        SHOULD NOT be placed inside preformatted blocks, but if they are, we
        now identify them. Note, however, that we DO NOT process the lists
        themselves (that would require a second pass through the source HTML).
        but we do compensate for the unfortunate spacing in the generated HTML.
        See ppfProcFormattedBlock() and ppfPFB_List().

   -- 'infodoc.texi' (test and documentation source document)
      - Update chapter 'Idpp Block Processing' to reflect changes in 'idpp' 
        related to processing preformatted blocks.
      - Other minor updates.

   -- Posted on website 24-Feb-2015.

v: 0.0.06 03-Feb-2015
   -- 'infodoc-styles.css' (CSS style definitions)
      - Bug Fix: <tt> tag: Add the attribute 'white-space: pre;' 

   -- 'idpp' (post-processing utility, version:0.0.03)
      - Bug fix: If <ul> or <ol> list ends with a block construct, then the 
        </ul> or </ol> tag was sometimes being missed.
      - Bug fix: If first chapter header is not for 'index-main-menu', then 
        end of TOC was not being found.
      - Bug fix: In ppfProcUL(), if user specified that <ul> lists should not 
        be processed, the disable-processing flag was not being set.
      - Remove the methods ppfCopyUL() and ppfCopyOL(). These made sense when 
        the algorithm for list processing was unstable, but are no longer 
        necessary.
      - Allow for a '0' (zero) value in response to the <ol> list processing 
        start value prompt IF the specified enumeration type == 'd' (decimal).
        This is to accomodate the fact that the text of both the GPL and FDL 
        licenses begin with item '0'. Note that the prompt still calls for a 
        value >= 1.
      - Add a special test for GPL and FDL license text. Process the enumerated
        lists associated with these licenses (unless the '--no_mods' option 
        has been specified). See 'ppfProcGNU' method for details.

   -- 'infodoc.texi' (test and documentation source document)
      - Incorporate the GPL/FDL license boilerplate text into the chapter, 
        'Copyright Notice' because processing them is now part of the 'idpp' 
        test suite.
      - Add description of GPL/FDL text processing.
      - Minor corrections and updates.

   -- Posted on website 13-Feb-2015.

v: 0.0.05 06-Dec-2014
   -- 'infodoc-styles.css' (CSS style definitions)
      - Add 'ol.enum-decimal-zero' class for leading-zero-decimal enumeration.
      - Add 'quotation' class for <blockquote> tags: 
        <blockquote class="quotation">
        Note that the HTML <blockquote> tag continues to be re-defined at this 
        time. If this becomes a problem, we can remove the definition.
      - For all the 'small' versions of the block classes, add the element:
        'font-weight: bolder;'  This was done because the contrast between a 
        'smallXXX' block and the surrounding text is actually too great, making 
        it difficult to read. Applies to the following classes: 'smallquotation', 
        'smallindentedblock', 'smallexample', 'smalldisplay', 'smallformat'.
      - For the 'table th' definition, add the element 'text-align:center' to 
        center the column headings of the table.
      - Add a new class: 'table.bordered'. This is a <table> tag class which 
        allows for modifying the plain <table> output to include a border/grid.
        Minor changes have been made to the 'table.index-cp' and 'table.jumpto' 
        classes to accomodate this new functionality.
      - Enable the 'table.cartouche' class definition. Formerly, this was 
        commented out, but the 'idpp' post-processor now handles the callout for 
        these objects. (without post-processing, cartouche paragraphs will have 
        overlapping border definitions).
      - Remove the extended comments at the end of the file. These comments have
        been moved into the formal documentation.

   -- 'idpp' (post-processing utility, version:0.0.02)
      - First effort. Written entirely in straightforward C++.
      - 'idpp' contains 4,700 line of code -- 3,000 of those are NEW, so there 
        will be bugs. 
      - Also, there is no way that a utility of this kind can anticipate every 
        possible Texinfo command combination that results in HTML markup, so 
        please have patience. We will address the issues as they are reported.

   -- 'infodoc.texi' (test and documentation source document)
      - Clean up descriptions and notations about makeinfo bugs
      - Add new tests or modify some existing tests to exercise the 
        post-processing utility.
      - Split the .texi source into chapters and update the Makefile to match.
      - Add chapters for automatic (idpp) and manual post-processing of HTML
        documents. Some of the information in these chapters is incomplete in 
        the current release.
   -- Posted on website 02-Feb-2015.

v: 0.0.04 01-Dec-2014
   - Add a node to the documentation: 'Adjusting Style Definitions' which is a 
     beginner's guide to customizing the CSS style definitions.
   - Document the classes which default to the <h1> <h2> <h3> and <h4> tags.
     Certain classes are not defined, but default to a pleasing and consistent 
     display format.
       <h1> 'settitle', 'top'
       <h2> 'contents-heading', 'unnumbered'
       <h3> 'section', 'heading', 'unnumberedsec'
       <h4> 'subsection', 'subheading'
   - Define the 'subsubsection' class and 'subsubheading' class.
     These are called out, and if not defined, they default to our <h4> 
     definition; however, we have defined them to differentiate between 
     subsection/subheading classes and subsubsection/subsubheading classes.
   - Add a definition for the 'header' class which controls the navigation bar 
     which lives at the top of each node. The navigation bar looks fine using 
     the defaults, so the class definition is commented out, but it's available 
     in case you want to tweak it.
   - Add a definition for the 'cartouche' class. The contents of this class 
     are commented out because the generated HTML interferes with it, so it 
     would be necessary to manually delete the string 'border="1"' from the HTML 
     in order for this class to work as expected.
   - Add a definition for the 'nolinebreak' class. This class is (sometimes) 
     called out by HTML code for a @w{ ... } TexInfo command sequence. 
   - Add a definition for the 'contents' class and its associated <ul> levels:
     'toc-level1', 'toc-level2', 'toc-level3'.
     This replaces the 'ul.toc_level1', 'ul.toc_level2' and 'ul.toc_level3' 
     definitions in the previous version. If you used these in the past, 
     sorry, they're gone--but it's now a much better design.
   - Change default background color from #D0FFD0 to #66FF99. This is a 
     'standard' color as defined by W3C.
   - Add cute 'W3C Valid CSS3' logo at top of 'infodoc_css.html'.
   - Posted on website 06-Dec-2014.

v: 0.0.03 13-Oct-2014
   - Add <li> definition for <ol> tags to provide item spacing.
   - Add 'Copyright' and 'Technical Support' nodes to infodoc.texi because 
     it's now a real release.
   - Additional tests in infodoc.texi which were needed for submitting an 
     enhancement request for TexInfo commands: @itemize and @enumerate.
   - Other changes to infodoc.texi to support bug reporting to gnu.org.
   - Cleanup of documentation and code comments.
   - Posted on website 30-Nov-2014

v: 0.0.02 11-Oct-2014 
   - This became an interesting project in itself.
   - Created 'infodoc.texi' to test the CSS styles.
   - Comprehensive investigation of the HTML markup generated by the 
     'makeinfo' utility. This effort identified at least five (5) bugs in 
     makeinfo and approximately 19 bugs and other issues with the texi-to-HTML 
     converter.
   - Significant expansion of infodoc-styles.css to compensate for as many 
     of the identified issues as possible.
   - Generated both internal project documentation AND user-oriented 
     documentation.
   - Posted on website 12-Nov-2014.
 
v: 0.0.01 05-Oct-2014 
   - Initial effort. A quick style sheet created to beautify the HTML version 
     of the gString documentation posted on the website.
   - Written in CSS version 3
   - Posted on website 02-Nov-2014

