README file for Infodoc project archive.
Copyright 2014-2015 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.

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 AND for 
the Infodoc Post Processor utility.

The directory tree of files included in this Infodoc release is organized 
according to sub-project.

Infodoc/
       /infodoc-styles.css    // CSS (Cascading Style Sheet) definition file
       /infodoc*.texi         // Project documentation and test suite source
                              // (one source file per chapter)
       /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    // redirected to stdin to automatically answer
                              // 'idpp' queries (see 'apply')

       /idpp/                 // directory containing Infodoc Post Processor
            /GlobalDef.hpp    // Generic definitions and includes
            /gString.hpp      // gString class definition
            /gString.cpp      // gString class methods
            /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
            /Makefile         // Make file for building 'idpp'

       /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.

-- 'idpp', Infodoc Post Processor
   -- The Infodoc HTML post-processing utility is a new project (less than 3 
      months old), consisting of almost 5,000 lines of C++, 3,000 of which are 
      NEW code. For this reason, you should expect that there WILL BE bugs. 
      We're good, but nobody is _that_ good...
   -- This is an early release, so not all functionality is fully implemented.
      However, all basic functionality is operational, and functions smoothly 
      and without errors on our test suite. (see below for known issues)
      Our test suite stresses the functional limits of both the texi-to-HTML 
      converter and the 'idpp' utility well beyond anything you may 
      _intentionally_ create in your documents, and all operations execute 
      cleanly; however bugs and logical errors WILL arise. Have patience, and 
      we will address each issue as it is reported.
   -- '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.
   -- Running a second or subsequent processing pass on the same document 
      _should_ produce the expected results, but this has not been thoroughly 
      tested. For this release, it is recommended that you do all your 
      post-processing of the document in a single pass.
   -- In the current release, we do not provide a 'no-load' binary, so please 
      compile 'idpp' on your target system. 
      See the chapter 'Build idpp from source' for instructions on compiling 
      'idpp' from source.

   -- Known bugs and other issues:
      -- The 'makeinfo' utility documents a large number of build options and 
         'customization variables' which can affect the HTML output. We have 
         not yet tested all of these options with the 'idpp' post processor. 
         Some of these options generate HTML markup that 'idpp' is not yet 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 currently defined, meaning that the 
         browser defaults are used for these constructs.
         Please see the chapter 'Texinfo Build Options' in the 'idpp' 
         documentation for details.
      -- The '--css_mods' option is not yet fully implemented.
         Because manual modification of the CSS whole-document definitions is 
         straightforward, we have postponed implementation of this option until 
         the next release.
      -- 'idpp' is not particularly fast. In the current release, we have 
         focused on robustness and maintainability over blinding speed. However, 
         even on our ancient 800MHz doorstop, a very large source document can 
         be processed in less than two (2) seconds . If this is more than you 
         can bear to wait for stylish web pages, we might suggest that you 
         switch to decaf.
      -- The dialog-based 'idpp' user interface is not yet implemented. We are 
         not sure that it is necessary, so we're waiting for user feedback 
         before proceeding with that part of the project.

Please note that a large number of Texinfo/makeinfo (v:5.1 and 5.2) bugs were 
uncovered during the development of this project. The author has reported these 
bugs to the maintainers of Texinfo, and several bug fixes have already been put 
into the update stream for the next 'makeinfo' release. (Many thanks to the 
Texinfo crew for their quick response!) Each identified bug is marked in the 
'texi' source file with the literal sequence:  '@c BUG!'. Note that this is a 
'texi' comment and the current state of bug repair will be noted on that 
comment line.

