Next:   [Contents][Index]

Infodoc HTML Styling Package

Copyright © 2014-2024 Mahlon R. Smith, The Software Samurai This document describes version 0.0.15 of 'infodoc-styles.css' and version 0.0.15 of 'idpp'. The infodoc-styles.css CSS style definitions are released under the GNU General Public License (GPL 3+), and the user documentation (this document) is released under the GNU Free Documentation License (FDL 1.3+): Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is available from the Free Software Foundation: ‘http://www.gnu.org/licenses/

Infodoc CSS styles and HTML post-processor documentation.
This document describes ‘infodoc-styles.css’ version 0.0.15 and ‘idpp’ version 0.0.15.

This document is also a Texinfo source template for testing the post-processing algorithms used to process the raw HTML markup generated by ‘makeinfo’ (texi2any).

Because this is a test document and may produce some odd output at times: for ’info’ output, please open your terminal window to at least 132 columns and for HTML output, open your browser to full-screen mode.





Table of Contents


Overview

Why Are We Doing This Project?

"I know it’s only documentation, but I like it, like it, yes I do.
— Mick Jagger and Keith Richards (with Ronnie Wood)

User-oriented documentation is the public face of any product, and serves as the primary contract between developer and customer. Documentation reflects the professionalism and reliability (or lack thereof) of the developer. Thus, when a developer creates documentation, he or she expects it to be of highest quality; and in our experience, the better the documentation is, the better the product will be.

The Texinfo ’makeinfo’ documentation system (along with TeX) is the official documentation engine for GNU/Linux, its utilities and applications. ’makeinfo’ is a great tool, but because it must serve a broad range of user needs, it is necessarily limited both in flexibility and in professional polish. This Infodoc package provides a tool for beautifying the documentation produced by the texi-to-HTML converter.



Infodoc Package Components

'infodoc-styles.css' is a Cascading Style Sheet (CSS) definition file. This file may be applied to the raw HTML output generated by the Texinfo ‘makeinfo’ utility to correct and beautify the raw HTML document.
See CSS Definition File, (version: 0.0.15)

'idpp' Infodoc Post Processor is a small, console utility written in C++. 'idpp' automatically applies the CSS style definitions of 'infodoc-styles.css' as well as correcting the more outstanding errors and formatting weaknesses found in the raw HTML generated by the ‘makeinfo’ documentation engine.
See Infodoc Post-processor, (version: 0.0.15)

‘infodoc_xx.texi’ are the Texinfo source code files for the Infodoc package documentation for both 'infodoc-styles.css' and 'idpp'. Build the documentation files using the standard ‘make’/‘gmake‘ utility and the provided ‘Makefile’. (Pre-built copies are included in the package.)
See Rebuilding the info and HTML documents.

This document also includes a comprehensive test suite which exercises all the major functionality of ‘makeinfo’ which is likely to affect the quality of the HTML output, documenting its capabilities as well as its shortcommings. The test suite focues on the info-format and the HTML-format documents generated simultaneously from the ’texi’ source. Special attention is given to the similarities AND differences between the two document formats.
See Makeinfo Testing.



The ‘makeinfo’ Texi-to-HTML Converter and Why It Needs Our Help

The makeinfo utility creates HTML output when invoked with the −−html option. This generates references to a large number of CSS class names; however, these classes, if defined at all, are really just stubs which need to be defined in a more meaningful way to create professional-looking HTML output.

The raw HTML output relies on browser defaults to handle the missing or incompletely-defined classes. Considering the wide variety of browsers, HTML syntax versions and rendering standards currently in use, this is a reasonable default process; however, we find it to be a bit too Wild-West for our taste.

To customize the HTML output, it is necessary to robustly define the named classes referenced in the HTML output. This is not entirely straightforward because classes are often embedded within other classes, inheriting from, or overriding definitions of the parent class.

The makeinfo texi-to-HTML converter a.k.a texi2any is a work-in-progress. The conversion from the C language to Perl was a nerd’s dream project, but it has taken several years to recover from the bugs and questionable design decisions of that project. In fact, your author originally created 'infodoc-styles.css' and 'idpp' to ease the transition to Perl.

Software Sam wants to express his sincere gratitude to Gavin, Pat, Karl, and everyone who has contributed to this project over the last decade.

Thank You, Everyone



CSS Definition File

The CSS definition file, 'infodoc-styles.css' robustly defines all the CSS class definitions called out in the HTML documents generated by the Makeinfo texi-to-HTML converter. Many other class definitions and HTML tag re-definitions are also provided to rescue your lovingly-crafted documents from the often ugly, and sometimes barely-readable rendering inflicted on your document by the browser’s default settings.

The styled HTML has been functionally verified by the the test suite included in this document. The page rendering has been visually and aesthetically verified for use with reasonably up-to-date versions of Firefox(tm), Chromium(tm), Brave(tm) and Opera(tm) browsers. (Note that Internet Explorer(tm) version 11 is now obsolete, and that in our opinion only a fool would use “Edge”.)




Summary of CSS Definitions

The CSS definitions in 'infodoc-styles.css' fall into the following broad categories.

  1. Whole-document (<body>) Definitions
  2. CSS Class Definitions
  3. Sub-class Tag Definitions
  4. Redefinition of Inadequate or Deprecated HTML Tags

Basic Document Style

Every HTML document needs certain style definitions. Often, the browser’s default definition for an object is quite acceptable. At other times, the various browsers can’t agree on how to render an object, so it may look great in one browser/version and nasty in another browser/version. Your customer will immediately assume that this is your fault. Applying CSS style gives you greater control over how your document will be displayed to the user.

The following table shows the 'infodoc-styles.css' style definitions which apply to the entire document.
Please see Adjusting Style Definitions for a detailed description of each of these style elements.

FUNCTIONHTML/CSS OBJECTSTYLE ELEMENT
 Background Color <body>background-color:
 Text Color <body>color:
 Font Size <body>font-size:
 Font Family <body>font-family:
 Container Width ’infodoc_container’ classmax-width:, padding-right:, padding-left:


Matching Your Texinfo Commands to CSS Definitions

This table describes the relationship between your '.texi' source code commands and the HTML output generated from them when using the makeinfo texi-to-HTML converter.

TEXINFO COMMANDHTML OBJECTEXAMPLES AND TESTS
 ♦♦♦ Block Environments ♦♦♦
 @quotationCSS: ’blockquote’ class and ’blockquote.quotation’ class
<blockquote class="quotation">
see Quotation Commands
 @smallquotationCSS: ’blockquotation’ class and ’blockquote.smallquotation’ class
<blockquote class="quotation smallquotation">
 @indentedblockCSS: ’indentedblock’ class
<blockquote class="indentedblock">
see Indentedblock Commands
 @smallindentedblockCSS: ’smallindentedblock’ class
<blockquote class="indentedblock smallindentedblock">
 @exampleCSS: ’example’ class
<div class="example"> <pre class="example-preformatted">
see Example Commands
 @smallexampleCSS: ’smallexample’ class
<div class="example smallexample">
<pre class="example-preformatted">
 @lispCSS: ’lisp’ class
<div class="example lisp">
<pre class="lisp-preformatted">
see Example Commands
 @smalllispCSS: ’smalllisp’ class
<div class="example smalllisp lisp">
<pre class="lisp-preformatted">
 @displayCSS: ’display’ class
<div class="display"> <pre class="display-preformatted">
see Display Commands
 @smalldisplayCSS: ’smalldisplay’ class
<div class="display smalldisplay">
<pre class="display-preformatted">
 @formatCSS: ’format’ class
<div class="format"> <pre class="format-preformatted">
see Format Commands
 @smallformatCSS: ’smallformat’ class
<div class="format smallformat">
<pre class="format-preformatted">
 @verbatimCSS: ’pre’ class and ’pre.verbatim’ class
<pre class="verbatim">
see Verbatim Commands

 
 ♦♦♦ Block Modifiers ♦♦♦
 @flushleftCSS: ’flushleft’ class and ’flushleft-paragraph’ class
<div class="flushleft"><p class="flushleft-paragraph">
see Misc Block Modifiers
 @flushrightCSS: ’flushright’ class and ’flushright-paragraph’ class
<div class="flushright"><p class="flushright-paragraph">
 @raggedrightCSS: none   (minimal support in HTML)
 @cartoucheCSS: ’table.cartouche’ class
<table class="cartouche" border="1">
 @exdentCSS: ’exdent’ class
<pre class="exdent">   (minimal support in HTML)
 @w{}CSS: none
spaces replaced by ’&nbsp;’ elements
 @centerCSS: ’center’ class
<div class="center">...</div>
 @indent and @noindentCSS: none   (not supported in HTML)
 @allowcodebreaksCSS: none   (not supported in HTML)
 
 ♦♦♦ Lists ♦♦♦
 @itemize<ul>...</ul>
’no-bullet’ class
’disc-bullet’ class
’circle-bullet’ class
’square-bullet’ class
’custom-bullet’ class
see Itemized Lists
 @enumerate<ol>...</ol>
’enum-decimal’ class
’enum-decimal-zero’ class
’enum-lower-alpha’ class
’enum-upper-alpha’ class
’enum-lower-roman’ class
’enum-upper-roman’ class
’enum-lower-greek’ class
’enum-upper-greek’ class
’enum-cjk-decimal’ class
’enum-katakana’ class
’enum-hebrew’ class
’enum-arabic-indic’ class
’enum-custom’ class
see Enumeration Lists
 
 ♦♦♦ Tables ♦♦♦
 @multitable<table> tag, plus <thead>, <th>,
<tr>, <td>, ’table.bordered’ class
and its subclasses
see Table and Multitable
 @table<dl> tag, plus <dl>, <dt>, <dd>
 
 ♦♦♦ Font Modifiers ♦♦♦
 @sc (smallcaps)<small> tagsee Font Modification
 @emph (emphasis)<em> tag
 @strong<strong> tag
 @b (bold)<b> tag
 @i (italic)<i> tag
 @r (roman)’roman’ class
 @t (typewriter)<tt> tag (redefined)
 @sansserif’sansserif’ class
 @slanted<i> tag
 
 ♦♦♦ Object Indicators ♦♦♦
 @code<code> tagsee Object Indicators
 @samp<samp> tag
 @var<var> tag
 @cite<cite> tag
 @abbr<abbr> tag
 @kbd<kbd> tag,
’kbd’ class
 @env<code> tag
 @file<samp> tag
 @command<code> tag
 @option<samp> tag
 @dfn<em> tag
 @verb<tt> tag
 @key<kbd> tag,
’key’ class
 @acronyn<acronym> tag (redefined)
 @indicateurl<p> tag
 @url<a href="xxxx">
 @email<a href="mailto:xxxx">
 
 ♦♦♦ Headings ♦♦♦
 Document Title<h1> tagsee Basic Tests
 Chapter Titles<h2> tag
 @section<h3> tag
 @heading<h3> tag
 @subsection<h4> tag
 @subheading<h4> tag
 @subsubsection’h4.subsubsection’ class
 @subsubheading’h4.subsubheading’ class
 Level-5 Heading<h5> tag - defined in HTML, but not used
by texi-to-HTML converter
 Level-6 Heading<h6> tag - defined in HTML, but not used
by texi-to-HTML converter
 
 ♦♦♦ Miscellaneous ♦♦♦
Table of Contents’contents’ class
’toc-numbered-mark’ class
see Info TOC and Index
 Texinfo Menus’mini-toc’ class plussee InfoMenu Structure
 Index’cp-entries-printindex’ class,
’jumpto’ class
see Index Notes
 Paragraph Text<p> tag (redefined)
Note that each block
environment defines
it own <p> tag.
see Basic Tests


Normally, it is not necessary to worry about the exact HTML/CSS construct being generated for a given sequence of source commands because the post-processor is designed to handle it transparently; however, if a problem arises, then the table above will help you to find the offending sequence.

Please note that this list is not exhaustive. Many Texinfo commands which have little or no effect on the HTML output are not listed. However, we have documented all the Texinfo constructs which the texi-to-HTML converter references and/or which have a significant effect on documents in HTML format.

Some Texinfo HTML-only commands, variables and build options are not considered here. Instead we rely on the defaults for these modifiers in order to simplify testing. Some examples of these are: 'DOCTYPE', 'BODYTEXT', 'TEXI2HTML', 'simple_menu', the variables listed in Texinfo Chapter 22.5.3, ‘HTML Customization Variables’, and others. If you find that 'idpp' has trouble handling documents that uses these modifiers, please send us a note describing the problem (see Technical Support).




Applying the CSS Definitions

Applying the CSS definitions in 'infodoc-styles.css' to your HTML document can be done using the 'idpp' Infodoc Post Processor, or may be done by manually editing your HTML document. We recommend using 'idpp' to style your documents. Not only will it save time and effort, it will help to avoid introducing markup errors. Any additional manual processing may then be done after the CSS styles have been applied. For instructions on both automatic and manual application of CSS style, please refer to the chapter on post-processing your HTML documentation:
See HTML Post-processing.

Painless CSS Style

If you are having issues converting your own ‘texi’ source documents to an acceptable HTML format, or if you are having to perform significant post-processing on the HTML to get the desired appearance, then we believe that the CSS styles defined in 'infodoc-styles.css' may ease your burden.

It is hoped that the application of these styles:

a) will create better consistency across object blocks b) will provide firmer control over the generated HTML output, and c) will give you the flexibility customize the output for your needs.



Adjusting Style Definitions

The CSS style definition file 'infodoc-styles.css' contains a large number of style definitions for the various constructs that may be generated by the Texinfo texi-to-HTML converter. Please feel free to experiment with these definitions to find out what CSS can do for you.

Important Note: Software Samwise says: Always make a backup copy of the definition file in case you decide to undo your changes.

Whole-document Definitions

The CSS definitions which apply to the whole document are located near the top of the file inside the definition of the <body> tag.

  • Background Color: ’background-color: #66FF99;’
    The background color is a hexadecimal number which contains two digits (256 possibilities each) for Red, Green and Blue respectively. Any Red/Green/Blue combination may be specified, but in general it is best to use one of the "standard" combinations for consistency across browsers. For a list of the "standard" colors, please visit the author’s web-color description page: http://www.softwaresam.us/docs/html_doc/web-safe_color.html

    or visit: http://w3.org/

  • Text Color: ’color: #000000;’
    The foreground (text) color is also a hexadecimal number, and is initially set to #000000; i.e. Black. Again, any Red/Green/Blue combination may be specified, but should contrast clearly with the specified background color.
  • Base Font Size: ’font-size: 18px;’
    The base font size indicates the size of the text rendered within a set of plain paragraph <p> ... </p> tags. The size of the text in all other constructs is calculated as a percentage of the base font. What this means is that if you change the base ’font-size’, then the size of all text in the document will be calculated from this specified size.

    Note that changing the ’font-size’ value in any of the other definitions is not recommended. In the words of Chandler Bing,
    "Can open... worms, everywhere!"

  • Font Family: ’font-family: sans-serif;’
    The ’font-family’ specification takes an arbitrary number of font-family names, allowing the browser to use the leftmost name if available. If the leftmost name is not available to the browser, then the next name to the right is used, and so on. Good programming style dictates that the last (rightmost) name be ’sans-serif’ which is available to all browsers. Example:
    font-family: "Noto Sans", Helvetica, "Lucida Grande", sans-serif;
  • Container Dimensions:
    The ’.infodoc_container’ class defines the horizontal dimensions for the active area of the browser window. This is the area within which data may be written. This dimension is important because text that ’flows’ will wrap to the next line at the edge of the active space.

    The current dimensions are specified by three (3) elements within the ’.infodoc_container’ class:

    max-width: 1170px; padding-right: 15px; padding-left: 15px;

    These specify the width of the container (in display pixels), and the padding (unused space) inside the right and left margins of the container. The container is defined to fit quite comfortably within a 1280-pixel screen width. Because your Texinfo source document is probably defined to fit within a width of 80 characters or less, 1280 pixels is much wider than the console window in which the ’info-format’ document is displayed. Display resolution, base font size, kerning and other factors all contribute to selection of the container width.

    Optionally, a border around the container may be enabled and styled. This is controlled by the following style element which is commented out by default:
           border: 1px solid blue;



Adjusting Individual Styles

If a particular block or other construct in the HTML document is not being displayed as you would like, then you can adjust the definition associated with its HTML tag or CSS class definition. These modifications will require at least a basic understanding of CSS syntax and the style elements and values available for the target construct.

To match the visual display to its styling, open the HTML document for editing and search for the displayed text. Note the environment(s) within which the text lives (paragraph, div, class, span, etc.), then find its definition in the 'infodoc-styles.css' definition file.

Example: The HTML mark-up for THIS paragraph looks like the following: <div class="example"><pre class="example"> ... </pre></div> To modify the definition for this paragraph, open 'infodoc-styles.css' and go to the definition for the '.example' class, which will look something like this: .example { font-family: monospace; font-size: inherit; font-style: inherit; font-weight: inherit; color: inherit; white-space: pre; margin-left: 3.2em; } .example pre { font-family: inherit; font-size: inherit; font-style: inherit; font-weight: inherit; color: inherit; white-space: inherit; margin-left: 0; }

For a smooth introduction to CSS please visit the Mozilla Developer Network which is maintained by the Mozilla Project:
https://developer.mozilla.org/en-US/docs/Web/CSS/Reference


Use care when adjusting individual style definitions because inheritance of style elements is an important issue in HTML documents generated from Texinfo source data. Any changes you make may affect more than just the bit of text you’re viewing at the moment.

In summary, have fun! The worst you can do is to bend an electron too far and cause worldwide nuclear annihilation. :-)




HTML Post-processing

Automatic post-processing can be performed on your HTML documents using the 'idpp' Infodoc Post Processor utility. For the tweakers in the crowd, the steps performed by 'idpp' may also be performed manually




Infodoc Post-processor

Automatically perform post-processing on HTML documents generated from Texinfo source. We hope that this simple utility will help you to create professionally styled HTML documentation for your project. Enjoy!
— Software Sam




Post-processor Overview

The Infodoc Post-processor automatically applies CSS style to the raw HTML generated by the ’makeinfo’ utility. If you write HTML documentation using Texinfo, but don’t have time to learn HTML markup and CSS style, then this post-processing utility is for you.


What the Post-processor Does

This section describes the modifications made to the source document if no process-modification switches are specified on the command line.
See Invoking idpp for information on command-line switches.

For a more detailed explanation of the changes made, please refer to the chapter on making manual modifications to the source document. The automatic modifications closely mirror the descriptions in
see Manual Post-processing.

  • Update the <!DOCTYPE> declaration. If no DOCTYPE declaration found, insert one AND replace the <html ...> tag with a plain <html> tag.
  • Discard everything inside the <head>...</head> block except the <title> and any HTML comments. Note that makeinfo includes (within a comment) a small group of in-line style elements. These entries only clutter the area and are therefore deleted during post-processing.
    For more information on controlling the contents of the <head>...</head> section, please see Texinfo Build Options.
  • At the top of the <head> block, insert a link to the external CSS definition file. This is 'infodoc-styles.css' unless otherwise specified.
  • Replace the complex <body ...> tag with a plain <body> tag.
  • Just below the <body> tag, insert the <div> tag which establishes the container class.
  • Modify the "Up: (dir)" target link in the Main Menu page so that if the user clicks it, it won’t generate a "target-not-found" message.
    Note that by default, makeinfo now omits the "Up: (dir)" sequence. A Texinfo build option is available to include it if desired.
  • For enumeration lists, “<ol>”, optionally modify or expand the the enumeration type and initial value for the list.
  • For itemized (bullet) lists, optionally specify an alternate bullet characterand adjust the horizontal offset of the bullet characters.
  • Eliminate the unnecessary (and annoying) extra whitespace above all instances of the following block types:
    'format' class '@format' command 'smallformat' class '@smallformat' command 'display' class '@display' command 'smalldisplay' class '@smalldisplay' command 'example' class '@example' command 'smallexample' class '@smallexample' command 'lisp' class '@lisp' command 'smalllisp' class '@smalllisp' command

    Note that under rare circumstances we may not be able to parse the block header, so in that case, we just leave it unmodified.

  • Macros defined for adjusting the font size within text blocks.
    The Texinfo language includes built-in support for decreasing the font size of text within all block types (except the @verbatim block type).
    @smallindentedblock @smallquotation @smallformat @smalldisplay @smallexample @smalllisp

    'idpp' supports these commands and the file “infodoc-styles.css” provides robust style classes for each block type.

    'idpp' also adds support for “large” versions of these commands implemented as Texinfo macros, as well as macros supporting small and large versions of the @verbatim block command.
    Please see Macros In Infodoc for more information on macros.

  • If a <blockquote> ... </blockquote> (’@quotation’ command) block is found, modify it to access the 'quotation' class:
    <blockquote> becomes <blockquote class="quotation'>
  • If a <blockquote>...</blockquote> (’@quotation’ command) block or <blockquote class="smallquotation"> ... </blockquote> (’@smallquotation command) block is found, AND if the line following the block contains a sequence indicating that an ’@author’ sub-command was used, then realign the author’s name.
  • For ’cartouche’ objects (bordered paragraphs), remove the forced border styling so the ’cartouche’ class can control the style of the object. Optionally apply a CSS flowing-text style and/or a smaller or larger font size.
  • If the GNU General Public License and/or the GNU Free Documentation License is included in the document, then 'idpp' silently corrects the enumeration lists contained in these sub-documents so the numbering will be consistent with the source data. (Never give a lawyer cause for complaint.)
  • In the Index, point the two “Jump to:” tables to the “jumpto” class.
  • Just above the </body> tag, terminate the container class.

What the Post-processor Assumes

This is a very simple application. We have tried to avoid the usual sources of embarrassment that arise from software developers making assumptions about what users may do with the application; however, you should be aware of the assumptions we have made about the HTML source documents:

  1. First, 'idpp' verifies the contents of 'infodoc-styles.css', the CSS definition file by checking the copyright message and the version number. Beyond that, 'idpp' relies on the definitions in 'infodoc-styles.css' to be intact. If you have modified these definitions, 'idpp' has no way of knowing about it, so use care.
  2. It is assumed that the source document is UTF-8 encoded.
  3. It is assumed that the terminal environment has indicated the correct (UTF-8 aware) locale (language-specific processing) for the data being processed.
    Note: To determine the locale used by your terminal, enter the ’locale’ command.
  4. It is assumed that the lines of the source document are of reasonable length, Any more than approximately 3000 bytes of UTF-8 data per line might be considered unreasonable.
  5. Source document lines may end with either a linefeed or a CRLF (0x0D, 0x0A) sequence; however, lines of target documents will be terminated with a linefeed (0x0A) only.
  6. Lists embedded within block constructs and Blocks embedded within other blocks.

    Lists (@itemize and @enumerate) created inside an @indentedblock environment (including its small/large versions) are accurately identified and processed. Example: see Lists Inside Blocks.

    However, it is recommended that lists should not be embedded inside preformatted blocks (@display, @format, @example, @lisp, and their small/large equivalents). The HTML markup generated by the texi-to-HTML converter in these blocks can become quite tortured and difficult to parse. 'idpp' does its best to correct this garbage, but the results are still not pretty. It is STRONGLY RECOMMENDED that lists not be placed inside pre-formatted data blocks.

    Also, Texinfo allows for blocks nested within blocks to the limit of the margins. Data constructs inside an @indentedblock will be handled smoothly. Beyond that, however, it is recommended that nested blocks be used cautiously if the document is to be converted to HTML.
    See Blocks Inside Blocks.

  7. It is assumed that there may be hand-crafted HTML markup inside a @html ... @end html sequence in your ’.texi’ source document; however, there is no way for 'idpp' to know whether it is embedded or auto-generated data. Please refer to the HTML markup embedded directly into the ‘.texi’ source of this document. Although for test purposes, much of this embedded HTML is intentionally similar to the auto-generated code, 'idpp' passes all of it through unmodified. For example, we can say with some confidence that your lovingly-crafted HTML will never look as nasty as this:
    (see embedded HTML example).

    Still, it is possible that your embedded HTML may cause the output-line counter to be off a bit or in rare cases you may see that 'idpp' has attempted to reformat your embedded HTML code, so you should visually confirm any HTML which you have embedded directly into the texi source.

  8. It is assumed that the user is not a Bozo.
    1. In other words, it is expected that the source document was actually generated by the Texinfo ’makeinfo’ utility using the ’−−html’ switch, and optionally, the ’−−no-split’ switch.
      Example:
      makeinfo --html --no-split yourdoc.texi
      

      The formatting of HTML documents created by the texi-to-HTML converter is very specific. Post-processing an HTML document created by other means will yield wildly unpredictable results.

    2. Any manual modifications to the document should be performed AFTER the post-processor has been run.
    3. It is recommended that all post-processing of the document be done in a single pass. Although 'idpp' allows for multiple passes on a source document under most circumstances, the results may be disappointing.
      - If you accidentally run 'idpp' a second time on the same document using automatic processing (invoked with no interactive options), 'idpp' SHOULD create an identical copy of the document, but this cannot be guaranteed. - If 'idpp' is invoked the second time with interactive options, it is likely that the sequence of user prompts will be different from those of the first pass. - If manual responses are provided for the processing, the results can of course be immediately verified. - If however, a response file is used to provide responses (see idpp --response option), the response tokens will likely become out-of-synch, producing undesirable results. For this reason, if 'idpp' detects that a response file is provided for a second pass on a previously-processed HTML file, processing will continue, but modification of the file will be disabled to prevent unintended consequences. (see idpp --no_mods option)

      Please see idpp -V option which instructs 'idpp' to verify whether the source file has been previouly processed.




Invoking idpp

This chapter describes the processing options available as command-line switches.

Please refer also to the next chapter, which describes the logic behind the 'idpp' user interface. See Interface Logic.


idpp -i option Interactive Mode
idpp -a option All files
idpp -d option Specify target directory
idpp -f option Specify CSS file
idpp -c option Table of Contents (format as list)
idpp -r option Table of Contents (remove)
idpp -v option Verbose diagnostics
idpp -V option Verify unprocessed file
idpp -h option Command-line help (short form)
idpp --bullet_list option  — Interactive bullet-list formatting
idpp --enum_list option    — Interactive enumeration-list formatting
idpp --table_border option Interactive table formatting
idpp --block_font option   — Interactive block font size selection
idpp --cartouche option    — Text formatting option for Cartouche
idpp --fixed_list option   — Assign CSS class to all bullet lists
idpp --up_target option    — Specify link target from top of document
idpp --my_metadata option  — Insert custom metadata into HTML header
idpp --response option     — Specify an interactive-response file
idpp --no_mods option      — Scan only, no document modifications
idpp --no_special option   — Disable special-case processing
idpp --no_html5 option     — Do not update obsolete HTML constructs
idpp --no_meta option      — Do not discard valid metadata
idpp --no_links option     — Do not discard auto-generated links
idpp --no_body option      — Do not modify the <body> tag
idpp --no_uplink option    — Do not modify top-node up-link
idpp --no_block option     — Do not modify pre-formatted blocks
idpp --no_author option    — Do not adjust quotation “author”
idpp --no_contain option   — Do not create CSS container for document
idpp --version option      — Display version and copyright info
idpp --help option         — Display command-line help
idpp --scan option         — Debugging command
idpp --book option         — Debugging command
idpp --step option         — Debugging command
idpp --skip option         — Debugging command

'idpp' is invoked as a standard GNU/Linux console utility with all user interaction occuring through the console I/O streams ‘wcout’ and ‘wcin’ (stdin/stdout in C-language terms).

Although 'idpp' may be launched in fully-automatic processing mode, the application includes several options for specifying the desired level of direct interaction, including specific options for lists, formatted-data blocks, tables and more.

Please see below for a detailed description of the available processing options.


Processing Options

Usage : idpp [OPTIONS][HTML_FILENAMES]

Example: idpp −cv −−enum_list=specify home.htm   



Specifying Source Documents

Specify between one (1) and 24 HTML source documents to be processed.

Specify the documents by their filename only, not by a path/filename. The path is assumed to be the current working directory (or the specified target directory: '-d' option).

Example:
idpp -ic MyNovel.html mnChapter01.html mnChapter02.html mnChapter03.html

To specify all HTML source files in the directory, use the '-a' option.

Before processing begins, all specified documents are validated as HTML markup. Please see Interface Logic for details on source-document validation. If any document fails the validation process, then no documents will be processed.

Documents will be processed in the order in which they are specified. Please also see the -a option below.



Invocation Options

–i Start the application in Interactive Mode.

Launch the application in full interactive mode. (automatic processing is the default)

This option is a shorthand for a combination of the following options:

  --bullet_list=specify
  --enum_list=specify
  --table_border=specify
  --block_font=specify
  --cartouche=specify

For each of the above object types, 'idpp' will display a short description of the available formatting options and will prompt for the desired option.
Please refer to these individual options for additional details.

Example: idpp -i mypage.html

–a Process all source files in target directory.

Process everything in the target directory that look like HTML.

Scans the current working directory (or specified target directory) for HTML documents, adding each valid HTML document found to the list of files to be processed, up to a maximum of 24 files.

Example: idpp -a

In order to avoid filename duplication, any source-document filenames specified directly on the command line will be discarded before the directory scan begins.

Files are initially identified by their filename extensions. The recognized filename extensions are:
'html' 'htm' 'shtml' 'shtm' 'xhtml'

Each identified file is then validated according to the criteria described above (see idpp source docs).


–d Specify an alternate source directory.

By default, all source files specified for processing as well as the CSS definition reference file are assumed to be located in the current working directory (CWD).

Use this option to specify a different directory in which to look for the source files and the CSS definition file.

All processed HTML target files will also be written to the specified directory.

Examples: idpp -d=public_html home_en.html home_sp.html home_cn.html idpp -d ../../src_dir idpp -d=/home/Sam/Documents/htm_dir

–f Specify an alternate CSS definition file.

Specify the filename of the CSS definition file to use for applying style to the HTML document(s).

By default, 'idpp' looks for the file 'infodoc-styles.css' in the current working directory (or the working directory specified by the ‘−d’ option). If you have a customized CSS definition file with a different name or location, you can specify it here. Please specify either a filename ONLY, or a relative path/filename specification with no aliases.

Because the path/filename you specify with this option is written directly into the HTML document, the file must be in the same relative position for both post-processing AND for live rendering by the browser.

Note that an absolute path specification MIGHT work, but experience shows that absolute paths are rather fragile in this context, especially when moving the document from your local development environment to a hosted server.

Examples: idpp -f my-styles.css mypage.html idpp -f='../resources/my-styles.css' mypage.html idpp -f=my-styles.css mypage.html

–c Process the Table of Contents as a list.

Process the document’s Table of Contents as a multi-level unordered list. This option converts the Table of Contents from a simple list of chapter links into a multi-level bulleted list.

(Our art consultant says it looks better this way, but of course this a subjective decision.)

Note that this option will apply only to a Table of Contents which is located before all chapter nodes and sectioning.

Note also that the '-c' option is incompatible with the '-r' option, below. If both are specified, then the '-r' option takes precedence.

Example: idpp -c mypage.html

By default, the Table of Contents is unmodified. For more information on how the Table of Contents is constructed, please
see Info TOC and Index.


–r Remove the Table of Contents from the document.

Because Texinfo documents are based on a system of chapter headers and menus, you may find that having a Table of Contents seems rather useless. If so, you can use this option to remove the entire Table of Contents without breaking the intra-document links.

Note that this option will apply only to a Table of Contents which is located before all chapter nodes and sectioning.
See also the Texinfo '@contents' command.

Example: idpp -r mypage.html

By default, the Table of Contents is unmodified. For more information on how the Table of Contents is constructed, please see Info TOC and Index.


–v Verbose output, report details of each operation.

Verbose output is useful if idpp is encountering a parsing error or other problem because it will show the approximate line number at which the error occurred. And if you have OCD, verbose output will give you comfort.

