README file for Infodoc project archive.
Copyright 2014-2025 by The Software Samurai
on the web:  http://www.SoftwareSam.us/
Software released under GPL3+, and documentation released under FDL1.3+
=======================================================================

Unpack this archive into a clean directory using:
                tar -xjvf infodoc-styles-x.x.xx.tar.bz2

This package provides CSS Style for HTML documents created by the 
Texinfo/makeinfo documentation engine, version 6.8 and above.
The current release is tested against makeinfo/texi2any v:7.1.1.

      IMPORTANT NOTE:
      For HTML documents created with makeinfo 6.7 and earlier,
      please use Infodoc version 0.0.13.
      For HTML documents created with makeinfo 6.0 and earlier,
      please use Infodoc version 0.0.07.

The HTML output generated from Texinfo souce is certainly readable and can be 
used without modification, but it was never intended to represent stylish 
formatting. Applying the style definitions in infodoc-styles.css will beautify 
the HTML output, AND will give you full control of each of the CSS class 
definitions (referenced, but not meaningfully defined) in the raw HTML 
output.

  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -
This package contains a CSS (Cascading Style Sheet) style definition file, 
HTML post-processing utility, and full documentation for applying these style 
definitions to your HTML documents. The documentation also serves as a 
comprehensive test suite for both the Texinfo texi-to-HTML converter (texi2any) 
AND for the Infodoc Post Processor utility.

The directory tree of files included in this Infodoc release is organized 
as follows:

Infodoc/
   /infodoc-styles.css    // CSS (Cascading Style Sheet) definition file
   /infodoc*.texi         // Project documentation and test suite source
                          // (one source file per chapter)
   /texi_macros.texi      // Useful macro definitions for Texinfo source
   /same_author.texi      // List of other projects by the same author
   /gpl-3.0.texi          // GNU GPL license, sub-document
   /fdl-1.3.texi          // GNU FDL license, sub-document
   /Makefile              // Make file for generating 'info' and HTML output
   /infodoc.info          // Info-format document generated from infodoc*.texi
   /infodoc.html          // HTML-format document generated from infodoc*.texi
   /infodoc_css.html      // infodoc.html after post-processing for style
   /applycss              // Shell script for invoking 'idpp' to apply CSS
                          // style to the HTML document
   /apply_response.txt    // Response file for interactive processing
                          // (responds to 'idpp' queries)

   /idpp/                 // directory containing Infodoc Post Processor
      /gString.hpp        // gString class definition
      /gString.cpp        // gString class methods (text parsing and formatting)
      /idpp.hpp           // Idpp class definition and misc. definitions/data
      /idpp.cpp           // Main application methods
      /idpp_file.hpp      // Definitions for access to source and target files
      /idpp_file.cpp      // Methods for read/write/verify of files
      /idpp               // Executable file (built for x86_64 hardware)
      /Makefile           // Make file for building 'idpp'
      /dolist             // Perl script for post-processing 'list'  (see below)
      /doblock            // Perl script for post-processing 'block' (see below)

   /idpp/list/            // directory containing 'list' test document
      /list.texi          // texi source
      /list.info          // Info-format document
      /list.html          // HTML-format document (as generated by texi2any)
      /Makefile           // Make file for building 'list'

   /idpp/block/           // directory containing 'block' test document
      /block.texi         // texi source
      /block.info         // Info-format document
      /block.html         // HTML-format document (as generated by texi2any)
      /Makefile           // Make file for building 'block'

   /VERSION_HISTORY       // Project change log
   /README                // Package description, release notes (this file)


To read the full Texinfo documentation for this package, type: 
                   info -f infodoc.info
or even better, open the 'infodoc_css.html' file in your favorite browser.

The procedure and options for applying CSS style to your raw HTML output can 
be found in the chapter, 'Infodoc Post-processor'

  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -
NOTES on the current release of the Infodoc project:

-- The CSS style definitions in 'infodoc-styles.css' are the base of this 
   project. 
   -- These definitions transform the formatting of your HTML documents 
      generated from Texinfo source.
   -- 'infodoc-styles.css' contains robust definitions and re-definitions for 
       all aspects of your Texinfo-generated HTML document.
   -- No outstanding problems have been identified.
   -- See VERSION_HISTORY for updates made for this release.

-- The primary document is built from Texinfo source (included) and builds to 
   three documents: 'infodoc.info'. 'infodoc.html' and 'infodoc_css.html'.
   Taken together these documents provide the test base for the 'idpp' HTML 
   post-processing application.
   -- This document contains more information that you will probably ever want 
      or need, but it's function is more about its syntax than the actual 
      information it contains.
   -- Please give particular attention to the file 'texi-macros.texi'. 
      This file contains the various Texinfo macros which have been developed 
      to ease the pain of creating attractive and readable documents in both 
      the 'info' and HTML output formats.
      See also the chapter "Macros In Infodoc" which describes how these 
      macros are designed and how to use them efficiently.