Example: idpp -v mypage.html

–V Verify that source file was not previously processed.

Scan the first source file in the list of files to be processed to determine whether it has already received post-processing. Second and subsequent source files will not be scanned for previous post-processing.

If the file has been previously processed, the application will ask for verification that you want to process it again. If you answer in the affirmative, then all source files will be processed, without regard to whether they have been previously processed. If you answer in the negative, the application will exit immediately without processing any files.

Example: idpp -V mypage.html

By default, the application will perform post-processing on all specified HTML source files, regardless of any previous post-processing.

In general, an HTML source file should receive post-processing only once.
Please refer to the discussion of post-processing assumptions for additional information.


–h Command-line Help (short form).

Display a list of available command-line options and brief examples.
See idpp --help option for more information.

Example: idpp -h

––bullet_list Interactive bullet-list formatting.

Specify the type of formatting that should be applied to bullet lists in the document.

Specify this option with one of three possible arguments: auto Automatic formatting of all bullet lists. (default) none Do not aly formatting to bullet lists. specify For each bullet list in the source document, the application will ask which kind of formatting should be applied to that list. Example: idpp −−bullet_list=specify mypage.html

By default automatic formatting is applied to all bullet lists.

Note: Bullet lists are specified in the ‘.texi’ source using the "@itemize" command.

Almost any bullet character may be specified in the ‘.texi’ source, and when the document is built for the ‘info’ reader, the list will be formatted in an acceptable way. However, when the docment is built as HTML markup, only three(3) types of bullet lists are directly supported by web browser applications: ’disc’, ’circle’ and ’square’.

  • Disc bullets
  • Circle bullets
  • Square bullets

Of these, only the disc bullet is fully supported in the ‘.texi’ source (@itemize @bullet), and the circle bullet is partially supported through (@itemize @textdegree).

'idpp' provides formatting for whatever bullet character was specified in the ‘.texi’ source, and interactive post-processing of bullet lists expands user control over the available options.
Please see Interactive Processing for details.

If an invalid response is entered, the application will continue to prompt for a correct response, unless you enter the abort command 'quit' (or until you hit the Panic Button (CTRL+C)).

If creating a response file, (see Response File), the default formatting value may be specified by the literal string, "default_token". The “default” value is determined by the bullet type declared in the source HTML data; or if the type cannot be determined directly, then the HTML default (disc) is encoded in the output.

Please see Itemized Lists for a detailed discussion of bullet lists.


––enum_list Interactive enumeration-list formatting.

Specify the type of formatting that should be applied to enumeration lists in the document.

Specify this option with one of three possible arguments: auto Automatic formatting of all enumeration lists. (default) none Do not apply formatting to enumeration lists. specify For each enumeration list in the source document, the application will ask which kind of formatting should be applied to that list. Example: idpp −−enum_list=none mypage.html

By default automatic formatting is applied to all enumeration lists.
The "--enum_list" option is implemented to provide interactive control over list processing for documents that require it.

Note: Enumeration lists are specified in the ‘.texi’ source using the "@enumerate" command.

Three(3) type of enumeration lists are directly supported within the ‘.texi’ source:

Decimal Numeric:         1 ... 999 ... 1000 .... Lower-case Alphabetic:   a ... z ... aa ... zz ... aaa .... Upper-case Alphabetic:   A ... Z ... AA ... ZZ ... AAA ....

In addition to the type of enumeration, the ‘.texi’ source can also specify the value of the initial list item.

Please see Enumeration Lists for a discussion of makeinfo support for enumeration lists.

It must be noted that the HTML5/CSS style specification has much broader support for enumeration lists in three categories:

 HTML5 CSS3 Function
 type list-style-type enumeration type (approx. 50 types)
 start n/a value of first list item
 reverse n/a (boolean) list items in ascending or descending order

Although it is not practical to provide the full range of functionality available under HTML5/CSS3, 'idpp' provides a robust subset of options. Each of these options is associated with a CSS class definition in 'infodoc-styles.css' which provides the necessary formatting.
Please see Interactive Processing for a description of the available interactive processing options.

Automatic processing of enumeration lists is also conditioned by the idpp --no_special option, below.

Please see Enumeration Lists for a detailed discussion of ordered lists.


––table_border Interactive formatting of tables.

Specify whether tables will have borders.

Specify the option with one of the following arguments:

  • auto — Draw all tables in the documents with borders. (default)
  • none — Draw all tables in the documents without borders.
  • specify — For each table in the source document, the application will ask whether the table should be constructed with a border and grid.
Example: idpp −−table_border=auto mypage.html

In hand-crafted HTML documents, table objects are usually constructed with borders, and other style elements. However, an HTML-format table generated from a Texinfo source document is rather plain and featureless at best.
To beautify these tables, 'idpp' draws all tables with a border-and-grid by default.

The following examples are simple tables created using the Texinfo @multitable command. In the HTML-format document, 'infodoc-styles.css' (with CSS style applied), the first instance is drawn without a border (<table class="borderless">), and the second instance is drawn with a border (<table class="bordered">).

HEADING AHEADING BHEADING C
row 1, column ’a’row 1, column ’b’row 1, column ’c’
row 2, column ’a’row 2, column ’b’row 2, column ’c’
row 3, column ’a’row 3, column ’b’row 3, column ’c’

HEADING AHEADING BHEADING C
row 1-a, borderedrow 1-b, borderedrow 1-c, bordered
row 2-a, borderedrow 2-b, borderedrow 2-c, bordered
row 3-a, borderedrow 3-b, borderedrow 3-c, bordered

Note: Tables are specified in the ‘.texi’ source using the "@multitable" command.
Please see Multitable Command for additional information on multitable objects.

See interactive multitable processing for a description of interactive post-processing.


––block_font Interactive font-size selection for text blocks.

Specify the font size for each type of block text defined in the Texinfo source.

Specify this option with one of the following arguments:

  • auto — Block types inherit the font size from the parent container. (default)
  • specify — For each type of text block in the, document, the application will ask whether the block should be drawn with a smaller, larger, or standard font size.
Example: idpp −−block_font=specify mypage.html

The following types of formatted text blocks are defined within Texinfo source documents. @indentedblock @quotation @format @display @lisp @example @verbatim

In previous versions of the texi-2-HTML converter, (prior to v:6.6_2019_02_10), six of the seven block types supported the “small...” versions of the block type. For example “@smallquotation”. The small versions of these block types had all the same characteristics of the standard versions except that the font size was smaller. The “small...” option was still available for Tex and other output formats. Beginning with version 7.0 of the texi-2-HTML converter, support for these commands has been restored.

We have implemented the --block_font option in 'idpp' to compensate for this loss of functionality. Indeed, the Infodoc package offers CSS style and Texinfo macros to support both a “small...” and a “large...” post-processing option for all the above types of text blocks.
Please see Macros In Infodoc to see how these macros are constructed.

See interactive block-text processing for a description of interactive post-processing.


––cartouche Specify text formatting option.

The French word “cartouche” refers to bordered writing on an ancient Egyptian scroll or engraved block indicating the name of a pharaoh. While this is a rather too-fancy way of describing text surrounded by a border, it’s fun, and shows that at least a few tech nerds also have a classical education.

The Texinfo “@cartouche” command defines a paragraph surrounded by a border. Although the border is invisible in the 'info' document (but see our Texinfo macros), it is rendered attractively in HTML as shown in this example.

There once was a man from Nantucket, Who kept all his cash in a bucket. But his daughter, named Nan, Ran away with a man, And as for the bucket, Nantucket. — Princeton Tiger, 1902

The text within the object is pre-formatted by default; however, for some types of data,we have found it useful to allow the text to “flow”. This option provides control over selection of the formatting style.

Specify the option with one of the following arguments:

  • auto — Apply the default pre-formatted text style to each object.
    By default, text within a cartouche is treated as pre-formatted text; that is, all data remains in its original position.
  • flow — Apply flowing-text formatting to each object.
    Existing line breaks are ignored, and text is allowed to flow to the full width of the parent container.
  • specify — For each cartouche object, the application will ask for the formatting options to be applied.
Examples: idpp −−cartouche=flow mypage.html idpp −−cartouche=specify mypage.html

Cartouche with flowing text


There was a young lady of Wight, Who traveled much faster than light. She set out one day In a relative way And came back the previous night.

Please see Cartouche Command for a full description of the cartouche object.

Refer to interactive cartouche processing for a discussion of interactive post-processing.

Technical Note: In earlier releases of 'idpp', the '--no_cartouche' option handled cartouche formatting; however, that option is now deprecated in favor of the '--cartouche' option which is more flexible.



––fixed_list Do not allow browsers to modify bullet lists.

For all bullet lists which do not specify a CSS class, assign the default (disc) class.

Example: idpp −−fixed_list mypage.html

Web browsers will automatically demote bullet lists which are embedded within other lists unless the type of list is explicity specified.

The browser’s rendering engine will determine that the following is a multi-level itemized list (<ul> lists with no formatting class specified), and will automagically convert the list to level-down bullets:

disc bullets become circle bullets circle bullets become square bullets square bullets remain square bullets
  • top-level item
    • second-level item
      • third-level item
        • Fourth-level item
        • Fourth-level item
      • third-level item
    • second-level item
  • top-level item

To prevent automatic reformatting of nested lists, use the "--fixed_list" option to automatically assign a class definition to any list which does not have one, or by using the idpp --bullet_list option to interactively specify the bullet class for each list.

Technical Note: As of makeinfo version 7+, all bullet lists are assigned a CSS class by the texi-2-HTML engine, so this option will have limited usefulness and may be deleted from future versions of 'idpp'.
To allow the browser to automatically configure nested bullet lists, please see Unstyled Bullet Lists for a discussion of the @CIRCLESLASH macro.


––up_target Specify parent document path.

Use this option to specify the path to the parent document represented by the top node’s "Up" hyperlink. This will usually be a relative path which steps up one level in the document tree.

The displayed text representing the hyperlink is also modified. By default, the displayed text will be set to ’(top)’; however, you may optionally specify the text which will be displayed.

To specify the display text, append the new display text to your argument string separated by a comma (’,’) as shown in the example.

Example (default display text): idpp −−up_target='../parent_node.htm' yields: ... Up: <a href="../parent_node.htm" accesskey="u" rel="up">(top)</a>... Example (specify display text): idpp −−up_target='../parent_node.htm,(mama)' yields: ... Up: <a href="../parent_node.htm" accesskey="u" rel="up">(mama)</a>...

Due to changes in the makeinfo document generator, the “up_target” syntax now defaults to a link pointing at the top of the current document. The default texi2any behavior may be modified by using one of the Texinfo command-line options: TOP_NODE_UP_URL, TOP_FILE or TOP_NODE_FILE_TARGET. (Refer to the documentation: info texinfo -n ’HTML Customization Variables’) For these reasons, the --up_target option is no longer required, and if specified, will be ignored. This option may be discontinued in a future 'idpp' release.


––my_metadata Insert custom metadata elements.

The texi-to-HTML converter inserts some (rather useless) metadata elements, links and other data into the '<head>...</head>' block. By default, 'idpp' discards all this questionable data (but see the '--no_meta' and '--no_links' options below).

Use this option to insert meaningful metadata elements, comments or other data into your document. The contents of the specified file will be copied into the document’s ’<head>’ block, just above the ’</head>’ tag.

Please note that this option is roughly equivalent to the Texinfo ’EXTRA_HEAD’ customization variable, but is much easier to use. Please see Texinfo HTML Customization Variables.

Specify the input file as a filename (current directory), OR as a relative or absolute path/filename specification.

Examples: idpp −−my_metadata=metadata.txt mypage.html idpp −−my_metadata='../../extra/metadata.htm' mypage.html idpp −−my_metadata='/home/Sam/Documents/metadata.txt' mypage.html

Note that the contents of the specified file are copied to the target document without validation of any kind, so be sure it is valid HTML markup and that it behaves as intended.

It is strongly recommended that you not insert CSS style elements in this way because they will interfere with, or override the definitions in the 'infodoc-styles.css' CSS definition file. To modify the CSS definitions, edit the 'infodoc-styles.css' file directly.


––response Specify response file for interactive formatting.

When one or more of the interactive-formatting options has been specified, a response file may be specified as a substitute for direct user interaction.

Example: idpp -i −−response=postproc.txt mypage.html

Although 'idpp' provides fully-automatic processing of the source HTML files, there are circumstances when finer control over formatting is required. You may respond to application requests directly using the keyboard; however, if the HTML source file is very large or if you are rebuilding the file more than a few times, then writing a response file can save time and reduce typing errors.

The response file is a plain text file with responses to each 'idpp' prompt, one response per line. Comments may be included in the file to assist in synchronizing the responses with the 'idpp' prompts.
Please see Response File for details on writing a response file for your project.


––no_mods Do not perform document modifications.

Scan the HTML source document and report the operations that WOULD BE performed when invoking 'idpp' with the specified options. The source document is not modified, and no target file is generated.

Specifying the '--no_mods' option implies the '-v' (verbose output) option AND bypasses all interactive user prompts.

Use this option to pre-scan a document, to locate a specific object in the document, or to locate potential post-processing problems.

Examples: idpp −−no_mods testdoc.html idpp -v −−no_mods testdoc.html

––no_special No special-case list processing. (deprecated)

The 'idpp' application performs certain “special-case” operations to overcome weaknesses in the texi-2-HTML converter (makeinfo/texi2any). While these automatic repairs are generally correct and desirable, the "--no_special" option is provided to disable these special-case operations.

Example: idpp −−no_special mypage.html

The formatting that is affected includes:

  • Bullet lists that are handled incorrectly by ‘texi2any’ or that are not directly supported by HTML syntax are formatted to correspond to that of ordinary lists.

    Please see Itemized Lists for additional information on the types of formatting performed.

  • Enumeration lists are interpreted according to the criteria detailed in the idpp --enum_list option above. Disabling special processing causes these lists to be interpreted literally.

    Please see Enumeration Lists for additional information on the types of formatting performed.

  • Lists within pre-formatted text blocks
    Technically, lists should never be embedded within pre-formatted data blocks (@format, @display, etc.) because lists are naturally “flowing” data while pre-formatted data have forced line breaks. If however, a list is detected within one of these blocks, special processing is performed on the list to minimize the ugliness.

    Please see Idpp Block Processing for additional information on the types of formatting performed.


––no_html5 Do not upgrade obsolete HTML constructs.

Disable replacement of obsolete HTML v:3/v:4 constructs.

Example: idpp −−no_html5 mypage.html

The makeinfo texi-2-HTML document generator has finally stumbled into the current century by abandoning the ancient HTML3 syntax and most of the HTML4 syntax. This includes the HTML MIME type at the top of the document which now uses the standard HTML5 MIME type. (<!DOCTYPE HTML>). This means that --no_html5 is now obsolete, and if specified, will be ignored.


––no_meta Do not remove valid metadata.

By default, 'idpp' removes all of the metadata tags of the form: '<meta name=...' from the <head>...</head> section of the document.

These metadata entries are discussed in detail in the chapter:
see Post-processing Notes. Briefly, however, the default contents of these entries is rather useless, and some of the entries are invalid HTML according to modern standards.

Currently, the HTML specification allows only the metadata names "application-name", "author", "description", "generator", "keywords", (or one of the registered Metadata Extension names). See W3.org for details:
http://www.w3.org/TR/html-markup/meta.name.html

If you have generated meaningful metadata entries, then use the '--no_meta' option to preserve the intended data.

Example: idpp −−no_meta mypage.html

See the Texinfo '@documentdescription' command and the customization variable, ’EXTRA_HEAD’
(see Texinfo Invocation Options) for additional details.

Special Note: If you specify the ’makeinfo’ ’DATE_IN_HEADER’ configuration variable during the build, then the --no_meta' option will retain the resulting metadata entry in addition to the metadata entries described above.
Please see Texinfo HTML Customization Variables.

For more information, also see idpp --my_metadata option, above.


––no_links Do not delete <link> elements in <head>.

By default, 'idpp' removes all of the <link> tags from the <head>...</head> section of the document.

These <link> entries are discussed in detail in the chapter:
see Post-processing Notes.
Briefly, however, the default entries tend to be either incorrect or meaningless.

If you have generated meaningful data for these entries, then use the '--no_links' option to preserve the intended data.

Example: idpp −−no_links mypage.html

Please see Texinfo HTML Customization Variables for additional information on including/excluding <link> tags.


––no_body Do not update the <body> tag.

The '<body>' tag indicates the beginning of the user-visible part of the HTML document. By default, the texi-to-HTML converter inserts some (mostly redundant) information into this tag.
Unfortunately, these data may, and probably will interfere with the CSS style information in 'infodoc-styles.css'.

The 'idpp' post-processor discards the extra data by default, leaving only a pristine '<body>' tag.

However, if your document specifically indicates a <body> declaration (see the Texinfo ’BODYTEXT’ configuration variable), then use the '--no_body' option to preserve the intended <body ...> data. (not recommended)

Example: idpp −−no_body mypage.html

For more information, see Post-processing Notes.


––no_uplink Do not modify top node "Up" link.

Do not modify the target specified in the "Up" hyperlink at the top of the document.

Example: idpp −−no_uplink mypage.html

Due to changes in the makeinfo document generator, the “up_target” link syntax now defaults to a link pointing at the top of the current document. The default texi2any behavior may be modified by using one of the Texinfo command-line options: TOP_NODE_UP_URL, TOP_FILE or TOP_NODE_FILE_TARGET. (Refer to the documentation: info texinfo -n ’HTML Customization Variables’) For these reasons, the --no_uplink option is no longer required, and if specified, will be ignored. This option may be discontinued in a future 'idpp' release.


––no_block Do not remove extra whitespace from formatted-block objects.

The texi-to-HTML converter uses a double-layer construct when creating pre-formatted block objects. This creates an unnecessary extra blank line in the HTML output.

By default, 'idpp' removes this extra blank line by eliminating the completely unnecessary inner '<div>' construct. This adjustment applies to the following block objects: 'format', 'display', 'example', 'lisp' and their 'small...' variants.

Use the '--no_block' option to disable this automatic adjustment.

Example: idpp −−no_block mypage.html

For more information, see Other Manual Processing.


––no_author Do not adjust ‘<blockquote>’ ‘author’ field.

If you create a <blockquote> object using the Texinfo ‘@quotation’ command, the ‘@smallquotation’ command or the ‘@largequotation’ macro, then you may also have used the associated '@author' sub-command.

This combination of commands works well in info-format documents, but looks very bad indeed in HTML-format documents.

By default, 'idpp' adjusts the position, and if necessary the font size of the ’author’ field.

Use the '--no_author' option to disable this automatic adjustment.

Example: idpp −−no_author mypage.html

If no ‘@author’ sub-command was used with a quotation block, then this option has no effect.
For more information, see Quotation Commands.


––no_contain Do not insert the ‘infodoc_container’ class into document.

The 'idpp' post-processor inserts a so-called ’container class’ into the styled HTML document to define the left and right borders within which all displayed data must live. In our view, this is significantly more attractive than allowing the HTML text to wander all across the browser window.

However, if you want your data to be un-contained, you may use the '--no_contain' option to disable insertion of the 'infodoc_container' class.

Example: idpp −−no_contain mypage.html

This container is described and discussed in:
see Summary of CSS Definitions,
see Adjusting Style Definitions, and
see Basic Manual Processing.


––version Display version number and copyright notice.

This option displays the application title, the application version number, the author’s copyright notice and the GNU GPL license notice.

Note that if this option is specified, then all other options and arguments on the command line will be ignored.

If you need technical support, then make a note of the reported version number and include it with your support request.
See Technical Support.

Example: idpp --version

The following is an example of the Version message:

Infodoc Post-processor (idpp) version: 0.0.15 Copyright (C) 2014-2024 The Software Samurai License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html> This is free software: you are free to modify and/or redistribute it under the terms set out in the license. There is NO WARRANTY, to the extent permitted by law.

––help  (–h) Command-line Help.
––helpless  (–hl)

Command-line Help. Display a brief summary of command-line usage and examples.

The help text may be displayed in either of two way:
♦ ––help  Write the text directly to 'stdout', or
♦ ––helpless  Pipe the data through the system’s 'less' utility.

Note that if specified, a request for Help overrides everything else on the command line (except ’−−version’).

Examples: idpp --help idpp -h or idpp --helpless idpp -hl

If this option is specified, then no source documents will be processed.





Additional invocation options and command arguments may be added from time to time. Existing options may be redefined or removed, but only for very good reason.



Additional options are defined for application debugging only:


––scan Debugging Option.

During development of the 'idpp' application this option is used to display the line numbers of the source HTML document as it is read.

This allows the developer to identify and isolate any HTML construct which is being parsed incorrectly.

Examples: Display all source line numbers: idpp −−scan mypage.html Display source line numbers from line 1275 onward: idpp −−scan=1275 mypage.html Display source line numbers in the range 1275 to 1350: idpp −−scan=1275,1350 mypage.html
––book Debugging Option.

During development of the 'idpp' application this option is used to create a “bookend” message for each data construct in the HTML document as it is read.

This allows the developer to identify and isolate any HTML construct which is being parsed incorrectly.

Example: idpp −−book mypage.html
––step Debugging Option.

During development of the 'idpp' application this option may be used to pause processing after each token read from the response file so that the developer has time to see how each user prompt was handled.

The delay is specified in tenths of a second, with a minimum of two(2) tenths of a second and a maximum of five(5) seconds per token. The default delay is one(1) second.

When used in combination with the --scan option described above, the delay may be designated as active only within the range specified.

Example: idpp −−step mypage.html idpp −−step=15 idpp −−step=50 −−scan=250,500
––skip Debugging Option.

This option may be used during post-processing of a document to step over a specific number of user prompts to reach the area of interest in the document.

The count specifies the number of user prompts to be processed automatically, without user interaction. When the specified number of items have been handled automatically, the application shifts to full interactive mode (see idpp -i option).

The --skip option is recognized only when full-automatic processing is enabled, and when no user-response file has been specified. This means that NONE of the following options should be specified in combination with the --skip option:

-i --bullet_list --enum_list --table_border --block_font --cartouche --response Example: idpp −−skip=15 mypage.html Wrong: idpp −i −−skip=15 mypage.html idpp −−block_font −−skip=15 mypage.html idpp −−skip=15 mypage.html −−response=répondre.txt



Interface Logic

The design of human-to-computer interactional logic falls midway between engineering and philosophy. For this reason, the way an application gathers information from a user, processes that information and presents the results is seldom, if ever carefully docummented—at least not by the people who wrote it.

Instead, the user is left on his or her own to experimentally determine what the software designer was thinking when she wrote the application, and how that thinking was translated into the actual human-to-computer interface.

Trying to determine the way in which people from a wide variety of language, cultural and intellectual backgrounds "naturally" think about a task is a nearly-impossible challenge. Software designers, if we think about this issue at all, tend to see the "natural" flow of human-to-computer interaction through a very personal lens.

We have a responsibility, then, to explain how the software actually organizes the gathering, processing and reporting of information. While no interface can please everyone, we can at least inform everyone about what we have done.

Editorial: We were repeatedly told by a previous maintainer of one of the GNU packages
that they DON’T WANT TO document the way the software works, because if they do, they
will have to be constantly checking to ensure that the software behaves as documented.
However, most of our GNU community knows that knowledge is power and that detailed
knowledge is freedom. For everyone else,there’s Windoze....
— Software Sam


The 'idpp' Post-Processor Interface Logic

  1. Note that your HTML source document(s) are not modified, so you need not worry about loss or corruption of your source data during processing.

    Each source document specified for processing is renamed as a backup file, that is, a ’~’ (tilde character) is appended to the original filename, and the processed document takes on the original filename.

    Note that an existing backup file (if any) will be overwritten.

    Note also that by default backup files are not displayed by most GUI file management utilities. (This is the GUI mavens’ idea of being ’helpful’.) Backup filenames ARE however reported by the console ’ls’ command. Example: ls -l *.htm*

Example: Source document: 'mypage.html' is renamed as 'mypage.html~' Target document: is written as 'mypage.html'
  1. At least one (1) and up to a maximum of (24) source documents may be specified on the command line, (but see idpp -a option).

    IMPORTANT NOTE: Specify filenames ONLY, not a path. The path to a specified file is assumed to be the current working directory, (but see idpp -d option). Also, the specified file must be a ’Regular’ file, not a symbolic link. Symbolic links are not followed.

    Each specified file is validated as an HTML document: If the first line of the document begins with one of the following text sequences, it is considered to be an HTML document. Leading whitespace is ignored, and the test is case insensitive.
    "<!DOCTYPE html"  OR  "<HTML"

    Although this is not a definitive test, we have some confidence that any HTML document created by ’makeinfo’ can be identified in this way.

  2. Each source document specified must exist in the target directory AND it must be valid HTML code. If any file fails the validation test, then no files will be processed.
  3. If an error in processing is encountered, the last line read from the source document will be written to the target file and processing will be terminated. (It cannot be assumed, however, that the last line written to the target actually caused the error.)

    — Previously processed files will be complete.
    — The file in which the error occurred will be incomplete.
    — Any unprocessed source files will be ignored.

    Please note that the most likely cause of a processing error is if the parsing algorithm cannot identify an end-of-block token to match a previously identified start-of-block token.

  4. All processing options are optional.
  5. A request for command-line help overrides all other options except ’−−version’.
  6. A request for the application version (’−−version’) overrides all other options.
  7. Options and source document names may be specified in any order. However, mandatory or optional command arguments must immediately follow the command with which they are associated.

    Example:
    idpp -cv mypage1.htm --table_border=specify mypage2.htm -f=mystyles.css

    Note that if you accidentally specify the same option more than once, then the argument (if any) for the last option specified takes precedence; however, avoid accidents by avoiding duplication of options.

  8. Certain processing tasks are performed by default.
    See Post-processor Overview.
  9. Other tasks are performed only if the corresponding option is selected.
  10. Default processing tasks may be selectively disabled.
  11. Some options take no arguments (parameters), while other options have mandatory or optional arguments.

    Note that if a command argument contains spaces it must be enclosed in quotation marks so the the shell program will interpret it as a single item.

Example: idpp -d 'my html doc directory'
  1. There are two types of options:
    • short-form options consist of a single dash (minus sign) followed by a single character.

      Some short-form options have mandatory arguments. These arguments may be specified with or without an intervening space, OR with a connecting ’=’ (equals sign) without intervening spaces:

      The following examples are functionally identical:
      idpp -d public_html mypage.html
      idpp -dpublic_html mypage.html
      idpp -d=public_html mypage.html

      Short-form options without arguments may be combined.

      Example:
      idpp -icvV mypage.html

      The following is also acceptable:
      idpp -icvd=public_html mypage.html

    • long-form options consist of a double dash (two consecutive minus signs) immediately followed by the command.

      Some long-form options have mandatory or optional arguments. If an argument is specified, the command must be immediately followed by a ‘=’ character, which is immediately followed by the argument without intervening spaces.

      Examples:
      idpp -i --response=postproc.txt mypage.html
      idpp --up_target="../parent_node.htm,(home)" mypage.html

      For long-form options, you must specify enough of the command to uniquely identifiy it. Currently, this is (9) characters (7) characters beyond the double dash). However, when new options are added, this relaxed specification may change, so it is recommended that the entire command name be specified.

  2. Interactive Post-Processing
    By default, all post-processing is performed automatically, without direct user interaction. However, post-processing may be performed interactively by invoking 'idpp' using the idpp -i option.
    Optionally, interactive processing for one or more specific types of object may be specified, with other types of objects being processed automatically:
    Text blocks : see idpp --block_font option
    Itemized Lists : see idpp --bullet_list option
    Enumerated Lists: see idpp --enum_list option
    Multitables : see idpp --table_border option
    Cartouche : see idpp --cartouche option

    In interactive processing mode, for each configurable construct, 'idpp' will display identifying information about the construct, and a list of valid responses. The application then waits for a response from the keyboard.

    Please see Interactive Processing for more information.


  3. Response File for Interactive Options
    For processing options that require user responses, a plain-text response file may be used. The contents of this file is read as a substitute for direct user interaction.

    Example:
    idpp -cv --table_border=specify --response=postproc.txt mypage.html

    Please see Response File for suggestions and examples for constructiong a response file for your project.





Interactive Processing

Responding To the User Prompt

By default, all post-processing is performed automatically, without direct user interaction. However, post-processing may be performed interactively by invoking 'idpp' using the idpp -i option.
Optionally, interactive processing for one or more specific types of object may be specified, with other types of objects being processed automatically:
Text blocks : see idpp --block_font option
Itemized Lists : see idpp --bullet_list option
Enumerated Lists: see idpp --enum_list option
Multitables : see idpp --table_border option
Cartouche : see idpp --cartouche option

Direct User Interaction

In interactive processing mode, for each configurable construct, 'idpp' will display identifying information about the construct, and a list of valid responses. The application then waits for a response from the keyboard. Examples of prompts for each configurable object are described below.

Response Tokens

Most responses consist of a single character followed by the ENTER key; however some multi-character responses are defined. These tokens may be entered directly from the keyboard, or may be inserted into a response file.

default_token
The literal string "default_token" may be used to respond to the prompt. This token indicates that the default response will be selected from the available responses. This is useful in creating automated responses to be read from a response file: (see Response File, below).

quit
The literal string "quit" may be used to terminate interactive processing and immediately exit the application.
Note that this is a cleaner exit than hitting the panic button (CTRL_C), which would leave files and memory allocations in an indeterminate state.

If an invalid response is received, the application will prompt for a correction:
"Invalid response, your choice?: _ "
To abort interactive processing, enter the token: 'quit' followed by the ENTER key.

primary and secondary options
In addition to the tokens described above, some additional multi-character responses are recognized for special cases. These multi-character tokens are defined for circumstances where both a primary formatting option and one or more secondary formatting option(s) are available. The syntax of these sequences are specific to the target object being processed. Please see below for the responses defined for each type of object.



Formatted Text Blocks

There are 7 types of text block objects defined in the Texinfo language:
indentedblock
quotation
display
format
example
lisp
verbatim
Each of these block types has its own formatting characteristics.
Please see Block Commands for a description of each block type.

Under 'infodoc-styles.css' these block types share one formatting characteristic:
All defined block-text objects may be displayed in any of three(3) font sizes. Makeinfo directly supports some of these options, and 'idpp' post-processing provides support for the remaining options.

The example shown here is the prompt for interactive processing of the “display” text block object, which is representative of prompts for all the text block objects. The formatting option consists of specifying the relative font size used for the object in the HTML document.

___________________________________ Block: "Display" (source line:250) First Line : Take what you can! Give nothing back! Choose font size: i:inherit (std.) s:smaller (-10%) a:automatic (default) l:larger (+10%) A:All automatic your choice: _

The choices are ['i' | 's' | 'l' | 'a' | 'A'] followed by the ENTER key. 'i' specifies that the font size of the block should be inherited from the parent container. 's' specifies that the font size should be 10% smaller than the parent container. 'l' specifies that the font size should be 10% larger than the parent container. 'a' (automatic) indicates that the response should be automatically determined by the syntax of the HTML source. For more information on management of HTML syntax, please see Macros In Infodoc, below.

A response of 'A' ("All") (uppercase A), specifies that formatting for the current block object, and all subsequent block objects will be determined automatically. To put it another way, all subsequent block objects will be formatted automatically, as if the 'a' response had been received, but without further user interaction.

If an invalid response is entered, the application will continue to prompt for a correct response, unless you enter the abort command 'quit' (or until you hit the Panic Button (CTRL+C)).

If creating a response file, (see Response File), the default value is indicated by a response of 'a' (automatic) or by the special value "default_token".

Smaller/Inherited/Larger Text Blocks

These examples are for the @quotation block environment, but they are representative of the font size for each of the block environments.

"Take what you can, give nothing back!"
— Mr. Gibbs & Jack Sparrow

"Take what you can, give nothing back!"
— Mr. Gibbs & Jack Sparrow

"Take what you can, give nothing back!"
— Mr. Gibbs & Jack Sparrow




Itemized (unordered) Lists

___________________________________ Bullet List: (source line:1655) First Line Item: Download the package from the website. Auto-definition: <ul class="itemize mark-bullet"> Choose Bullet-list type: with (s)=smaller text, or (l)=larger text d:disc (⏺) a:automatic (default) c:circle (⚬) A:All automatic s:square (▪) x:no modification n:no bullet response format: BULLET_TYPE[FONT_SIZE] your choice: _

The user prompt shown above includes the following information:

  1. source line: the line number of the source file where the list begins.
  2. first line item: the text of the first line item in the list. This provides a visual reference identifying the contents of the list.
  3. auto-definition: the CSS class that the application would assign to this list during automatic post-processing.
    Please see itemized list special processing for a description of the bullet characters supported by 'idpp'.
  4. optional secondary response options:
    The relative font size may optionally be specified as either 's' (smaller) or 'l' (larger). See below for details.
  5. bullet type: select the bullet type
    The choices are ['d' | 'c' | 's' | 'n' | 'a' | 'A' | 'x'] followed by the ENTER key.
    'd' specifies a filled disc bullet
    'c' specifies a circle (hollow disc) bullet
    's' specifies a square bullet
    'n' specifies that the list will be displayed without bullet characters
    'a' (automatic) indicates that the response should be automatically determined by
    the syntax of the HTML source. For more information on management of HTML syntax,
    please see Macros In Infodoc, below.
    'x' specifies that the list will be written to the target file without modification.
    'A' ("All") (uppercase A), specifies that formatting for the current list,
    and all subsequent lists will be determined automatically.
  6. response format:
    The primary formatting option is the character corresponding to the desired bullet type from the list, described above.
    The optional secondary formatting option specifies the relative font size used to display the list, and directly follows the bullet type with no intervening space. The supported values are:
    'i' inherit the font size from the parent environment (default)
    's' smaller font – approximately 15% smaller, (0.85em)
    'l' larger font – approximately 15% larger, (1.15em)
    Example: "cs" which indicates a circle bullet and smaller font size.

    The relative font size for the list may also be specified using an embedded formatting token.See embedded formatting tokens for details.

If an invalid response is entered, the application will continue to prompt for a correct response, unless you enter the abort command 'quit' (or until you hit the Panic Button (CTRL+C)).

To enable interactive processing of itemized lists, see idpp --bullet_list option.




Enumerated Lists

Select the enumeration type for the list.
The makeinfo engine fully supports three enumeration types:
'numeric', 'lower-case alpha' and 'upper-case alpha'.
The makeinfo engine also supports specification of the starting point for the enumeration sequence.

'idpp' supports an additional subset of the HTML enumeration options, as described below.

___________________________________ Enumerated List: (source line:340) First Line Item: Select a price range Auto-definition: lower-alpha Choose Enumeration type: d:decimal D:leading-zero decimal j:CJK(informal) l:lower case alpha u:upper case alpha k:Katakana i:lower case Roman I:upper case Roman h:Hebrew g:lower case Greek G:upper case Greek e:Arabic-Indic a:automatic(default) A:All automatic x:no modification response format: TYPE[START_NUM[FONT_SIZE[DIR]]] your choice: _

The user prompt shown above includes the following information:

  1. source line: the line number of the source file where the list begins.
  2. first line item: the text of the first line item in the list. This provides a visual reference identifying the contents of the list.
  3. auto-definition: the CSS class that the application would assign to this list during automatic post-processing.
    Please see enumeration list special processing for a description of the bullet characters supported by 'idpp'.
  4. enumeration type: select the type of enumeration for the list
    The choices are
    ['d' | 'D' | 'l' | 'u' | 'i' | 'I' | 'g' | 'G' ]
    ['j' | 'k' | 'h' | 'e' | 'a' | 'x']
    followed by the ENTER key.

    'd' specifies a decimal numeric list 'D' specifies a decimal numeric list with leading zero (ex: 01, 02, etc.) 'l' specifies a lowercase alpha list 'u' specifies an uppercase alpha list 'i' specifies a list using lowercase Roman numerals 'I' specifies a list using uppercase Roman numerals 'g' specifies a list using lowercase Greek letters 'G' specifies a list using uppercase Greek letters Note that not all browsers support uppercase Greek. 'j' specifies a list using CJK, Chinese/Japanese/Korean (Han informal) numbers (一,二,三,四,五 etc.) 'k' specifies a list using Katakana “alpha” (Gojūon) letters 'h' specifies a list using Hebrew letters Note that Hebrew is an RTL (Right-To-Left) language. 'e' specifies a list using Arabic-Indic numerals Note that Arabic is an RTL (Right-To-Left) language. 'a' apply automatic formatting based the source HTML syntax. 'x' specifies that the list will be written to the target file without modification.

    A response of 'A' ("All") (uppercase A), specifies that formatting for the current list, and all subsequent lists will be determined automatically.
    Note: 'c' (custom type) is currently still supported, but has been deprecated and may be removed in a future release.

  5. Secondary Formatting Options
    1. initial sequence value
      By default each enumeration sequence begins at the top of the sequence (1, A, a, etc.) without prompting for a value. While this is the correct behavior in most cases, your source document (like this document) may contain a list that is broken into segments. Use this optional parameter to ensure that each section of your list begins at the desired point in the sequence.
      Specify the starting value by placing a comma (',') after the enumeration type followed by a positive decimal number indicating the offset; for instance, a response of "u,7" will yield an upper-case alpha list with an initial value of 'G', 'G' being the 7th character of the latin alphabet.
    2. relative font size
      The relative font size used to display the list, seperated from the sequence direction by a comma. The supported values are:
      'i' inherit the font size from the parent environment (default)
      's' smaller font – approximately 15% smaller, (0.85em)
      'l' larger font – approximately 15% larger, (1.15em)
      Example: "d,1,a,s" which indicates decimal enumeration, beginning at 1, in ascending order, and smaller font size.

      The relative font size for the list may also be specified using an embedded formatting token.See embedded formatting tokens for details.

    3. sequence direction
      The optional sequence direction defaults to “ascending” (1, 2, 3...), (A, B, C...), (i, ii, iii, iv) and so on. While there is seldom a need to list items in descending order (4, 3, 2, 1, 0), the HTML syntax allows it, and it is simple to implement, so we include it for completeness.
      Specify the sequence direction by placing a comma (',') after the starting value followed by either 'a' (ascending) or 'd' (descending).
      Example: "u,26,d" indicates upper-case alpha, beginning at the 26th letter (’Z’) and descending toward ’A’.
      Important Note: Do not allow the list to descend into negative values.

Respond to the prompt by selecting the letter corresponding to the desired enumeration type, and optionally the initial value, sequence direction (ascending/descending) and font size.

If an invalid response is entered, the application will continue to prompt for a correct response, unless you enter the abort command 'quit' (or until you hit the Panic Button (CTRL+C)).

If creating a response file, (see Response File), the default value is indicated by a response of 'd' (decimal) or by the special value "default_token".




Multitable Objects

For '@multitable' objects, two formatting options are available:

1) border The primary formatting option is whether a border should be applied to the table. 'y' render the table with a border 'n' render the table without a border By default, all multitable objects are rendered with a border in the HTML document. 2) relative font size The optional secondary formatting option is used to specify the relative font size for the text within the table: 'i' font size inherited from parent (default) 's' font size 10% smaller 'l' font size 10% larger

The example responses apply to both data entered from the keyboard and tokens read from a response file.

____________________________________________ Table found on Line:1280 First Row: Macro Name Hex Value Example Output with (s)=smaller text, or (l)=larger text b: add a border n: no border A:all response format: BORDER[FONT_SIZE] your choice: _ -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- Example Responses: b apply a border (font size inherited from parent) bi apply a border and use the font size inherited from parent bs apply a border and use a smaller font size n no border nl no border and use a larger font size A apply a border to this table and all subsequent tables

If an invalid response is entered, the application will continue to prompt for a correct response, unless you enter the abort command 'quit' (or until you hit the Panic Button (CTRL+C)).

If creating a response file, (see Response File), the default value is indicated by a response of 'y' (yes) or by the special value "default_token".

Multitable formatting options may also be specified using embedded formatting tokens which indicate the border option and relative font size without the need for interactive post-processing.
Please see embedded formatting tokens for more information.




Cartouche Objects

For '@cartouche' objects, the primary formatting option is whether the text is "pre-formatted" or "flowing".
The optional, secondary formatting option may be used to specify the relative font size for the text within the cartouche:
'i' = inherited (default), 's' = 10% smaller, 'l' = 10% larger
Examples: 'fs' or 'al'
If a secondary argument is not specified, font size is inherited from the parent environment.

____________________________________________ Cartouche found on Line:2241 First Row: Yes, but why is the rum gone? Text formatting option: with (s)=smaller text, or (l)=larger text a:automatic, fixed text format (default) f:flow text within field A:All automatic your choice: _ -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- Example Responses: a automatic (pre-formatted) text (font size inherited from parent) ai automatic (pre-formatted) text with font size inherited from parent as automatic (pre-formatted) text using a smaller font size f flowing text (font size inherited from parent) fl flowing text using a larger font size A automatic (pre-formatted) text for this object and all subsequent cartouche objects.

Note that for an individual cartouche object, pre-formatted vs. flowing text and font size may be specified using Texinfo macros.
(see Cartouche macro)

Cartouche formatting options may also be specified using embedded formatting tokens which indicate the text-flow option and relative font size without the need for interactive post-processing.
Please see embedded formatting tokens for more information.




Interaction Via a Response File

The “response file” is a plain-text file containing responses to the interactive formatting prompts displayed by 'idpp' during post-processing.

Although is is certainly acceptable to type responses directly from the keyboard, a very large document, could produce hundreds of prompts. The response file can be constructed to automatically provide responses to the promts for which you have already determined the correct response, so you can focus on queries later in the document under development.

To specify a response file to be used during post-processing, (see idpp --response option).

Response File Syntax

  • A response file consists of a a series of response tokens, one token per line.
    Note that in this context a “token” is a text string which contains no spaces.
  • Blank lines and comments in the response file will be ignored.
    A comment is identified by the '#' (hash mark) character, and all text following the '#' on that line will be ignored. The following example is excerpted from the “apply_response.txt” file included with this package.

    # Response file for post-processing of "infodoc_css.html" #-------------------------------------------------------- # Table Of Contents Page s # Copyright Message - smalldisplay a # Preamble - indentedblock # Overview - Chapter 1.0 a # Overview - quotation only-rock-n-roll # CSS Definition File - Chapter 2.0 (menu only) # Summary of CSS Definitions - Chapter 02.01 default_token # Summary of CSS - enumerate_1 b # Summary of CSS - multitable_bordered b # Summary of CSS - multitable_bordered
  • If the response file contains too few tokens, then you will need to respond manually to the remaining prompts.
  • If the end of your source document is reached, leaving some tokens in the response file unused, then the extra tokens will be ignored.
  • For convenience, a response file may optionally contain placeholder response tokens consisting of the literal string:
             “default_token
    which if read by the user input routine will cause the default response for that query to be inserted at that point in the input stream.
  • Also as a convenience during the development of a response file, an abort signal may be inserted into the file to halt processing. The abort signal consists of the literal string:
             “Quit
    Within the 'idpp' application, the abort signal has the same effect as if an HTML syntax error had been encountered. When detected, the abort signal will cause the application to immediately halt processing, and exit.
    Note that this produces a much cleaner exit than hitting the panic button (Ctrl+C).

A response file is useful if you are developing a new document and are repeatedly regenerating the HTML document. For instance, while developing this document, we regenerated the HTML output well over 500 times. For additional examples, please refer to the response file for this document, ’apply_response.txt’.

Use care in creating and maintaining response files because a change in your source document can easily cause the response file to become out-of-sequence with the interactive prompts. Re-processing a source document that has already been post-processed may also cause the responses to be out-of-sequence.

Programmer's Note:

To ensure that our response file is in synch with this source document, we have intentionally specified
that the last response will be a non-default value, for easy visual confirmation that synchronization is correct.
(Index Notes is set to a smaller block-font size.)






Build idpp from source

The 'idpp' utility is a simple console application written in C++ and using the standard ’wide’ character I/O streams ‘wcout’ and ‘wcin’.

Preliminaries

First, open a terminal window. then unpack the distribution archive file into a clean directory (see README file for details). Next, navigate to the idpp subdirectory: ’cd Infodoc/idpp’

Tools Needed

Note that building from source requires the GNU compiler 'g++' version 4.8.0 or later, with full support for the ’gnu++11’ library option. (Compiler versions as early as 4.7.3 MAY work, but this cannot be guaranteed.) 'g++' v:10.2.1 or greater is recommended.

Standard Build

A makefile is provided which by default builds a standard binary executable which references the shared libraries for the target machine. To build the standard binary, simply enter the command:
'gmake' (produces: 'idpp')

The build should complete without errors and without warnings.
We are, after all, not just animals pooping in the forest.

Optional Static Build

Optionally, the binary can be built as a stand-alone application which does not reference external libraries. Software nerds call this a ’static build’, because it uses the ’-static’ build option. See, we ain’t so dumb:-) This binary should run on any system with the same basic architecture and a compatible operating system. Enter the command:
               ’gmake static’       (produces: ’idpp_s’)

Note, however, that using this option brings into play a number of things that can bite you in the ass, so if you aren’t sure about the configuration of the potential target systems, it is more reliable to do a standard build on each individual target system. Then when the application is invoked, it will reference the shared libraries for that system.

Testing the Build

Test the results by entering the following command:
'./idpp --version'

If the title/copyright/version message is successfully displayed, then congratulations are in order, and you can copy the 'idpp' binary to a directory on your search path (usually ’/home/yourname/bin’ or ’/usr/local/bin’).

Otherwise, please check your compiler version, environment settings, library paths and the other usual suspects.

If you just can’t get a successful build, please send us a message with all the relevant information, and we will wave our magic wand at the problem. See Technical Support.




Manual Post-processing

Automatic post-processing using the 'idpp' utility is preferred for consistency, speed and ease; however, if you prefer the hands-on approach, or if you want to know the details of what 'idpp' is doing, simply follow these step-by-step instructions.

Modifying the HTML mark-up by hand is not difficult. You do not need to understand HTML or CSS in order to make these modifications.





Basic Manual Processing

  1. Copy the 'infodoc-styles.css' file to the directory where your HTML document lives and open your HTML document for editing.
    We use Bluefish(tm) or jEdit(tm), but any text editor will work.
  2. Replace the ’doctype’ declaration at the top of the file.
    This declaration is the standard way of indicating that what follows is HTML markup. The texi-to-HTML converter generates an out-of-date reference to HTML version 3 or 4 and DTD (Document Type Definition). Unless you are forced to retain compatibility with 15-year-old technology, replace the existing declaration with a simple: <!DOCTYPE html> which is the correct choice for most web documents and is the HTML5 standard.
  3. Just below the <head> tag and above <title>, insert the following two lines which will establish a link to the style sheet file.
    <meta charset="utf-8" /> <!−− Import the global stylesheet −−>
    <link rel="stylesheet" href="infodoc-styles.css" lang="en" type="text/css"/>
  4. Delete any other auto-generated metadata in the '<head>...</head>' data block: (<meta name=...>) and links (<link href=...>). These are unnecessary to the rendering of the page, so unless you have a specific reason for retaining them, get rid of them. Two possible exceptions are:
       '<meta name=\"description...>  OR <meta name=\"keywords...>'
    Although the defaults generated by the texi-to-HTML converter are rather useless, you might, if desired, modify them to be more meaningful.
  5. Delete all auto-generated HTML style definitions in the '<head>...</head>' element. These definitions are more completely and robustly defined in the CSS definition file, so these old stub definitions may interfere with our new-and-improved definitions.
  6. Replace the '<body ...>' tag with a plain '<body>' tag.
    The texi-to-HTML converter embeds several default values for background color, etc. into the <body> tag, and again, these will interfere with our new definitions.
  7. Establish the container class:
        a) Just after <body>, insert  : <div class="infodoc_container">
        b) Just above </body>, insert : </div>  <!−− infodoc_container −−>
    This restricts the left and right margins to fit comfortably within a 1280-pixel display and presents a much more pleasing visual style. For detailed information about the container class, see ’.infodoc_container’ in the 'infodoc-styles.css' definition file.

    If desired, you can disable the border around this container by commenting out the ’border: 1px solid;’ line in the container definition.

  8. The "Up" Target of your main document.
    Recent versions of makeinfo efficiently define the “up” target for the top node of the document as:
    <a href="#Top" accesskey="u" rel="up>
    where "#Top" is a cross-reference target near the document title.

    Earlier versions of makeinfo let this reference point off into space, which could be quite embarrassing (ERROR 404 territory). This should no longer be a problem.

  9. Itemized and Enumerated Lists:
    The texi-to-HTML converter (makeinfo version 7.0.3) provides much improved handling of lists compared to makeinfo v:6.x. However, because your ’.texi’ source document almost certainly uses the @itemize and/or the @enumerate commands to create lists, it is important to know the converter’s strengths and weaknesses.

    Please see Itemized Lists and Enumeration Lists, respectively, for a discussion of how lists are constructed.

    Please refer to the next chapter (Manual List Processing) which describes post-processing of lists.

  10. HTML Comments
    If HTML comments are manually inserted into the generated document, Be Absolutely Sure that none of the three reserved HTML characters are enclosed within the comment:
    '<' (less than), '>' (greater-than) and '&' (ampersand)
    These may be interpreted as actual HTML markup. Use &lt; &gt; and &amp; instead.   You have been warned!



Manual List Processing

IMPORTANT NOTE:
The 'idpp' post-processing utility handles all issues discussed in this chapter with very little human intervention. Please refer to the 'idpp' command-line options for processing lists: see Infodoc Post Processor.

The texi-to-HTML converter’s handling of lists has evolved significantly over time; however, it is still a weak area that should be considered carefully when performing post-processing. It is recommended that all itemized/unordered/bulleted lists AND all enumeration/ordered/sequenced lists be scanned and assigned to specific list-class definitions, either automatically or interactively.

Texi : @enumerate a Raw HTML: <ol class="enumerate" type="a" start="1"> Becomes : <ol class="enum-lower-alpha" start="1"> Texi : @itemize @bullet Raw HTML: <ul class="itemize mark-bullet"> (not modified) Texi : @itemize @LSQUARE Raw HTML: <ul class="itemize" style="list-style-type: '◻'"> Becomes : <ul class="square-large">

The multi-level list below is designed as a real-world example. ’makeinfo’ creates a very clean and attractive list in the info-format document; however, the corresponding HTML document can benefit from post-processing.

The following is a summary of the 'infodoc-styles.css' class definitions which support lists.
Please refer to see Summary of CSS Definitions, or directly to the CSS style definitions for more details.


  1. Unordered (bulleted) Lists
    1. The @itemize command generates ’<ul>...</ul>’ list sequences.
    2. The texi-to-HTML converter (v:7.0.3) correctly specifies the HTML markup for: ’@itemize’ (with no argument) and ’@itemize @bullet’ by generating a ’disc-bullet’ list (bullet is similar to ●, but is browser specific).
    3. Three additional bullet-type arguments are directly assigned to a CSS class by makeinfo: @textdegree, @minus, and @w{}.
      For these, makeinfo declares classes in the HTML markup which 'infodoc-styles.css' defines to provide a robust design.
      Example: <ul class="itemize mark-none"> <li> ... </li></ul>
    4. By design, bulleted lists are intended to have a hanging-indent format, where the bullet is set close to the margin, and all text content is inset from the bullet and vertically aligned. Below, is a simulation of what the item should look like if properly formatted.
        ⚬ For the 1995 film "Sense and Sensibility," Emma Thompson 
          received Academy Award nominatons for both best actor, and 
          best screenplay, winning in the best screenplay category. 
          Thompson is the only person to have won Oscars for both 
          acting and screenwriting.
      
        ⚬ "Sense and Sensibility," directed by Ang Lee as his first 
          film outside China, is based on Jane Austen's novel of the 
          same name. Emma Thompson stars, with Kate Winslet, Hugh 
          Grant and Alan Rickman giving workman-like performances.
      

      See Itemized Lists for test code related to bullet lists.

    5. One other issue comes into play with unordered lists: if the lists are not explicity tied to formatting the browser will recognize when a bulleted list is nested within another list and will automatically demote the bullet character for the list from ’disc’ to ’circle’ or from ’circle’ to ’square’ UNLESS invocation of the list includes a specific CSS class declaration.
      As of v:7.0.3, all itemized lists declare an associated CSS class, so this should no longer be a problem.
    6. Please see Interactive Processing for more information on interactive bullet-type selection.
    7. Please see embedded formatting tokens for a discussion of embedding styling instructions within the text of the list.

  2. Unordered List Classes With Custom Bullet Characters
    Makeinfo directly implements three custom bullet classes:

    • ul.mark-textdegree
      For unordered lists specified in the ’.texi’ source with the command: @itemize @textdegree.
    • ul.mark-none
      For unordered lists specified in the ’.texi’ source with the command: @itemize @w{}.
    • ul.mark-minus
      For unordered lists specified in the ’.texi’ source with the command: @itemize @minus.
      Note that while this looks very good in the info document, it is a bit pathetic in HTML unless the "mark-minus" class has been defined. 'infodoc-styles.css' defines this class to correct the unfortunate default formatting. An example of this automatic correction is shown below.
    • Makeinfo handles other custom bullet characters in a straightforward way by declaring the “itemize” class and then embedding a style element directly into the <ul> tag.
      Example: <ul class="itemize" style="list-style-type: '◇'">
      <li> ... </li></ul>

      The following examples demonstrate this embedded styling.

      • @itemize @CLUBSUIT
        • Six of Clubs
        • King of Clubs
      • @itemize @HEARTSUIT
        • Nine of Hearts
        • Queen of Hearts
      • @itemize @SPADESUIT
        • Ace of Spades
        • Seven of Spades
      • @itemize @DIAMONDSUIT
        • Four of Diamonds
        • Two of Diamonds
      • @itemize ¥
        • Twenty-five Yuán (二十五元)
        • One-hundred Kuai (一百块)
    • Styling Tips for Custom Bullet Characters
      Single-width characters used as bullet characters appear as visually too close to the text of the list, see the examples above). For this reason, when creating a CSS class to support your desired bullet character, it is useful to declare a two-character sequence as in the example.
      ul.diamond-small /* Infodoc class - see @DIAMONDSUIT macro */
      {
        list-style-type: '\2666\ ';
        list-style-position: outside;
      }
      
  3. Enumerated (sequenced) Lists
    1. The @enumerate command generates '<ol>...</ol>' list sequences.
    2. The texi-to-HTML converter (v:7.0.3) correctly specifies the HTML markup for: ’@enumerate’ (with no argument) and ’@enumerate 1’ by generating a decimal sequence beginning with the number ’1’.

      The texi-to-HTML converter also correctly identifies:
      lower-case alpha “@enumerate a” : (a, b, c, d, e, ...) and
      upper-case alpha “@enumerate A” : (A, B, C, D, E, ...).

      The texi-to-HTML converter also offers the option of beginning the count at an arbitrary point in the sequence simply by specifying the starting value. Example: ’@enumerate 21’ will begin the decimal count at ‘21’:  (21 22 23 24 25 ...)

      All enumeration lists appear in the raw HTML using the deprecated HTML element, “type”.
      Examples:
      <ol class="enumerate" type="1" start="1">...</ol>
      <ol class="enumerate" type="a" start="6">...</ol>
      <ol class="enumerate" type="A" start="3">...</ol>
      Each of these “type”s should be replaced with the appropriate CSS class definition.
      Examples:
      <ol class=="enum.decimal" start="1">...</ol>
      <ol class=="enum.lower-alpha" start="6">...</ol>
      <ol class=="enum.upper-alpha" start="3">...</ol>

      Please see Enumeration Lists for test code which exercises these constructs.

    3. If your ’.texi’ source specifies an enumeration type other than the three type described above then the texi-to-HTML converter ignores your specification and incorrectly defaults them to decimal numeric lists. For enumeration types suported by 'idpp', these errors can be corrected during post-processing.

      See idpp --enum_list option command-line option and Interactive Processing for more information.

    4. Please see embedded formatting tokens for a discussion of embedding styling instructions within the text of the list.

  4. Ordered List Classes
    To correct the enumeration type generated by default, modify the tag to reference the target class, and optionally specify an initial value and direction (ascending/descending). (These constructs are all handled automatically during post-processing.)

    • ordered list (defaults to decimal numbers)
      Generated: <ol class="enumerate">
      Becomes : <ol class="enum-decimal" start="1"">
    • ordered list specifying decimal numbers
      Generated: <ol class="enumerate">
      Becomes : <ol class="enum-decimal" start="1"">
    • ordered list specifying decimal numbers with leading zero
      Generated: <ol class="enumerate" type="A" start="4">
      Becomes : <ol class="enum-decimal" start="1"">
    • ordered list specifying lower-case alphabetic characters
      Generated: <ol class="enumerate" type="a" start="1">
      Becomes : <ol class="enum-lower-alpha" start="1">
    • ordered list specifying upper-case alphabetic characters
      Generated: <ol class="enumerate" type="A" start="1">
      Becomes : <ol class="enum-upper-alpha" start="1">
    • ordered list specifying lower-case Roman enumeration
      Generated: <ol class="enumerate" type="a" start="9">
      Becomes : <ol class="enum-lower-roman" start="1">
    • ordered list specifying upper-case Roman enumeration
      Generated: <ol class="enumerate" type="A" start="9">
      Becomes : <ol class="enum-upper/roman" start="1">
    • ordered list specifying lower-case Greek enumeration
      Generated: <ol class="enumerate" type="a" start="7">
      Becomes : <ol class="enum-lower-greek" start="1">
    • ordered list specifying upper-case Greek enumeration
      Generated: <ol class="enumerate" type="A" start="7">
      Becomes : <ol class="enum-upper-greek" start="1">
    • ordered list specifying CJK (Han informal) enumeration
      Generated: <ol class="enumerate" type="a" start="10">
      Becomes : <ol class="enum-cjk-decimal" start="1">
    • ordered list specifying Katakana (Japanese Gojūon) enumeration
      Generated: <ol class="enumerate" type="a" start="11">
      Becomes : <ol class="enum-katakana" start="1">
    • ordered list specifying Hebrew enumeration (RTL language)
      Generated: <ol class="enumerate" type="a" start="8">
      Becomes : <ol class="enum-hebrew" start="1">
    • ordered list specifying Arabic-Indic enumeration
      (The family of languages based on Arabic are RTL languages.)
      Generated: <ol class="enumerate" type="a" start="5">
      Becomes : <ol class="enum-arabic-indic" start="1">
    • ordered list specifying a custom enumeration type
      An additional class, “enum-custom”, is defined. This class can be specified during interactive post-processing.
      Then the 'infodoc-styles.css' file can be edited to define the enumeration type.
      Note: The interactive prompt no longer lists the 'c' option for specifying the ’enum-custom’ class, but the 'c' option is still accepted.



Other Manual Processing

  1. OPTIONAL:
    Eliminate extra blank line before pre-formatted blocks.
    The texi-to-HTML converter (unnecessarily in our view) creates two <div> block header declarations on successive lines causing the extra blank line. This extra whitespace is not critical, but we find it annoying, and the 'idpp' post-processor corrects this by eliminating the inner block. Example:
    <div class="format"> <pre class="format"> This is block text. Becomes: <div class="format"> This is block text.
  2. OPTIONAL:
    The @indentedblock, @quotation and @smallquotation commands, as well as the @largequotation macro all share the <blockquote> HTML tag.

    These commands each call out a specific CSS class to provide styling commands:

    <blockquote class="indentedblock"> <blockquote class="quotation"> <blockquote class="quotation smallquotation"> <blockquote class="largequotation">

    Under most circumstances, these commands will be handled automatically

  3. OPTIONAL:
    If your ’.texi’ source uses the @quotation or @smallquotation commands, or the @largequotation macro. the optional “@author” sub-command may be attached to the end of the block. You will find that the texi-to-HTML converter handles this rather poorly.
    <div class="center">&mdash; <em class="emph">Plato</em></div>

    Scan for the sequence which indicates the @author output, and move it INSIDE the ’</blockquote>’ tag. Example:

    <blockquote class="quotation">He was a wise man who invented beer. </blockquote> <div class="center">&mdash; <em class="emph">Plato</em> </div> Becomes: <blockquote class="quotation">He was a wise man who invented beer. <div class="center">&mdash; <em class="emph">Plato</em></div> </blockquote> Note that to beautify the 'author' line, the automatic post-processor takes this one step further: <blockquote class="quotation">He was a wise man who invented beer. <br><span style="margin-left:3.2em;">&mdash; <em>Plato</em> </p></blockquote>

    Also, see @Author macro for a cleaner solution.

  4. OPTIONAL:
    If your ’.texi’ source uses the @cartouche command (for bordered paragraphs), remove the forced styling created by the texi-to-HTML converter so the ’cartouche’ class can control the output.

    Generated: <table class="cartouche" border="1"><tr><td> Becomes: <table class="cartouche"><tr><td>

    Note that the reason the texi-to-HTML converter declares a ’<table>’ element is that in ancient versions of HTML, the ’table’ was the only elements which was defined with borders. This is an obsolete usage, of the ’<table>’ element, but is does not harm the output. However, without removing ’border="1"’ a double border will be generated around the paragraph.

    Also, see Cartouche macro and CartHtml macro.

  5. OPTIONAL:
    In the document’s Index there are three '<table>...<table>' sequences. Two of these are alphabetical "Jump to:" references. To avoid overlap with the standard ’<table>’ tag definition, point the two "Jump to:" tables to the ’jumpto’ class.
    See Info TOC and Index for more information.
  6. OPTIONAL:
    If you are using a sequence of interconnected documents, or if you are linking your document into a larger website tree structure, then be sure that the user has valid navigation links among the documents.

    Software Sam uses these links to aid visitors in website navigation; however, they are completely optional.

    Insert two (2) local links, at the top and bottom of the ’infodoc_container’ class. Of course these links can direct the user anywhere, but we direct the user back to the parent page, the main HTML Docs Page.

    <div class="infodoc_interlink"><a href="../docs.html"> Back To HTML Docs Page </a></div> and <div class="infodoc_interlink"><a href="../docs.html"> Back To HTML Docs Page </a></div><br>
  7. OPTIONAL:
    Modify the classes called out in the Table of Contents list.
    If you like the unmodified Table of Contents, then skip this step.
    Replace the ’no-bullet’ named class with specific class definitions.

    ♦ 1st TOC level : <ul class="toc-level1"> ♦ 2nd TOC level : <ul class="toc-level2"> ♦ 3rd (and subsequent): <ul class="toc-level3">

    We like this modification to visually and logically distinguish the Table of Contents from the chapter menus, but it is of course optional.

  8. OPTIONAL:
    You may find that the chapter menus make the Table of Contents seem
    redundant. If so, you can comment out or delete the entire Table Of
    Contents section which consists of the following data blocks:
    <h1 class="settitle" align="center">YOUR DOC TITLE</h1>
    <h2 class="contents-heading">Table of Contents</h2>
    <div class="contents"> ... </div>
    Be sure to _retain_ the link targets which are referenced by 
    the navigation bars for each node:
    'Contents' target: <a name="SEC_Contents"></a>
    'Top' target     : <a name="Top"></a>
    

    See Info TOC and Index for more information.

  9. OPTIONAL:
    To eliminate the navigation bar from the top of each node,
    you will need to do one of the following:
      a) remove each header individually
         These are identified by the sequence:
    <div class="header"> ... </div>
      b) generate the output using ’makeinfo −−html −−no-headers’.
    See Chapter 24 of the Texinfo documentation ’Generating HTML’
    for more information.
  10. OPTIONAL:
    Because the auto-generator always specifies the <pre> tag as
    <pre class="verbatim"> AND <pre> is specified at all kinds of unlikely points in the output, the unstyled output may not always be what you might expect. To correct this scatter-gun approach, we have defined the top-level <pre> tag and the '.verbatim' class to be identical, and we have also defined specialized <pre> tags for various block types, so it is unnecessary to manually modify the HTML output for these cases.
  11. OPTIONAL:
    Special note on documents containing the GNU General Public License and the GNU Free Documentation License.:

    Most Texinfo users write software and documentation to be released under the GPL and FDL licenses, and we include the text of these licenses, provided by the Free Software Foundation in our documentation. However both of these licenses are constructed using enumeration lists, nested within other enumeration lists, and as detailed above, the Texinfo texi-to-HTML converter does a less-than-stellar job of handling lists.

    Luckily, or unluckily, few people actually read these licenses; they exist primarily for legal reasons; however, you should be aware of the incorrect formatting which the texi-to-HTML converter applies to these licenses because lawyers really care about this kind of inconsistency in legal documents.

    • As written, each license begins with item ’0’ (zero). Of course, this means that the HTML lists begin with item ’1’ (one).
    • Each license uses a convential construct for multi-level lists. Example:
      5. Conveying Modified Source Versions. a. The work must carry ... b. The work must carry prominent ... c. You Must license ... 6. Conveying Non-Source Forms. a. Convey the object code ...

      It puts you to sleep, just looking at it, doesn’t it? However, the texi-to-HTML converter produces this:

      6. Conveying Modified Source Versions. 1. The work must carry ... 2. The work must carry prominent ... 3. You Must license ... 7. Conveying Non-Source Forms. 1. Convey the object code ...

      Showing an incorrectly formatted contract to a lawyer is like showing red meat to a shark. They are constitutionally unable to resist it. The difference is that sharks are passive by nature, and will completely ignore you unless they’re hungry. Lawyers, on the other hand, are agressive by nature, and they are always hungry. You have been warned.