-- 'idpp', Infodoc Post Processor
   -- Please see the documentation, chapter 'Build idpp from source' for 
      instructions on compiling 'idpp' from source.
   -- The 'idpp' application has been updated to address changes made between 
      versions 6.8 and 7.1.1 of the makeinfo (texi2any) utilities which are 
      distributed with the Texinfo development package.
      -- If you are using a version of makeinfo that is older that v:6.8, please 
         download the legacy version of the Infodoc package v:0.0.13.
   -- Most updates included in the current release address issues related to 
      modifications made to the HTML output formatting within the texi2any utility.
      Please see notes in VERSION_HISTORY for further details.
   -- 'idpp' v:0.0.16 includes only one major change:
      This release implements a scan for instances of a bug in the 'texi2any' 
      HTML output which inappropriately inserts HTML &para; entities into 
      <h...></> (heading) tags. The &para; entities are automatically identified 
      and removed by default, unless the '--no_paraent' command-line option is 
      specified.
   -- Other modifications for 'idpp' v:0.0.16 include:
      -- Bug Fix: In parsing command-line arguments, if single-characters options 
         were concatenated, scan of the token may have stopped too early, causing 
         option(s) to be missed.
      -- Bug Fix: The abort signal from the user was not being recognized under 
         some very specific circumstances, i.e. abort before the first chapter 
         heading.
      -- Bug Fix: If a "@verbatim" block is declared, but the block contains no 
         data, the scan was not seeing the closing tag for the block because 
         it is located on the same line as the opening tag.
              Example: "<pre class="verbatim"></pre><p>following_data"
      -- The interactive prompt for multitable border now silently accepts a 
         response of 'a' (automatic) as a substitute for the default 
         'b' (bordered) response. This was done for compatibility with the 
         'automatic' response which is valid in prompts for processing other 
         types of objects.
   -- 'idpp' v:0.0.15 significantly expanded support for enumerated lists (<ol> tags).
      -- Important Note: The order in which secondary formatting options are 
         specified during interactive processing has changed. If your project's 
         response file includes secondary style options for enumerated lists, 
         please verify that they are specified in the correct order.
   -- Infodoc v:0.0.15 was the first Infodoc release to include the author's test 
      documents: 'list.html' and 'block.html'. (A student wandered by our desk 
      and mentioned that they looked interesting, so they are now included 
      in the release. :-)
      -- These documents are used during development and testing of the 'idpp' 
         post-processor because they build in less than one second, and 'idpp' 
         takes less than half of one second to apply CSS style to them. 
         This is a useful attribute when making hundreds or thousands of small 
         changes over the course of the development process.
      -- These documents are built using a standard makefile, and receive 
         their post-processing through a simple Perl script which encapsulates 
         the various post-processing options used during development.
         See 'dolist' and 'doblock'.
      -- One interesting aspect of these test files is that all HTML adjustments 
         and application of CSS style is done automatically. No interactive 
         post-processing is necessary; consequently, no 'idpp' response file 
         is required. The long-term goal is to make post-processing of any HTML 
         document fully automatic through the use of macros, embedded styling 
         tokens and robust CSS styling classes. (We're pretty close. :-)
      -- Note that the more interesting tests contained in these documents have 
         been promoted to the main document 'infodoc.html', so there is some 
         duplication among them.
   -- 'idpp' has been built and tested only on Wintel hardware; however, our 
      code is intentionally generic, using no third-party libraries, so we would 
      anticipate few problems when building on other platforms that use the GNU 
      compiler. If you are building for ARM or other platforms, please send a 
      note on your experiences.

   -- Known bugs and other issues:
      -- The 'makeinfo' utility documents a large number of build options and 
         seldom-used 'customization variables' which can affect the HTML output. 
         We have not tested all of these options with the 'idpp' post processor. 
         Some of these options generate HTML markup that 'idpp' may not be able 
         to parse correctly; however, when using the default values for all of 
         these options, 'idpp' works smoothly.
         For some of these options, the texi-to-HTML converter calls out special 
         class names, none of which are defined, meaning that the 
         browser defaults will be used for these constructs UNLESS CSS style 
         is applied. Please see the chapter 'Texinfo Build Options' in the 'idpp' 
         documentation for details.
      -- The Infodoc package defines most, if not all the HTML/CSS styling 
         classes declared by the makeinfo engine. For some of the declared 
         styling classes, only CSS stubs are provided. For these classes, the 
         browser defaults seem to handle formatting in a relatively uniform 
         manner. The browsers used for testing are: Firefox, Brave, Chromium and 
         Opera. If you or your customers are viewing your documents through a 
         different brower, let us know about your experiences.
      -- The '--css_mods' option is not yet fully implemented, and is disabled.
         Because manual modification of the CSS whole-document definitions is 
         straightforward, we have postponed implementation of this option.

  **-------------------------------------------------------------------------**
    Many thanks to the Texinfo development team for their quick responses to 
    various makeinfo/texi2any bugs and logical inconsistencies uncovered 
    during development of the Infodoc project. 
  **-------------------------------------------------------------------------**