Texinfo HTML Options

The Texinfo ’makeinfo’ utility provides a large number of HTML-only commands and customization variables used by the texi-to-HTML converter to customize the format of the HTML document. While many of these have no effect on post-processing, some can significantly impact the operation of the 'idpp' automatic post-processor.

While our investigation is not comprehensive, some of the most commonly used options and the more critical issues are discussed here.





Embedded HTML Code

Two sets of Texinfo commands may be used to write data into your HTML document without affecting output in other formats.

The data within a '@ifhtml ... @end ifhtml' block will appear ONLY in the HTML output and not in any of the other output formats. The following data:
<p style="font-size: 1.5em;"> Big-ass text in an ’ifhtml’ block. </p>
is inserted into an @ifhtml block below. It should appear in the HTML output as simple text (not interpreted by the browser as markup commands). The block should be invisible in the ’.info’ output.

BEGIN BLOCK: <p style="font-size: 1.5em;"> Big-ass text in an ’ifhtml’ block. </p> :END BLOCK

Similar data is inserted into an '@html ... @end html' block below. The data within the block will be copied unmodified to the HTML output, and thus will be read by the browser as HTML markup. Again, the block should be invisible in the ’.info’ output.

BEGIN BLOCK:

Big-ass italic blue text in an 'html' block.

:END BLOCK


Similarly, the '@ifnothtml ... @end ifnothtml' block may be used to write data to all output formats except HTML. The following paragraph will appear in the info-format document, but will not be included in the HTML-format document.
- - - - -
- - - - -




Texinfo Build Options

This chapter is currently UNDER CONSTRUCTION.

This chapter contains a list of Texinfo customization options and notes on the way these option affect the generation of HTML documents.

The current version of the 'idpp' post-processor, may not be able to parse some of the special HTML constructs generated when these options are used. The author will investigate these special configuration options and their effects on the HTML output as time permits.

If one or more of these special options is causing problems with your post-processing runs, please leave the author a note via website.
See Technical Support



Texinfo Configuration Commands

  • @documentdescription
    The Texinfo texi-to-HTML converter generates a document-description metadata entry in the <head> section of the HTML document. By default the title of the document is used; however, you may use the '@documentdescription' command to specify the contents of this metadata entry.

    Example entry:
    <meta name="description" content="Infodoc HTML Post-processing">

    If you generate an HTML document containing the '@documentdescription', command, then you should also use the
    see idpp --no_meta option so that the entry will be retained.

  • @documentencoding
    Specifies the text-encoding system used by the source document.
    The 'idpp' post-processor assumes that the source document is UTF-8 encoded, which is the GNU/Linux default and is the only reasonable choice for most documents.

    Locale-specific encoding of special characters within the UTF-8 family may be set using the terminal emulator’s environment variables. For information on setting the locale of your system, please refer to the documentation for the ’locale’ command.

  • @documentlanguage=LANG
    Specifies the human language to be assumed for the output.
  • @ifhtml
    Conditional output: see Embedded HTML Code.
  • @ifnothtml
    Conditional output: see Embedded HTML Code.
  • @html
    Conditional output: see Embedded HTML Code.
  • @contents
    Create a Table of Contents at the point where this command is encountered. HTML-format documents contain a Table of Contents if this command is used, but note that this command has no effect on the info-format document.

    It is strongly recommended that the @contents command, if used, be placed at the top of the document before any chapter nodes or sectioning commands.

  • @shortcontents (@summarycontents)
    Create a “short” (summary) Table of Contents with only chapter names (and appendices, if any). This is not a very useful construct because it is nearly identical in form and content to the document’s main menu. However, in a very long document, or a document which is split into several pieces, it might provide the user with an additional navigation tool.

    Insert the '@shortcontents' command anywhere in your '.texi' source document, but OUTSIDE of any sectioning. Note that this command has no effect on the info-format document.

    Note that '@shortcontents' cannot be used as a substitute for the long-form Table of Contents. The long-form TOC must also be present for the hyperlinks to work.

    Note also that using this customization option calls out two (2) undefined CSS classes: ’shortcontents’ and ’shortcontents-heading’. The browser defaults are used for these objects.

    Use of this customization variable is unlikely to affect 'idpp'.

  • @setcontentsaftertitlepage
    Force the Table of Contents to be printed after the Title Page.
    This command applies primarily to printed documents.
  • @setshortcontentsaftertitlepage
    Force the Table of Contents AND the Short Table of Contents to be printed after the Title Page.
    This command applies primarily to printed documents.


Texinfo Invocation Options

  • --html
    Create HTML format document rather that the default ’info’ document.
    Please see Post-processor Overview
  • --no-split
  • --split=HOW
  • --css-include=FILE
    Include the entire CSS definition file into the HTML document, (not recommended). Please see Including Entire CSS File.
  • --css-ref=URL
    Specify an external URL containing CSS definitions, (don’t do this).
    Please see Including Entire CSS File.
  • -D VAR
    Define a variable as with the @set command.
  • -U VAR
    Un-define a variable as with the @clear command.
  • --footnote-style=STYLE (-s)
  • --internal-links=FILE (debugging)
  • --no-headers
    For HTML output, do not create node (chapter) navigation headers in a single-file document, or for split files, create only one header per file.

    Use of this customization variable is unlikely to affect 'idpp'.

  • --no-node-files
  • --node-files
  • --set-customization-variable VAR=VALUE (-c)
  • --enable-encoding

Texinfo HTML Customization Variables

  • AVOID_MENU_REDUNDANCY
  • AFTER_BODY_OPEN
  • AFTER_ABOUT
  • BEFORE_OVERVIEW and AFTER_OVERVIEW
  • BEFORE_TOC_LINES and AFTER_TOC_LINES
  • BIG_RULE
    Specify the top-page-seperator object.
    This is the '<hr>' tag by default.
    Use of this customization variable is unlikely to affect 'idpp'.
  • BODYTEXT
    Specify the extended contents of the '<body>' tag. This is a deprecated construct and is neither necessary nor desirable in modern documents. The information that was previously defined there is now handled through more modern constructs.

    The texi-to-HTML converter initializes these data based on the value specified in the document by the '@documentlanguage' command; however, the data here interfere with the CSS definitions in 'infodoc-styles.css', and so are removed by the 'idpp' post-processor.

    Example makeinfo invocation:
    makeinfo --html -c BODYTEXT='bgcolor="#6699FF" text="#33FF33"' mydoc.texi

    Example entry:
    <body bgcolor="6699FF" text="#33FF33">

    Please see Invoking idpp.

  • CHAPTER_HEADER_LEVEL
    Specify the HTML level of header used as chapter headings.
    The default is to use '<h2>', however, this option may be used to specify a different header level.

    Example makeinfo invocation:
    makeinfo --html -c CHAPTER_HEADER_LEVEL=3 mydoc.texi

    Example chapter heading:
    <h3 class="unnumbered">My Favorite Chapter</h3>

    Use of this customization variable is unlikely to affect 'idpp'.

  • COMPLEX_FORMAT_IN_TABLE
  • CSS_LINES
  • DATE_IN_HEADER
    Specify that a metadata entry indicating the date of document creation should be inserted into the <head>...</head> section of the HTML markup.

    Note that this IS NOT a valid metadata entry according to W3C.org.

    Example makeinfo invocation:
    makeinfo --html --set-customization-variable DATE_IN_HEADER=1 mydoc.texi

    Example metadata entry:
    <meta name="date" content="January 19, 2015">

    If you generate an HTML document using this customization variable, then you should also use the see idpp --no_meta option so that the entry will be retained.

  • DEF_TABLE
  • DEFAULT_RULE
    Specify the interelement-seperator object.
    This is the '<hr>' tag by default.
    Use of this customization variable is unlikely to affect 'idpp'.
  • DO_ABOUT
  • EXTRA_HEAD
    Specify additional elements to be inserted into the <head>...</head> block. Any data elements can be specified in this way, but care should be used to avoid conflicting definitions.

    These extra elements are inserted at the end of the <head> section, and thus override previous definitions, if any.

    Example makeinfo invocation:
    makeinfo --html -c \
    EXTRA_HEAD='<meta name="keywords" content="bee honey flower">' mydoc.texi

    Example entry:
    <meta name="keywords" content="bee honey flower">

    If you generate an HTML document using this customization variable, then you should also use the '--no_meta' option and/or the '--no_links' option (see Invoking idpp) so that the entries will be retained.

  • FOOTNOTE_END_HEADER_LEVEL
  • FOOTNOTE_SEPARATE_HEADER_LEVEL
  • FRAMES (obsolete in HTML)
  • FRAMESET_DOCTYPE
  • HEADER_IN_TABLE
    By default, chapter navigation headers are constructed inside a <div> object; however, the ’HEADER_IN_TABLE’ option may be used to construct the chapter headers inside a <table> object instead.

    Except for small formatting differences, these two formats are visually and functionally identical. They both call out the "header" class, which is currently undefined, so the objects inherit their definitions from the HTML <div> or <table> tag, respectively.

    Example header (default):
    <div class="header">
    . . .
    </div>
    
    Example header (in table):
    <table class="header" cellpadding="1" cellspacing="1" border="0">
    . . .
    </table>
    

    Note that 'infodoc-styles.css' contains a definition for the <div> version of the header class, but it is disabled (commented out) by default. 'infodoc-styles.css' redefines the HTML <table> tag, so a table-based navigation header will inherit its style from this custom definition.

    Use of this customization variable is unlikely to affect 'idpp'.

  • ICONS
  • IMAGE_LINK_PREFIX
  • INLINE_CONTENTS
  • INLINE_CSS_STYLE
    Do not use this option if you want external control over CSS style.
  • KEEP_TOP_EXTERNAL_REF
  • L2H (@math group)
  • MAX_HEADER_LEVEL
  • MENU_SYMBOL
  • MONOLITHIC
  • NO_CSS
  • PRE_ABOUT
  • PRE_BODY_CLOSE
  • PROGRAM_NAME_IN_FOOTER
  • SHOW_TITLE
  • SIMPLE_MENU
    Create HTML menus with a simple, preformatted menu structure rather than the standard menu based on a <table> object.

    (Sorry, this description may be out-of-date.)

    Example makeinfo invocation:
    makeinfo --html -c SIMPLE_MENU=1  mydoc.texi
    
    Example default menu:
    <table class="menu" border="0" cellspacing="0">
    <tr><td>...</td><td>...</td><td>...</td></tr></table>
    
    Example simple menu:
    <div class="menu"><pre class="menu-preformatted">...</pre></div>
    
  • TOC_LINKS
  • TOP_NODE_FILE_TARGET
  • TOP_NODE_UP_URL
    Specify the "Up" target URL. This URL is placed in the "Up" hyperlink of the top node of the document.
    (See also the ’TOP_NODE_UP’ variable.)
    Default node entry:
    ... Up: <a href="dir.html#Top" accesskey="u" rel="up">(dir)</a>...
    
    Example makeinfo invocation:
    makeinfo --html -c TOP_NODE_UP_URL='../../coolstuff.htm'  mydoc.texi
     
    Example node entry:
    ... Up: <a href="../../coolstuff.htm" accesskey="u" rel="up">(dir)</a>...
    

    If you generate an HTML document using this customization variable, then you should also use the see idpp --no_uplink option so that the entry will be retained.

    Please refer also to the '--up_target' option: see Invoking idpp.

    Use of this customization variable is unlikely to affect 'idpp'.

  • USE_ISO
  • USE_LINKS
    Create <link> entries in <head> section. The texi-to-HTML converter generates several <link> entries by default. Set this customization variable to false to prevent these entries from being generated.

    Example makeinfo invocation:
    makeinfo --html -c USE_LINKS=0 mydoc.texi

    Because 'idpp' deletes these <link> entries by default, use of this customization variable is unlikely to affect 'idpp'.

    To retain existing <link> entries,
    please see Invoking idpp.

  • USE_REL_REV
  • VERTICAL_HEAD_NAVIGATION
  • WORDS_IN_PAGE

Other Customization Variables

  • DOCTYPE
    Specify a custom <!DOCTYPE> tag indicating how the browser should interpret the HTML markup.

    Example makeinfo invocation:
    makeinfo --html -c DOCTYPE='<!DOCTYPE html spam and eggs>' mydoc.texi

    Equivalent HTML markup:
    <!DOCTYPE html spam and eggs>

    Note that any doctype tag specified should begin with the HTML5 "<!DOCTYPE" token. If it does not, then 'idpp' will assume that you wear a bearskin loincloth and live in a cave. Consequenty, your outdated tag will be replaced with something from this century.

  • ENABLE_ENCODING_USE_ENTITY
  • IGNORE_BEFORE_SETFILENAME
  • IGNORE_SPACE_AFTER_BRACED_COMMAND_NAME
  • OPEN_QUOTE_SYMBOL
  • SHOW_MENU
  • TEXINFO_DTD_VERSION (xml only?)
  • TOP_NODE_UP
    Specify the name for the "Up" target URL of the top node of the document. The name of the "Up" link is replaced, AND the "Up" hyperlink is modified accordingly.
    (See also the ’TOP_NODE_UP_URL’ variable.)
    Default node entry:
    ... Up: <a href="#Top" accesskey="u" rel="up>(dir)</a>
    
    Example makeinfo invocation:
    makeinfo --html -c 'TOP_NODE_UP=(coolstuff)'  mydoc.texi
    
    Example node entry:
    ... Up: <a href="coolstuff.html#Top" accesskey="u" rel="up">(coolstuff)</a>...
    

    (Note the odd, but necessary parentheses used to get the above invocation to work. Without them, makeinfo will run without errors or warnings; however, it will produce no output.)

    If you generate an HTML document using this customization variable, then you should also use the see idpp --no_uplink option so that the entry will be retained.

    Use of this customization variable is unlikely to affect 'idpp'.

  • TREE_TRANSFORMATIONS (cmd group)
  • USE_NUMERIC_ENTITY
  • USE_UP_NODE_FOR_ELEMENT_UP
  • USE_TITLEPAGE_FOR_TITLE


Note on Using Emacs

Emacs has a special mode for creating Texinfo documents, and this mode contains a very large number of build and configuration options which can affect the output created by the texi-to-HTML converter.

While Emacs is a wonderfully feature-rich and flexible environment, this author has not used Emacs since Pterodactyl poop last fell from the skies, and has no intention of revisiting it. Therefore, it is possible that if you are creating ’.texi’ source documents using Emacs, especially with the ’org’ (Organizer) extensions for HTML output, you may generate some source constructs that 'idpp' cannot parse. If so, you’re on your own, mate!




Including Entire CSS File

This is just a quick reference. For complete information on inserting CSS style information directly into the HTML output, or embedding HTML code in the .texi source document see the chapter ’Generating HTML’ in the Texinfo documentation.

Important Note: The technique discussed here copies the entire CSS definition file into the ’texi’ source file; however, in general, it is better to define a link to the CSS data file and let the browser read it, rather than copying the entire file into each document.

Use the ’−−html’ and ’−−css-include=infodoc-styles.css’ options when invoking makeinfo. This will copy the style definitions directly into the HTML output. Although this is certainly possible, it is messy, difficult to read and may require some additional manual tweaking of the HTML document as described in the previous chapter, See Manual Post-processing.

Note also that the 'idpp' post-processor will not be able to parse a document that includes the entire text of the CSS definition file.

Note: Please don’t eat up someone else’s bandwidth by using
      the ’−−css-ref=URL’ option to include CSS data.




Post-processing Notes

The texi-to-HTML converter makes a valiant effort to generate an HTML document that is similar in most respects to the native info-format document, while incorporating many of the advanced formatting features of HTML and CSS. Unfortunately, the effort has so far been only partially successful.

The following is an overview of the issues related to generating HTML markup directly from ’.texi’ source.



  1. Document Header
    The standard HTML5 document header (MIME type declaration) is: <!DOCTYPE html>
    Recent versions of the texi-2-HTML engine correctly specifies this tag. Older versions of makeinfo may generate something really ugly, such as:
    <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
    "http://www.w3.org/TR/html4/loose.dtd">

    If 'idpp' sees any such nonsence, it will be replaced with the standard document MIME type declaration, above.

    If you absolutely must specify an HTML version or other outdated rendering instructions, please refer to the Texinfo ’DOCTYPE’ or ’FRAMESET_DOCTYPE’ configuration variables: see Texinfo Build Options.
    See also the post-processor option: see idpp --no_html5 option.

    Please note also that DTD (Document Type Definition) was never anything more than a kludge, is no longer used in modern rendering and causes a huge performance hit due to an external URL reference. If your site is still using DTD, you need to take your sys-admin out for lunch and explain the facts of life....

  2. Auto-generated metadata
    In the <head>...</head> section of the document, there are several metadata tags. These data are generally incomplete, out-of-date, or useless, and can therefore be deleted.

    Example:

     <meta name="description" content="gString Text Conversion Guide">
     <meta name="keywords" content="gString Text Conversion Guide">
     <meta name="resource-type" content="document">
     <meta name="distribution" content="global">
     <meta name="generator" content="Bluefish 2.2.15" >
     <meta name="viewport" content="width=device-width,initial-scale=1">
     <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
    

    Please note that the "description" and "keywords" metadata entries shown above can be useful if properly updated.

    • '<meta name="description" ...>'
      By default, this entry specifies the document title; however, as a Texinfo build option, you can specify the text for this entry using the @documentdescription command: see Texinfo Build Options.
    • '<meta name="keywords" ...>'
      By default, this entry specifies the document title; however, this is worse than useless. First, search engines no longer use the "keywords" metadata entry due to massive abuse by porn sites, spammers and other lower forms of life. If you want search engines to find the page, place meaningful search keys in the <title> tag, the "description" metadata entry OR register your site with the individual search-engine companies. The only reasonable use for the "keywords" metadata entry that we can identify is for internal searches by corporate or in-house search algorithms.

    See also the post-processor '--no_meta' option:
    see Invoking idpp.

  3. Auto-generated head links
    In the <head>...</head> section of the document, there are several link tags.

    In theory, the browser will scan these tags for link information, however, in general, the default links are bad or useless information. These links will probably do no actual harm, but neither do they perform any useful task and therefore should be deleted.

    Example:

     <link href="#Top" rel="start" title="Top">
     <link href="#Index" rel="index" title="Index">
     <link href="#SEC_Contents" rel="contents" title="Table of Contents">
     <link href="dir.html#Top" rel="up" title="(dir)">
    

    See also the post-processor '--no_links' option:
    see Invoking idpp.

  4. Auto-generated style elements
    In the <head>...</head> section of the document, there are several partially implemented CSS definitions and class-name specifications. These are merely stubs inserted into the document to facilitate the application of CSS style during post-processing.

    Because these stubs interfere with the equivalent, more robust definitions in the 'infodoc-styles.css' file, THEY MUST BE DELETED.

    Example:

     <style type=:text/css"> 
       a.summary-letter {text-decoration: none}
       blockquote.smallquotation {font-size: smaller}
       div.display {margin-left: 3.2em}
       div.example {margin-left: 3.2em}
       div.indentedblock {margin-left: 3.2em}
       div.lisp {margin-left: 3.2em}
       div.smalldisplay {margin-left: 3.2em}
       div.smallexample {margin-left: 3.2em}
       div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
       div.smalllisp {margin-left: 3.2em}
       kbd {font-style:oblique}
       pre.display {font-family: inherit}
       pre.format {font-family: inherit}
       pre.menu-comment {font-family: serif}
       pre.menu-preformatted {font-family: serif}
       pre.smalldisplay {font-family: inherit; font-size: smaller}
       pre.smallexample {font-size: smaller}
       pre.smallformat {font-family: inherit; font-size: smaller}
       pre.smalllisp {font-size: smaller}
       span.nocodebreak {white-space:nowrap}
       span.nolinebreak {white-space:nowrap}
       span.roman {font-family:serif; font-weight:normal}
       span.sansserif {font-family:sans-serif; font-weight:normal}
       ul.no-bullet {list-style: none}
     </style>
    
  5. <body> tag
    ’makeinfo −−html’ generates the following ’body’ start tag (or something similar) by default, based on the global document settings:
    <body lang="en_US" bgcolor="#FFFFFF" text="#000000" link="#0000FF" 
    vlink="#800080" alink="#FF0000">
    

    First, this is isn’t necessarily what we want, and second, it interferes with the style definitions in 'infodoc-styles.css', so we remove them and use the elements in the external CSS style-definition file. Note that replacing the above with a simple <body> has no apparent effect on the actual rendering of the document because they are all defaults anyway.
    See also the Texinfo ’BODYTEXT’ global variable:
    see Texinfo Build Options.
    See also the post-processor option: see idpp --no_body option.

  6. Intra-page references
    The auto-generated code includes a huge number of <a> tags WITHOUT an ’href’ element, just a ’name’.

    examples: <a name="Introduction-to-gString-1"></a>
              <a name="index-07_002e01-Introduction-to-gString"></a>
    These tags are not rendered because there is no no associated link. They are intra-page link targets. HTML5 uses the following construct for the same purpose:
              <dfn id="Introduction-to-gString-1"></dfn>

    It is not necessary to replace the auto-generated references, they work perfectly; however, you may lose some ’cool-code points’ with the HTML5 validator.

  7. List formatting
    The auto-generated lists have several serious problems; however, until these problems are addressed through Texinfo enhancements, the 'idpp' post processor handles all itemized and enumeration lists issues.
    • An ordered list, <ol> generates a numbered list by default.
      (Texinfo 7.0.3) also supports lowercase and uppercase English alphabetical lists. 'idpp' and 'infodoc-styles.css' support several additional flavours of enumeration. See Enumeration Lists.
    • An unordered list, by default, is generated with a small disc (bullet) to indicate each line item; however, almost any character may be used as the bullet character, including no character at all.
      Please see Itemized Lists for more information.
    • The auto-generated Table of Contents is also constructed as a multi-level unordered list. By default, each level is a ’no-bullet’ level; however, the idpp -c option command may be used to convert the Table of Contents to a true multi-level bullet list.
    • See Texinfo commands: @itemize, @itemize @bullet, @itemize @textdegree,
      @itemize @minus, @itemize @w{}, @enumerate, @enumerate ’1’,
      @enumerate ’a’ and @enumerate ’A’.
      Please see Enumeration Lists for more information.
      See also the 'idpp' enumeration list special processing for detailed configuration for different enumeration types.
  8. How makeinfo uses some common HTML tags.
    • <h1>
      ’makeinfo’ defines this tag either with ’class="settitle"’ when used as the document title; OR with ’class="top"’ as the page title for the main menu. Because neither class is defined, the browser’s default <h1> style is used to render the titles.
    • <h2>
      ’makeinfo’ defines this tag ’class="contents-heading"’ i.e. The heading for the Table of Contents section. Because this class is not defined, the browser’s default <h2> style is used to render this heading.
    • <h3>
      ’makeinfo’ defines this tag in several different ways: ’class="section"’, ’class="heading"’, ’class="unnumberedsec"’ and others. Because none of these classes are defined, each of these defaults to the browser’s <h3> style.
    • <h4>
      ’makeinfo’ defines this tag ’class="subheading"’ and ’class="subsubheading"’, but again, because the classes are not defined, the browser’s default style is used.
    • <p>
      ’makeinfo’ does not define a class/style when using the paragraph tag, but uses it in a number of potentially incompatible scenarios which derive from the parent class. So long as everything uses the default style, there is no serious problem, but if a parent class is defined, it will be necessary to also define the associated <p> tag.
    • <table>
      ’makeinfo’ uses the <table> tag when creating menus, the Table of Contents, the Index, and of course in generating output for the @multitable and @cartouche commands. Within a <table> construct, there will also be <tr>, <td>, <th> and of course <a> tags. All of these use the browser’s default style. To regain control of the table construct, it is necessary to define all of these sub-tags.
    • <ul>
      ’makeinfo’ supports un-ordered lists through the @itemize command, and any single character may be specified as the bullet character. The most common bullet characters are @bullet (default), @minus, @textdegree (standard ’degrees’ symbol: &deg; &#176;)
      A no-bullet option is also supported using the @w{} sequence. Note that this option actually generates a ’space’ character as a bullet.

      For more information: see Itemized Lists.

      In HTML, unordered lists are enclosed within <ul></ul> tags, and can support certain pre-defined bullet characters or a no-bullet option through a CSS style element:
      list-style-type= [disc | circle | square | none];
      The styles for un-ordered lists can be found in the group of <ul> CSS classes defined in the 'infodoc-styles.css' file.

    • <ol>
      ’makeinfo’ supports ordered lists through the @enumerate command, with an argument of:
      [decimal numbers | lower-case alpha | upper-case alpha | none]

      For more information: see Enumeration Lists.

      In HTML, ordered lists are enclosed within <ol></ol> tags, and can support a number of enumeration types.
      The styles for ordered lists can be found in the group of <ol> CSS classes defined in the 'infodoc-styles.css' file.




Makeinfo Testing




Testing Overview

The Test Document

This document is designed to test the capabilities of the Texinfo texi-to-HTML converter. We have designed the ’texi’ source to exercise all the major functionality that could affect the generation of an HTML markup document.

This test document is certainly not comprehensive. It does not try to validate HTML/CSS style-definition inheritance through deeply-nested objects; however, common object-nesting constructs for Texinfo documentation such as multi-level lists work as expected.

Test output is generated by Texinfo (makeinfo) version 7.0.3.
HTML rendering and post-processing verified in Firefox version 126.0.


Rebuilding the 'info' and HTML documents

Rebuilding the test suite from the ’infodoc_XX.texi’ source requires installation of the ’makeinfo’ utility, version 7.0.3 or higher.
A ’Makefile’ is provided which rebuilds the documents in both info-format and HTML-format.

Note that HTML documents created using ’makeinfo’ v:6.7 or earlier require ’idpp’ v:0.0.13 for post-processing.

  1. If you have not yet built the 'idpp' Infodoc Post Processor for your system, do it now. See Build idpp from source.
  2. Open a console window and verify that the correct version of makeinfo is installed: 'makeinfo --version'
  3. Navigate to the ’Infodoc’ directory which contains the ’infodoc_0X.texi’ group of source documents.
  4. Use the gmake utility to invoke makeinfo: 'gmake'
    This will build both the ’.info’ and ’.HTML’ format documents.
  5. Run the 'idpp' post-processor on the raw HTML document.
    This is done with the help of a simple ’bash’ shell script and an automatic response file which responds to the interactive prompts from the post-processor: './applycss'

    Note that the build requires that a copy of the file 'infodoc-styles.css' be in the ’Infodoc’ subdirectory.

    The original HTML document is not modified. The CSS style is applied to a COPY of the original file which is named 'infodoc_css.html'.

    Note that you may also respond manually to the prompts by invoking the shell script with the ’i’ (interactive) option: ./applycss i
    The shell script includes additional invocation options for debugging purposes.

  6. Also, please feel free to invoke the post-processor utility with any and all options in order to become familiar with its functionality. Please refer to the chapter on invoking the 'idpp' utility: see Invoking idpp for more information.

Texinfo and the HTML Converter

Please note that Chapter 22 of the Texinfo documentation describes several ’HTML Customization Variables’. For consistency in testing, the current version of this test document does not use any of those modifiers and relies on the defaults for these variables.

The texi-to-HTML converter is an heroic effort on the part of the Texinfo volunteers at gnu.org, providing serviceable HTML which leverages the default behavior of browser rendering engines.
The release of version 7.0.3 has produced significant improvements over version 5.x which was the standard for several years. The converter ('texi2any') does have a number of issues for which we try to compensate using our style definitions and post-processing. The most noticeable of these are font size, line spacing and list processing. As these and other converter problems are addressed, we will update the style definitions and this document to reflect the changes.

To better understand the specific issues involved, open the default HTML and styled HTML files side-by-side in your browser and compare the formatting of each object defined for the test.

infodoc.html raw texi-to-HTML output infodoc_css.html HTML output with CSS styles applied

This project addresses the moving target of the makeinfo engine’s incremental updates toward full HTML5/CSS3 compliance, so please leave us a note about your experiences.

Faithfully yours, Software Sam -- http://www.SoftwareSam.us/


The author wishes to express his appreciation for the great support and encouragement received from the whole Texinfo group during the development of this project.




Default Style Set

The following is a list of all styles defined by the texi-to-HTML converter. These definitions are very simple and not particularly robust, but they provide hooks for assigning more comprehensive definitions to the styles defined and used by the generated HTML output.

This list is located in the <head></head> section of the document.
Note that the entire contents of the <style></style> sequence is commented out in the generated HTML code, BUT that these definitions may nevertheless be seen by the browser and applied where references to them are made. This is odd, and is likely related to the historical lack of standards in delimiting comments in HTML code. The sequence '<!-- -->' is an HTML comment but is ignored when encountered inside a CSS definition. (CSS uses C-style comments.)
Although it is definitely not recommended , the sequence may be uncommented for documents which have no other source of CSS style.

This ‘texi’ source file is designed so that the HTML output will produce data sequences which invoke each of the following definitions. Some object references are obvious because they call out the texi command names, but others are obscure or complex and require some fancy footwork. See the following chapters for details of our research.

The Auto-generated Style Definitions

For convenience, we have listed the items functionally, rather than alphabetically, and have provided references to the locations in this document where the actual CSS styles associated with these constructs are described.

Note that if you apply the advanced styles defined in 'infodoc-styles.css',
then the auto-generated style sequence shown here should be deleted from
the HTML to avoid conflicts.

For more information, please see the chapter see HTML Post-processing.

(The sequence begins with a "style" tag and the opening comment:) <style type="text/css"> <!−−

Horizontal Object Positioning

blockquote.indentedblock {margin-right: 0em} HTML: <blockquote class="indentedblock">...</blockquote> (see Indentedblock Commands) div.display {margin-left: 3.2em} HTML: <div class="display"> (see Display Commands) div.example {margin-left: 3.2em} HTML: <div class="example"> <pre class="example-preformatted">...</pre></div> (see Example Commands) p.flushleft-paragraph {text-align:left} HTML: <div class="flushleft"> <p class="flushleft-paragraph">...</p></div> p.flushright-paragraph {text-align:right} HTML: <div class="flushright"> <p class="flushright-paragraph">...</p></div> div.center {text-align:center} <div class="center">...</div> (see Misc Block Modifiers)

Text-flow Modifiers

pre.display-preformatted {font-family: inherit} HTML:<pre class="display-preformatted"> (see Display Commands) pre.format-preformatted {font-family: inherit} HTML: <pre class="format-preformatted"> (see Format Commands) span.w-nolinebreak-text {white-space: nowrap} HTML: <span class="w-nolinebreak-text"> (see nonbreaking lines)

Font Modifiers

kbd.kbd {font-style: oblique} HTML: <kbd class="kbd">...</kbd> kbd.key {font-style: normal} HTML: <kbd class="key">...</kbd> span.r {font-family: initial; font-weight: normal; font-style: normal} HTML: <span class="r"> span.sansserif {font-family: sans-serif; font-weight: normal} HTML: <span class="sansserif"> (see Font Modification

Itemized (un-numbered) Lists

ul.mark-bullet {list-style-type: disc} HTML: <ul class="itemize mark-bullet"> ul.mark-minus {list-style-type: "\2212"} HTML: <ul class="itemize mark-minus"> ul.mark-none {list-style-type: none} HTML: <ul class="itemize mark-none"> ul.mark-textdegree {list-style-type: "\00B0"} HTML: <ul class="itemize mark-textdegree"> (see Itemized Lists)

Table Of Contents and Document Index

ul.toc-numbered-mark {list-style: none} HTML: <div class="contents"><ul class="toc-numbered-mark"> (see Info TOC and Index) td.printindex-index-entry {vertical-align: top} HTML: <td class="printindex-index-entry"> td.printindex-index-section {vertical-align: top} HTML: <td class="printindex-index-entry"> th.entries-header-printindex {text-align:left} HTML: <th class="entries-header-printindex"> th.sections-header-printindex {text-align:left} HTML: <th class="entries-header-printindex"> (see Info TOC and Index) (The style tag is closed.) −−> </style>



Basic Tests

This chapter includes the most basic tests: Headings and Body Text.
In the HTML output, plain body text is written inside a set of
paragraph tags: <p> ... </p>

Sections and Headings

Texinfo defines “Sections” as indexed entities which are automatically included in the Table Of Contents and menus.
Texinfo defines “Headings” simply as fancy text which constrasts with the normal document text.

Note that ’makeinfo’ automatically demotes @section, @subsection and @subsubsection commands if they are in subordinate nodes (chapters) or other subordinate constructs. For instance, this chapter is subordinate to the ’Makeinfo Testing’ chapter, so defining a @section here, actually generates a @subsection in both the ’info’ and HTML documents.
As of makeinfo v:6.0, this automatic demotion also applied to @heading, @subheading and @subsubheading commands even though they are functionally simple text. This was a serious logical error which has been corrected in later versions. However, the happy result of this trek into the weeds has encouraged us to create heading macros which are outside the control of the makeinfo/texi2any engine.
See the discussion of these macros in heading macros.

Top-level '@heading'

It is a pleasure to tell you about my recent trip to New Zealand’s Great Barrier Reef.

The generated HTML for this command is:
<h3 class="heading">...</h3>

Second-level "@subheading"

It is a pleasure to tell you about my recent trip to New Zealand’s Great Barrier Reef.

The generated HTML for this command is:
<h4 class="subheading">...</h4>

Third-level "@subsubheading")

It is a pleasure to tell you about my recent trip to New Zealand’s Great Barrier Reef.

The generated HTML for this command is:
<h4 class="subsubheading">...</h4>

The Infodoc package defines CSS style classes for each of the HTML header tags. The following group of HTML-only examples demonstrates the style for the HTML <hx> tags.

<h1> Document Title

<h2> Chapter Title

<h3> Section Header

<h4> Sub-section Header

<h4> Sub-sub-section Header

<h5> Auxilliary Header (not referenced by text-2-HTML converter)
<h6> Auxilliary Header (not referenced by text-2-HTML converter)

In addition to the header tags shown above, the Infodoc package defines a set of macros to give the developer greater control over headings in both the 'info' and HTML document formats.
Please see Macros In Infodoc for more information.




List Commands




Itemized Lists

Itemized lists are created using the @itemize command with or without an argument indicating the bullet character to use.

Compliance:
The HTML markup for itemized lists has undergone significant improvements from makeinfo v:6x to makeinfo v:7x.
In general, all unordered lists <ul> are now constructed using either the invocation of two classes, or one class invocation plus a style element. This is a huge step forward from the embarrassing hack used for lists in earlier makeinfo versions, but lists can still benefit from some tweaking.
The 'infodoc-styles.css' file defines all unordered-list classes declared by makeinfo. This corrects any unfortunate visual artifacts generated by the browser defaults.

Output to ’info’ document: as specified
Output to ’HTML’ document: as specified EXCEPT as noted below

-- @itemize without arguments yields disc bullet items
<ul class="itemize mark-bullet">

  • CSS Class assigned: mark-bullet
  • Additional post-processing: none

-- @itemize @bullet yields disc bullet items!
<ul class="itemize mark-bullet">
HTML &bull; element (&#8226)

  • CSS Class assigned: mark-bullet
  • Additional post-processing: none

-- @itemize @textdegree yields something similar to the HTML standard circle bullets (U+00B0).
<ul class="itemize mark-textdegree">

  • CSS Class assigned: mark-textdegree
  • Additional post-processing: none

-- @itemize @minus yields the default (disc bullet) list style
unless the “mark-minus” class is defined.
<ul class="itemize mark-minus">

  • CSS Class assigned: mark-minus
  • Additional post-processing:
    Note that the Texinfo ’@minus’ generates U+2212 (Unicode minus) in the info document, but this looks very small and too close to the text in the HTML output. This is corrected within the defined 'mark-minus' class by replacing U+2212 with U+2213 (HTML &ndash; element).

-- @itemize @w{} yields the default (disc bullet) list style unless the “mark-none” class is defined.
<ul class="itemize mark-none">

  • CSS Class assigned: mark-none
  • Additional post-processing:
    'infodoc-styles.css' defines the 'mark-none' class to include the "list-style-type: none;" style element.

-- All other specified bullet characters follow a general pattern:
The specified character is declared using a “style” element as shown in the following examples.
<ul class="itemize" style="list-style-type: '♣'"> or
<ul class="itemize" style="list-style-type: '&clubs;'">

  • CSS Class assigned: itemize
  • CSS Style assigned: style="list-style-type: '♣'">
  • Additional post-processing: none

Support For Additional Bullet Characters

The 'idpp' post-processor enhances formatting for a range of common bullet characters by replacing the in-line style element with a CSS class invocation. Texinfo macros are defined for these common bullet characters and the macros reference CSS classes which provide style.
Of course it is not possible to anticipate every bullet character that could be used, but additional CSS classes may easily be added using the templates provided in 'infodoc-styles.css'.

  Texinfo Macro    CSS Class HTML   Description   
 @SDISC disc-small small disc
 @MDISC disc-medium medium disc
 @LDISC disc-large large disc
- - - - - - - - - - - -
 @SCIRCLE circle-small small circle
 @MCIRCLE circle-medium medium circle
 @LCIRCLE circle-large large circle
- - - - - - - - - - - -
 @SSQUARE square-small small square
 @MSQUARE square-medium medium square
 @LSQUARE square-large large square (outline)
- - - - - - - - - - - -
 @SPOINTER pointer-small small right-facing pointer
 @MPOINTER pointer-medium medium right-facing pointer
 @LPOINTER pointer-large large right-facing pointer (outline)
- - - - - - - - - - - - - - - -
 @SDIAMOND diamond-small small diamond
 @MDIAMOND diamond-medium medium diamond
 @LDIAMOND diamond-large large diamond (outline)

The following “itemized” lists demonstrate each of the bullet types listed in the above table. They may may be specified by constructing the list using one of the Texinfo macros listed in the table.
These macros are found in the file: 'texi_macros.texi'.

Example: @itemize @SSQUARE @item first item @item second item @item third item @end itemize

Please be aware that the font family used in the browser may affect the visual appeal of lists created using these bullet characters.

  • CSS Class disc-small — U+2022
    Was Miss Woozy Wombat whisked away by Wallowing Wallaby?
  • CSS Class disc-small — macro: @SDISC
    Perhaps Polly Platypus is playing with Penelope Potoroo.
  • CSS Class disc-medium — U+25CF (or ’disc’ style element)
    Was Miss Woozy Wombat whisked away by Wallowing Wallaby?
  • CSS Class disc-medium — macro: @MDISC
    Perhaps Polly Platypus is playing with Penelope Potoroo.
  • CSS Class disc-large — Unicode U+23FA
    Was Miss Woozy Wombat whisked away by Wallowing Wallaby?
  • CSS Class disc-large — macro: @LDISC
    Perhaps Polly Platypus is playing with Penelope Potoroo.
  • CSS Class circle-small — Unicode U+25E6
    Was Miss Woozy Wombat whisked away by Wallowing Wallaby?
  • CSS Class circle-small — macro: @SCIRCLE
    Perhaps Polly Platypus is playing with Penelope Potoroo.
  • CSS Class circle-medium — ’circle’ style element.
    Was Miss Woozy Wombat whisked away by Wallowing Wallaby?
  • CSS Class circle-medium — macro: @MCIRCLE
    Perhaps Polly Platypus is playing with Penelope Potoroo.
  • CSS Class circle-large — Unicode U+25CB
    Was Miss Woozy Wombat whisked away by Wallowing Wallaby?
  • CSS Class circle-large — macro: @LCIRCLE
    Perhaps Polly Platypus is playing with Penelope Potoroo.
  • CSS Class square-small — ’square’ style element.
    Was Miss Woozy Wombat whisked away by Wallowing Wallaby?
  • CSS Class square-small — macro: @SSQUARE
    Perhaps Polly Platypus is playing with Penelope Potoroo.
  • CSS Class square-medium — Unicode U+25AA
    Was Miss Woozy Wombat whisked away by Wallowing Wallaby?
  • CSS Class square-medium — macro: @MSQUARE
    Perhaps Polly Platypus is playing with Penelope Potoroo.
  • CSS Class square-large — Unicode U+25FB
    Was Miss Woozy Wombat whisked away by Wallowing Wallaby?
  • CSS Class square-large — macro: @LSQUARE
    Perhaps Polly Platypus is playing with Penelope Potoroo.
  • CSS Class pointer-small — Unicode U+2023
    Was Miss Woozy Wombat whisked away by Wallowing Wallaby?
  • CSS Class pointer-small — macro: @SPOINTER
    Perhaps Polly Platypus is playing with Penelope Potoroo.
  • CSS Class pointer-medium — Unicode U+25B8
    Was Miss Woozy Wombat whisked away by Wallowing Wallaby?
  • CSS Class pointer-medium — macro: @MPOINTER
    Perhaps Polly Platypus is playing with Penelope Potoroo.
  • CSS Class pointer-large — Unicode U+25B7
    Was Miss Woozy Wombat whisked away by Wallowing Wallaby?
  • CSS Class pointer-large — macro: @LPOINTER
    Perhaps Polly Platypus is playing with Penelope Potoroo.
  • CSS Class diamond-small — Unicode U+2666
    Was Miss Woozy Wombat whisked away by Wallowing Wallaby?
  • CSS Class diamond-small — macro: @SDIAMOND
    Perhaps Polly Platypus is playing with Penelope Potoroo.
  • CSS Class diamond-medium — Unicode U+25C6
    Was Miss Woozy Wombat whisked away by Wallowing Wallaby?
  • CSS Class diamond-medium — macro: @MDIAMOND
    Perhaps Polly Platypus is playing with Penelope Potoroo.
  • CSS Class diamond-large — Unicode U+25C7
    Was Miss Woozy Wombat whisked away by Wallowing Wallaby?
  • CSS Class diamond-large — macro: @LDIAMOND
    Perhaps Polly Platypus is playing with Penelope Potoroo.

The following list uses the greater-than '>' character which is a reserved character in HTML, and is therefore encoded by the makeinfo engine as an HTML constant entity: &gt;. It is included here to validate the 'idpp' parsing algorithm, and is not recommended for use a a bullet character.

  • First greater-than item
  • Second greater-than item

Unstyled Bullet Lists

If the specified class is not defined, the browser will generate the default ’disc’ bullet list, or in a nested list, an appropriate down-level bullet. Beginning with makeinfo version 7.x, all generated itemized lists are defined; therefore, the browser has no control over selection of the bullet type.
For this reason 'idpp' provides a Texinfo macro specifically to allow the browser to control nested bullet lists.
@CIRCLESLASH '⊘' (U+2298) &osol;
Post-processing replaces either of the makeinfo constructs:
<ul class="itemize" style="list-style-type: '⊘'"> OR
<ul class="itemize" style="list-style-type: '&osol;'">
with the plain <ul> list tag for each level of the nested construct, which allows the browser to apply its internal rules for nested lists.

Example:

   @itemize @CIRCLESLASH
   @item top-level item
      @itemize @CIRCLESLASH
      @item second-level item
         @itemize @CIRCLESLASH
         @item third-level item
            @itemize @CIRCLESLASH
            @item additional-level item
            @item additional-level item
            @end itemize
         @item third-level item
         @end itemize
      @item second-level item
      @end itemize
   @item top-level item
   @end itemize

Output:
(Of course, this would look odd in the 'info' document, so it is recommended to have different versions of the list for 'info' and HTML output.)

  • top-level item
    • second-level item
      • third-level item
        • additional-level item
        • additional-level item
      • third-level item
    • second-level item
  • top-level item



Enumeration Lists

Compliance:
Output to ’info’ document: as specified
Output to ’HTML’ document: as specified EXCEPT as noted below

Three(3) type of enumeration lists are directly supported within the ‘.texi’ source: positive integers, lower-case alpha and upper-case alpha. The texi-to-HTML converter directly supports enumeration lists in four different source formats with three output formats. The generated HTML for enumeration lists follows these general formats:

-- @enumerate without arguments defaults to numeric output <ol class="enumerate"> <li></li> ... <li></li> </ol> -- @enumerate with numeric arguments yields numeric output <ol class="enumerate" type="1" start="1"> <li></li> ... <li></li> </ol> -- @enumerate with lower-case latin alphabetic output <ol class="enumerate" type="a" start="1"> <li></li> ... <li></li> </ol> -- @enumerate with upper-case latin alphabetic output <ol class="enumerate" type="A" start="1"> <li></li> ... <li></li> </ol> For each list type, the initial value of the list may be specified. “@enumerate 7”    yields: 7 line item text 8 line item text 9 line item text . . . “@enumerate c”    yields: c line item text d line item text e line item text . . . “@enumerate G”    yields: G line item text H line item text I line item text . . .

The 'idpp' post-processor enhances the number of available list options either by interactively setting the format for each list
(see idpp --enum_list option) or by automatically interpreting the generated HTML for the list as described in the following table. This table describes how the post-processor expands the flexibility of enumeration lists.

Note: The older (possibly deprecated) HTML type="xxx" construct may not be recognized by future browsers.
For this reason, we use CSS to specify the enumeration type, either by assigning a specific CSS class or by using a direct styling attribute: <ol style:"list-style-type:xxx">


 Texinfo Source Auto-generated HTML Post-processor Interpretation Example List   
 @enumerate <ol class="enumerate"> <ol class="enum-decimal" start="1"> 1. line-item text
 2. line-item text
 3. line-item text
 @enumerate 1 <ol class="enumerate"> <ol class="enum-decimal" start="1"> 1. line-item text
 2. line-item text
 3. line-item text
 @enumerate 6 <ol class="enumerate" type="1" start="6"> <ol class="enum-decimal" start="6"> 6. line-item text
 7. line-item text
 8. line-item text
 @enumerate D <ol class="enumerate" type="A" start="4"> <ol class="enum-decimal-zero" start="1"> 01. line-item text
 02. line-item text
 03. line-item text
 @enumerate a <ol class="enumerate" type="a" start="1"> <ol class="enum-lower-alpha" start="1"> a. line-item text
 b. line-item text
 c. line-item text
 @enumerate A <ol class="enumerate" type="A" start="1"> <ol class="enum-upper-alpha" start="1"> A. line-item text
 B. line-item text
 C. line-item text
 @enumerate i <ol class="enumerate" type="a" start="9"> <ol class="enum-lower-roman" start="1">  i. line-item text
  ii. line-item text
 iii. line-item text
 @enumerate I <ol class="enumerate" type="A" start="9"> <ol class="enum-upper-roman" start="1">  I. line-item text
  II. line-item text
 III. line-item text
 @enumerate g <ol class="enumerate" type="a" start="7"> <ol class="enum-lower-greek" start="1"> α. line-item text
 β. line-item text
 γ. line-item text
 @enumerate G <ol class="enumerate" type="A" start="7"> <ol class="enum-upper-greek" start="1"> Α. line-item text
 Β. line-item text
 Γ. line-item text
 @enumerate j <ol class="enumerate" type="a" start="10"> <ol class="enum-cjk-decimal" start="1"> 一. line-item text
 二. line-item text
 三. line-item text
 @enumerate k <ol class="enumerate" type="a" start="11"> <ol class="enum-katakana" start="1"> ア. line-item text
 イ. line-item text
 ウ. line-item text
 @enumerate h <ol class="enumerate" type="a" start="8"> <ol class="enum-hebrew" start="1">    line-item text
    line-item text
    line-item text
 @enumerate e <ol class="enumerate" type="a" start="5"> <ol class="enum-arabic-indic" start="1">    line-item text
    line-item text
    line-item text

Example output for each option is shown below.

Automatic interpretation of list parameters may be disabled via command-line switch.
See idpp --no_special option, for more information.
Interactive specification of list type, initial value, font size and count direction is enabled by the idpp --enum_list option.

One additional CSS class definition is included for enumeration lists: "enum-custom".
This class may be modified as desired for any enumeration type not already covered by a
class definition. By default, this additional class is identical to the "enum-decimal-zero" class.

Each of the enumeration types may be displayed in standard, smaller or larger font size. Please see embedded formatting tokens for more information.


‘enumerate’ commands without post-processing

‘enumerate’ command without argument

  1. First item
    Was Miss Woozy Wombat whisked away by Wallowing Wallaby?
  2. Second item
    Perhaps Polly Platypus is playing with Penelope Potoroo.

‘enumerate’ command with numeric argument

  1. First item
    Was Miss Woozy Wombat whisked away by Wallowing Wallaby?
  2. Second item
    Perhaps Polly Platypus is playing with Penelope Potoroo.

‘enumerate’ command with lower-case alpha argument

  1. First item
    Was Miss Woozy Wombat whisked away by Wallowing Wallaby?
  2. Second item
    Perhaps Polly Platypus is playing with Penelope Potoroo.

‘enumerate’ command with upper-case alpha argument

  1. First item
    Was Miss Woozy Wombat whisked away by Wallowing Wallaby?
  2. Second item
    Perhaps Polly Platypus is playing with Penelope Potoroo.

‘enumerate’ commands with TARGETED arguments

These will receive post-processing according to the above table and application of the target class definitions in 'infodoc-styles.css'.


Targeting enum-lower-alpha class (@enumerate a)

  1. First item
    Was Miss Woozy Wombat whisked away by Wallowing Wallaby?
  2. Second item
    Perhaps Polly Platypus is playing with Penelope Potoroo.

Targeting enum-upper-alpha class (@enumerate A)

  1. First item
    Was Miss Woozy Wombat whisked away by Wallowing Wallaby?
  2. Second item
    Perhaps Polly Platypus is playing with Penelope Potoroo.

Targeting enum-lower-roman class (@enumerate i),
‘info’ and HTML will not be symmetrical.

  1. First item
    Was Miss Woozy Wombat whisked away by Wallowing Wallaby?
  2. Second item
    Perhaps Polly Platypus is playing with Penelope Potoroo.

Targeting enum-upper-roman class (@enumerate I),
‘info’ and HTML will not be symmetrical.

  1. First item
    Was Miss Woozy Wombat whisked away by Wallowing Wallaby?
  2. Second item
    Perhaps Polly Platypus is playing with Penelope Potoroo.

Targeting enum-lower-greek class (@enumerate g),
‘info’ and HTML will not be symmetrical.

  1. First item
    Was Miss Woozy Wombat whisked away by Wallowing Wallaby?
  2. Second item
    Perhaps Polly Platypus is playing with Penelope Potoroo.

Targeting enum-upper-greek class (@enumerate G),
‘info’ and HTML will not be symmetrical.

  1. First item
    Was Miss Woozy Wombat whisked away by Wallowing Wallaby?
  2. Second item
    Perhaps Polly Platypus is playing with Penelope Potoroo.
  3. Note that not all browsers support uppercase Greek enumeration.

Targeting CJK (Han) numeric (@enumerate j),
‘info’ and HTML will not be symmetrical.

  1. 第一个中日韩项目
    在哪里可以找到母语为普通话的人?
  2. 第二个中日韩项目
    我的普通话很差。
  3. 第三中日韩项目
    也许我会回到成都继续深造。

Targeted Katakana alpha (Gojūon) (@enumerate k),
‘info’ and HTML will not be symmetrical.

  1. 果物
    アルフレッドはキウイやオレンジやストロベリーやすっぱいのくだものがすきですよ!
  2. 中毒薬
    パトリックはビールやワインやアルコールはのみますか。

Targeting enum-hebrew class (@enumerate h),
‘info’ and HTML will not be symmetrical.

  1. יש שני דברים אינסופיים,
    היקום וטיפשות האדם ...
  2. ואני לא בטוח לגבי היקום.
    אלברט איינשטיין

Targeting enum-arabic-indic class (@enumerate e),
‘info’ and HTML will not be symmetrical.

  1. الذكاء
    أشد الفاقة عدم العقل
  2. شخص برئاسة المستوى
    اتق شر الحليم اذا غضب
  3. فعل الخير للآخرين
    أباد الله خضراءهم ابذل لصديقك دمك ومالك

‘enumerate’ command rendered in descending order

  1. All systems report Green.
  2. All personnel exit the gantry immediately.
  3. Lock helmets now.
  4. Verify oxygen flow to suits.
  5. Control team: clear all hold switches.
  6. Disengage life-support tether.
  7. Verify environmental readouts.
  8. Disengage LOx tether.
  9. Grip the hand rails.
  10. Tighten your sphincters.
  11. Blast Off !!

Notes on Enumeration

Implementation Issues

Note that HTML supports multi-language enumeration types and styles, but it is not practical to support all of them within this project, primarily because the author knows only four languages (and none of them well).

Post-processing

At this time, (makeinfo 7.0.3) post-processing of the HTML will be necessary for support of the extended enumerator types. because they currently have no common equivalent between the ‘info’ and HTML output formats.

Enhancement Possibilities

In 2014, an enhancement proposal was submitted to the Texinfo group at gnu.org. This proposal outlined a method for direct support of Roman and Greek enumerators in Texinfo, and/or the method of embedding a specific class call-outs for these into the HTML output. This proposal was partially implemented in Texinfo 6.0 but your author still thinks it would be a valuable enhancement. Proposal Summary: − @lowerroman OR − @lowerroman{n} (where ’n’ is the starting value) lower-case Roman numeral enumeration: i, ii, iii, iv, v, ... − @upperroman OR − @upperroman{n} (where ’n’ is the starting value) upper-case Roman numeral enumeration: I, II, III, IV, V, ... − @lowergreek OR − @lowergreek{n} (where ’n’ is the starting value) lower-case Greek enumeration: α, β, γ, δ, ε, ... Note that lower-case Greek lives at Unicode U+03B1 through U+03C9. − @uppergreek OR − @uppergreek{n} (where ’n’ is the starting value) upper-case Greek enumeration: Α, Β, Γ, Δ, Ε, ... Note that upper-case Greek lives at Unicode U+0391 through U+03A9. − For symmetry, we could add @loweralpha and @loweralpha{} @upperalpha and @upperalpha{} In our opinion, this is actually a much cleaner implementation than the current specification-by-literal-value.



Block Commands

This chapter contains test data for the Texinfo block-oriented commands.




Quotation Commands

The ‘@quotation’ Command

The @quotation block has the following characteristics:

  1. block is left-indented AND right-indented
  2. block inherits the font family and font size from the enclosing environment
  3. line breaks flow and whitespace is compacted
  4. embedded Texinfo commands are expanded

Compliance:
Output to ’info’ document: as specified EXCEPT as noted below
Output to ’HTML’ document: as specified EXCEPT as noted below

The generated HTML for this command is:
<blockquote class="quotation"><p> ... </p></blockquote>
The (awful) HTML generated for the optional @author sub-command is
<div class="center">&mdash; <em class="emph"> ... </em></div>

Quotations are indented at both left and right edges so the text will flow like in the 'indented' block, but in a more confined space. The examples shown here, display the quotation block with and without the @author sub-command, and both with and without the optional (bold text) heading.

The generated HTML for this object declares the ‘quotation’ class as belonging to the HTML ‘blockquote’ tag; however, the HTML “blockquote’ tag does not include a “margin-right” modifier, and is therefore not the same thing as the @quotation command. For this reason, it is necessary to define the “quotation” class to indent the text at both left and right margins.

The documentation says that the @quotation line and @end quotation lines do not generate a line of output. This is true in the ’info’ output but the HTML output generates a blank line before the block. This means that constructing ’correct’ formatting for info output is ’incorrect’ for HTML output. It is unlikely that anything can be done about this except through manual post-processing.

Centering the @author output is simple and reasonably effective in the ’info’ output, BUT produces garbage HTML output unless post-processing is applied. In addition, there should be no blank line in the output between the body of the quotation and the author line. This is true in the ’info’ output, but the HTML output generates a blank line between them because the generated @author command is, for some unknown reason, outside the quotation block.

The unfortunate formatting of the @author sub-command is easily corrected during post-processing. Alternatively, the @Author macro (uppercase ’A’) can be used to bypass the whole mishegas (@Author macro).


Makeinfo renders in bold any text that follows the @quotation command on the same line. These examples show Quotations with, and without optional bold header text.

"Hab SoSlI’ Quch!" Be careful when using this phrase since a challenge will surely follow - and you will very likely experience death by bat’telh.
— traditional

Klingon Insult: "Hab SoSlI’ Quch!" Be careful when using this phrase since a challenge will surely follow - and you will very likely experience death by bat’telh.
— traditional

The ‘@smallquotation’ Command

Between makeinfo v:6.6 and v:7, the “@small....” versions of block commands were not supported for HTML format.
When the texi-2-HTML converter encountered a “@small....” command, it substituted the standard block command.
As of makeinfo v:7, the generated HTML for this command is:
<blockquote class="quotation smallquotation">

The 'idpp' application provides post-processing options to specify both “@small....”  and  “@large....” versions for all block commands. Please see Interactive Processing for further details.

The @smallquotation has all the same characteristics as the @quotation above except that the font size is smaller.

Heroes are seldom born. Instead, they spring to life when circumstances demand it and recede into the background when the crisis has passed. The medieval knight-errant may have been heroic at times, but was essentially just an adventurer. Whipping out one’s sword and challenging someone to a duel to prove "manliness" is not heroic; it is arrogant, cruel and childish, resembling nothing quite so much as trying to stab someone with your metaphorical d..k.
— anon

See also the @largequotation macro at: font-size macros.




Indentedblock Commands

The ’@indentedblock’ Command

The @indentedblock command has the following characteristics:

  1. block is left-indented
  2. block inherits the font family and font size from the enclosing environment
  3. line breaks flow and whitespace is compacted
  4. embedded Texinfo commands are expanded

Compliance:
Output to ’info’ document: as specified
Output to ’HTML’ document: as specified

The generated HTML for this command is:
<div class="indentedblock"><p> ... </p></div>

When encouraging a shark to eat from your hand, be sure to have a paramedic AND a psychiatrist standing by for an immediate debriefing regarding the defective contents of your skull structure.

The ’@smallindentedblock’ Command

The @smallindentedblock has all the same characteristics as the @indentedblock above except that the font size is smaller.
The generated HTML for this command is:
<div class="indentedblock smallindentedblock"><p> ... </p></div>

When encouraging a shark to eat from your hand, be sure to have a paramedic AND a psychiatrist standing by for an immediate debriefing regarding the defective contents of your skull structure.

The 'idpp' application provides post-processing options to specify both “@small....”  and  “@large....” versions for all block commands. Please see Interactive Processing for further details.

See also the @largeindentedblock macro at: font-size macros.




Example Commands

The ‘@example’ Command

The @exaple block has the following characteristics:

  1. block is left-indented
  2. a fixed-width font family is used
  3. the font size is reduced; (however, see notes below)
  4. line break and whitespace formatting are retained as written
  5. embedded Texinfo commands are expanded

Compliance:
Output to ’info’ document: as specified
Output to ’HTML’ document: as specified EXCEPT as noted below

The generated HTML for this command is:
<div class="example"><pre class="example"> ... </pre></div>

PLEASE NOTE: The generated HTML for the @example block seems to be unnecessarily complex because the ‘example’ class itself defines text as “pre” (fixed line breaks) making the internal <pre...> tag redundant and in fact counter-productive.
PLEASE NOTE: The documentation says that the @example block delimiters do not generate a line of output. This is true in the ‘info’ output but the HTML output generates a blank line before the block because the <div> and <pre> classes are defined on successive lines. This means that constructing “correct” formatting for info output is “incorrect” for HTML output.

For output formats that support it, enclosing text which surrounds an @example block should be visually different from the contents of the block.

"Hab SoSlI' Quch!" Be careful when using this phrase since a challenge will surely follow - and you will very likely experience death by bat'telh.

The ‘@smallexample‘ Command

The @smallexample has all the same characteristics as the @example above except that the font size is smaller.
As of makeinfo v:7, the generated HTML for this command is:
<div class="example smallexample"><pre class="example-preformatted"> ... </pre></div>

"Hab SoSlI' Quch!" Be careful when using this phrase since a challenge will surely follow - and you will very likely experience death by bat'telh.

The 'idpp' application provides post-processing options to specify both “@small....”  and  “@large....” versions for all block commands. Please see Interactive Processing for further details.
See also the @largeexample macro at: font-size macros.


The ‘@lisp’ and ‘@smalllisp’ Commands

The @lisp command is really just a special case of the @example command.

The generated HTML for this command is:
<div class="example lisp"><pre class="lisp-preformatted"> ... </pre></div>

;;This is lisp. (example from an online tutorial at Simon Fraser U.). ;; Triple the value of a number (defun triple (X) "Compute three times X." ; Inline comments can (* 3 X)) ; be placed here. ;; Negate the sign of a number (defun negate (X) "Negate the value of X." ; This is a documentation string. (- X))


;;This is smalllisp. ;; Triple the value of a number (defun triple (X) "Compute three times X." ; Inline comments can (* 3 X)) ; be placed here. ;; Negate the sign of a number (defun negate (X) "Negate the value of X." ; This is a documentation string. (- X))

See also the @largelisp macro at: font-size macros.




Display Commands

The ‘@display’ Command

The @display block has the following characteristics:

  1. block is left-indented
  2. block inherits the font family and font size from the enclosing environment
  3. line break and whitespace formatting are retained as written
  4. embedded Texinfo commands are expanded

Compliance:
Output to ’info’ document: as specified
Output to ’HTML’ document: as specified EXCEPT as noted below

The generated HTML for this command is:
<div class="display"><pre class="display"> ... </pre></div>

PLEASE NOTE: The generated HTML for the @display block seems to be unnecessarily complex because the ‘display’ class itself defines text as “pre” (fixed line breaks) making the internal <pre...> tag redundant and in fact counter-productive.
PLEASE NOTE: The documentation says that the @display block delimiters do not generate a line of output. This is true in the ‘info’ output but the HTML output generates a blank line before the block because the <div> and <pre> classes are defined on successive lines. This means that constructing “correct” formatting for info output is “incorrect” for HTML output.

When encouraging a shark to eat from your hand, be sure to have a paramedic AND a psychiatrist standing by for an immediate debriefing regarding the defective contents of your skull structure.

The ‘@smalldisplay’ Command

The @smalldisplay has all the same characteristics as the @display above except that the font size is smaller.
As of makeinfo v:7, the generated HTML for this command is:
<div class="display smalldisplay"> ... </pre></div>

When encouraging a shark to eat from your hand, be sure to have a paramedic AND a psychiatrist standing by for an immediate debriefing regarding the defective contents of your skull structure.

The 'idpp' application provides post-processing options to specify both “@small....”  and  “@large....” versions for all block commands. Please see Interactive Processing for further details.
See also the @largedisplay macro at: font-size macros.




Format Commands

The ‘@format’ Command

The @format block has the following characteristics:

  1. block is not indented
  2. block inherits the font family and font size from the enclosing environment
  3. line break and whitespace formatting are retained as written
  4. embedded Texinfo commands are expanded

Compliance:
Output to ’info’ document: as specified
Output to ’HTML’ document: as specified EXCEPT as noted below

The generated HTML for this command is:
<div class="format"><pre class="format-preformatted"> ... </pre><div>

Please Note: The generated HTML for the @format block seems to be unnecessarily complex because the ‘format’ class itself defines text as “pre” (fixed line breaks) making the internal <pre...> tag redundant and in fact counter-productive.

The documentation says that the @format block delimiters do not generate a line of output. This is true in the ‘info’ output but the HTML output generates a blank line before the block because the <div> and <pre> classes are defined on successive lines. This means that constructing “correct” formatting for info output is “incorrect” for HTML output.

When encouraging a shark to eat from your hand, be sure to have a paramedic AND a psychiatrist standing by for an immediate debriefing regarding the defective contents of your skull structure.

The ‘@smallformat’ Command

The @smallformat has all the same characteristics as the @format above except that the font size is smaller.
As of makeinfo v:7, the generated HTML for this command is:
<div class="format smallformat"><pre class="format-preformatted"> ... </pre></div>

When encouraging a shark to eat from your hand, be sure to have a paramedic AND a psychiatrist standing by for an immediate debriefing regarding the defective contents of your skull structure.

The 'idpp' application provides post-processing options to specify both “@small....”  and  “@large....” versions for all block commands. Please see Interactive Processing for further details.
See also the @largedisplay macro at: font-size macros.




Verbatim Commands

The ‘@verbatim’ Command

The ‘@verbatim’ block command is similar to the @format block command above, but carefully note the differences when choosing which one to use.

The @verbatim block has the following characteristics:

  1. block is not indented
  2. font family is not inherited; instead, a fixed-width font is used.
  3. line break and whitespace formatting are retained as written
  4. embedded Texinfo commands are not expanded, but are written as plain text.

Compliance:
Output to ’info’ document: as specified
Output to ’HTML’ document: as specified EXCEPT as noted below

The generated HTML for this command is:
<pre class="verbatim"> ... </pre>

The following is 'verbatim' text: with whitespace and line breaks preformatted.
Note that @code{} block command IS NOT PROCESSED, but is rendered as plain text.

If    cows    can    @code{jump}    over    the    moon, 
   then    what    do    sheep    jump    over?

The ‘@smallverbatim’ and ‘@largeverbatim’ Commands

Makeinfo does not support a @smallverbatim command. The 'idpp' application compensates by providing post-processing options to specify both “@small....”  and  “@large....” versions for all block commands. In addition 'idpp' defines a @smallverbatim macro and a @largeverbatim macro, although they have a minor limitation based on the fact that Texinfo syntax uses curley braces to delimit macro arguments. This is seldom a problem for other block types because braces typically appear in matching pairs as part of other Texinfo commands. In the small and large verbatim macros, however, all text including braces is (or should be) interpreted as plain text. While it is true that matching pairs of braces are interpreted as plain text, but an unmatched brace must be “escaped” to avoid a Texinfo syntax error. For a further discussion on this issue, please see Macros In Infodoc.

Please see Interactive Processing for further details.
See also the @smallverbatimand @largeverbatim macros at: font-size macros.

A “smallverbatim” block is especially useful for documentation which includes examples of source code.
The following text is rendered with whitespace and line breaks preformatted and the font size approximately ten percent (10%) smaller than the surrounding text.

class commArgs
{
   public:
   commArgs ( int argc, char** argv, char** argenv ) :
               argCount(argc), argList(argv), envList(argenv)
   {
      this->reset() ;
   }
   void reset ( void )
   {
      this->preFlag = this->verFlag = this->helpFlag = false ;
   }
   short    argCount ;     // command-line arguments
   char**   argList ;      // list of argument strings
   char**   envList ;      // pointer to terminal environment
   bool     preFlag ;      // 'true' if pre-scan is to be performed
   bool     verFlag ;      // 'true' if application version request (overrides all others)
   bool     helpFlag ;     // 'true' if command-line help (overrides all except verFlag)
} ;

A “@largeverbatim” block can be used to hit the user over the head with important information:

Petting the alligators is not recommended,
unless you LIKE the nickname 'Stumpy' !!



Misc Block Modifiers

The ‘@flushleft’ Command

Rather than justifying the text, (spreading it across the full width of the line), text is set flush with the left margin.

This is presumably to prevent justification in outputs that support it. Note that neither ’info’ output nor earlier versions of HTML markup justify text, but for HTML, the enclosing environment may be ’centered’ or some other format, so the @flushleft command overrides the parent environment. @flushleft has no function in the ’info’ output.

Generated HTML:
<div class="flushleft"><p class="flushleft-paragraph">...</p></div>


Example @flushleft paragraph:

When I left home for the first time, I took with me all the treasures of a magical youth: three toy soldiers, a bag of cat’s-eye marbles, my dad’s Scout knife, a clean handkerchief, $3.73 and my teddybear, Beathan.




The ‘@flushright’ Command

Text is set flush with the right margin.

As the documentation shows, this is useful for setting a return address or other paragraph to align with the right margin. The @flushright implies pre-formatting of the text except for the edge alignment.

Please Note: Because @flushright implies pre-formatting of lines in the ’info’ output, long lines (that would otherwise have wrapped), may not appear as right-aligned.
In the HTML output, if the paragraph’s environment would normally wrap, then it is correctly converted to flush-right (with wrapping); however, explicitly pre-formatted HTML output will override the @flushright command.

Please Note: Related to the above is the fact that outside an environment, the info output for @flushright is seen as preformatted text (no explicit line breaks necessary). However, the HTML output for this will not be seen as preformatted; therefore, explicit line breaks will be necessary. Thus, info and HTML output are visually incompatible.

If you are generating HTML output, we would recommend that you avoid using the @flushright command because beautification would require specific manual modification to the HTML markkup. Please review the CSS style element "text-align:right;" for applying flush-right formatting across a wide area.

Generated HTML:
<div class="flushright"><p class="flushright-paragraph">...</p></div>


Example @flushright paragraph outside an environment (with and without line breaks):

Note that the following examples reference the defined CSS classes. (see above)

Jungle, George of the
Ape Mountain, South
Bukubu Territory
Deepest Africa

Jungle, George of the Ape Mountain, South Bukubu Territory Deepest Africa


Example @flushright within an @example environment i.e. with pre-formatted line breaks:

Jungle, George of the Ape Mountain, South Bukubu Territory Deepest Africa

Example @flushright within an @indentedblock environment i.e. indented and with flowing text:

In painting and gemmary, Fortunato, like his countrymen, was a quack, but in the matter of old wines he was sincere. In this respect I did not differ from him materially; –I was skillful in the Italian vintages myself, and bought largely whenever I could.
(Ci scusiamo con i nostri amici Italiani.) — Edgar Allen Poe —

Direct HTML Output for pre-formatted, right-aligned text: Jungle, George of the Ape Mountain, South Bukubu Territory Deepest Africa



The ‘@raggedright’ Command

This command applies only to output formats that can ’justify’ i.e. spread text to fill the line; and while modern versions of HTML markup support text justification, the texi-2-HTML converter does not support justification in the generated HTML output.

For this reason, the @raggedright command has no practical value in HTML markup generated from Texinfo source data.



The ‘@cartouche’ Command

For output formats that support it, the paragraph within a “@cartouche” sequence is enclosed within a border.
Generated HTML: <table class="cartouche" border="1">
               <tbody><tr><td><p> ... </p></td></tr></tbody></table>
Even thought the genenerated HTML is more complex (and fragile) than it needs to be, it works by leveraging the definition for the <table> tag, which in earlier versions of HTML was the only element that was allowed to have borders.

The following cartouche object is rendered through the @Cartouche macro so that the 'info' version of the document can display a bit of style. In contrast, the HTML version of the document is enclosed within a border according to the CSS ‘cartouche’ class definition.

Even though the generated HTML does not define the ’cartouche’ class, the enclosing border is still drawn. Be aware, however, that the generated code explicitly invokes the HTML attribute: border="1", which overrides the class definition in 'infodoc-styles.css'. Modern HTML uses CSS to set the border attributes, so the 'idpp' post-processor removes this obsolete syntax, allowing the ’cartouche’ class to take control of the styling.

Within an HTML document, the bordered cartouche construct can be useful in highlighting the important items. For details, see the ‘table.cartouche’ CSS class in 'infodoc-styles.css'.

To increase the flexibility of this construct, the 'idpp' post-processor provides two modification options:
1) Pre-formatted versus flowing text.
2) Relative font size of text within the object.
These options may be invoked interactively during processing.
Pre-formatted vs. flowing text may also be specified globally through the '--cartouche' command line option.
Please see idpp --cartouche option and idpp -i option for more information.

In addition, cartouche formatting options may be specified via an encoded token embedded in the Texinfo source.
See Interactive Processing for more information.

Technical Description of the Cartouche Object

The texi-to-HTML converter calls out the ‘cartouche’ class for this type of object, but does not define the class. Instead, it (inappropriately, in our view), inserts a border style element directly into the HTML document. This direct styling violates Texinfo’s own stated goal of avoiding direct styling of the document. For this reason, 'idpp' removes this direct styling so the ‘cartouche’ class defined in 'infodoc-styles.css' can control the object.

The dimensions of a cartouche object are determined by the data it contains.
If the object contains preformatted text, the height is the number of text rows, and the width is the width of the widest row. However, when the object contains flowing text, the width of the cartouche expands to the width of the parent HTML construct (<div> etc.), and the height is automatically adjusted to the number of rows needed to display the text.

In the HTML document, the cartouche object is technically defined as a table, (@multitable) similar to the table in the Comparison Chart chapter ; however, the cartouche table is defined with only one field. This was a logical design decision by the Makeinfo developers because it is easy to draw the border around a table object.




The ‘@exdent’ Command

The @exdent command removes indentation for the current text line, shifting the line to begin at the left margin. Frankly, we can’t find a use for this, but it exists, so it should work correctly.

The @exdent command is logically useful only within the following block types: @example and @display. In the output, these are the block types which are both indented and with pre-formatted line breaks.

Other block types either use automatic line breaks and/or are already positioned at the left margin. Makeinfo v:5.x handled the @exdent badly, and it was reported to the developers. As of makeinfo version 6.0, the @exdent command was ignored for all block types.
As of makeinfo version 7.0 (approximately), the @exdent command generates a class declaration: <pre class="exdent"> which is defined within the 'infodoc-styles.css' package and is referenced within the following examples. Use it cautiously, however, because it generates some unfortunate HTML constructs consistent with embedding preformatted blocks within other preformatted blocks which the post processor will either discard or ignore. For pre-formatted blocks (example/display), the @exdent construct is discarded, and for blocks with flowing text (quotation/indentedblock), it is ignored (which causes ugliness), as shown in these examples.

@example block unmodified line exdented line unmodified line
@display block unmodified line exdented line unmodified line

@quotation block
This is an indented line.

This is an ’exdented’ line.

This is an indented line.

@indentedblock block
This is an indented line.

This is an ’exdented’ line.

This is an indented line.



The ‘@w{}’ Command

Text within a @w{ ... } command block is protected from automatic line breaks. This is useful for ensuring that a certain phrase will be displayed entirely on one line, or that the line break will happen only where you specify. For both the ’info’ output and the HTML output, the phrase will be displayed entirely on the line where it begins OR if it would extend beyond the margin, the entire phrase will be moved to the next line.

For example, you may want to enclose a phrase such as "all you can eat, only $5.99!" to ensure that it is displayed all on the same line. This will be encoded in HTML as: "all&nbsp;&nbsp;you&nbsp;can&nbsp;eat,&nbsp;only&nbsp;$5.99!" Note also that makeinfo inserts a completely useless HTML comment (<!-- /@w -->) after the sequence.
Presumably this is done to mark the spot for some unspecified future enhancement.

If the non-breaking sequence is surrounded by other text, makeinfo encloses it within an HTML <span>...</span> sequence. For example, a Texinfo source line:
When life hands you lemons, @w{make tequila shooters} for everyone!
will be rendered with the @w{} sequence as:
<span class="w-nolinebreak-text">make&nbsp;tequila&nbsp;shooters</span>
While this makes no sense at all, because it negates the usefulness of the declared CSS class, it is more logical that when a @w{} sequence is not surrounded by other text. For instance:
@w{Clean your room,} young man!
would be rendered as:
<p>Clean&nbsp;your&nbsp;room, young man!</p> In this case it is not possible for the post-processor to locate the sequence because it is within a completely generic <p>...</p> (paragraph) tag sequence.

Neither of these constructs is conducive to intelligent post-processing, and a solution to the problem is being explored.

One place where this functionality would be useful is for cross-reference entries. A cross-reference should not break across lines in any document format, and should certainly not be stuffed full of &nbsp; elements.
In the HTML document, cross-references declare the "xref", "pxref" and "ref" classes for the commands, @xref, @pxref and @ref, respectively; thus, in the HTML, this is handled directly by defining these classes as non-breaking sequences. Example @ref: This is a test of preventing a cross-reference from breaking across lines at the edge of the HTML container: secret to eternal happiness. It may, or may not break across lines within the ‘info’ document based solely on the statistical likelihood of the cross-reference text crossing the right margin.

── ── ── ── ── ── ──

@W Macro for non-breaking text

The Infodoc package provides the @W{} macro (upper-case W) to implement non-breaking text sequences without the need for substituting &nbsp; elements for the whitespace characters.

Technical Note: In the Texinfo source, the @W macro, like many macros, will cause makeinfo to generate a warning message if the macro is not invoked at the left edge of the containing environment.

The following syntax would generate a warning:
The 2022 Oscar winner is: @W{Everthing Everywhere All At Once.}
Although a warning is generated, the output will be on a single line as expected.

For flowing-text environments, the following will generate the same output, but a warning will not be generated.
The 2022 Oscar winner is:
@W{Everthing Everywhere All At Once.}

Note that this text is within an @indentedblock environment, and the macro is positioned at the left edge of the environment. Here is the actual output for the second syntax format, with the leading text extended to push the non-breaking sequence into the right margin of the document, triggering a wrap to the next line:

The 2022 best picture Oscar winner will be accepted by producers, Daniel Kwan, Daniel Scheinert and Jonathan Wang: Everthing Everywhere All At Once.

Here is the same sequence with text modifiers inside the macro:

The 2022 best picture Oscar winner will be accepted by producers, Daniel Kwan, Daniel Scheinert and Jonathan Wang: Everthing Everywhere All At Once.



The ‘@center’ Command

The @center command horizontally centers the text which follows on the same line between the left and right margins. The centering is approximate only.

Example: This text is centered horizontally.

One interesting side-effect is that because this command creates a <div> ... </div> sequence, a whole paragraph can be centered.

This paragraph is horizontally centered
so long as the source text is all on one line.
with line breaks specified by ’@*’.

A newline character in the source closes the <div> container.



The ‘@indent’ and ‘@noindent’ Commands

These commands apply only to text which is outside any block environment. However, until recently, the Texinfo documentation on this was unclear. It has now been clarified that the @indent and @noindent commands do not apply to the HTML output.



The ‘@allowcodebreaks’ Command

This command controls automatic insertion of line breaks at hyphenation points ('-' and '_') within a ’@code’ (or similar) block, and according to the documentation(chapter 13.4) affects only TeX output and is no longer supported in HTML output.




Comparison Chart

This chart compares the formatting characteristics of the various Texinfo block-oriented commands. The variable factors are:

  1. Indentation
    Blocks may be indented on the left, on both right and left, or unindented.
  2. Font Family and Font Size (HTML output)
    The font family and font size are either inherited from the parent block, (generally sans-serif) or are directly specified as part of block’s definition.
  3. Formatting
    The contents of the block are formatted according to the block’s definition:
    • automatically wrap lines and compress whitespace
    • retain preformatted line breaks and whitespace
  4. Texinfo Command Expansion
    Texinfo commands are expanded (interpreted as commands) EXCEPT within @verbatim blocks.
COMMANDL-INDENTR-INDENTFONTFORMATTING@commands
quotationyesyesinheritedautomaticexpand
indentedblockyesnoinheritedautomaticexpand
exampleyesnomonospacepreformattedexpand
displayyesnoinheritedpreformattedexpand
formatnonoinheritedpreformattedexpand
verbatimnonomonospacepreformattedas text
The @lisp and @smalllisp block environments are simply special cases of @example, and so are not included in the table.

Note that only ‘info’ and ‘HTML’ output formats are considered here. Output to Tex, PDF, Docbook, XML and others are not addressed in this test document.




Table and Multitable

The ‘@table’ Command

A two-column table with the ‘@samp’ attribute for the first column.
Note that the @ftable and @vtable commands produce the same display, but also automatically create indices for each entry.

Compliance:
Output to ’info’ document: as specified
Output to ’HTML’ document: as specified EXCEPT as noted below

The generated HTML for this command is:

texi2any v:7 <dl class="table"> <dt>&lsquo;<samp class="samp">for</samp>&rsquo;</dt> <dt>&lsquo;<samp class="samp">while</samp>&rsquo;</dt> <dd><p>loop while the condition evaluates to &rsquo;true&rsquo; </p></dd> <dt>&lsquo;<samp class="samp">if</samp>&rsquo;</dt> <dd><p>execute once if the condition evaluates to &rsquo;true&rsquo; </p></dd> </dl> texi2any v:6 <dl compact="compact"> <dt><span>&lsquo;<samp>for</samp>&rsquo;</span></dt> <dt><span>&lsquo;<samp>while</samp>&rsquo;</span></dt> <dd><p>loop while the condition evaluates to &rsquo;true&rsquo; </p></dd> <dt><span>&lsquo;<samp>if</samp>&rsquo;</span></dt> <dd><p>execute once if the condition evaluates to &rsquo;true&rsquo; </p></dd> </dl> In HTML4, this is called a “definition list”, while in HTML5, this is called a “description list”. Either way, the browser’s default formatting is likely the same.
for
while

loop while the condition evaluates to ’true’

if

execute once if the condition evaluates to ’true’


Please note that the above table looks rather bad in ’info’ format and looks terrible in unstyled HTML. For this reason, we recommend that you consider building all your tables using the @multitable command described below.
If you must use the @table command, we strongly recommend the use of 'infodoc-styles.css' which redefines the <dl> tag so the HTML ouput is visually much nearer to the ’info’ output.




The ‘@multitable’ Command

Compliance:
Output to ’info’ document: as specified
Output to ’HTML’ document: as specified EXCEPT as noted below

The generated HTML for this command is:

<table class=“multitable”> <thead><tr><th>aaaaa</th><th>bbbbb</th><th>ccccc</th></tr></thead> <tbody><tr><td>aaaaa</td><td>bbbbb</td><td>ccccc</td></tr> <tr><td>aaaaa</td><td>bbbbb</td><td>ccccc</td></tr> <tr><td>aaaaa</td><td>bbbbb</td><td>ccccc</td></tr> </tbody> </table> This example is of a simple three(3) column multitable which includes a @headitem (column headings) sub-command. ’aaaaa’ represents data in first column, ’bbbbb’ is the second column and ’ccccc’ is the third column.


AnimalCohortExample Sentence
cowPlacentalThe cow jumped over the fence.
horsePlacentalThe horse eats flowers and grass.
wombatMarsupialThe wonderful wombat can’t jump, but seems quite happy!


Note that the output looks quite different in ’info’ format and HTML format, primarily because of column spacing, fixed versus monospace font, line-break points and underlining of ’info’ column headings. Some of these differences rise to the level of bugs.

There is no guarantee that all tables in a document will be acceptable using the same formatting, so simply defining a table style in our CSS definition file will not solve all the possible formatting problems; however, as an intermediate goal, our definition of the <table> element produces HTML tables that more closely resemble the ’info’ tables.
Please see idpp --table_border option for information on optionally drawing the table using border/grid formatting.

Please Note: Column spacing within the HTML output of a multitable is not handled well. The whitespace specified in the 'texi' source and displayed correctly in the 'info' output is ignored for the HTML output (whitespace sequences are compressed to a single space).

Note that this is handled by our redefinition of the HTML <table> element, but should possibly be addressed directly by a future release of the texi-to-HTML converter.

Please see Comparison Chart for a more complex multitable example.

To increase the flexibility of this construct, the 'idpp' post-processor provides two modification options:
1) Render the table with, or without border.
2) Font size of text within the object.
These options may be invoked interactively during processing, or through an embedded configuration token.

In addition, multitable formatting options may be specified via an encoded token embedded in the Texinfo source.
Please see Interactive Processing for a description of interactive specification of formatting options.
See also embedded formatting tokens for instructions on placing formatting tokens within object declarations.




Font Modification

The Smallcaps ’@sc’ Command

IN THE ’INFO’ OUTPUT, THE TEXT IS SIMPLY CONVERTED TO UPPERCASE; WHILE THE HTML OUTPUT IS SPECIFIED AS UPPERCASE, BUT IN A SMALLER FONT SIZE.

The generated HTML for this command is:
<small class="sc"> ... </small>

The Texinfo documentation suggests that smallcaps be avoided due to inconsistencies across output formats, but it seems reliable for HTML.

The Emphasis ’@emph’ Command

The @emph command delimits the text with underscore characters in ’info’ output. The HTML output is italicized.

The generated HTML for this command is:
<em class="emph"> ... </em>

Note that the actual appearance of the <em> ... </em> block in the HTML output is dependent on the number of ancestor levels, but this should seldom be an issue when generating the HTML from ’texi’ source.

The Strong ’@strong’ Command

The @strong command delimits the text with asterisk characters in the ’info’ output. The HTML output is in bold and in contrast with surrounding text.

The generated HTML for this command is:
<strong class="strong"> ... </strong>

The Texinfo documentation suggests that @strong be used seldom and carefully due to possible mis-interpretation as a cross-reference within the 'info' document.

Editorial Note: Both ’@emph’ and ’@strong’ unfortunately look like crap in the ’info’ output, but are relatively cool in the HTML output.

The Keyboard ’kbd’ and Key ’key’ Commands

These commands are intended to support technical documentation, representing user keyboard interaction and the names of keyboard keys, respectively. The Texinfo documentation recommends that the 'kbd' command be displayed in monospace-oblique text, and the 'key' command, which is often embedded within the 'kbd' sequence, should contrast with the 'kbd' text. Therefore, the CSS classes are constructed to reflect those recommendations.
Enter your password: _

Press ENTER to exit.

The ’@w’ Command - (non-breaking-line sequence)

(generated HTML: Text&nbsp;within&nbsp;the&nbsp;sequence.)
Note that makeinfo replaces the whitespace characters within the source with the HTML &nbsp; element.
This sentence is used to determine whether the browser will break the line at the beginning of the '@w' segment where it should at: Text within a ’@w’ sequence.


Miscellaneous Font-modification Commands

The following commands specify modifications to the basic text font. These are used by printed (i.e. typeset) documents and by the HTML output. They are ignored for the info-format output.

@b command - Bold text. (generated HTML: <b class="b"> ... </b>)
   Text within a ’@b’ sequence.

@i command - Italic text. (generated HTML: <i class="i"> ... </i>)
   Text within a ’@i’ sequence.

@t command - Fixed-width (typewriter) font family.
(generated HTML: <code class="t"> ... </code>)
   Text within a '@t' sequence.

Generic Font Families

Note: The web page being viewed in a browser can specify the font to be used, but the browser settings can override the website’s specification. The 'infodoc-styles.css' style sheet specifies that the default font is the sans-serif variant of the active font family. The Texinfo language defines some minimal support for font selection, the @r and @sansserif commands; however, the "Roman" (Times New Roman) which was the dominant font family for newspapers about thirty years ago, is inadequate for modern digital applications.

Default text (probably sans-serif)
(generated HTML: <p> ... </p>)
   Friends, Romans, Countrymen! Lend me your ear!

@serif command - generic serif.
(generated HTML: <span class="serif"> ... </span>)
   Friends, Romans, Countrymen! Lend me your pen!
   Friends, Romans, Countrymen! Lend me your pen!
   Friends, Romans, Countrymen! Lend me your pen!

@sansserif command - generic sans-serif.
(generated HTML: <span class="sansserif"> ... </span>)
   Friends, Romans, Countrymen! Lend me your golf clubs!
   Friends, Romans, Countrymen! Lend me your golf clubs!
   Friends, Romans, Countrymen! Lend me your golf clubs!

@monospace command - generic monospace.
(generated HTML: <span class="monospace"> ... </span>)
   Friends, Romans, Countrymen! Lend me your phone!
   Friends, Romans, Countrymen! Lend me your phone!
   Friends, Romans, Countrymen! Lend me your phone!

@cursive command - generic cursive.
(generated HTML: <span class="cursive"> ... </span>)
   Friends, Romans, Countrymen! Lend me your lawnmower!
   Friends, Romans, Countrymen! Lend me your lawnmower!
   Friends, Romans, Countrymen! Lend me your lawnmower!

@fantasy command - generic fantasy.
(generated HTML: <span class="fantasy"> ... </span>)
   Friends, Romans, Countrymen! Lend me your beach house!
   Friends, Romans, Countrymen! Lend me your beach house!
   Friends, Romans, Countrymen! Lend me your beach house!

@r command - Roman font family (defined as serif)
(generated HTML: <span class="r"> ... </span>)
   Friends, Romans, Countrymen! Lend me your class notes!
   Friends, Romans, Countrymen! Lend me your class notes!
   Friends, Romans, Countrymen! Lend me your class notes!

@slanted command - Slanted text (defined as oblique)
Slanted Roman text.
(generated HTML: <span class="r"><i class="slanted"> ... </i></span>)
   Friends, Romans, Countrymen! Lend me your ATM card!
Friends, Romans, Countrymen! Lend me your ATM card!




Object Indicators

This is a list of object-identifier commands from the Texinfo documentation. Most of these commands are supported using standard HTML tags. If the browser’s default for these does not satisfy, then please see the stubs in 'infodoc-styles.css' for explicitly defining these elements.

Those identifiers which are directly supported by auto-generated style definitions are so indicated.

@code: Indicate text that is a literal example of a piece of a program.
Supported by : HTML tag
Generated HTML: <code class="code"> ... </code>

@samp: ‘Indicate text that is a literal example of a character sequence.
Supported by : HTML tag
Generated HTML: <samp class="samp"> ... </samp>

@var : Indicate a metasyntactic variable.
Supported by : HTML tag
Generated HTML: <var class="var"> ... </var>

@cite: Indicate the name of a book.
Supported by : HTML tag
Generated HTML: <cite class="cite"> ... </cite>

@abbr: Indicate an abbreviation.
Supported by : HTML tag
Generated HTML: <abbr class="abbr"> ... </abbr>
A useful trick is to use the 'title' attribute with the <abbr> tag
to expand an abbreviation on mouse-over: Please support the FSF.

@kbd : Indicate keyboard input.
Supported by : HTML tag and ’kbd’ class
Generated HTML: <kbd class="kbd"> ... </kbd>

@key : Indicate the conventional name for a key on a keyboard.
Supported by : <kbd> HTML tag, "key" class
Generated HTML: <kbd class="key"> ... </kbd>

@env : Indicate an environment variable.
Supported by : none
Generated HTML: <code class="env"> ... </code>

@file: Indicate the name of a file.
Supported by : none
Generated HTML: <samp class="file"> ... </samp>

@command: Indicate the name of a command.
Supported by : none
Generated HTML: <code class="command"> ... </code>

@option: Indicate a command-line option.
Supported by : none
Generated HTML: <samp class="option"> ... </samp>

@dfn : Indicate the introductory or defining use of a term.
Supported by : HTML tag
Generated HTML: <em class="dnf"> ... </em>

@verb: Write a verbatim sequence of characters.
Supported by : none
Generated HTML: <code class="verb"> ... </code>

@acronym: Indicate an acronym.
Supported by : none
Generated HTML: <abbr class="acronym"> ... </abbr>
     (Please note that the <acronym> tag is no longer supported in HTML5.)

@indicateurl: ‘Indicate a (nonfunctional) example URL
(Use @url command for live URLs.)
Supported by : none
Generated HTML: &lsquo;<code class="indicateurl"> ... </code>&rsquo;

@email:
Supported by : none
Generated HTML: <a class="email" href="mailto:xxxx> ... </a>
(where ‘xxxx’ is the email address)   In the HTML, the text of the address is displayed as a link.




InfoMenu Structure

Menus are at the core of organizing a Texinfo document. Menus in ’info’ format are simply a list of hyperlinks to various nodes (chapters) within the document. For the ’info’ output, each item in a menu consists of a bullet (asterisk character), a @xref (hyperlink) and an optional description of the link content.

Menus as constructed in the HTML output use a <table> structure to implement the same functionality. The HTML code block below was generated for the ’List Commands’ chapter of this document.

  • The menu itself is a <table class="menu"> ... </table> sequence.
  • There are two items in this menu, each defined within a <tr> ... <tr> element.
  • Each item consists of three <td> ... </td> elements
       a) the bullet character AND the hyperlink: <a> ... </a> element
       b) the space between hyperlink and description
       c) the description
<table class="menu" border="0" cellspacing="0"> <tr> <td align="left" valign="top">&bull; <a href="#Itemized-Lists" accesskey="1">Itemized Lists</a>: </td> <td>&nbsp;&nbsp;</td> <td align="left" valign="top">Test –html option &rsquo;itemize&rsquo; list output </td> </tr> <tr> <td align="left" valign="top">&bull; <a href="#Enumeration-Lists" accesskey="2">Enumeration Lists</a>: </td> <td>&nbsp;&nbsp;</td> <td align="left" valign="top">Test –html option &rsquo;enumerate&rsquo; list output </td> </tr> </table>

There are two pre-defined styles generated by the texi-to-HTML converter:
  pre.menu-comment {font-family: serif} and
  pre.menu-preformatted {font-family: serif}
Neither of these is actually used in normal HTML output. We have been told that they may be invoked under very special circumstances, but we have not been able to generate a test that invokes them.
Instead, the ’menu’ class is invoked: <table class="menu"> to create menus. This class is not defined in the generated HTML, but the browser uses its default table definitions for the elements within the table. This seems to work without problems in the raw HTML output, but note that we re-define the <table> element in 'infodoc-styles.css' to support the @multitable command, so we must also define the the ’menu’ class. This is both more reliable and easier to customize than simply relying on the browser defaults.




Info TOC and Index

Table Of Contents Structure

Although the default info-format document does not include a Table of Contents, the HTML version of the document does.

The HTML document’s Table of Contents consists of a multi-level, un-ordered list which provides links to all the chapters and sections (sub-chapters) in the document.

  • The main Table of Contents is an un-ordered (<ul>) list which contains links to all the document’s top-level chapters.
  • Additional lists may be nested within the top-level list, and these contain links to the sub-chapters, sub-sub-chapters and so on.
  • Each of these lists and sub-lists calls out the ’toc-numbered-mark’ class:
             '<ul class="toc-numbered-mark">'
    which in the raw HTML document is defined with a stub:
             'ul.toc-numbered-mark {list-style: none}'.
  • The entire list tree structure is enclosed within two HTML blocks:
             '<div class="element-contents" id="SEC_Contents"> ... </div>'
             '<div class="contents"> ... </div>'
    which call out the (undefined) table-of-contents classes.
  • Between the above ‘<div>’ block declarations is the Table of Contents title:
             '<h2 class="contents-heading">Table of Contents</h2>'
    Again, the ’contents-heading’ class is not defined in the raw HTML document.

What follows is an example taken from the HTML version of the document you are now reading.

<div class="element-contents" id="SEC_Contents"> <h2 class="contents-heading">Table of Contents</h2> <div class="contents"> <ul class="toc-numbered-mark"> <li><a id="toc-Overview-1" href="#Overview">Overview</a></li> <li><a id="toc-CSS-Definition-File-1" href="#CSS-Definition-File">CSS Definition File</a> <ul class="toc-numbered-mark"> <li><a id="toc-Summary-of-CSS-Definitions-1" href="#Summary-of-CSS-Definitions">Summary of CSS Definitions</a></li> <li><a id="toc-Applying-the-CSS-Definitions-1" href="#Applying-the-CSS-Definitions">Applying the CSS Definitions</a></li> <li><a id="toc-Adjusting-Style-Definitions-1" href="#Adjusting-Style-Definitions">Adjusting Style Definitions</a></li> </ul></li> <li><a id="toc-HTML-Post_002dprocessing-1" href="#HTML-Post_002dprocessing">HTML Post-processing</a> . . . </ul></li> . . . </ul> </div> </div>

With few exceptions, the entire Table of Contents relies on the browser’s default settings to render it in the window. In the browsers used for our testing (see browsers used for testing), the output actually looks great with no post-processing at all. However, the 'infodoc-styles.css' CSS definition file fully defines the ’toc-numbered-mark’, ’contents’ and ’contents-heading’ classes for safety, and defines additional classes for customization of the Table of Contents. The following post-processing options are also available for Table of Contents customization or removal, respectively.
See idpp -c option.
See idpp -r option.


Structure of the Document Index

The document index consists of three tables: the primary index which contains the cross-reference indices for the indexed data, and quick-reference tables above and below the primary index table which act as alphanumeric hash tables for the data of the primary index.

The index page begins with a <div> enclosure:
<div class="printindex cp-printindex">

This is followed by the opening alphanumeric quick-reference table:
<table class="cp-letters-header-printindex">

Next is the primary index table with the entries listed alphabetically:
<table class="cp-entries-printindex" border="0">

This is followed by the closing alphanumeric quick-reference table:
<table class="cp-letters-footer-printindex">

The CSS classes declared on the index page are defined in 'infodoc-styles.css'; however, with few exceptions, the defined classes contain no styline commands. The browser defaults are allowed to apply the default style to these elements, and in our view, the result is quite acceptable. If however the index does not meet your expectations, style may be added to these empty classes.





Misc Formatting

No misc. formatting tests identified at this time.




Macros In Infodoc

Macros are an essential part of any large documentation project. The Infodoc package includes various macros to assist in creating attractive documentation. These macros are defined in the file 'texi_macros.texi'.
Feel free to experiment with them to determine which macros suit your documentation style.

what's a macro
font-size macros
heading macros
text-decoration macros
embedded formatting tokens

For designers who are not yet familiar with Texinfo macros, in brief:

  1. A macro is constructed using the @macro command, with (optional) arguments:
    @macro MyMacro{x,y}
    Hello \x\.@*
    My name is \y\.@*
    @end macro

    Within the macro definition, arguments are indicated by a token delimited by backstroke characters: \x\, \y\, etc. where ’x’, ’y’ represents the text of the argument(s).

    This example macro takes two arguments, and would be invoked as:
    @MyMacro{Janet,Charles}

    and would be displayed in the document as:
    Hello Janet.
    My name is Charles.

  2. In a macro invocation, the arguments (if any) are enclosed between braces: ’{’ and ’}’.
    1. If the data of an argument includes brace characters: they must appear in matching pairs UNLESS they are escaped.
      Note: To ’escape’ a character means to temporarily negate or nullify its special meaning.

      As an example of a matched pair of braces, the "t" command is constructed using a pair of braces to enclose the text sequence, so the following macro invocation will be rendered without error:
      @MyMacro{ @t{Your Name:} }

    2. The Texinfo documentation (ambiguously) states that a brace may be used as a literal character within a macro argument if it is preceeded by the backstroke character: ’\’ e.g. '\{' '\}' — however, this is not entirely true.
    3. In a standard Texinfo environment or outside an environment, the Texinfo syntax for a literal brace character is: "@{" where the ’at’ character (’@’) escapes the brace character. For example,
      Texi source of: A brace character looks like this: '@{'
      would yield : A brace character looks like this: '{'
    4. Inside a macro invocation, however, the ’@’ character alone does not escape brace characters, so it is necessary to escape the escape character. For instance, you would need to invoke the 'largedisplay' macro by using the 'at' character ('@') to escape the backstroke character '\' which in turn escapes the brace character '}':
      @largedisplay{A brace character looks like this: '@\}' } which would yield:
      A brace character looks like this: ’}’
    5. Invoking the macros for the 'smallverbatim' and 'largeverbatim' block environments is a special case in that the Texinfo parser should interpret everything within the argument as plain text, with the unfortunate and somewhat schizophrenic exception of brace characters ’{’ or ’}’. Because braces are used to enclose macro arguments, the Texinfo parser would see a single brace character as a syntax error:
      @smallverbatim{A brace character looks like this: '{' }
      while a matched pair of braces would be parsed without error:
      @smallverbatim{A pair of braces looks like this: '{' '}' }

      To address this schizophrenic behavior, the special backstroke escape sequence: '\}' must be used.
      For example: @smallverbatim{Brace yourself: '\{' } would yield:

      Brace yourself: '{'
      
  3. Macros may be designed with any reasonable number of arguments.
    For macros which have more than one argument, the arguments are seperated by commas (',').
    1. If the macro takes only one argument (or no argument), then any commas in the text of the argument will automatically be processed as text.
    2. If the macro takes multiple arguments, and if the text of any argument includes commas, they must be preceeded by the backstroke character. This macro invocation takes two arguments seperated by a comma, and the second argument includes commas as ordinary text:
      @MyMacro{Starbucks,55 Broad St.\, New York\, New York}.
      The @comma macro may also be used to indicate a literal comma.
      @MyMacro{Starbucks,55 Broad St.@comma{} New York@comma{} New York}.
    3. A comma inside an embedded construct will also be rendered as a literal character.
      @MyMacro{@emph{New York, New York} is my hometown.}
  4. A literal backstroke character is indicated by doubling it: '\\'.

(Dear Macro-maven, does your head hurt yet? :-)


The Font-size Group

Block text “environments” are the primary beneficiaries of font-size selection, but other environments such as Itemized and Enumerated Lists, Multitables, the Cartouche, and even plain text can also benefit from an ability to specify the font size for display, (see below).

There are seven(7) types of text block objects defined in the Texinfo language:

indentedblock quotation display format example lisp verbatim

Each of these block types has its own formatting characteristics; however, they share in common the ability to be displayed in any of three(3) different font sizes:

  1. Inherit the font size from the parent environment (1.0em default)
  2. Use a 10 percent smaller font size: (0.9em)
  3. Use a 10 percent larger font size: (1.1em)

All other characteristics of the block are unchanged.

Note: ’em’ is a term used by font nerds meaning the width of character in the current font size,
and equivalent to the number of pixels required to display that character. And just to get into the
weeds a bit further, in CSS, the ’em’ is the height of the font. (see also ’root em’ and ’en space’.)

Texinfo syntax supports the default "inherited" font size for all block types, and in addition, supports the "smaller' font size for all block types except for verbatim. CSS styling classes are defined for each of these block types.

The Infodoc package implements support for the remaining smaller/larger font-size options for these block enviroments through simple Texinfo macros.

  DECLARATION     STRUCTURE  │  DECLARATION      STRUCTURE
  @smallindentedblock  Texinfo Command    │  @smallexample      Texinfo Command
  @indentedblock  Texinfo Command    │  @example  Texinfo Command
  @largeindentedblock  Infodoc Macro      │  @largeexample  Infodoc Macro  
  @smallquotation  Texinfo Command    │  @smalllisp  Texinfo Command
  @quotation  Texinfo Command    │  @lisp  Texinfo Command
  @largequotation  Infodoc Macro      │  @largelisp  Infodoc Macro  
  @smalldisplay  Texinfo Command    │  @smallverbatim  Infodoc Macro  
  @display  Texinfo Command    │  @verbatim  Infodoc Macro  
  @largedisplay  Infodoc Macro      │  @largeverbatim  Infodoc Macro  
  @smallformat  Texinfo Command    │    
  @format  Texinfo Command    │    
  @largeformat  Infodoc Macro      │    

Please see Comparison Chart for additional details on the the the various block environments.

The macro shown here is for '@largedisplay' which is typical of the macros for the block objects.

@macro largedisplay{x} @smalldisplay @ifhtml =l= @end ifhtml \x\ @end smalldisplay @end macro

The embedded token, "=l=" is written to the HTML document only, and is an (invisible) signal to the 'idpp' post-processor that the block is to be adjusted to reference the larger-font CSS style class.

For the 'verbatim' block type, Texinfo syntax supports only the "inherited" font size; therefore, both the '@smallverbatim' and '@largeverbatim' macros are provided, but with a caveat. See the discussion of escaping brace characters, above.

For more information see embedded formatting tokens, below.

── ── ── ── ── ── ──

Itemized Lists

Use the @SmallItemize macro to create an itemized list using a smaller font size.

The @SmallItemize macro takes two arguments:
  1) the bullet type, and
  2) the text for the first line item of the list.
Note that if the text of the item includes commas, they must be escaped as described in commas inside macros, above.

The macro is invoked using the format:
@SmallItemize{bullet_type,text of first line item}
Example:
@SmallItemize{@bullet,Shopping List: tomatoes\, cabbage\, celery}
@item ginger ale, pizza, chips and salsa
@end itemize

The macro arguments are enclosed in braces. Note the comma separating the bullet type from the item text, AND note the escaped commas in the item-text argument. (Commas in other line items are not escaped.)

The @SmallItemize macro includes the embedded token =s= (in the HTML output only), which instructs the 'idpp' post-processor to render the list referencing the CSS "ul.font-small" class in 'infodoc-styles.css'. This styling class applies a font size of 0.85em which is approximately 15% smaller than the text of the parent environment.

@macro SmallItemize{BULL,ITEM} @itemize \BULL\ @item @ifhtml =s= @end ifhtml \ITEM\ @end macro

Here is an example itemized list created using the @SmallItemize macro.

  • Outside of a dog, a book is man’s best friend.
  • Inside of a dog, it’s too dark to read.
  •    − Groucho Marx

Use the @LargeItemize macro to create an itemized list using a larger font size.

The @LargeItemize macro is the same as the @SmallItemize macro described above, except that the embedded token is =l= and the 'idpp' post-processor renders the list to reference the CSS "ul.font-large" class in 'infodoc-styles.css'. This styling class applies a font size of 1.15em which is approximately 15% larger than the text of the parent environment.

  • I find television very educational.
  • Every time somebody turns on the set,
    I go into the other room and read a book.
  •    − Groucho Marx
── ── ── ── ── ── ──

Enumerated Lists

Use the @SmallEnumerate macro to create an enumerated list using a smaller font size.

The @SmallEnumerate macro takes two arguments:
  1) the enumeration type, and
  2) the text for the first line item of the list.
Note that if the text of the item includes commas, they must be escaped as described in commas inside macros, above.

The macro is invoked using the format:
@SmallEnumerate{enumeration_type,text of first line item}
Example:
@SmallEnumerate{A,Shopping List: tomatoes\, cabbage\, celery}
@item ginger ale, pizza, chips and salsa
@end enumerate

The macro arguments are enclosed in braces. Note the comma separating the enumeration type (’A’, upper-case alpha) from the item text, AND note the escaped commas in the item-text argument. (Commas in other line items are not escaped.)

The @SmallEnumerate macro includes the embedded token =...s.= (in the HTML output only), which instructs the 'idpp' post-processor to render the list referencing the CSS "ol.font-small" class in 'infodoc-styles.css'. This styling class applies a font size of 0.85em which is approximately 15% smaller than the text of the parent environment.

@macro SmallEnumerate{ETYPE,ITEM} @enumerate \ETYPE\ @item @ifhtml =...s.= @end ifhtml \ITEM\ @end macro

Here is an example itemized list created using the @SmallEnumerate macro.

  1. Eat sensibly,
  2. Exercise extensively,
  3. Drive defensively,
  4. Love decisively,
  5. Live intentionally.
       − Sam, 2022

Use the @LargeEnumerate macro to create an enumerated list using a larger font size.

The @LargeEnumerate macro is the same as the @SmallEnumerate macro described above, except that the embedded token is =...l.= and the 'idpp' post-processor renders the list to reference the CSS "ol.font-large" class in 'infodoc-styles.css'. This styling class applies a font size of 1.15em which is approximately 15% larger than the text of the parent environment.

This list is created using the @LargeEnumerate macro.
Name the film in which each of these quotations appears...

  1. Hasta la vista, baby.
  2. There’s no crying in baseball.
  3. May the Force be with you.
  4. Inconceivable!
  5. You can’t handle the truth!
  6. You shall not pass!
  7. Frankly, my dear, I don’t give a damn.
  8. Go ahead, make my day.
  9. Gentlemen, you can’t fight in here,
    this is the War Room!
  10. Toto, I’ve a feeling we’re not in Kansas anymore.

The formatting token may also be embedded directly into the list, bypassing the list macros. See embedded formatting tokens, below.




The @Heading Group

The Heading macros are created to support both HTML and 'info' document formats. They take two parameters: 1) The heading text, and 2) the underline character (which is referenced by the 'info' document only). Texinfo syntax specifies that these parameters are enclosed in braces (curley brackets) and are seperated by a comma (’,’).

Note that the heading text should not include commas (’,’) unless they are escaped, because that would confuse the makeinfo parsing algorithm. (See commas inside macros, and the example below.)

By convention, the specified underline character should correspond to those used by makeinfo for the equivalent construct:
The @Heading character is: '=' (equals)
The @Subheading character is: '-' (minus)
The @Subsubheading character is: '.' (full stop)

The makeinfo engine has no construct corresponding to the @H5, @H6, @H7 and @H8 headings; however, the recommended underline character for these is '▔', Unicode U+2594. Unicode U+2500 ('─') can also be visually effective:

h5 heading text or h5 heading text
▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔ ───────────────

The macro may be invoked with both parameters on the same line:

@H5heading{Ice Cream $ .99,▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔}

or on succeeding lines:

@H5heading{Ice Cream $ .99,
▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔}

(For technical reasons, makeinfo discards leading whitespace BEFORE macro text, but NOT after.)

Note that in this example, the commas which are part of the display text for the macro are “escaped”.

@H5heading{Today only\, Ice Cream\, $ .99,
▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔}


The @Heading Macro - corresponds to "h3" (chapter title)

The @Subheading Macro - corresponds to "h4"

The @Subsubheading Macro - corresponds to "h4" class="subsubheading"

The @H5heading Macro - is bold text with underline

The @H6heading Macro - is bold/italic text with underline

The @H7heading Macro - is normal text with underline

The @H8heading Macro - is italic text with underline




The Text-Decoration Group

Text “decorations” as they are called in HTML/CSS can draw the reader’s attention to important passages of your document. The following are a few text-decoration macros which correspond with the indicated CSS styling classes.

These macros enclose the text within an HTML <span class"xxx"> ... </span>.

Underline ▬▶    Hello, World!    ◀▬  Macro: @uline  —  CSS class: "uline"

Overline ▬▶    Hello, World!    ◀▬  Macro: @oline  —  CSS class: "oline"

Throughline ▬▶    Hello, World!    ◀▬  Macro: @tline  —  CSS class: "tline"

Smaller Text ▬▶    Hello, World!    ◀▬  Macro: @smalltext  —  CSS class: "smalltext"

Smaller Bold Text ▬▶    Hello, World!    ◀▬  Macro: @smallboldtext  —  CSS class: "smallboldtext"

Larger Text ▬▶    Hello, World!    ◀▬  Macro: @largetext  —  CSS class: "largetext"

Smaller Red Text ▬▶    Hello, World!    ◀▬  Macro: @Sredtext  —  CSS class: "smallredtext"

Standard Red Text ▬▶    Hello, World!    ◀▬  Macro: @redtext  —  CSS class: "redtext"

Larger Red Text ▬▶    Hello, World!    ◀▬  Macro: @Lredtext  —  CSS class: "largeredtext"


Technical Note: The above macros function best in "flowing" text. This is because
the makeinfo parser will generate a warning if commands like this do not begin at
the left edge of the container. Study the source files for this document for practical
examples of navigating between flowing and pre-formatted text.



Miscellaneous Macros

The @Author macro can be used to replace the Texinfo @author command which is a weak spot in Texinfo document formatting, both for the ’info’ document, and perhaps more importantly for the HTML document.
Here is a simple quotation with the author’s name specified by the @Author macro.

“We live our lives in a certain way,
 And with any luck, we survive the day.”
— Brainius Minimus 481 A.D.


The Page-divider group consists of various styles of horizontal lines used to visually separate items on the page. For instance the @hr20 macro is used above and below to separate the sections of this chapter.

These macros take the form: "hr" ("horizontal rule") plus a number representing the percentage of the window width they span plus an optional line-style indicator. hr90 standard line, 90 percent of window width hr90w ’wide’ (thick) line, 90 percent of window width hr40 standard line, 40 percent of window width hr40d dotted line, 40 percent of window width hr20 standard line, 20 percent of window width hr20d dotted line, 20 percent of window width



Tokens Embedded In the Texi Source

For certain Texinfo “environments” (object types) a token may be embedded withing the Texi source of the object to indicate the formatting options to be applied. Each of the following environments may optionally include an embedded (invisible) token which is interpreted by the 'idpp' post-processor as HTML/CSS formatting instructions.
'idpp' extracts this embedded token, decodes it, and then discards it so that it does not appear in the displayed text.

The token has a specific format so that it can easily be distinguished from the text to be displayed. It takes the form: =xyz= where ’x’, ’y’ and ’z’ are the formatting instructions and the pair of equals signs ('=') delimit the instructions. The number of characters included between the ’=’ characters is determined by the number of formatting options available for the object in which the token is embedded as shown in the table below.
— Options must be listed in the specified sequence.
— The full-stop character ’.’ may be used to specify that the default value
for the option at that position. Example: =.s=

Technical Note: A better character for the default value would have been the '-' minus (dash); however, the makeinfo engine automagically converts a double minus (--) to "ndash" and a triple minus (---) to an "emdash". In HTML, these are the constant elements: "&ndash;" and "&emdash;". For this reason, minus characters cannot be used in the context of embedded tokens. Sorry.


TEXINFO OBJECT FORMATTING OPTIONS TEXINFO OBJECT FORMATTING OPTIONS
Itemized Lists
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
Font Size:
   s smaller
   i inherited (default)
   l larger  
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
Enumerated Lists Enumeration Type
   d decimal (default)
   D decimal, leading zero
   a lower alpha
   A upper alpha
   i lower Roman
   I upper Roman
   g lower Greek
   G upper Greek
   j CJK (informal)
   k Katakana
   h Hebrew
   e Arabic-Indic
Initial Value
   00-99 numerics
   01-99 alphabetics
         (default value: 01)
Font Size:
   s smaller
   i inherited (default)
   l larger
Sequence Direction:
   a ascending (default)
   d descending
Multitable Table Border:
   b border (default)
   n no border
Font Size:
   s smaller
   i inherited (default)
   l larger
  Cartouche Text Flow:
   p preformatted (default)
   f flowing
Font Size:
   s smaller
   i inherited (default)
   l larger

The formatting tokens described above can be inserted as text directly into the command invocation, but alternatively,
the @embedTOKEN macro
may be used to simplify the process of embedding the token into an object. An example of each is shown in the multitable section, below.

During automatic post-processing, the value(s) in the embedded token will be used to configure the object. During interactive post-processing, these values can be overridden by the user input, but will be the configuration values used when the user response is ’a’ (automatic). See Interactive Processing for details.


Itemized Lists - Formatting Tokens

Itemized lists support one embedded-formatting option, the relative size of the font used to display the list.

TOKEN FONT-SIZE OPTION ───── ─────────────────── =i= inherited font size (this is the default) =s= smaller font size =l= larger font size Important Note: Always use the @embedTOKEN macro to insert the token to avoid having the token appear in the 'info' format document.

Specify smaller text for an @itemize list:
Embedded the token =s= to obtain a smaller font size, or =l= to obtain a larger font size.
Example: @item @embedTOKEN{s}When your mother asks,...

  • When your mother asks, ‘Do you want a piece of advice?’ it is a mere formality.
  • It doesn’t matter if you answer yes or no.
  • You’re going to get it anyway. – Erma Bombeck
  • When your mother asks, ‘Do you want a piece of advice?’ it is a mere formality.
  • It doesn’t matter if you answer yes or no.
  • You’re going to get it anyway. – Erma Bombeck

Enumerated Lists - Formatting Tokens

In HTML, enumerated (ordered) lists are designed to be very flexible and inclusive of language and enumeration type; however, other output formats supported by makeinfo/texi2any are more restrictive.

Makeinfo directly supports decimal (1, 2, 3, etc.), lower-case alpha (a, b, c, etc.), and upper-case alpha (A, B, C, etc.).

The Infodoc project has implemented a combination of in-line encoding, Texinfo macros, embedded styling tokens and CSS style definitions to support a larger variety of enumeration lists in the HTML generated by makeinfo. Please refer to the chart at Enumeration Lists for a list of supported enumeration types.

Enumerated lists support four(4) embedded-formatting options in the following order with no intervening spaces:
1) enumeration type,
2) initial sequence value,
3) relative font size, and
4) sequence direction.
A default value is specified by a full-stop (’.’) i.e. a period character.

TOKEN ENUM TYPE START FONT-SIZE DIRECTION ───── ───────── ───── ────────── ────────── =t....= list type (see list of options above) =.nn..= --------- decimal value 00-99 (note: this is TWO digits) =...i.= --------- ----- inherited - =...s.= --------- ----- smaller - =...l.= --------- ----- larger - =....a= --------- ----- - ascending =....d= --------- ----- - descending Examples: =d01ia= decimal enumeration/starting at 01/inherited font size/ ascending sequence (this is the default data set) - Example: 1 2 3 4 5 ... =D10ld= decimal-leading-zero/starting at 10/larger font size/ descending sequence - Example: 10 09 08 07 06 ... =...s.= default enumeration/default start value/smaller font size/ default sequence direction - Example: 1 2 3 4 5 ... =i01ia= lower-case Roman numerals/starting at 01/inherited font size/ ascending sequence - Example: i ii iii iv v vi ... Important Note: Always use the @embedTOKEN macro to insert the token to avoid having the token appear in the 'info' format document.

Descending decimal numbers, smaller font size:
The first line item for this list: @item @embedTOKEN{...sd}strawberries

  1. strawberries
  2. blueberries
  3. raspberries
  4. tomatoes

Ascending lower-case Roman numerals, larger font size:
The first line item for this list: @item @embedTOKEN{...la}carrots

  1. carrots
  2. cucumbers
  3. apricots
  4. potatoes



Multitable Formatting Tokens

The embedded token is constructed as a four-character sequence which specifies the formatting parameters:

TOKEN BORDER OPTION FONT-SIZE OPTION ───── ───────────── ─────────────────── =bi= bordered table, inherited font size (this is the default) =bs= bordered table, smaller font size =bl= bordered table, larger font size =ni= no-border table, inherited font size =ns= no-border table, smaller font size =nl= no-border table, larger font size Example (bordered table with "smaller" font size): @multitable {xxxxxxxxxxxxxx} {xxxxxxxxxxxxxxx} {xxxxxxx} {xxxxxxxxxx} @headitem =bs=SMALLER @tab MULTI-TABLE @tab WITH @tab HEADER @item Smaller Font @tab Field #2 @tab  Field#3 @tab Field#4 @item Smaller Font @tab Field #2 @tab  Field#3 @tab Field#4 @item Smaller Font @tab Field #2 @tab  Field#3 @tab Field#4 @end multitable

The token is embedded in the first field of the first row of the table. In the example shown, the @headeritem row is the first row; however, if @headeritem is not used, then the token would be embedded in the first @item row instead: @item =bs=Smaller Font ...

In this example, the embedded token is: "=bs=" indicating that 'idpp' should process the table with a border and smaller font size.

SMALLER  MULTI-TABLE   WITH HEADER
 Smaller Font Field #2 Field#3 Field#4
 Smaller Font Field #2 Field#3 Field#4
 Smaller Font Field #2 Field#3 Field#4

In this example, the embedded token is: "=bl=" indicating that 'idpp' should process the table with a border and larger font size.

Because this table has no header row, the token is embedded in the first @item row. Also, the token is created using the embedTOKEN macro which automatically provides the delimiter characters, so only the actual formatting parameters must be specified:
@item @embedTOKEN{bl} Larger Font @tab Multi-Field #2 @tab Field#3 @tab Field#4

 Larger Font Multi-Field #2 Field#3 Field#4
 Larger Font Multi-Field #2 Field#3 Field#4
 Larger Font Multi-Field #2 Field#3 Field#4



Cartouche Formatting Tokens

The following examples of the cartouche object are created through the '@CartHtml' macro which includes an embedded (invisible) token which specifies the text formatting and font size used. 'idpp' extracts this embedded token, decodes it, and then discards it so that it does not appear in the displayed text. The following shows the construction of the '@CartHtml' macro and an example invocation.

Custom Cartouche macro for HTML output only. @macro CartHtml{x} @ifhtml @cartouche \x\ @end cartouche @end ifhtml @end macro Argument 'x' is the text to be displayed. At the beginning of the text insert one of the following 4-character tokens which specifies the formatting parameters: TOKEN BORDER OPTION FONT-SIZE OPTION ───── ──────────────────────── ─────────────────── =ai= auto (preformatted) text, inherited font size (this is the default) =as= auto (preformatted) text, smaller font size =al= auto (preformatted) text, larger font size =fi= flowing text, inherited font size =fs= flowing text, smaller font size =fl= flowing text, larger font size Example: (automatic text formatting and "smaller" font size): @CartHtml{=as=Hello World, how are you?} Or, the embedding macro may be used to insert the formatting token: @CartHtml{@embedTOKEN{as}Hello World, how are you?}

Note that the @CartHtml macro produces output only in the HTML document.
See Cartouche macro, below which outputs data to both 'info' and HTML document formats.

(THE FOLLOWING EXAMPLES ARE VISIBLE ONLY IN THE HTML OUTPUT.)

Format Using Inherited Font Size with Pre-formatted Text (default)

A “cartouche” is a bordered paragraph. The border is not visible within the ‘info’ document, and may as well have beeen ignored. However, the border is rendered correctly within the HTML document. CSS style for margins and interior padding is added to beautify the output. By default, text within an HTML cartouche block is pre-formatted and is not modified during post-processing. However, the text formatting style may be selected using the "--cartouche" post-processing option.


Format Using Smaller Font Size with Pre-formatted Text

Teresita’s First Crush:   Aaron isn’t like the other boys. He’s very mature. He never plays tricks on people the way my stupid brothers do. And he smiles almost all the time, even when Mrs. Ratburger is giving him a hard time, (his English isn’t very good.) To tell the truth, my English isn’t so great either. That’s why we’re both in the immersion class together, even though he’s in second grade, and I’m just in first grade. He sits in the front row, and I sit three rows back and one to the left. Of course, I’ve never talked to him. I would just die if he ever looked at me.


Format Using Larger Font Size with Pre-formatted Text

Teresita’s First Crush:   Aaron isn’t like the other boys. He’s very mature. He never plays tricks on people the way my stupid brothers do. And he smiles almost all the time, even when Mrs. Ratburger is giving him a hard time, (his English isn’t very good.) To tell the truth, my English isn’t so great either. That’s why we’re both in the immersion class together, even though he’s in second grade, and I’m just in first grade. He sits in the front row, and I sit three rows back and one to the left. Of course, I’ve never talked to him. I would just die if he ever looked at me.


Format Using Inherited Font Size with Free-flowing Text


Teresita’s First Crush:   Aaron isn’t like the other boys. He’s very mature. He never plays tricks on people the way my stupid brothers do. And he smiles almost all the time, even when Mrs. Ratburger is giving him a hard time, (his English isn’t very good.) To tell the truth, my English isn’t so great either. That’s why we’re both in the immersion class together, even though he’s in second grade, and I’m just in first grade. He sits in the front row, and I sit three rows back and one to the left. Of course, I’ve never talked to him. I would just die if he ever looked at me.


Format Using Smaller Font Size with Free-flowing Text


Teresita’s First Crush:   Aaron isn’t like the other boys. He’s very mature. He never plays tricks on people the way my stupid brothers do. And he smiles almost all the time, even when Mrs. Ratburger is giving him a hard time, (his English isn’t very good.) To tell the truth, my English isn’t so great either. That’s why we’re both in the immersion class together, even though he’s in second grade, and I’m just in first grade. He sits in the front row, and I sit three rows back and one to the left. Of course, I’ve never talked to him. I would just die if he ever looked at me.


Format Using Larger Font Size with Free-flowing Text


Teresita’s First Crush:   Aaron isn’t like the other boys. He’s very mature. He never plays tricks on people the way my stupid brothers do. And he smiles almost all the time, even when Mrs. Ratburger is giving him a hard time, (his English isn’t very good.) To tell the truth, my English isn’t so great either. That’s why we’re both in the immersion class together, even though he’s in second grade, and I’m just in first grade. He sits in the front row, and I sit three rows back and one to the left. Of course, I’ve never talked to him. I would just die if he ever looked at me.


── ── ── ── ── ── ──

the @Cartouche macro

Note that because the basic Texinfo @cartouche command is essentially meaningless within the 'info' document format, the Infodoc package includes the @Cartouche macro to add some style to the 'info' cartouche output, while simultaneously producing output to the HTML document.

The primary difference between the @Cartouche macro and the CartHtml macro above, is that an embedded styling token should not be used in the @Cartouche macro because the token would be displayed as plain text in the 'info' document.

This is what the output to the 'info' document looks like when using the @Cartouche macro:

     ┌────────────────────────────────────────
      There once was a bloke from Iran,
      Who while cycling as fast ere he can,
      Got some dust in his eye,
      Which did cause him to cry,
      Whereupon he was hit by a van.
     └────────────────────────────────────────

The macro itself is split between ’info’ and HTML output, with the data for the info document inserted into an '@example' block, which provides both an indent from the left margin and pre-formatted lines of text. The text itself is bracketed between sequences of line-drawing characters to set it apart from the surrounding text. In the author’s opinion, a full implementation of the @cartouche command for the 'info' document would be an interesting project for the makeinfo maintainers (hint, hint).
The HTML output is identical to that of the @CartHtml macro described above.





Block Text - Formatting Tokens

Note that the block-text environments defined by Infodoc macros also include embedded tokens for relative font size; however, those tokens are automatically handled through the macro invocation and require no direct manipulation. See font-size macros above.








Idpp Testing

Automatic post-processor parsing, and document-modification tests.

Because scanning automatically-generated HTML markup is a complex process, and because even a small difference in the expected formatting can cause the post-processor to choke, the following tests provide a broad sample of the markup that may be generated by the Texinfo texi-to-HTML converter.




Idpp List Processing

The following are lists nested inside other lists which exercises the ’idpp’ list-recursion algorithm.

@enumerate nested within @enumerate

  1. Nested Enumerate (a)
    The HTML for this list should be post-processed with (a)
    New Boots
    1. There once was a man from Nantucket
    2. Who always peed into a bucket
    3. Till one day, he missed
    4. And his boots got all pissed,
    5. And shouted "Now I’ll have to wash them!"
  2. Nested Enumerate (A)
    The HTML for the following list should be post-processed with (A)
    Old Wife
    1. There once was a man from Poughkeepsie
    2. Who often got rather tipsy.
    3. He was roundly ashamed;
    4. Twas his wife that he blamed,
    5. For she was quite prone to be ditzy.

@itemize nested within @enumerate

This over-the-top test of nested lists exercises the 'idpp' algorithm for identifying lists within lists and applying post-processing where necessary.

Technical Note: In the absence of explicit styling, the browser will automatically assign bullet types to bullet lists based on the depth of nesting. Note that as of makeinfo v:7x all bullet lists are explicitly styled by default, so the browser renders these lists as written. To enable the browser’s automatic formatting of bullet lists, it would be necessary to first remove explicit styling. Please see Unstyled Bullet Lists for an example of unstyled nested lists.
  1. Nested Itemize @bullet(•)
    "Your Love" from: "The One Where Monica Gets a New Roommate"
    • Love is sweet as summer showers,
      Love is a wondrous work of art.
    • But your love, oh your love, your love
      is like a giant pigeon, crapping on my heart.
  2. Nested Itemize @SDIAMOND (♦)
    Although there are at least seven children born during the
    series, this one occurred during the birth of Ross’ son Ben.
    "Babies" from "The One With the Birth"
    • They’re tiny and chubby and so sweet to touch
      Soon they’ll grow up and resent you so much
    • Now they’re yelling at you and you don’t know why
      And you cry and you cry and you cry
    • And you cry and you cry...
  3. Nested Itemize @textdegree(°)
    The HTML for the following list should be post-processed with (°).
    "Crazy Underwear" from: "The One With Ross’s Thing"
    • Crazy underwear,
      creepin up my butt.
    • Crazy underwear,
      Always in a rut.
    • Crazy underwear...
  4. Nested Itemize @minus(−)
    This is a three-level itemized list. Each level is declared using the @minus bullet type.
    "Smelly Cat" from "The One With the Baby On the Bus, et al"

    • Smelly cat, smelly cat
      What are they feeding you?
    • Smelly cat, smelly cat
      It’s not your fault
      • They won’t take you to the vet
        You’re obviously not their favorite pet.
      • You may not be a bed of roses
        And you’re no friend to those with noses.
    • Smelly cat, smelly cat
      What are they feeding you?
    • Smelly cat, smelly cat
      It’s not your fault

@itemize nested within @itemize

  • Nested Itemize @bullet(•)
    Barney
    • There was a cute girl from Killarney
    • Got seduced by a tosser named Barney.
    • Though he’d touted his prowess,
    • When they got to his howse,
    • She found it was all naught but blarney.
  • Nested Itemize @textdegree(°)
    Long Jack
    • Jack was a rough ’un from Bristol.
    • Who was wont to whip out his pistol.
    • Though not much of a shot,
    • And he’d miss like as not,
    • In length, ’twas surprisingly distal.
  • Nested Itemize @minus(−)
    Wedding Night Blues
    • Though the bride was quite powerfully built,
    • The groom vowed he’d prevail ’neath the quilt.
    • But try as he might
    • Through the long wedding night,
    • ’Twas his nose blood that finally got spilt.

@enumerate nested within @itemize

  • The HTML for the following should be post-processed with lowercase Roman
    The items in this group of lists are specified in the Texinfo source
    as ’@enumerate r’, ’@enumerate R’ and ’@enumerate g’, respectively.
    After post-processing, the HTML and ’info’ documents will not be symmetrical.
    This is necessary for this test document, but use care when creating production
    documents, so that the ’info’ and post-processed HTML documents remain synchronized.
    "Blackout" from "The One With the Blackout"

    1. New York City has no power,
      and the milk is getting sour;
    2. But to me, it is not scary
      ’cause I stay away from dairy.
  • The HTML for the following should be post-processed with uppercase Roman
    "Shower Song" from "The One With the Baby On the Bus"

    1. I’m in the shower,
      and I’m writing a song.
    2. Stop me if you’ve heard it.
    3. My skin is soapy,
      and my hair is wet,
    4. and Tegrin spelled backward
      is Nirget.
    5. Lather, rinse, repeat
      and lather, rinse, repeat
      and lather, rinse, repeat
    6. as needed.
  • The HTML for the following should be post-processed with lowercase Greek
    "Barnyard Animals" from "The One After the Superbowl, Part One"

    1. Oh, the cow in the meadow goes ’moo’,
      the cow in the meadow goes ’moo’.
    2. Then the farmer hits him in the head,
      and grinds him all up
    3. and that’s how we get hamburger.
    4. Noooowww chickens!...

Deeply Nested Lists

  1. Itemized Below Enumerated (disc bullet)
    "Sticky Shoes" from "The One With Phoebe’s Ex-partner"

    • My favorite shoes, so good to me
      I wear them every day.
    • Down at the heel, holes in the toe
      Don’t care what people say.
    • My feet’s best friend, pals to the end
      with them I’m one hot chickie
    • Thought late one night, not much light
      I stepped in something icky...

      Enumerated Below Itemized (decimal leading-zero)

      1. Sticky shoes, sticky shoes
        Always make me smile.
      2. Sticky shoes, sticky shoes
        Next time, I’ll avoid the pile!
  2. All Hail, Phoebe Buffay!


Lyrics in this section copyright (c) NBC / Warner Bros. Television.
(but the limericks are our fault :-)



Idpp Block Processing

Lists Inside Blocks

Formatted constructs such as @enumerate (<ol>) lists, @itemize (<ul>) lists or other formatted constructs should usually be built outside any other block construct, or what the Texinfo documentation refers to as an "environment."

Placing one formatted construct (such as a list) inside another formatted environment is not recommended due to likely formatting conflicts.

The native ’.info’ output for such constructs is surprisingly good; however, converting these constructs in your Texinfo source to non-native formats can be a technically difficult task, and in the case of the texi-to-HTML converter, can yield some very disappointing results.

For this reason we urge caution when placing formatted (non-paragraph) data inside a formatted block environment. These environments are:

  • @format, @smallformat and @largeformat
  • @display, @smalldisplay and @largedisplay
  • @example, @smallexample and @largeexample
  • @lisp, @smalllisp and @largelisp
  • @quotation, @smallquotation and @largequotation
    (see Idpp Misc Tests)

This discussion does not apply to @verbatim environments because all contents of a @verbatim environment are output as literal text.

For a detailed description of block environments,
please see Comparison Chart.


@indentedblock

The @indentedblock environment is not preformatted, and so may contain any other construct without difficulty. This is the environment recommended for all formatted constructs that must be built inside an environment.

Here we are inside an @indentedblock block.

  • Bathe.
  • Brush your teeth.
  • Shave unwanted hair.
  • Eat a healthful breakfast.
  • Pack your bag.
  • Kiss all family members.
  • Go to work.
  1. Bathe.
  2. Brush your teeth.
  3. Shave unwanted hair.
  4. Eat a healthful breakfast.
  5. Pack your bag.
  6. Kiss all family members.
  7. Go to work.

Leaving the @indentedblock block.


@display block

The ’info’ document for the following blocks looks surprisingly good; however, the texi-to-HTML converter generates some rather tortured HTML inside blocks that are defined as "preformatted."

If the block-definition classes called out by the generated HTML are not defined, then the HTML looks fairly ok because the class callouts are ignored. When the classes ARE defined, however, the weakness of the auto-generated code becomes obvious. Without post-processing, the following lists are unreadable.

Although ’idpp’ is not guaranteed to cleanly parse the tortured HTML of these lists, it does an adequate job here (except for the extra blank lines).

If you want professionally formatted lists, then the correct answer is:
     DON’T PUT LISTS INSIDE PRE-FORMATTED BLOCK ENVIRONMENTS!!


This is a preformatted block containing an itemized list and an enumerated list.

Here we are inside a @display block.
  • Bathe.
  • Brush your teeth.
  • Shave unwanted hair.
  • Eat a healthful breakfast.
  • Pack your bag.
  • Kiss all family members.
  • Go to work.
  1. Bathe.
  2. Brush your teeth.
  3. Shave unwanted hair.
  4. Eat a healthful breakfast.
  5. Pack your bag.
  6. Kiss all family members.
  7. Go to work.
Leaving the @display block.

The raw HTML markup generated for this sequence

<div class="display">
<pre class="display-preformatted">Here we are inside a @display block.
</pre><ul class="itemize mark-bullet">
<li><pre class="display-preformatted">Bathe.
</pre></li><li><pre class="display-preformatted">Brush your teeth.
</pre></li><li><pre class="display-preformatted">Shave unwanted hair.
</pre></li><li><pre class="display-preformatted">Eat a healthful breakfast.
</pre></li><li><pre class="display-preformatted">Pack your bag.
</pre></li><li><pre class="display-preformatted">Kiss all family members.
</pre></li><li><pre class="display-preformatted">Go to work.
</pre></li></ul>
<pre class="display-preformatted">

</pre><ol class="enumerate">
<li> <pre class="display-preformatted">Bathe.
</pre></li><li> <pre class="display-preformatted">Brush your teeth.
</pre></li><li> <pre class="display-preformatted">Shave unwanted hair.
</pre></li><li> <pre class="display-preformatted">Eat a healthful breakfast.
</pre></li><li> <pre class="display-preformatted">Pack your bag.
</pre></li><li> <pre class="display-preformatted">Kiss all family members.
</pre></li><li> <pre class="display-preformatted">Go to work.
</pre></li></ol>
<pre class="display-preformatted">Leaving the @display block.
</pre></div>

The same sequence after post-processing

Note that the extra ' <pre class...>' and '</pre> tags associated with individual line items have been removed.

<div class="display">Here we are inside a @display block.
<ul class="itemize mark-bullet">
<li>Bathe.
</li><li>Brush your teeth.
</li><li>Shave unwanted hair.
</li><li>Eat a healthful breakfast.
</li><li>Pack your bag.
</li><li>Kiss all family members.
</li><li>Go to work.
</li></ul>

<ol class="enumerate">
<li> Bathe.
</li><li> Brush your teeth.
</li><li> Shave unwanted hair.
</li><li> Eat a healthful breakfast.
</li><li> Pack your bag.
</li><li> Kiss all family members.
</li><li> Go to work.
</li></ol>
Leaving the @display block.
</div>

@example block

Here is another type of preformatted block containing an itemized list and an enumerated list. This block is the same as the previous block except that it is defined to use a monospace font. The post-processing for the block is identical.

Here we are inside an @example block.
  1. Bathe.
  2. Brush your teeth.
  3. Shave unwanted hair.
  4. Eat a healthful breakfast.
  5. Pack your bag.
  6. Kiss all family members.
  7. Go to work.
  • Bathe.
  • Brush your teeth.
  • Shave unwanted hair.
  • Eat a healthful breakfast.
  • Pack your bag.
  • Kiss all family members.
  • Go to work.
Leaving the @example block.



Idpp Misc Tests

@quotation and @smallquotation with 'author' Attached

Correct is better than fast. Simple is better than complex.
Clear is better than cute. Safe is better than insecure.
— Sutter and Alexandrescu, C++ Coding Standards

A designer knows he has achieved perfection not when there is
nothing left to add, but when there is nothing left to take away.
— Antoine de Saint-Exupery



Blocks Inside Blocks

Except for @indentedblock blocks it is strongly recommended that block environments NOT be nested within other block environments, but we run a few tests here, just to see what happens.
(Note that ’idpp’ handles these tests smoothly :)

Remember: Preformatted data including other preformatted blocks should not be nested inside preformatted blocks — unless you LIKE ugly. Data inside preformatted blocks are, with few exceptions, processed as plain text. No interactive formatting is performed for a preformatted block within another preformatted block.

@indentedblock within @indentedblock block

This text is part of the outer indented block. It should be indented by a few spaces as specified by the document’s @exampleindent command (5 spaces by default in info output).

This is a doubly-indented paragraph, i.e. it lives within a nested @indentedblock. This is a bit unlikely is a production document, but we want to see how makeinfo handles it for info-format and HTML-format output.

This text is part of the outer indented block. It should be indented by a few spaces as specified by the document’s @exampleindent command (5 spaces by default in info output).

@example within @indentedblock block

This text is part of the outer indented block. It should be indented by a few spaces as specified by the document’s @exampleindent command (5 spaces by default in info output).

This text is within an @example block (monospaced text). It can often be useful to change font families for emphasis.

This text is part of the outer indented block. It should be indented by a few spaces as specified by the document’s @exampleindent command (5 spaces by default in info output).

Simple @quotation block with @author

"Give a man a fish, and he’ll eat fish."
— Samwise Gamgee

@quotation block within @indentedblock

This text is within the indented block. It should be indented by a few spaces as specified by the document’s @exampleindent command if present (5 spaces by default in info output).

"Give a man a fish, and he’ll think something is rotten in Denmark, but teach a man to fish, and he’ll think you want to have sex with him."
— Samwise Shakespeare

This text is within the indented block. It should be indented by a few spaces as specified by the document’s @exampleindent command if present (5 spaces by default in info output).

@indentedblock within @quotation block

"Why is the rum gone?"

"One, Because it is a vile drink that turns even the most respectable men into complete scoundrels..."

This text is within an indented block within a @quotation command.

"But why is the rum gone?"

"... and two, because that signal is over a thousand feet high. The entire royal navy is out looking for me; do you think there is even the slightest chance they won’t see it?"

This text is within an indented block within a @quotation command. We don’t name the author of this exchange because everyone on the planet already knows who the speakers are–but it is after all, copyrighted material–so give credit where credit is due.

"There’ll be no living with her after this."
— Copyright 2003, the Walt Disney Company


Deeply Nested Block Environments (stupid - but possible)

’format’ block
’display’ block
'example' block
'indentedblock' block =='verbatim block'== 'indentedblock' block
'example' block
’display’ block
’format’ block


Bullet Characters

The character codes used by HTML for unordered lists. Note that the characters shown in the ’info’ document only approximate the characters in the HTML document which are browser-specific and are affected by the font family used as well as other factors.

HTML NAMENESTING LEVELEXAMPLE
’disc’top( ⏺ )
’circle’second( ⚬ )
’square’third and lower( ▪ )

HTML-only output follows: default unordered lists nested to demonstrate the bullets used by default for each level.

This is embedded HTML markup:
  • Some stuff A
    • Some stuff B
      • Some stuff C
        • Some stuff D

Bullet Characters Defined in Texinfo

Texinfo character @bullet ( • ) texi-to-HTML converter outputs ’&bull;’ U+2022 Texinfo character @textdegree ( ° ) texi-to-HTML converter outputs ’&deg;’ U+00B0 Texinfo character @minus ( – ) texi-to-HTML converter outputs ’–’ U+2212 (Unicode minus)

Useful Character Codes

UNICODEEXAMPLEHTML(hex)DESCRIPTION
U+25CF( ● )&#x25CF;black-circle
U+26AB( ⚫ )&#x26AB;medium-black-circle
U+2022( • )&#x2022;medium-small-black-circle
U+2219( ∙ )&#x2219;bullet-operator (math)
U+25CB( ○ )&#x25CB;white-circle
U+26AA( ⚪ )&#x26AA;medium-white-circle
U+26AC( ⚬ )&#x26AC;medium-small-white-circle
U+25E6( ◦ )&#x25E6;white-bullet
U+25A0( ■ )&#x25A0;black-square
U+25FC( ◼ )&#x25FC;black-medium-square
U+25FE( ◾ )&#x25FE;black-medium-small-square
U+25AA( ▪ )&#x25AA;black-small-square

Please see itemized list special processing for examples of the bullet characters
directly supported by 'infodoc-styles.css' Texinfo macros and CSS style.




Ad-hoc Tests

Write your own test sequences here

** NO AD-HOC TESTS DEFINED AT THIS TIME **






Technical Support

Please Note: All trademarks and service marks mentioned in this document are the entirely-too-proprietary property of their respective owners, and this author makes no representation of affiliation with or ownership of any of the damned things.

Contact

All source code and documentation for this project were written and are maintained by: Mahlon R. Smith, The Software Samurai Beijing University of Technology on the web at: www.SoftwareSam.us For bugs, suggestions, periodic updates, or possible praise, please post a message to the author via website.

By the Same Author

  • NcDialog Application Programming Interface (API) library.
    The NcDialog API forms the basis for most of our other software projects. It provides the application developer with the tools to create dialog-based console applications, without the need to learn anything about the complexities of the underlying ‘ncurses’ C-language library.

    Console applications have always been the most efficient and easily-implemented of computer programs. What they lacked was a friendly and visually-pleasing user interface.

    With the NcDialog API, console applications can now be used and understood by experts and novice users alike.

  • FileMangler (fmg), is a compact, fast and flexible tool for handling all your file management needs.

    FileMangler performs all basic file management tasks, as well as performing scheduled and ad-hoc file backup and synchronization activities.

    FileMangler runs in a console window, and thus provides access to many system tools not available to a GUI application. FileMangler also provides full support for accessing the local Trashcan.

    FileMangler is based on the NcDialog API, and thus will run in almost any GNU/Linux or UNIX terminal environment.

  • Console Trashcan (ctrash) is a simple, console-based (command-line) utility for managing the contents of your local Trashcan. Send items to the trash, restore items from the trash, report the trashcan contents, and empty the trash. ’ctrash’ is designed as a safer, and more flexible alternative to the ’rm’ and ’rmdir’ commands.

  • gString text internationalization tool.
    gString implements a C++ class that may be integraged into any application for smooth and painless text formatting, and for converting between UTF-8 and ‘wchar_t’ (wide) character encoding.

    The gString class is lightweight, consisting of one C++ source module and one header file. The gString class may be directly integrated into an application, or may be built as a link library.
    The gString class is also embedded within the NcDialog API library (see above).

  • Taggit (taggit) is a demonstration program written for students, or for anyone who wishes to create a console application with a multilingual user interface.

    Conceptually, Taggit is an audio-file tag editor (metadata editor), and is album oriented rather than file oriented so that all audio files in an album may be edited simultaneously.

    Taggit is not intended as a full-featured tag editor; for instance, Taggit does not access online databases of audio tag information. Taggit fully supports tag editing for audio formats: MP3, M4A, OGG/Vorbis and WMA.

    The OGG/Vorbis I specification is supported for all text tags in '.ogg' and '.oga' audio files.

    For MP3 audio files, all tag frames of the ID3v2.3 standard are supported, along with some features of ID3v2.4, such as support for UTF-8 text encoding which enables writing text tags in any language.

    Taggit is implemented in four(4) user interface languages: Español (Spanish), Zhōngwén (中文) (Chinese, simplified), Tiếng Việt (Vietnamese) and English (U.S.). Additional user interface languages (both LTR and RTL) may be added with minimum effort.

  • AnsiCmd Library and EarthPoints test application.
    The AnsiCmd link library defines a simple and comprehensive way to configure a console program’s text attributes, as well as cursor positioning, area erasure and other operations defined by ANSI escape sequences in the ANSI X3.64 standard.

    ANSI escape sequences are available for setting foreground and background color, including 3-bit and 4-bit color, 8-bit color, 24-bit (RGB) color, greyscale color, and the aixterm (IBM) extensions.

    Text modifiers include bold/faint, italic, underline, double-underline, overline, strikethrough, blinking text (fast/slow), reversed fgnd/bkgnd, and invisible text; as well as commands to disable each of these modifiers.

    A suite of cursor-positioning commands and text erasure commands are also supported.

    The standard also specifies escape sequences for little-used and seldom-supported options such as Fractur, Ideogram, Framed, Encircled and Alternate-font. The AnsiCmd library implements these escape sequence commands; however, most modern terminal emulators do not support them.

    AnsiCmd also provides some common terminal configuration operations such as flexible input buffering options and capture of the Panic Button (break signal).

    Also included in the AnsiCmd library are application-level functions such as line-drawing, creation of windowed objects, direct control of the cursor-movent keys and reasonably sophisticated user input methods.

    Because this is primarily an experimental project, comprehensive testing of all functionality is integrated into the AnsiCmd library.

  • Source Profiler (srcprof) is a source code analysis tool for determining the ‘maintainability’ of source code modules.

    ‘srcprof’ can be used to profile source code for high-level languages such as C, C++ and Java, as well as various assembly languages and scripting languages such as Python, Perl and Ruby. For a complete list of currently-supported source languages, please see the Source Profiler documentation.

    ’srcprof’ can be used both as a productivity-measurement tool and as a tool for testing source code quality based on an evaluation of its ‘maintainability’.

    Source Profiler is a console-based utility, which runs as either a pure, command-line utility, OR as a dialog application based on the NcDialog API.

  • WaylandCB, clipboard access for console applications.
    Access to the system clipboard under the Wayland communications protocol, leveraging Sergey Bugaev’s "wl-clipboard" application suite.

    WaylandCB is a simple C++ class definition which provides console applications with seemless access to the system clipboard.

  • Exercalc (ecalc) is a utility for tracking daily exercise activity.
    Specify the type of exercise, walk/bike/run/cardio/free weights, etc. and either the elapsed time, distance travelled, or energy expended (KCal or METs). Exercalc then calculates the efficiency and progress over time. Archive the data, retrieve and analyze the data in various ways including tables, comparisons and bar charts.

    The application is specifically designed to be a student exercise in creating applications which incorporate a multi-language user interface. Exercalc is implemented in four(4) user interface languages: Español (Spanish), Zhōngwén (中文) (Chinese, simplified), Tiếng Việt (Vietnamese) and English (U.S.). Additional user interface languages (both LTR and RTL) may be added with minimum effort.

  • DVD Repair (dvdrep) is a utility for exploring the contents of a damaged DVD video disc and rescuing as much of the data as possible.

    ‘dvdrep’ can be used to rescue data from any non-encrypted DVD video source disc that is formatted using the Universal Disc Format (UDF) filesystem (as all commercially produced DVD movies are).

    ‘dvdrep’ takes a layered approach to the analysis of the source disc. A detailed log file is maintained for each step of the process in case manual intervention is needed at a later step.

    DVD Repair is based on the NcDialog API, and thus will run in almost any GNU/Linux or UNIX terminal environment.

  • crcPlus (crcplus) is a reference model and demonstration program for implementating CRC (Cyclic Redundancy Check) data error detection. crcPlus provides a reliable reference algorithm for verifying the function of other CRC generators and decoders as well as providing the tools to build a fully customizable hash table (lookup table) for creating your own high-speed CRC generator.
  • Various other Linux utilities designed as academic exercises are also available for student use. For example: interprocess communication pipes, FIFOs, sockets, shared memory blocks, multi-threading, the ’Sleeping Barber’ problem and so on.
    These cannot be considered as production-worthy, but they demonstrate the concepts in simple terms.





Index

Jump to:   0  
A   B   C   D   E   F   G   H   I   L   M   N   O   P   Q   R   S   T   U   V   W  
Index Entry  Section

0
01 Overview: Overview
02 CSS Definition File: CSS Definition File
02.01 Summary of CSS Definitions: Summary of CSS Definitions
02.02 Applying the CSS Definitions: Applying the CSS Definitions
02.03 Adjusting Style Definitions: Adjusting Style Definitions
03 HTML Post-processing: HTML Post-processing
03.01 Infodoc Post-processor: Infodoc Post-processor
03.01.01 Post-processor Overview: Post-processor Overview
03.01.02 Invoking idpp: Invoking idpp
03.01.03 Interface Logic: Interface Logic
03.01.04 Interactive Processing: Interactive Processing
03.01.05 Build idpp from source: Build idpp from source
03.02 Manual Post-processing: Manual Post-processing
03.02.01 Basic Manual Processing: Basic Manual Processing
03.02.02 Manual List Processing: Manual List Processing
03.02.03 Other Manual Processing: Other Manual Processing
03.02.04 Texinfo HTML Options: Texinfo HTML Options
03.02.04a Embedded HTML Code: Embedded HTML Code
03.02.04b Texinfo Build Options: Texinfo Build Options
03.02.04c Including Entire CSS File: Including Entire CSS File
03.02.05 Post-processing Notes: Post-processing Notes
04 Makeinfo Testing: Makeinfo Testing
04.01 Testing Overview: Testing Overview
04.02 Default Style Set: Default Style Set
04.03 Basic Tests: Basic Tests
04.04 List Commands: List Commands
04.04.01 Itemized Lists: Itemized Lists
04.04.02 Enumeration Lists: Enumeration Lists
04.05 Block Commands: Block Commands
04.05.01 Quotation Commands: Quotation Commands
04.05.02 Indentedblock Commands: Indentedblock Commands
04.05.03 Example Commands: Example Commands
04.05.04 Display Commands: Display Commands
04.05.05 Format Commands: Format Commands
04.05.06 Verbatim Commands: Verbatim Commands
04.05.07 Misc Block Modifiers: Misc Block Modifiers
04.05.09 Comparison Chart: Comparison Chart
04.06 Table and Multitable: Table and Multitable
04.07 Font Modification: Font Modification
04.08 Object Indicators: Object Indicators
04.09 InfoMenu Structure: InfoMenu Structure
04.10 Info TOC and Index: Info TOC and Index
04.11 Misc Formatting: Misc Formatting
04.12 Macros In Infodoc: Macros In Infodoc
05 Idpp Testing: Idpp Testing
05.01 Idpp List Processing: Idpp List Processing
05.02 Idpp Block Processing: Idpp Block Processing
05.03 Idpp Misc Tests: Idpp Misc Tests
05.04 Ad-hoc Tests: Ad-hoc Tests
06 Technical Support: Technical Support
07 Copyright Notice: Copyright Notice
07.01 GNU General Public License: GNU General Public License
07.02 GNU Free Documentation License: GNU Free Documentation License

A
adjust style definitions: Adjusting Style Definitions
apply CSS to HTML document: Applying the CSS Definitions
arguments, idpp command line: Invoking idpp
auto-generated styles: Default Style Set
automatic post-processing: Infodoc Post-processor

B
basic post-processing: Basic Manual Processing
basic tests, makeinfo: Basic Tests
block command comparison chart: Comparison Chart
block environments: Block Commands
block modifiers: Misc Block Modifiers
block text, embedded tokens: Macros In Infodoc
body text: Basic Tests
browsers, testing done with: CSS Definition File
bullet lists: Itemized Lists

C
cartouche option: Invoking idpp
cartouche, embedded tokens: Macros In Infodoc
cartouche, makeinfo: Misc Block Modifiers
character type and style: Font Modification
commands for data blocks: Block Commands
commas inside macros: Macros In Infodoc
comparison chart for block commands: Comparison Chart
contact info: Technical Support
contact information: Technical Support
cross-references: Misc Block Modifiers

D
date_in_header: Texinfo Build Options
default HTML styles: Default Style Set
display command: Display Commands
document index: Info TOC and Index

E
em (font size): Macros In Infodoc
embedded tokens: Macros In Infodoc
embedded tokens, block text: Macros In Infodoc
embedded tokens, cartouche: Macros In Infodoc
embedded tokens, enumerate: Macros In Infodoc
embedded tokens, itemize: Macros In Infodoc
embedded tokens, multitable: Macros In Infodoc
embedded tokens, multitable: Macros In Infodoc
enumerate command, texinfo: Enumeration Lists
enumerate, embedded tokens: Macros In Infodoc
environments, blocks: Block Commands
example command: Example Commands

F
font, modifying: Font Modification
format command: Format Commands

G
global document commands, Texinfo: Texinfo HTML Options

H
headings: Basic Tests
HTML automatic post-processor: Infodoc Post-processor
HTML customization variables: Texinfo HTML Options

I
idpp command line arguments: Invoking idpp
include CSS in texi source: Including Entire CSS File
indentedblock command: Indentedblock Commands
index, document: Info TOC and Index
indicators, object-type: Object Indicators
interactive mode: Invoking idpp
interactive processing: Interactive Processing
introduction to Infodoc: Overview
invoking idpp: Invoking idpp
itemize command, texinfo: Itemized Lists
itemize, embedded tokens: Macros In Infodoc

L
large-block macros: Post-processor Overview
LargeItemize macro: Macros In Infodoc
largeverbatim command: Verbatim Commands
linebreak, none: Misc Block Modifiers
lisp command: Example Commands
list special processing: List Commands
lists, ordered and unordered: List Commands
lists, post-processing of: Basic Manual Processing
lists, post-processing of: Manual List Processing
logic, interface: Interface Logic

M
macros, commas inside: Macros In Infodoc
macros, text decoration: Macros In Infodoc
macros, using: Macros In Infodoc
macros,small- and large-block: Post-processor Overview
main menu: Top
makeinfo basic tests: Basic Tests
makeinfo tables: Table and Multitable
manual post-processing: Manual Post-processing
menus, Texinfo: InfoMenu Structure
miscellaneous makeinfo tests: Misc Formatting
miscellaneous tests: Misc Formatting
modifying font: Font Modification
multitable: Table and Multitable
multitable command: Table and Multitable
multitable, embedded tokens: Macros In Infodoc
multitable, embedded tokens: Macros In Infodoc

N
non-breaking macro: Misc Block Modifiers
non-breaking xrefs: Misc Block Modifiers
no_cartouche (deprecated): Invoking idpp
nuclear annihilation: Adjusting Style Definitions

O
object-type indicator: Object Indicators
ol lists: Enumeration Lists
operational overview: Overview
option, cartouche: Invoking idpp
optional post-processing: Other Manual Processing
ordered lists: Enumeration Lists
other projects: Technical Support
overview: Overview
overview of CSS definitions: Summary of CSS Definitions
overview of testing: Testing Overview

P
panic button: Invoking idpp
paragraph text: Basic Tests
post-processing of lists: Manual List Processing
post-processing, basic: Basic Manual Processing
post-processing, optional: Other Manual Processing

Q
quotation command: Quotation Commands

R
raw HTML output: Post-processing Notes
response file: Interface Logic

S
small-block macros: Post-processor Overview
smalldisplay command: Display Commands
smallexample command: Example Commands
smallformat command: Format Commands
smallindentedblock command: Indentedblock Commands
SmallItemize macro: Macros In Infodoc
smalllisp command: Example Commands
smallquotation command: Quotation Commands
smallverbatim command: Verbatim Commands
style definitions, adjusting: Adjusting Style Definitions
style stubs: Default Style Set
support: Technical Support
switches, idpp command line: Invoking idpp

T
table of contents, Texinfo: Info TOC and Index
tables, makeinfo: Table and Multitable
Technical Support: Technical Support
testing, basic makeinfo: Basic Tests
testing, overview of: Testing Overview
texi-to-HTML converter: Post-processing Notes
texinfo enumerate command: Enumeration Lists
Texinfo global document commands: Texinfo HTML Options
texinfo itemize command: Itemized Lists
Texinfo menus: InfoMenu Structure
Texinfo table of contents: Info TOC and Index
text decoration macros: Macros In Infodoc
tokens, embedded tokens: Macros In Infodoc
translate menus to HTML: InfoMenu Structure
translate TOC to HTML: Info TOC and Index

U
ul lists: Itemized Lists
unordered lists: Itemized Lists
using macros: Macros In Infodoc

V
variables, HTML customization: Texinfo HTML Options
verbatim command: Verbatim Commands

W
w, no linebreak: Misc Block Modifiers




Notes on Index Formatting

The generated index looks quite good in HTML without any modification at all. There are only two things we do to style the Index: 1) We define the class "a.summary-letter-printindex" which removes the underline from the summary letters. 2) We define the <th> tag of the "cp-letters-header-printindex" and "cp-letters-footer-printindex" classes which removes the underline from the summary table header. Please refer to Post-processor Overview for more information on post-processing.