text:
|• Overview:
|Description of the Infodoc package
|• CSS Definition File:
|Understanding the CSS definitions
|• HTML Post-processing:
|Automatic and manual post-processing
|• Makeinfo Testing:
|Validation tests: makeinfo 'info' and HTML output
|• Idpp Testing:
|Automatic post-processor parsing/modification tests
|• Technical Support:
|Make suggestions, report problems
|• Copyright Notice:
|Boring but useful
|• Index:
|Index of topics and test cases
Infodoc CSS styles and HTML post-processor documentation.
This document describes version 0.0.07 of 'infodoc-styles.css'
and version 0.0.04 of 'idpp'.
This document is also a Texinfo Source Template used for testing the conversion of 'texi' source to HTML output.
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.
Next: CSS Definition File, Previous: Top, Up: Top [Contents][Index]
"I know it's only documentation, but I like it, like it, yes I do.
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-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
See CSS Definition File, (version: 0.0.07)
'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.04)
'infodoc.texi' is the Texinfo source code 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 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 also suffers from a number of bugs and logical inconsistencies for which the CSS definitions in conjunction with the 'idpp' post-processor attempts to compensate.
Next: HTML Post-processing, Previous: Overview, Up: Top [Contents][Index]
The CSS definition file, 'infodoc-styles.css' robustly defines all the CSS class definitions called out in the HTML documents generated by the Texinfo 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), Chrome(tm) and Opera(tm) browsers. (Note that Internet Explorer(tm) version 11 and higher renders sloppy, but readable formatting, although in our opinion, only a fool would use IE.)
|• Summary of CSS Definitions:
|An overview of the definition file
|• Applying the CSS Definitions:
|Applying the definitions to your HTML document
|• Adjusting Style Definitions:
|Tweaking the CSS style definitions
Next: Applying the CSS Definitions, Up: CSS Definition File [Contents][Index]
The CSS definitions in 'infodoc-styles.css' fall into the following broad categories.
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 our 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 (see Adjusting Style Definitions) for a detailed description of each of these style elements.
|Background Color
|Text Color
|Font Size
|Font Family
|Container Width
|'infodoc_container' class
|max-width:, padding-right:, padding-left:
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.
|♦♦♦ Block Environments ♦♦♦
|'quotation' class,
 tag
|see Quotation Commands
|'smallquotation' class
|'indentedblock' class
|see Indentedblock Commands
|'smallindentedblock' class
|'example' class, 'example.pre' class
|see Example Commands
|'smallexample' class,
'smallexample.pre' class
|'lisp' class,
'lisp.pre' class
|see Example Commands
|'smalllisp' class,
'smalllisp.pre' class
|'display' class, 'display.pre' class
|see Display Commands
|'smalldisplay' class,
'smalldisplay.pre' class
|'format' class, 'format.pre' class
|see Format Commands
|'smallformat' class,
'smallformat.pre' class
|
 tag,
'pre.verbatim' class
|see Verbatim Command
|♦♦♦ Block Modifiers ♦♦♦
|

|see Misc Block Modifiers
|

|(not supported in HTML)
|'table.cartouche' class
|'nocodebreak' class
|'nolinebreak' class, ' '
|♦♦♦ Lists ♦♦♦
|'no-bullet' class
'disc-bullet' class
'circle-bullet' class
'square-bullet' class
'custom-bullet' class
|see Itemized Lists
|'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-custom' class
|see Enumerated Lists
|♦♦♦ Tables ♦♦♦
|
 tag, plus
, ,

, , 'table.bordered' class
and its subclasses
|see Table and Multitable
|
 tag, plus
,
,

|♦♦♦ Font Modifiers ♦♦♦
|@sc (smallcaps)
| tag
|see Font Modification
|@emph (emphasis)
| tag
| tag
|@b (bold)
| tag
|@i (italic)
| tag
|@r (roman)
|'roman' class
|@t (typewriter)
|<tt> tag (redefined)
|'sansserif' class
| tag
|♦♦♦ Object Indicators ♦♦♦
| tag
|see Object Indicators
|<samp> tag
|<var> tag
| tag
| tag
| tag,
'kbd' class(discarded)
| tag
|<samp> tag
| tag
|<samp> tag
| tag
|<tt> tag
|<tt> tag,
'key' class(discarded)
|<acronym> tag (redefined)
|
 tag
|
|
|♦♦♦ Headings ♦♦♦
|Document Title
|
 tag (redefined)
|Chapter Titles
|
 tag (redefined)
|
 tag
|see Basic Tests
|
 tag
|
 tag
|
 tag
|'h4.subsubsection' class
|'h4.subsubheading' class
|Level-5 Heading
|
 tag
redefined, but not used
by texi-to-HTML converter
|♦♦♦ Miscellaneous ♦♦♦
|Table of Contents
|'contents' class
|see InfoTOC Structure
|Texinfo Menus
|'menu' class plus
|see InfoMenu Structure
|'index-cp' class,
'jumpto' class
|see Index Notes
|Paragraph Text
|
 tag (redefined)
Note that each block
environment defines
it own
 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 carefully 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).
Next: Adjusting Style Definitions, Previous: Summary of CSS Definitions, Up: CSS Definition File [Contents][Index]
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
See HTML Post-processing. .
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.
Previous: Applying the CSS Definitions, Up: CSS Definition File [Contents][Index]
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: Always make a backup copy of the definition file in case you decide to undo your changes.
The CSS definitions which apply to the whole document are located near the top of the file inside the definition of the  tag.
or visit: http://w3.org/
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: Helvetica, Arial, "Lucida Grande", sans-serif;
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;
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:

 ...

 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:
Use care when adjusting individual style definitions because inheritance of style elements is an important issues 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. :-)
Next: Makeinfo Testing, Previous: CSS Definition File, Up: Top [Contents][Index]
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:
|Modifying the HTML mark-up interactively
|• Manual Post-processing:
|Modifying the HTML mark-up manually
Next: Manual Post-processing, Up: HTML Post-processing [Contents][Index]
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!
|• Post-processor Overview:
|Why post-processing?
|• Text Mode:
|Text-only operational mode
|• Interactive Mode:
|Dialog-based operational mode
|• Invoking idpp:
|Specify the processing options
|• Interface Logic:
|Human-to-computer logical interaction
|• Build idpp from source:
|Building the idpp utility for your machine
Next: Text Mode, Up: Infodoc Post-processor [Contents][Index]
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.
This section describes the modifications made to the source document
if no process-modification switches are specified on the command line.
See 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.
'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.
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:
Lists (@itemize and @enumerate) created inside an @indentedblock or @smallindentedblock environment 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' equivalents). The HTML markup generated by the texi-to-HTML converter in these blocks can become quite tortured and difficult to parse. For this reason, 'idpp' does not scan the contents of preformatted blocks, but merely copies the block contents unmodified from source to target.
Also, Texinfo allows for blocks nested within blocks to the limit of
the margins. It is recommended, however, that nested blocks be used
cautiously if the document is to be converted to HTML.
See Blocks Inside Blocks.
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.
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.
- If you accidentally run 'idpp' a second time on the same document using the same command-line switches, it SHOULD create an identical copy of the document, but this is not guaranteed. - If you run 'idpp' a second time on the same document using DIFFERENT command-line switches, the output of the second pass will PROBABLY be what you expect, but again, this cannot be guaranteed.
Next: Interactive Mode, Previous: Post-processor Overview, Up: Infodoc Post-processor [Contents][Index]
When invoked in Text Mode, 'idpp' is 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). Input may come from from the keyboard or from a re-directed response file. Output may be redirected to a UTF-8 text file if desired.
With few exceptions, after initial invocation, Text Mode processing occurs without user intervention. Processing is quite fast. For instance, the HTML-formatted documentation for this package contains approximately 5,500 lines of HTML markup code which on a relatively ordinary system is processed in less than two (2) seconds excluding the time spent waiting for user decisions.
Please see a detailed description of the available processing options in the chapter see Invoking idpp.
Next: Invoking idpp, Previous: Text Mode, Up: Infodoc Post-processor [Contents][Index]
The dialog-based user interface for 'idpp' is not yet implemented.
If there is user demand for Interactive Mode processing, the author will implement it in a later release.
The idea behind a dialog-based user interface is to provide clearer feedback on the processing being done AND to provide the user with finer control over the processing options.
The most useful functions of an interactive post-processor will be to overcome Texinfo shortcommings regarding HTML lists, to format tables and to allow the user to adjust line spacing in the HTML output.
Additionally, Interactive Mode would allow convenient adjustment
of the whole-document options in the CSS style-definition file:
1) background color
2) base text color
3) base font size
4) font family
5) container dimensions
For more information, see Adjusting Style Definitions.
Next: Interface Logic, Previous: Interactive Mode, Up: Infodoc Post-processor [Contents][Index]
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.
Usage : idpp [OPTIONS][HTML_FILENAMES] Example: idpp -to --no_meta home.htm
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 -t MyNovel.html mnChapter01.html mnChapter02.html mnChapter03.html
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.
Text Mode is the application default. If no processing mode is specified,
then Text Mode is assumed.
See Text Mode, for a description of the Text Mode interface.
Interactive Mode is not currently implemented.
See Interactive Mode.
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.
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.
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.
♦ Interactive Command ♦
Application prompts for a decision on each
 list.
Because Texinfo/makeinfo incompletely implements ordered lists in HTML-formatted documents, some of your original data may have been lost; specifically, the enumeration type and the sequence start point. This option (and the '-p' option below) allow you to interactively specify these lost parameters.
Example Prompt: ____________________________ Enumerated List: Line: 340 First Line Item:
 Buying your first car
 Choose Enumeration type (decimal is the default) d:decimal D:leading-zero decimal a:lower case alpha A:upper case alpha r:lower case Roman R:upper case Roman g:lower case Greek c:custom enumeration your choice: _
The prompt shown above indicates the line number of the source file at which the
 list was found and as a reference, also displays the first line of the first item of the list.
Your response should be a single character selected from the options provided, followed by the 'ENTER' key. If you enter an invalid response, you will be re-prompted until you select a valid response, or until you hit the Panic Button (CTRL+C)
['default_token' response == 'd' (see response file)]
♦ Interactive Command ♦
By default each ordered-sequence list 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 may contain a list that is broken into sections. Use this option to ensure that each section of your list begins with the desired sequence number.
Note that by specifying this option you are also implicity selecting the '-o' option above.
Example Prompt: ____________________________ Enumerated List: Line: 340 First Line Item:
 Buying your first car
 Choose Enumeration type (decimal is the default) d:decimal D:leading-zero decimal a:lower case alpha A:upper case alpha r:lower case Roman R:upper case Roman g:lower case Greek c:custom enumeration your choice: A Sequence start(1-n): _
Your response should be a decimal numeric value of one (1) or greater, followed by the 'ENTER' key.
For example, if you have an list whose items are ordered by lower-case alpha, and you want the sequence to begin at the letter 'e', you would respond to the prompt with the decimal value '5' i.e. the 5th letter of the alphabet.
If you enter a non-numeric value or a value less than zero, you will be re-prompted until you enter a valid number, or until you hit the Panic Button (CTRL+C).
['default_token' response == '1' (see response file)]
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 -dpublic_html idpp -d ../../src_dir idpp -d=/home/Sam/Documents/htm_dir
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
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.
By default, the Table of Contents is unmodified. For more
information on how the Table of Contents is constructed, please
see InfoTOC Structure.
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.
By default, the Table of Contents is unmodified. For more
information on how the Table of Contents is constructed, please
see InfoTOC Structure.
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: (top)... Example (specify display text): idpp --up_target='../parent_node.htm,(mama)' yields: ... Up: (mama)...
If your document is a stand-alone document, or if it is the top node on a document tree, then the auto-generated "Up" hyperlink at the top of the document will probably be pointing to an invalid target by default (but see the Texinfo customization variable, 'TOP_NODE_UP_URL').
If the user clicks on this invalid hyperlink, the browser will display a message that the target was not found. This would be confusing for the user and embarrassing for you, the designer. For this reason, 'idpp', by default, points this hyperlink to the top of the current page (but see the '--no_uplink' option below).
Note that for info-format documents, this default "Up" link would be used to link the document into the top node of the 'info' document tree, but this is usually not applicable to the top of an HTML document tree.
♦ Interactive Command ♦
Draw tables in the HTML document using a grid between elements and a border around the entire table.
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, use the --table_border option to draw the elements of the table with borders.
The --table_border option has two (2) sub-options.
Note that the table constructs which define the Chapter Menus
and the document's Index tables are never given borders.
Examples: ./idpp --table_border mypage.html ./idpp --table_border=all mypage.html ./idpp --table_border=specify mypage.html
If invoked with the sub-option, 'specify', then for each table found in the source document, you will be asked whether to draw a border around the table.
The following examples are simple tables created using the Texinfo @multitable command. In the HTML-format document, 'infodoc_css.html' (with CSS style applied), the first instance is drawn without a border, and the second instance is drawn with a border.
|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'
|row 1-a, bordered
|row 1-b, bordered
|row 1-c, bordered
|row 2-a, bordered
|row 2-b, bordered
|row 2-c, bordered
|row 3-a, bordered
|row 3-b, bordered
|row 3-c, bordered
This is the prompt which asks whether you want this table to have a border.
Example Prompt: ____________________________ Table found on Line:1350 First Row:

HEADING A	. . . Add border to this table? your choice (y/n): _
The prompt shown above indicates the line number of the source file at which the
 tag was found and as a reference, also displays the data of the first column of the first row of the table.
Note that for this example, the first row of the table is a heading row, but if your table has no column headings, then the first data row will be displayed.
Your response should be either a 'y' or an 'n', followed by the 'ENTER' key. If you enter an invalid response, you will be re-prompted until you select a valid response, or until you hit the Panic Button (CTRL+C).
['default_token' response == 'n' (see response file)]
The texi-to-HTML converter inserts some (rather useless) metadata elements, links and other data into the '...' 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 '' block, just above the '' 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 (text only) 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.
Until this option is implemented, you may manually edit the CSS definition file to adjust these parameters.
(See Adjusting Style Definitions.)
- - - - - - - - - -
Interactively edit specific CSS definitions in the 'infodoc-styles.css' definition file, or the specified alternate CSS file.
Examples: ./idpp --css_mods ./idpp --css_mods -f=infodoc-styles.css ./idpp --css_mods -f=myCSSdefs.css
Note that if this option is specified, then any HTML source files and HTML post-processing options specified on the command line are ignored. Only the '-f=alternate_css_filename.css' option is recognized. (see idpp -f option for details.).
The current values for the following CSS parameters are displayed, and you may specify new values for these parameters as desired.
Note that the original CSS file is not modified. Instead it is renamed according to the file's modification date and changes are written to a new file using the original filename.
For a more detailed discussion of adjusting the CSS definitions, please see Adjusting Style Definitions.
Because the terminal window is not capable of displaying the colors available to a browser application, only the hexadecimal values for the background and foreground colors are shown, (sorry about that). To select the desired foreground or background color, please visit the author's website for a demonstration of the so-called web-safe colors available to browser applications. Chart of Web-Safe Colors
The base font size that you choose for your document is based primarily on the screen resolution of the systems on which the document will be displayed. For instance, a 10pt or 12pt point font is clearly visible on a 640x480 pixel display, but is nearly unreadable on a modern 1080p (1920x1080 pixel) display.
The base font size is the size of text displayed in a normal paragraph (like this paragraph) which contains no additional styling. We have chosen our default value (referred to as '1.0em;') because it is readily visible to average college-student eyes at 1080p display resolution. The size of all other text in the document is calculated as a percentage of this base size. Thus, if you adjust this base size, all text in the document will be automatically adjusted as well.
As an additional note, if your web content targets an older audience or those with visual disabilities, you may want to increase the font size to compensate for the potentially weaker eyesight of your visitors. If you still get complaints, then your tech support staff should be prepared to explain the universal browser functions: 'CTRL+' and 'CTRL-'.
Because display resolution has a significant impact on display of HTML documents in a browser, the layout you craft so carefully on your development system may be rendered in a significantly different format on other systems. For this reason it is generally a good idea to set a maximum width for display of your document. In this way, you can be confident that the displayed document will be quite similar on a large majority of systems.
Our artistic consultant believes (and we concur) that the width of a document should be limited to a range of 1,000 to 1,600 pixels for maximum readability. We have chosen a conservative value for the default container width, because it is an aesthetic match to the corresponding info-format document, but you should select a value that works for YOU.
The data container may optionally be specified with a border. Currently, we are undecided whether the document looks better with, or without a border, and the style of that border is of course a matter of personal preference.
The Infodoc package is distributed with this border invisible; however, please feel free to experiment with the width, style and color to see what works best for you.
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 -tcov --no_mods testdoc.html
The <!DOCTYPE ...>' specification is the first line in an HTML file and specifies the HTML-version criteria that the browser should use in interpreting the document.
Unfortunately, the texi-to-HTML converter specifies the ancient 'HTML4.01 transitional' version. For this reason, 'idpp' replaces this with the standard '<!DOCTYPE html>' specifier by default.
However, if your document specifically indicates an HTML version that the
browser should use (see the Texinfo 'DOCTYPE' configuration variable),
then use the '--no_doctype' option to preserve the intended
doctype data.
Please also see Texinfo Build Options.
Example: ./idpp --no_doctype mypage.html
For more information, see Post-processing Notes.
By default, 'idpp' removes all of the metadata tags of the form: '<meta name=...' from the ... 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
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
Please see Texinfo HTML Customization Variables.
For more information, also see idpp --my_metadata option, above.
By default, 'idpp' removes all of the <link> tags from the ... 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.
By default, the texi-to-HTML converter inserts a lot of (useless) information into the  tag which indicates the beginning of the user-visible part of the HTML document.
First, these values are all default values, and are therefore unnecessary. Second, they are outdated HTML constructs. Third, they may, and probably will interfere with the CSS style information in 'infodoc-styles.css'.
The 'idpp' post-processor discards all this garbage by default, leaving only a pristine '' tag.
However, if your document specifically indicates a  declaration (see the Texinfo 'BODYTEXT' configuration variable), then use the '--no_body' option to preserve the intended  data. (THIS IS NOT RECOMMENDED.)
Example: ./idpp --no_body mypage.html
For more information, see Post-processing Notes.
As mentioned in several places in this document, the Texinfo texi-to-HTML converter does not handle lists well. Fortunately, un-ordered (bullet) lists (created using the Texinfo @itemize command) can be easily corrected by the 'idpp' post-processor.
By default, 'idpp' reformats un-ordered lists without any human intervention. However, you can use the '--no_bullet' option to disable the automatic processing of un-ordered lists.
Example: ./idpp --no_bullet mypage.html
For more information, see Itemized Lists.
Do not modify the target specified in the "Up" hyperlink at the top of the document.
By default, 'idpp' modifies this link to prevent the browser from generating a 'target not found' message if the user clicks on the link. The defaut value for the hyperlink is set to the top of the current page, and the default display text for the link is set to "(top)".
Note that this option is incompatible with the '--up_target' option, and if both are specified, then the '--no_uplink' option will be ignored.
For more information, see idpp --up_target option above.
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 for the following block objects: 'format', 'display', 'example', 'lisp' and their 'smallformat' variants.
Use the '--no_block' option to disable this automatic adjustment.
Example: ./idpp --no_block mypage.html
For more information, see Other Manual Processing.
If you create a
 object using the Texinfo '@quotation' command or the '@smallquotation' command, then you may also have used the optional '@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 the '@quotation' or
'@smallquotation' block, then this option does nothing.
For more information, see Quotation Commands.
A 'cartouche' block is a paragraph enclosed within a border.
This command has no effect in info-format documents, but in HTML-format documents, the paragraph (
...
) object is surrounded by a border.
The Texinfo 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.
Our CSS definition file, 'infodoc-styles.css', fully defines the cartouche class, but this class conflicts with the directly-styled cartouche paragraph. Therefore, 'idpp' removes the inappropriate direct styling so that the 'cartouche' class can control the object. (Note that in the HTML version of this document, this paragraph is defined as a cartouche.)
Use the '--no_cartouche' option to disable this automatic adjustment.
Example: ./idpp --no_cartouche mypage.html
If the document contains no 'cartouche' objects, then this option
does nothing.
For more information, see Misc Block Modifiers.
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.
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.04 Copyright (C) 2014-2015 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 change and redistribute it. There is NO WARRANTY, to the extent permitted by law.
Display a list of available command-line options and brief examples.
Note that if specified, a request for Help overrides everything else on the command line (except '--version').
If this option is specified, then no source documents will be processed.
All examples are functionally equivalent: idpp --help idpp -h idpp -H idpp -?
Two additional options are defined for application debugging only:
'--scan' and '--book'
Because the definition of these options may change at any time, they are not documented here. Please refer to the 'idpp' source code (Idpp::GetCommandLineArgs method) for information on using these debugging options.
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.
Next: Build idpp from source, Previous: Invoking idpp, Up: Infodoc Post-processor [Contents][Index]
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....
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.
Example: Source document: 'mypage.html' is renamed as 'mypage.html~' Target document: is written as 'mypage.html'
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*
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.
— 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.
Example: ./idpp -toc mypage1.htm --table_border=all 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.
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'
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 -tcop mypage.html The following is also acceptable: ./idpp -tcopd=public_html mypage.html
Some long-form options have mandatory or optional arguments. If an argument is specified, it must be joined to its option with the '=' (equal sign) character without intervening spaces.
Example: ./idpp --up_target='../parent_node.htm' 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.
Example: ./idpp -top --table_border=specify mypage.html <response.txt
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 with response files because a change in your source document can easily cause the response file to become de-synchronized with the prompts. Also, using a response file on a source document that has already been post-processed will almost certainly cause the responses to be out-of-sequence.
As an alternative to using response files during document development, simply avoid specifying processing options that require interactive responses unless you are testing that particular part of the document.
Previous: Interface Logic, Up: Infodoc Post-processor [Contents][Index]
The 'idpp' utility in its current form is a simple console utility written in C++ and using the standard 'wide' character I/O streams 'wcout' and 'wcin'.
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'
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.)
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.
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, doing a standard build on each individual target system, (which will reference its shared libraries) is more reliable.
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.
Previous: Infodoc Post-processor, Up: HTML Post-processing [Contents][Index]
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:
|Minimum set of changes to HTML documents
|• Manual List Processing:
|Manual post-processing of
 and
 lists
|• Other Manual Processing:
|Optional, but useful modifications
|• Texinfo HTML Options:
|Texinfo options for generating HTML documents
|• Post-processing Notes:
|Notes on how the HTML document is constructed
Next: Manual List Processing, Up: Manual Post-processing [Contents][Index]
If desired, you can enable the border around this container by un-commenting the 'border: 1px solid;' line in the container definition.
Auto-generated: Up: (dir) Replace with: Up: (top) (this references the top of the current page) Or: Up: (docs) (example of the HTML page one level up in the tree)
Bulleted lists: @@itemize command, yields
...
 (bulleted) tag lists Enumerated Lists: @@enumerate command, yields
...
 (sequenced) tag lists.
Please refer to the next chapter discussing post-processing of lists: See Manual List Processing.
Next: Other Manual Processing, Previous: Basic Manual Processing, Up: Manual Post-processing [Contents][Index]
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.
Because the texi-to-HTML converter does not handle lists well, it is strongly recommended that all itemized/unordered/bulleted lists AND all enumerated/ordered/sequenced lists be scanned and assigned to specific list-class definitions.
Example :
 Becomes :
 Example :
 Becomes :
 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 requires significant post-processing. The HTML document is legible in its raw form; however, without post-processing, it looks significantly and confusingly different from the original document AND it will not meet any kind of professional criteria for HTML documentation.
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.
⚪ 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. ⚪ 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.
See also the test code for unorderd lists
(see Itemized Lists).
In order to implement the embedded-bullet construct described above, the texi-to-HTML converter unfortunately calls out the 'no-bullet' class for everything except the browser's default bullet type.
What this means in practical terms is that the actual bullet (if any) appearing in the HTML document is rather unpredictable. The following considerations contribute to the confusion:
– Note that this class definition implements the auto-generated HTML
 tags – If your .texi source uses the @itemize keyword with any bullet argument other than @bullet (or none), then whatever bullet you specified is ALREADY shown in the
 item, although it will appear as 'inside' the item. – If this class is not defined, then the (default) bullet rendered for each line item is placed outside the item. This is standard HTML behavior; however, you may now have TWO bullet characters in the HTML output. – Note that the '@itemize @w{}' sequence places a single space character where the bullet would have been, and the line items themselves need no modification. – Note that to allow the auto-generator output for lists to stand without modification, the 'no-bullet' class must be defined–either the default definition created by the auto generator OR in the infodoc-styles.css file (but not both).

 Becomes:

 Becomes:
 Then delete: a) the embedded degree or other symbol, and b) one space character which follows it
The HTML will now look as if the list was generated using direct HTML markup.

 Becomes:
 Then delete: a) the embedded symbol, and b) one space character which follows it
The HTML will now look as if the list was generated using direct HTML markup.

 OR
 Becomes:

See also the test code for ordered lists
(see Enumerated Lists).
'makeinfo' 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 count at '21'.
In HTML, numbered list are enclosed within

 tags, and can support
item counts in terms of:
decimal digits : 1, 2, 3 ... lower-case alpha: a ... z upper-case alpha: A ... Z lower-case Roman: i, ii, iii, iv, v, vi ... upper-case Roman: I, II, III, IV, V, VI ... lower-case Greek: α, β, γ, δ, ε, ζ ... decimal, leading '0': 01, 02, 03 ... 10, 11 ... As well as lower-latin, upper-latin, armenian, georgian and none.
HTML also supports starting the sequence at an arbitrary point. However the texi-to-HTML converter does not pass information about the enumeration type or start point to the HTML document. To specify the enumeration type and optionally the starting value during post-processing, please refer to the '-o' and '-p' options in see Invoking idpp.

 Becomes:

 Becomes:

 Becomes:

 Becomes:

 Becomes:

 Becomes:

 Becomes:

 Becomes:

Then edit the 'infodoc-styles.css' file to specify the enumeration type to be used. Additional types available in CSS3 are: decimal-leading-zero (infodoc default), lower-latin, upper-latin, armenian, georgian, inherit
Next: Texinfo HTML Options, Previous: Manual List Processing, Up: Manual Post-processing [Contents][Index]

 This is block text. Becomes:

 This is block text.

 Becomes:

Scan for the sequence which indicates the @author output,
and move it INSIDE the '
' tag. Example:

He was a wise man who invented beer.

— Plato Becomes:
He was a wise man who invented beer.
— Plato
 Note that to beautify the 'author' line, the automatic post-processor takes this one step further:
He was a wise man who invented beer.
— Plato

 Becomes:

Note that the reason the texi-to-HTML converter declares a '
' 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 '
' element, but is does not harm the output. However, without removing 'border="1"' a double border will be generated around the paragraph.

Jump to: ... Becomes:

Jump to: ...
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.

 Back To HTML Docs Page
 and
 Back To HTML Docs Page

♦ 1st TOC level :
 ♦ 2nd TOC level :
 ♦ 3rd (and subsequent):

We like this modification to visually and logically distinguish the Table of Contents from the chapter menus, but it is of course optional.
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 enumerated lists, nested within other enumerated lists, and as detailed above, the Texinfo texi-to-HTML converter does a poor job of handling lists, especially nested 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.
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.
Next: Post-processing Notes, Previous: Other Manual Processing, Up: Manual Post-processing [Contents][Index]
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:
|Inserting HTML directly into texi source
|• Texinfo Build Options:
|Build options and customization variables
|• Including Entire CSS File:
|How to 'include' styles into source
Next: Texinfo Build Options, Up: Texinfo HTML Options [Contents][Index]
Two sets of Texinfo commands may be used to write data into your HTML document without 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:

 Big-ass text in an 'ifhtml' block.

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:
 Big-ass text in an 'ifhtml' block.
 :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.
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.
- - - - -
- - - - -
Next: Including Entire CSS File, Previous: Embedded HTML Code, Up: Texinfo HTML Options [Contents][Index]
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.
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.
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.
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.
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'.
Use of this customization variable is unlikely to affect 'idpp'.
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:
Please see Invoking idpp.
Example makeinfo invocation: makeinfo --html -c CHAPTER_HEADER_LEVEL=3 mydoc.texi Example chapter heading:
My Favorite Chapter

Use of this customization variable is unlikely to affect 'idpp'.
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.
These extra elements are inserted at the end of the  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.
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
 or
 tag, respectively.
Example header (default):
 . . .
 Example header (in table):
 . . .

Note that 'infodoc-styles.css' contains a definition for the
 version of the header class, but it is disabled (commented out) by default. 'infodoc-styles.css' redefines the HTML
 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'.
Note that as of Texinfo 5.2, this option does not function. A huge number of warning and error messages are generated indicating that either the menu is missing, or the intra-page hyperlinks are upgefuched.
Note that an invocation with the following should do
approximately the same thing, but it is not recognized by makeinfo
as a valid option
'-c TREE_TRANSFORMATIONS=simple_menu'
In brief, DON'T USE THIS OPTION!
Example makeinfo invocation: makeinfo --html -c SIMPLE_MENU=1 mydoc.texi Example default menu:

...	...	...

 Example simple menu:

...

Default node entry: ... Up: (dir)... Example makeinfo invocation: makeinfo --html -c TOP_NODE_UP_URL='../../coolstuff.htm' mydoc.texi Example node entry: ... Up: (dir)...
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'.
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.
Example makeinfo invocation: makeinfo --html -c DOCTYPE='<!DOCTYPE html spam and eggs>' mydoc.texi Equivalent HTML markup: <!DOCTYPE html spam and eggs>
If you generate an HTML document using this customization variable, then you should also use the see idpp --no_doctype option so that the entry will be retained.
Default node entry: ... Up: (dir)... Example makeinfo invocation: makeinfo --html -c 'TOP_NODE_UP=(coolstuff)' mydoc.texi Example node entry: ... Up: (coolstuff)...
(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. Note also that the link will probably not be what was intended – this is a Texinfo bug.)
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'.
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!
Previous: Texinfo Build Options, Up: Texinfo HTML Options [Contents][Index]
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.
Previous: Texinfo HTML Options, Up: Manual Post-processing [Contents][Index]
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.
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
The above declaration is showing its age. Reasonably-strict HTML5
markup is recommended for all new projects. For this reason, the
above document header generated by 'makeinfo' should be replaced by
the new standard identifier:
<!DOCTYPE html>
Aside from a possible (very small) performance hit, this has no affect on the actual rendering of the document in any reasonably modern browser and will allow the browser to choose the correct level of standards compliance during rendering. Also, if you embed HTML markup directly into your '.texi' source document, it will probably not match the ancient HTML version referenced by the default DOCTYPE header.
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_doctype 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....
<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.6" > <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.
See also the post-processor '--no_meta' option:
see Invoking idpp.
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.
<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.
Because these stubs interfere with the equivalent, more robust definitions in the 'infodoc-styles.css' file, THEY MUST BE DELETED.

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  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.
examples:

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.
Note that for HTML documents the generated lists are incompletely
For more information: see Itemized Lists.
In HTML, unordered lists are enclosed within

 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
 CSS classes defined in the 'infodoc-styles.css' file.
Note that for HTML documents the generated lists are incompletely
For more information: see Enumerated Lists.
In HTML, ordered lists are enclosed within

 tags, and can support
a number of enumeration types.
The styles for ordered lists can be found in the group of
 CSS classes defined in the 'infodoc-styles.css' file.
Next: Idpp Testing, Previous: HTML Post-processing, Up: Top [Contents][Index]
|• Testing Overview:
|What we test, and why we test it
|• Default Style Set:
|List of HTML styles defined in the default output
|• Basic Tests:
|Test of headings and body text
|• List Commands:
|Test of 'itemize' and 'enumerate' lists
|• Block Commands:
|Data blocks, indent, quotation, etc.
|• Table and Multitable:
|Two-column and multi-column tables
|• Font Modification:
|Font modifiers for typeset and HTML output
|• Object Indicators:
|Various text attributes that indicate object type
|• InfoMenu Structure:
|Description of how 'info' menus are constructed
|• InfoTOC Structure:
|Description of the 'info' Table of Contents
|• Misc Formatting:
|Miscellaneous formatting tests
Next: Default Style Set, Up: Makeinfo Testing [Contents][Index]
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 5.2.
HTML rendering and post-processing verified in Firefox version 32.0.
Rebuilding the test suite from the 'infodoc_XX.texi' source requires
installation of the 'makeinfo' utility, version 5.2 or higher.
A 'Makefile' is provided which rebuilds the documents in both info-format and HTML-format.
Note that older versions of 'makeinfo' may work, but un-addressed bugs in these older versions may cause some loss of beauty in your document.
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 modifying the
execution line of the shell script to exclude the response file.
'./idpp/idpp -toc --table_border=specify infodoc_css.html'
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.
However, as of version 5.2, the converter does have a number of issues for which we try to compensate using our style definitions. 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 is a work-in-progress, so please leave us a note about your experiences.
Faithfully yours, Software Sam – http://www.SoftwareSam.us/
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Please note that a number of Texinfo bugs and other issues have been uncovered during the development of this project. The author has reported all these bugs and has discussed the other issues with the Texinfo group. Several bugs, both in the 'makeinfo' utility and in the HTML converter have already been corrected and will be included in the next major Texinfo release. Each identified issue is marked in the 'texi' source file using the literal sequence: '@c BUG!'. Note that this is a 'texi' comment and the current state of the bug repair is noted on that comment line. The author wishes to express his appreciation for the great support and encouragement received from Karl, Pat, Gavin, and the whole Texinfo group during the development of this project. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Next: Basic Tests, Previous: Testing Overview, Up: Makeinfo Testing [Contents][Index]
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.
It must be assumed that the designer of the texi-to-HTML converter considered this to be the complete list of style definitions needed to represent the conversion from texi source to HTML; so logically, if we fully define all of these classes in a CSS stylesheet file, then we will have covered most aspects of the designer's intent. Bug fixes and stylistic enhancements, of course, may follow.
Note that the entire contents of the  sequence is
commented out in the generated HTML code, BUT that these
definitions are nevertheless seen by the browser are are 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.
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.
This HTML style-definition sequence is generated by the texi-to-HTML converter and is located in the  section of the document. For convenience, we have listed the items functionally, rather than alphabetically, and have provided references to the locations in this document where the styles are invoked.
Note that if you apply the advanced styles defined in
infodoc-styles.css, then the auto-generated style sequence should be deleted from the HTML to avoid conflicts.
For more information, please see the chapter
see HTML Post-processing.

Note that the list is not symmetrical: ......................................
Next: List Commands, Previous: Default Style Set, Up: Makeinfo Testing [Contents][Index]
This section includes the most basic tests: Headings and Body Text.
In the HTML output, plain body text is written inside a set of
paragraph tags:
 ...

Note that 'makeinfo' automatically demotes @section 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. This automatic demotion does not apply to @heading commands because they are not indexed.
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:

...
 OR
...

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:

...
 OR
...

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:

...
 OR
...
 Note that the 'subsubheading' and subsubsection' classes are not defined by default, but ARE defined in 'infodoc-styles.css'.
Next: Block Commands, Previous: Basic Tests, Up: Makeinfo Testing [Contents][Index]
|• Itemized Lists:
|Test --html option 'itemize' list output
|• Enumerated Lists:
|Test --html option 'enumerate' list output
Next: Enumerated Lists, Up: List Commands [Contents][Index]
Itemized lists are created using the @itemize command with or without an argument indicating the bullet character to use.
Output to 'info' document: as specified
Output to 'HTML' document: as specified EXCEPT as noted below
The generated HTML for this command is:
For '@itemize' (no argument) and '@itemize @bullet' :

 ...

For other bullet types:

 ...

The texi-to-HTML conversion for itemized lists does not handle the bullet argument cleanly. The HTML code generated from the first two examples correctly takes advantage of the default HTML behavior.
However, the HTML code for the remaining examples references the 'no-bullet' class and whatever bullet character was specified is embedded inside the item itself. This would not be a big issue except that second-line indent for the item is vertically aligned with the bullet character rather than being inline with the body of the item. And although we can see the technical reason for this implementation, it looks nasty.
Note that the Infodoc Post-processor handles these embedded bullet characters and the associated vertical mis-alignment, but we are hoping that the next major release of Texinfo/makeinfo will correct the underlying problem.
Note that the '@minus' argument generates U+2212 (Unicode minus)
for 'info' output, but U+002D (ASCII minus) for HTML output.
Note that this generates an extra space character in the 'info' output where the bullet would have been, which is consistent with the other explicit bullet types. 'Outside position' in HTML output is blank, and no extra space character is embedded in the line item. This is the correct 'no-bullet' sequence for the HTML output.
The following examples are enclosed within a non-converted sequence:
'@html ... @end html'
The examples reference the style definitions within the 'infodoc-styles.css' file. If this file is not referenced within the HTML output, then the examples will be style-less and therefore not representative of the referenced classes.
This code will not be visible within the 'info' output, but should be passed through the texi-to-HTML converter as unprocessed HTML markup.
Some unprocessed HTML code examples for
 lists.
Requires linking in the 'infodoc-styles.css' file.
Note that HTML supports:
'disc' (default), 'circle' and 'square' bullet types, plus 'none'.
Note: Bullet character SHOULD NOT be embeded within the item.
if ( argument == none || argument == @bullet ) generate:
 ...
 OR
 ...
 (note: the default bullet type is 'disc') else if ( argument == @w{} || (TABLE OF CONTENTS) ) generate:
 ...
 else if ( argument == @textdegree || argument == @BCIRCLE(U+26AC) ) generate:
 ...
 else generate:
 ...
 (note: for bullet characters not supported by ) ( HTML, default to the third type of HTML bullet)
If the specified class is not defined, the browser will generate the default 'disc' bullet list (or nested-list equivalent); however, if the class is defined, then the browser will obey. (It's GOOD to be the king! − Mel Brooks)
Previous: Itemized Lists, Up: List Commands [Contents][Index]
Output to 'info' document: as specified
Output to 'HTML' document: as specified EXCEPT as noted below
The generated HTML for this command is:

 ...

 ...

The texi-to-HTML converter uses the HTML default sequence above for all markup generated from '@enumerate' lists, regardless of the argument specified in the 'texi' source. For lists specified using '@enumerate' (no argument) or '@enumerate 1', the HTML output defaults to the correct behavior.
Other enumeration types are ignored by the texi-to-HTML converter. While this is annoying and technically incorrect, we can't really classify it as a bug because the converter would have to be enhanced to support all the enumeration types tested here. So, let's call it an urgent enhancement request. Until that happens, we can use some post-processing to assign CSS definitions for each of the unsupported enumeration types.
The texi-to-HTML converter has an off-by-one problem with item spacing in lists. This is not a serious issue, but without styling, the 'info' output and the HTML output will have different spacing between items.
(targeted lower-alpha)
(targeted upper-alpha)
(targeted lower-roman, 'info' and HTML will not be symmetrical)
(targeted upper-roman, 'info' and HTML will not be symmetrical)
(targeted lower-greek, 'info' and HTML will not be symmetrical)
The following examples are enclosed within a non-converted sequence:
'@html ... @end html'
The examples reference the style definitions within the 'infodoc-styles.css' file. If this file is not referenced within the HTML output, then the examples will be style-less and therefore not representative of the referenced classes.
This code will not be visible within the 'info' output, but should be passed through the texi-to-HTML converter as unprocessed HTML markup.
Some unprocessed HTML code examples for
 lists.
Requires linking in the 'infodoc-styles.css' file.
Note that HTML supports multiple-language enumeration, but these are the basic set: 'decimal' (default), 'decimal-leading-zero', 'lower-alpha', 'upper alpha', 'lower-roman', 'upper-roman' and 'lower-greek' enumeration types, plus 'none'. Our Texinfo enumerated lists may never be fully symmetrical with HTML, because we allow starting the count at other than '1' 'a' 'A', (but see the (possibly deprecated) 'start' attribute for the
 element).Post-processing
At this time, (Texinfo 5.2) post-processing of the HTML will be necessary for support of the new enumerators. For lower- and upper-case Alpha which begin at 'a' or 'A', this is a straightforward addition of a class name.
 ...
 becomes
> ...
 or
> ...
 Other enumerators (or sequences that do not start at the beginning) are somewhat more complex because they currently have no common equivalent between the 'info' and HTML output formats.Enhancement Possibilities
An enhancement proposal has been submitted to the Texinfo group at gnu.org. This proposal outlines a method for direct support of Roman and Greek enumerators in Texinfo, and/or the method of embedding a specific class call-out for these into the HTML output. This proposal is under consideration. To see the full text of the proposal, visit the Texinfo bug report archive: 27 Nov. 2014 "@itemize and @enumerate enhancements" 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. − Alternatively, any lower-case Greek letter could signal a start of enumeration from that point. Example: @enumerate β Note however, that Roman sequences use ASCII characters, and these would be indistinguishable from alphabetical enumeration without an additional environment-modification switch. − 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.
// (test in order of likelihood) if ( argument == (DECIMAL NUMBER) || argument == (NONE) ) info: 1, 2, 3, 4, 5, ... (or start at specified point) HTML:
 ...
 else if ( argument >= 'a' && argument <= 'z' || argument == @loweralpha ) info: 'a'-'z' as currently implemented, @loweralpha as if it were 'a', or @loweralpha{n} where 'n' is the start point HTML:
 ...
 else if ( argument >= 'A' && argument <= 'Z' || @upperalpha ) info: 'A'-'Z' as currently implemented, @upperalpha as if it were 'A' or @upperalpha{n} where 'n' is the start point HTML:
 ...
 if ( argument == @lowerroman ) info: i, ii, iii, iv, v, ... or @lowerroman{n} where 'n' is the start point HTML:
 ...
 else if ( argument == @upperroman ) info: I, II, III, IV, V, ... or @upperroman{n} where 'n' is the start point HTML:
 ...
 else if ( argument == @lowergreek ) info: α, β, γ, δ, ε, ... or @lowergreek{n} where 'n' is the start point HTML:
 ...
 else // (default to decimal) info: 1, 2, 3, 4, 5, ... HTML:
 ...

Next: Table and Multitable, Previous: List Commands, Up: Makeinfo Testing [Contents][Index]
This chapter contains test data for the Texinfo block-oriented commands.
|• Quotation Commands:
|Left-and-right indented block (inherit, flow)
|• Indentedblock Commands:
|Left-indented block (inherit, flow)
|• Example Commands:
|Left-indented block (fixed, pre-formatted)
|• Display Commands:
|Left-indented block (inherit, pre-formatted)
|• Format Commands:
|Unindented block (inherit, pre-formatted)
|• Verbatim Command:
|Unindented block (fixed, pre-formatted, no expand)
|• Misc Block Modifiers:
|Miscellaneous block/non-block modifiers
|• Comparison Chart:
|Compare the characteristics of the block commands
Next: Indentedblock Commands, Up: Block Commands [Contents][Index]
The @quotation block has the following characteristics:
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:

 ...

The generated HTML for the optional @author sub-command is

 ...

Quotations are indented at both left and right edges so the text will flow in a more confined space. Examples show quotation block with the @author command, and both with and without the optional heading.
PLEASE NOTE: A bug in makeinfo v:5.2 which fails to define the right margin of the quotation block. (this bug has been reported)
(This bug does not apply to HTML output, but see next note).
PLEASE NOTE: The generated HTML for this is simply:

 ...

The HTML 'blockquote' tag does not include a 'margin-right modifier, and is therefore not the same thing as the @quotation command. This is a logical error in the HTML output, but 'infodoc-styles.css' compensates by redefining the HTML
 element to indent on both left and right margins.
PLEASE NOTE: There is another bug in makeinfo v:5.2 related to the @smallquotation command. The '@author' sub-command (if present) is not visible in the 'info' output.(This bug has been reported.) Note that the 'author' field is correctly generated in the HTML output.
PLEASE NOTE: 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.
PLEASE NOTE: Centering the @author output is simple and reasonably effective in the 'info' output, BUT looks like crap in the HTML output. For the HTML, we have recommended something like the following, but no action has been taken.
div.author {margin-left: 20%;} or div.author {text-indent: 20%;}

 ...

If using a percentage is unacceptable, just use the 'margin-left: 3.2em;' as is done in other indent situations.
PLEASE NOTE: Also related to the @author sub-command: 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.
Quotations with, and without optional 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.
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.
The @smallquotation is the same as @quotation above except that the
font size is smaller. The generated HTML output defines this block with

 ...

The generated HTML for the optional @author sub-command is

 ...

PLEASE NOTE: If the optional @author command is used with the @smallquotation command, the text for the author's name does not match the text of the quotation itself. This is a bug that should be addressed if the Texinfo group takes our suggestion about revising the output for @quotation and @smallquotation command blocks.
Until then, the automatic post-processor utility compensates.
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.
Next: Example Commands, Previous: Quotation Commands, Up: Block Commands [Contents][Index]
The @indentedblock command has the following characteristics:
Output to 'info' document: as specified
Output to 'HTML' document: as specified
The generated HTML for this command is:

 ...

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 generated HTML for this command is:

 ...

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.
Next: Display Commands, Previous: Indentedblock Commands, Up: Block Commands [Contents][Index]
The @exaple block has the following characteristics:
Output to 'info' document: as specified
Output to 'HTML' document: as specified EXCEPT as noted below
The generated HTML for this command is:

 ...

 ...

PLEASE NOTE: The HTML seems to be unnecessarily complex because the 'example' and 'smallexample' classes are themselves defined as 'pre' making the
 tag redundant.
See also discussion of the @exdent command: (see exdent issues).
PLEASE NOTE: The HTML font size changes to the page default. (which is almost certainly a bug!). We believe that the font family should change to fixed-width as specified, BUT that the font size should be inherited–or at most stepped down only one size.
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
 and
 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.
Surrounding text surrounding text surrounding text surrounding text
The @smallexample is the same as @example above except that the font size is smaller.
Surrounding text surrounding text surrounding text surrounding 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.
Surrounding text surrounding text surrounding text surrounding text
The @lisp and @smalllisp commands are really just special cases of @example and @smallexample, respectively.
The generated HTML for these commands is:

 ...

 ...

;;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))
Next: Format Commands, Previous: Example Commands, Up: Block Commands [Contents][Index]
The @display block has the following characteristics:
Output to 'info' document: as specified
Output to 'HTML' document: as specified EXCEPT as noted below
The generated HTML for these commands are:

 ...

 ...

PLEASE NOTE: The HTML seems to be unnecessarily complex because the 'display' and 'smalldisplay' classes are themselves defined as 'pre' making the
 tag redundant.
See also discussion of the @exdent command: (see exdent issues).
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
 and
 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 is the same as @display above except that the font size is smaller.
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.
Next: Verbatim Command, Previous: Display Commands, Up: Block Commands [Contents][Index]
The @format block has the following characteristics:
Output to 'info' document: as specified
Output to 'HTML' document: as specified EXCEPT as noted below
The generated HTML for these commands are:

 ...

 ...

PLEASE NOTE: The HTML seems to be unnecessarily complex because the 'format' and 'smallformat' classes are themselves defined as 'pre' making the
 tag redundant.
PLEASE NOTE: 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
 and
 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 is the same as @format above except that the font size is smaller.
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.
Next: Misc Block Modifiers, Previous: Format Commands, Up: Block Commands [Contents][Index]
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:
Output to 'info' document: as specified
Output to 'HTML' document: as specified EXCEPT as noted below
The generated HTML for this command is:

 ...

PLEASE NOTE: In the HTML output, the font size is reduced to the page default, which we believe is a bug caused by the font-size being inherited from the wrong place. What this means is that without the application of CSS style, the full-sized @verbatim example and the @smallformat+@verbatim example use the same font size.
This is Verbatim body text: with whitespace and line breaks preformatted. Note that @code{} block command below IS NOT processed. If cows can @code{jump} over the moon, then what do sheep jump over?
Note that there is no '@smallverbatim' command (it's an oxymoron); however, the same effect can be achieved by enclosing the 'verbatim' block within a 'smallformat' block.
The generated HTML for this command is:

 ...

This is small Verbatim body text: with whitespace and line breaks preformatted. Note that @code{} block command below IS NOT processed. If cows can @code{jump} over the moon, then what do sheep jump over?
Next: Comparison Chart, Previous: Verbatim Command, Up: Block Commands [Contents][Index]
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 HTML output 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:
 ...

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.
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.
Outside an environment (with and without explicit line breaks):
Generated HTML:
 ...

Jungle, George of the
Ape Mountain, South
Bukubu Territory
Deepest Africa
Jungle, George of the Ape Mountain, South Bukubu Territory Deepest Africa
In an @example environment:
Generated HTML: (see chapter for 'example' blocks)
Jungle, George of the Ape Mountain, South Bukubu Territory Deepest Africa
Outside an environment: Generated HTML: (
 ...
)
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.
In an @example environment:
Generated HTML: (see chapter for 'example' blocks)
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.
In an @indentedblock environment:
Generated HTML:

 ...

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.
This command applies only to output formats that can 'justify' i.e. spread text to fill the line. Text is left-justified (indented if specified), but leaving the right margin ragged.
@raggedright does not apply to 'info' and HTML output, where text should be written as ordinary paragraph text.
Generated HTML: (no HTML generated)
PLEASE NOTE: The paragraph below is not present at all in the HTML output; however, it should be written to the HTML output as ordinary paragraph text.
For output formats that support it, the paragraph within a
@cartouche{ ... } sequence is enclosed within a border.
Generated HTML:

 ...

Even thought the genenerated HTML is vastly more complex and fragile than it needs to be, it works by leveraging the definition for the
 tag, which in earlier versions of HTML was the only element that was allowed to have borders.
The HTML output for the following paragraph is enclosed within a border:
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 by default, the 'idpp' post
processor removes this obsolete syntax, allowing the 'cartouche' class
to take control of the styling.
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 block types are indented and pre-formatted.
@example block unmodified line
exdented line
unmodified line
@display block unmodified line
exdented line
unmodified line
Other block types either use automatic line breaks and/or are already positioned at the left margin. As of Texinfo version 5.2, the @exdent command is also (inappropriately) recognized within @quotation blocks and @indentedblock blocks where it successfully shifts the line to the left margin BUT unfortunately, this prevents the line from being automatically line wrapped.
@quotation block
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.
@indentedblock block
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.
PLEASE NOTE: The texi-to-HTML converter SHOULD ignore all instances of the @exdent command; however, the texi-to-HTML converter IS processing @exdent (but not well), with each line of the paragraph being treated as a separate paragraph (double-spaced AND without an exdented line). This problem has been discussed with the Texinfo group, and possible HTML support for the @exdent command in @example and @display blocks is under consideration
These commands apply only to text which is outside any block environment. However, the Texinfo documentation on this is unclear.
Note also that the global document command @paragraphindent must be set to
allow indenting of the first line of paragraphs in order for these commands
to be recognized. First-line indentation is not enabled for this document;
however, you can temporarily enable it by setting the global
@paragraphindent 3 to view indentation.
The @indent and @noindent commands do not apply to the HTML output.
Applying @indent
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.
Applying @noindent
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.
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 antirely on the line where it begins OR if it would extend beyond the margin, the entire phrase would be moved to the next line.
The HTML code generated for this command can take one of two forms, based on the complexity of the text in the sequence:
For a simple text sequence, space characters (U+000020) may simply be
replaced by the HTML definition: (non-breaking-space), as in
the following:
"Extremely Loud and Incredibly Close"
For a more complex text sequence, the 'nolinebreak' class will be called out:
 ...
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.
In either case, the font within the block will be the same as the surrounding text (and the unnecessary HTML comment will be ignored). Note also that it would be unwise to make any assumptions about which HTML construct above will be generated by a particular text sequence.
Please note that there is a long-standing bug in the 'makeinfo' utility which fails to wrap a @w{ ... } command block if it crosses the margin of the 'info' output. This bug was introduced when makeinfo was converted from 'C' to Perl and is present at least up to version 5.2. This bug has been reported, and we believe that the problem has been corrected in the code base and that the update will be part of the next major release.
This command controls automatic insertion of line breaks at hyphenation points ('-' and '_') within a '@code' (or similar) block, and affects only TeX and HTML output. Note that for 'info' format, data inside a @code block is seen as pre-formatted and is not subject to line breaks.
With '@allowcodebreaks false', the generated HTML for a code block is:
 ...
With '@allowcodebreaks true', the generated HTML for a code block is:
Code breaks off: text beyond browser's right edge is not wrapped:
Code breaks on: text beyond browser's right edge (or edge of container) is wrapped:
Previous: Misc Block Modifiers, Up: Block Commands [Contents][Index]
This chart compares the formatting characteristics of the various Texinfo
block-oriented commands. The variable factors are:
|as 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.
Next: Font Modification, Previous: Block Commands, Up: Makeinfo Testing [Contents][Index]
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.
Output to 'info' document: as specified
Output to 'HTML' document: as specified EXCEPT as noted below
The generated HTML for this command is:

'<samp>COL1_DATA</samp>'

'<samp>COL1_DATA</samp>'

COL2_DATA

'<samp>COL1_DATA</samp>'

COL2_DATA

 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
loop while the condition evaluates to 'true'
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.
PLEASE NOTE: If you must use the @table command, we strongly recommend the use of 'infodoc-styles.css' which redefines the
 tag so the HTML ouput is visually much nearer to the 'info' output.
Output to 'info' document: as specified
Output to 'HTML' document: as specified EXCEPT as noted below
The generated HTML for this command is:

aaaaa	bbbbb	ccccc

aaaaa	bbbbb	ccccc

aaaaa	bbbbb	ccccc

aaaaa	bbbbb	ccccc

 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.
|Example Sentence
|The cow jumped over the fence.
|The horse eats flowers and grass.
|The 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 want 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
 element produces HTML tables that more closely resemble the 'info' tables.
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
 element, but can possibly be addressed directly by the texi-to-HTML converter.
For a more complex example of a multitable, please see the chapter See Comparison Chart.
Next: Object Indicators, Previous: Table and Multitable, Up: Makeinfo Testing [Contents][Index]
The generated HTML for this command is:

 ...

The Texinfo documentation suggests that smallcaps be avoided due to inconsistencies across output formats.
The @emph command delimits the text with underscore characters in 'info' output. The HTML output is italicized.
The generated HTML for this command is:

 ...

Note that the actual appearance of the  ...  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 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:

 ...

The Texinfo documentation suggests that @strong be used seldom and carefully due to possible mis-interpretation as a cross-reference.
Editorial Note: Both '@emph' and '@strong' unfortunately look like crap in the 'info' output, but are relatively cool in the HTML output.
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 uses  ... )
Text within a '@b' sequence.
@i command - Italic text. (generated HTML uses  ... )
Text within a '@i' sequence.
@r command - Roman font family.
(generated HTML uses  ... )
The font size is inappropriately reduced, but this is compensated by application of CSS definition file.
Text within a '@r' sequence.
@t command - Fixed-width (typewriter) font family
(generated HTML uses <tt> ... </tt>)
The font size is inappropriately reduced, but this is compensated by application of CSS definition file.
Text within a '@t' sequence.
Please note that the <tt> tag is no longer supported in HTML5, but is explicitly defined in infodoc-styles.css.
@sansserif command - Sans serif font family
Default text:
(generated HTML uses
 ...
)
Friends, Romans, Countrymen! Lend me your pen!
Roman text with serif.
(generated HTML uses  ... )
Friends, Romans, Countrymen! Lend me your golf clubs!
Roman text without serif.
(generated HTML uses  ... )
Friends, Romans, Countrymen! Lend me your car!
Fixed-width text with serif.
(generated HTML uses <tt> ... </tt>)
Font size is inappropriately reduced here also.
Friends, Romans, Countrymen! Lend me your beach house!
Fixed-width text without serif.
(generated HTML uses <tt> ... </tt>)
Font size is inappropriately reduced here also.
Friends, Romans, Countrymen! Lend me your spouse!
@slanted command - Slanted text
Slanted Roman text.
(generated HTML uses  ... )
The font size is inappropriately reduced, but this is compensated by application of CSS definition file.
Friends, Romans, Countrymen! Lend me your phone!
Slanted Fixed-width text.
(generated HTML uses <tt> ... </tt>)
The font size is inappropriately reduced, but this is compensated by application of CSS definition file.
Friends, Romans, Countrymen! Lend me your ATM card!
Next: InfoMenu Structure, Previous: Font Modification, Up: Makeinfo Testing [Contents][Index]
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.
Indicate text that is a literal example of a piece of a program.
Supported by : HTML tag
Generated HTML:
 ...

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

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

@cite: Indicate the name of a book.
Supported by : HTML tag
Generated HTML:
 ...

@abbr: Indicate an abbreviation.
Supported by : HTML tag
Generated HTML:
 ...

A useful trick is to use the 'title' attribute with the  tag
to expand an abbreviation on mouse-over: Please support the FSF.
@kbd : Indicate keyboard input.
Supported by : auto-generated: kbd {font-style:oblique}
Generated HTML:
 ...

(Please note that the  tag is a standard HTML ) (tag, and does not need the converter's explicit definition.)
@env :
Indicate an environment variable.
Supported by : none
Generated HTML:
 ...

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

Indicate the name of a command.
Supported by : none
Generated HTML:
 ...

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

@dfn : Indicate the introductory or defining use of a term.
Supported by : none
Generated HTML:
 ...

(Please note that the <dfn> tag is a standard HTML) (tag, and does not need the  substitution. )
@verb: Write a verbatim sequence of characters.
Supported by : none
Generated HTML:
<tt> ... </tt>

(Please note that the <tt> tag is no longer supported in HTML5,) (but is explicitly defined in infodoc-styles.css. See .)
@key : Indicate the conventional name for a key on a keyboard.
Supported by : none ("key" class not defined)
Generated HTML:
<tt class="key"> ... </tt>

(Please note that the 'key' sub-class of <tt> is ) (also explicitly defined in infodoc-styles.css.)
@acronym: Indicate an acronym.
Supported by : none
Generated HTML:
<acronym> ... </acronym>

(Please note that the <acronym> tag is no longer supported in HTML5,) (but is explicitly defined in infodoc-styles.css. See . )
@indicateurl: '
Indicate an example (nonfunctional) URL'
(Use @url command for live URLs.)
Supported by : none
Generated HTML:
 ...

@email: Indicate an electronic mail address.
Supported by : none
Generated HTML:
 ...

(where 'xxxx' is the email address)
PLEASE NOTE: The following object identifiers inappropriately use the default HTML page font (extremely small):
@kbd, @env, @file, @command, @option, @verb, @key, @indicateurl
All of these are compensated by applying 'infodoc-styles.css'.
Next: InfoTOC Structure, Previous: Object Indicators, Up: Makeinfo Testing [Contents][Index]
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
 structure to implement the same functionality. The HTML code block below was generated for the 'List Commands' chapter of this document.

 • Itemized Lists: 	  	 Test –html option 'itemize' list output

 • Enumerated Lists: 	  	 Test –html option 'enumerate' list output

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:
 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
 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.
Next: Misc Formatting, Previous: InfoMenu Structure, Up: Makeinfo Testing [Contents][Index]
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 in the document.
What follows is an example taken from the HTML version of the document you are now reading.

Overview

CSS Definition File

Summary of CSS Definitions

Applying the CSS Definitions

Adjusting Style Definitions

HTML Post-processing . . .

 . . .

With the exception of the stub definition of the 'no-bullet' class
described above, 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
'no-bullet', '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.
Previous: InfoTOC Structure, Up: Makeinfo Testing [Contents][Index]
No misc. formatting tests identified at this time.
Next: Technical Support, Previous: Makeinfo Testing, Up: Top [Contents][Index]
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:
|Specific post-processor tests for lists
|• Idpp Block Processing:
|Lists embedded within block environments
|• Idpp Misc Tests:
|Miscellaneous post-processor tests
|• Ad-hoc Tests:
|Space for creating your own tests
Next: Idpp Block Processing, Up: Idpp Testing [Contents][Index]
The following are lists nested inside other lists which exercises the 'idpp' list-recursion algorithm.
Note that the browser's rendering engine will determine that the
following itemized (
) lists are nested, 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
To prevent this automatic modification, it will be necessary to trick the browser by using bullet characters that it cannot convert — which is not as easy as it sounds (see simulated disc-bullet list below) ==OR== assign a specific bullet-type class.
The HTML for the following list should not need post-processing, but the browser sees that it is nested and automagically converts the 'disc' bullets to (level-down) 'circle' bullets. (See note above and simulated disc-bullet list below.)
"Your Love" from: "The One Where Monica Gets a New Roommate"
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"
This is a three-level itemized list, and the HTML for all levels should be post-processed with (▪) bullets. "Smelly Cat" from "The One With the Baby On the Bus, et al"
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"
"Shower Song" from "The One With the Baby On the Bus"
"Barnyard Animals" from "The One After the Superbowl, Part One"
Enumerated Below Itemized (decimal leading-zero)
Lyrics in this section copyright (c) NBC / Warner Bros. Television. (but the limericks are our fault :-)
Next: Idpp Misc Tests, Previous: Idpp List Processing, Up: Idpp Testing [Contents][Index]
Formatted constructs such as @enumerate (
) lists, @itemize (
) 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:
This discussion does not apply to @verbatim environments because all contents of a @verbatim environment are output as plain text.
For a detailed description of block environments,
please see Comparison Chart.
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.
Leaving the @indentedblock 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 able to parse the tortured HTML of these lists themselves (it would require a second pass), it does automatically repair the worst of the formatting problems.
If you want professionally formatted lists, then the correct answer is:
This is a preformatted block containing an itemized list and an enumerated list.
Here we are inside a @display block.
Brush your teeth.
Shave unwanted hair.
Eat a healthful breakfast.
Pack your bag.
Kiss all family members.
Go to work.
Brush your teeth.
Shave unwanted hair.
Eat a healthful breakfast.
Pack your bag.
Kiss all family members.
Go to work.
Leaving the @display block.

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.

Bathe.

Brush your teeth.

Shave unwanted hair.

Eat a healthful breakfast.

Pack your bag.

Kiss all family members.

Go to work.

Leaving the @display block.

Note that the extra '
' and '
 tags associated with individual line items have been removed. For consistency, the '

' tags outside the lists are ignored.

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.

Bathe.

Brush your teeth.

Shave unwanted hair.

Eat a healthful breakfast.

Pack your bag.

Kiss all family members.

Go to work.

Leaving the @display 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.
Brush your teeth.
Shave unwanted hair.
Eat a healthful breakfast.
Pack your bag.
Kiss all family members.
Go to work.
Brush your teeth.
Shave unwanted hair.
Eat a healthful breakfast.
Pack your bag.
Kiss all family members.
Go to work.
Leaving the @example block.
Next: Ad-hoc Tests, Previous: Idpp Block Processing, Up: Idpp Testing [Contents][Index]
Correct is better than fast. Simple is better than complex.
Clear is better than cute. Safe is better than insecure.
A designer knows he has achieved perfection not when there is nothing left to add, but when there is nothing left to take away.
Except for @indentedblock blocks (and possibly @quotation 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 that preformatted data including other preformatted blocks should not be nested inside preformatted blocks — unless you LIKE ugly.
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).
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).
"Give a man a fish, and he'll eat fish."
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."
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).
"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. Note that we cannot follow an @author sub-command with an indented block because makeinfo always places the @author just inside the end of the @quotation block.
"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."
'format' block
'display' block
'example' block
'indentedblock' block
=='verbatim block'==
'indentedblock' block
'example' block
'display' block
'format' block
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.
|( ⚫ )
|( ⚬ )
|third and lower
|( ▪ )
HTML-only output follows: default unordered lists nested to
demonstrate the bullets used by default for each level.
Texinfo character @bullet ( • ) texi-to-HTML converter outputs '•' U+2022 Texinfo character @textdegree ( ° ) texi-to-HTML converter outputs '°' U+00B0 Texinfo character @minus ( - ) texi-to-HTML converter outputs '-' U+002D (which is incorrect) texi-to-info outputs U+2212 i.e. Unicode minus
|( ● )
|( ⚫ )
|( • )
|( ∙ )
|bullet-operator (math)
|( ○ )
|( ⚪ )
|( ⚬ )
|( ◦ )
|( ■ )
|( ◼ )
|( ◾ )
|( ▪ )
Previous: Idpp Misc Tests, Up: Idpp Testing [Contents][Index]
Next: Copyright Notice, Previous: Idpp Testing, Up: Top [Contents][Index]
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.
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.
|NcDialog API
|Build dialog-based console applications in C++
|Dialog-based console file management utility
|Text internationalization and formatting tool
|Source code 'maintainability' analyzer
|Rescue data from damaged DVD video discs
Next: Index, Previous: Technical Support, Up: Top [Contents][Index]
Copyright © 2014-2015 Mahlon R. Smith, The Software Samurai This document describes version 0.0.07 of 'infodoc-styles.css' and version 0.0.04 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: '
|• GNU General Public License:
|• GNU Free Documentation License:
Next: GNU Free Documentation License, Up: Copyright Notice [Contents][Index]
Copyright © 2007 Free Software Foundation, Inc. http://fsf.org/ Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
The GNU General Public License is a free, copyleft license for software and other kinds of works.
The licenses for most software and other practical works are designed to take away your freedom to share and change the works. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change all versions of a program—to make sure it remains free software for all its users. We, the Free Software Foundation, use the GNU General Public License for most of our software; it applies also to any other work released this way by its authors. You can apply it to your programs, too.
When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for them if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs, and that you know you can do these things.
To protect your rights, we need to prevent others from denying you these rights or asking you to surrender the rights. Therefore, you have certain responsibilities if you distribute copies of the software, or if you modify it: responsibilities to respect the freedom of others.
For example, if you distribute copies of such a program, whether gratis or for a fee, you must pass on to the recipients the same freedoms that you received. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.
Developers that use the GNU GPL protect your rights with two steps: (1) assert copyright on the software, and (2) offer you this License giving you legal permission to copy, distribute and/or modify it.
For the developers' and authors' protection, the GPL clearly explains that there is no warranty for this free software. For both users' and authors' sake, the GPL requires that modified versions be marked as changed, so that their problems will not be attributed erroneously to authors of previous versions.
Some devices are designed to deny users access to install or run modified versions of the software inside them, although the manufacturer can do so. This is fundamentally incompatible with the aim of protecting users' freedom to change the software. The systematic pattern of such abuse occurs in the area of products for individuals to use, which is precisely where it is most unacceptable. Therefore, we have designed this version of the GPL to prohibit the practice for those products. If such problems arise substantially in other domains, we stand ready to extend this provision to those domains in future versions of the GPL, as needed to protect the freedom of users.
Finally, every program is threatened constantly by software patents. States should not allow patents to restrict development and use of software on general-purpose computers, but in those that do, we wish to avoid the special danger that patents applied to a free program could make it effectively proprietary. To prevent this, the GPL assures that patents cannot be used to render the program non-free.
The precise terms and conditions for copying, distribution and modification follow.
"This License" refers to version 3 of the GNU General Public License.
"Copyright" also means copyright-like laws that apply to other kinds of works, such as semiconductor masks.
"The Program" refers to any copyrightable work licensed under this License. Each licensee is addressed as "you". "Licensees" and "recipients" may be individuals or organizations.
To "modify" a work means to copy from or adapt all or part of the work in a fashion requiring copyright permission, other than the making of an exact copy. The resulting work is called a "modified version" of the earlier work or a work "based on" the earlier work.
A "covered work" means either the unmodified Program or a work based on the Program.
To "propagate" a work means to do anything with it that, without permission, would make you directly or secondarily liable for infringement under applicable copyright law, except executing it on a computer or modifying a private copy. Propagation includes copying, distribution (with or without modification), making available to the public, and in some countries other activities as well.
To "convey" a work means any kind of propagation that enables other parties to make or receive copies. Mere interaction with a user through a computer network, with no transfer of a copy, is not conveying.
An interactive user interface displays "Appropriate Legal Notices" to the extent that it includes a convenient and prominently visible feature that (1) displays an appropriate copyright notice, and (2) tells the user that there is no warranty for the work (except to the extent that warranties are provided), that licensees may convey the work under this License, and how to view a copy of this License. If the interface presents a list of user commands or options, such as a menu, a prominent item in the list meets this criterion.
The "source code" for a work means the preferred form of the work for making modifications to it. "Object code" means any non-source form of a work.
A "Standard Interface" means an interface that either is an official standard defined by a recognized standards body, or, in the case of interfaces specified for a particular programming language, one that is widely used among developers working in that language.
The "System Libraries" of an executable work include anything, other than the work as a whole, that (a) is included in the normal form of packaging a Major Component, but which is not part of that Major Component, and (b) serves only to enable use of the work with that Major Component, or to implement a Standard Interface for which an implementation is available to the public in source code form. A "Major Component", in this context, means a major essential component (kernel, window system, and so on) of the specific operating system (if any) on which the executable work runs, or a compiler used to produce the work, or an object code interpreter used to run it.
The "Corresponding Source" for a work in object code form means all the source code needed to generate, install, and (for an executable work) run the object code and to modify the work, including scripts to control those activities. However, it does not include the work's System Libraries, or general-purpose tools or generally available free programs which are used unmodified in performing those activities but which are not part of the work. For example, Corresponding Source includes interface definition files associated with source files for the work, and the source code for shared libraries and dynamically linked subprograms that the work is specifically designed to require, such as by intimate data communication or control flow between those subprograms and other parts of the work.
The Corresponding Source need not include anything that users can regenerate automatically from other parts of the Corresponding Source.
The Corresponding Source for a work in source code form is that same work.
All rights granted under this License are granted for the term of copyright on the Program, and are irrevocable provided the stated conditions are met. This License explicitly affirms your unlimited permission to run the unmodified Program. The output from running a covered work is covered by this License only if the output, given its content, constitutes a covered work. This License acknowledges your rights of fair use or other equivalent, as provided by copyright law.
You may make, run and propagate covered works that you do not convey, without conditions so long as your license otherwise remains in force. You may convey covered works to others for the sole purpose of having them make modifications exclusively for you, or provide you with facilities for running those works, provided that you comply with the terms of this License in conveying all material for which you do not control copyright. Those thus making or running the covered works for you must do so exclusively on your behalf, under your direction and control, on terms that prohibit them from making any copies of your copyrighted material outside their relationship with you.
Conveying under any other circumstances is permitted solely under the conditions stated below. Sublicensing is not allowed; section 10 makes it unnecessary.
No covered work shall be deemed part of an effective technological measure under any applicable law fulfilling obligations under article 11 of the WIPO copyright treaty adopted on 20 December 1996, or similar laws prohibiting or restricting circumvention of such measures.
When you convey a covered work, you waive any legal power to forbid circumvention of technological measures to the extent such circumvention is effected by exercising rights under this License with respect to the covered work, and you disclaim any intention to limit operation or modification of the work as a means of enforcing, against the work's users, your or third parties' legal rights to forbid circumvention of technological measures.
You may convey verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice; keep intact all notices stating that this License and any non-permissive terms added in accord with section 7 apply to the code; keep intact all notices of the absence of any warranty; and give all recipients a copy of this License along with the Program.
You may charge any price or no price for each copy that you convey, and you may offer support or warranty protection for a fee.
You may convey a work based on the Program, or the modifications to produce it from the Program, in the form of source code under the terms of section 4, provided that you also meet all of these conditions:
A compilation of a covered work with other separate and independent works, which are not by their nature extensions of the covered work, and which are not combined with it such as to form a larger program, in or on a volume of a storage or distribution medium, is called an "aggregate" if the compilation and its resulting copyright are not used to limit the access or legal rights of the compilation's users beyond what the individual works permit. Inclusion of a covered work in an aggregate does not cause this License to apply to the other parts of the aggregate.
You may convey a covered work in object code form under the terms of sections 4 and 5, provided that you also convey the machine-readable Corresponding Source under the terms of this License, in one of these ways:
A separable portion of the object code, whose source code is excluded from the Corresponding Source as a System Library, need not be included in conveying the object code work.
A "User Product" is either (1) a "consumer product", which means any tangible personal property which is normally used for personal, family, or household purposes, or (2) anything designed or sold for incorporation into a dwelling. In determining whether a product is a consumer product, doubtful cases shall be resolved in favor of coverage. For a particular product received by a particular user, "normally used" refers to a typical or common use of that class of product, regardless of the status of the particular user or of the way in which the particular user actually uses, or expects or is expected to use, the product. A product is a consumer product regardless of whether the product has substantial commercial, industrial or non-consumer uses, unless such uses represent the only significant mode of use of the product.
"Installation Information" for a User Product means any methods, procedures, authorization keys, or other information required to install and execute modified versions of a covered work in that User Product from a modified version of its Corresponding Source. The information must suffice to ensure that the continued functioning of the modified object code is in no case prevented or interfered with solely because modification has been made.
If you convey an object code work under this section in, or with, or specifically for use in, a User Product, and the conveying occurs as part of a transaction in which the right of possession and use of the User Product is transferred to the recipient in perpetuity or for a fixed term (regardless of how the transaction is characterized), the Corresponding Source conveyed under this section must be accompanied by the Installation Information. But this requirement does not apply if neither you nor any third party retains the ability to install modified object code on the User Product (for example, the work has been installed in ROM).
The requirement to provide Installation Information does not include a requirement to continue to provide support service, warranty, or updates for a work that has been modified or installed by the recipient, or for the User Product in which it has been modified or installed. Access to a network may be denied when the modification itself materially and adversely affects the operation of the network or violates the rules and protocols for communication across the network.
Corresponding Source conveyed, and Installation Information provided, in accord with this section must be in a format that is publicly documented (and with an implementation available to the public in source code form), and must require no special password or key for unpacking, reading or copying.
"Additional permissions" are terms that supplement the terms of this License by making exceptions from one or more of its conditions. Additional permissions that are applicable to the entire Program shall be treated as though they were included in this License, to the extent that they are valid under applicable law. If additional permissions apply only to part of the Program, that part may be used separately under those permissions, but the entire Program remains governed by this License without regard to the additional permissions.
When you convey a copy of a covered work, you may at your option remove any additional permissions from that copy, or from any part of it. (Additional permissions may be written to require their own removal in certain cases when you modify the work.) You may place additional permissions on material, added by you to a covered work, for which you have or can give appropriate copyright permission.
Notwithstanding any other provision of this License, for material you add to a covered work, you may (if authorized by the copyright holders of that material) supplement the terms of this License with terms:
All other non-permissive additional terms are considered "further restrictions" within the meaning of section 10. If the Program as you received it, or any part of it, contains a notice stating that it is governed by this License along with a term that is a further restriction, you may remove that term. If a license document contains a further restriction but permits relicensing or conveying under this License, you may add to a covered work material governed by the terms of that license document, provided that the further restriction does not survive such relicensing or conveying.
If you add terms to a covered work in accord with this section, you must place, in the relevant source files, a statement of the additional terms that apply to those files, or a notice indicating where to find the applicable terms.
Additional terms, permissive or non-permissive, may be stated in the form of a separately written license, or stated as exceptions; the above requirements apply either way.
You may not propagate or modify a covered work except as expressly provided under this License. Any attempt otherwise to propagate or modify it is void, and will automatically terminate your rights under this License (including any patent licenses granted under the third paragraph of section 11).
However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently, if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessation.
Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice.
Termination of your rights under this section does not terminate the licenses of parties who have received copies or rights from you under this License. If your rights have been terminated and not permanently reinstated, you do not qualify to receive new licenses for the same material under section 10.
You are not required to accept this License in order to receive or run a copy of the Program. Ancillary propagation of a covered work occurring solely as a consequence of using peer-to-peer transmission to receive a copy likewise does not require acceptance. However, nothing other than this License grants you permission to propagate or modify any covered work. These actions infringe copyright if you do not accept this License. Therefore, by modifying or propagating a covered work, you indicate your acceptance of this License to do so.
Each time you convey a covered work, the recipient automatically receives a license from the original licensors, to run, modify and propagate that work, subject to this License. You are not responsible for enforcing compliance by third parties with this License.
An "entity transaction" is a transaction transferring control of an organization, or substantially all assets of one, or subdividing an organization, or merging organizations. If propagation of a covered work results from an entity transaction, each party to that transaction who receives a copy of the work also receives whatever licenses to the work the party's predecessor in interest had or could give under the previous paragraph, plus a right to possession of the Corresponding Source of the work from the predecessor in interest, if the predecessor has it or can get it with reasonable efforts.
You may not impose any further restrictions on the exercise of the rights granted or affirmed under this License. For example, you may not impose a license fee, royalty, or other charge for exercise of rights granted under this License, and you may not initiate litigation (including a cross-claim or counterclaim in a lawsuit) alleging that any patent claim is infringed by making, using, selling, offering for sale, or importing the Program or any portion of it.
A "contributor" is a copyright holder who authorizes use under this License of the Program or a work on which the Program is based. The work thus licensed is called the contributor's "contributor version".
A contributor's "essential patent claims" are all patent claims owned or controlled by the contributor, whether already acquired or hereafter acquired, that would be infringed by some manner, permitted by this License, of making, using, or selling its contributor version, but do not include claims that would be infringed only as a consequence of further modification of the contributor version. For purposes of this definition, "control" includes the right to grant patent sublicenses in a manner consistent with the requirements of this License.
Each contributor grants you a non-exclusive, worldwide, royalty-free patent license under the contributor's essential patent claims, to make, use, sell, offer for sale, import and otherwise run, modify and propagate the contents of its contributor version.
In the following three paragraphs, a "patent license" is any express agreement or commitment, however denominated, not to enforce a patent (such as an express permission to practice a patent or covenant not to sue for patent infringement). To "grant" such a patent license to a party means to make such an agreement or commitment not to enforce a patent against the party.
If you convey a covered work, knowingly relying on a patent license, and the Corresponding Source of the work is not available for anyone to copy, free of charge and under the terms of this License, through a publicly available network server or other readily accessible means, then you must either (1) cause the Corresponding Source to be so available, or (2) arrange to deprive yourself of the benefit of the patent license for this particular work, or (3) arrange, in a manner consistent with the requirements of this License, to extend the patent license to downstream recipients. "Knowingly relying" means you have actual knowledge that, but for the patent license, your conveying the covered work in a country, or your recipient's use of the covered work in a country, would infringe one or more identifiable patents in that country that you have reason to believe are valid.
If, pursuant to or in connection with a single transaction or arrangement, you convey, or propagate by procuring conveyance of, a covered work, and grant a patent license to some of the parties receiving the covered work authorizing them to use, propagate, modify or convey a specific copy of the covered work, then the patent license you grant is automatically extended to all recipients of the covered work and works based on it.
A patent license is "discriminatory" if it does not include within the scope of its coverage, prohibits the exercise of, or is conditioned on the non-exercise of one or more of the rights that are specifically granted under this License. You may not convey a covered work if you are a party to an arrangement with a third party that is in the business of distributing software, under which you make payment to the third party based on the extent of your activity of conveying the work, and under which the third party grants, to any of the parties who would receive the covered work from you, a discriminatory patent license (a) in connection with copies of the covered work conveyed by you (or copies made from those copies), or (b) primarily for and in connection with specific products or compilations that contain the covered work, unless you entered into that arrangement, or that patent license was granted, prior to 28 March 2007.
Nothing in this License shall be construed as excluding or limiting any implied license or other defenses to infringement that may otherwise be available to you under applicable patent law.
If conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot convey a covered work so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not convey it at all. For example, if you agree to terms that obligate you to collect a royalty for further conveying from those to whom you convey the Program, the only way you could satisfy both those terms and this License would be to refrain entirely from conveying the Program.
Notwithstanding any other provision of this License, you have permission to link or combine any covered work with a work licensed under version 3 of the GNU Affero General Public License into a single combined work, and to convey the resulting work. The terms of this License will continue to apply to the part which is the covered work, but the special requirements of the GNU Affero General Public License, section 13, concerning interaction through a network will apply to the combination as such.
The Free Software Foundation may publish revised and/or new versions of the GNU General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.
Each version is given a distinguishing version number. If the Program specifies that a certain numbered version of the GNU General Public License "or any later version" applies to it, you have the option of following the terms and conditions either of that numbered version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of the GNU General Public License, you may choose any version ever published by the Free Software Foundation.
If the Program specifies that a proxy can decide which future versions of the GNU General Public License can be used, that proxy's public statement of acceptance of a version permanently authorizes you to choose that version for the Program.
Later license versions may give you additional or different permissions. However, no additional obligations are imposed on any author or copyright holder as a result of your choosing to follow a later version.
If the disclaimer of warranty and limitation of liability provided above cannot be given local legal effect according to their terms, reviewing courts shall apply local law that most closely approximates an absolute waiver of all civil liability in connection with the Program, unless a warranty or assumption of liability accompanies a copy of the Program in return for a fee.
If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms.
To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively state the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found.
one line to give the program's name and a brief idea of what it does. Copyright (C) year name of author This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.
Also add information on how to contact you by electronic and paper mail.
If the program does terminal interaction, make it output a short notice like this when it starts in an interactive mode:
program Copyright (C) year name of author This program comes with ABSOLUTELY NO WARRANTY; for details type 'show w'. This is free software, and you are welcome to redistribute it under certain conditions; type 'show c' for details.
The hypothetical commands 'show w' and 'show c' should show the appropriate parts of the General Public License. Of course, your program's commands might be different; for a GUI interface, you would use an "about box".
You should also get your employer (if you work as a programmer) or school, if any, to sign a "copyright disclaimer" for the program, if necessary. For more information on this, and how to apply and follow the GNU GPL, see http://www.gnu.org/licenses/.
The GNU General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Lesser General Public License instead of this License. But first, please read http://www.gnu.org/philosophy/why-not-lgpl.html.
Previous: GNU General Public License, Up: Copyright Notice [Contents][Index]
Copyright © 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. http://fsf.org/ Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
The purpose of this License is to make a manual, textbook, or other functional and useful document free in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.
This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.
We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.
This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you". You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law.
A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.
A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.
The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none.
The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words.
A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not "Transparent" is called "Opaque".
Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only.
The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text.
The "publisher" means any person or entity that distributes copies of the Document to the public.
A section "Entitled XYZ" means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as "Acknowledgements", "Dedications", "Endorsements", or "History".) To "Preserve the Title" of such a section when you modify the Document means that it remains a section "Entitled XYZ" according to this definition.
The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License.
You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.
You may also lend copies, under the same conditions stated above, and you may publicly display copies.
If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.
If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.
If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.
It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.
You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:
If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles.
You may add a section Entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various parties—for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.
You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.
The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.
You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers.
The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.
In the combination, you must combine any sections Entitled "History" in the various original documents, forming one section Entitled "History"; likewise combine any sections Entitled "Acknowledgements", and any sections Entitled "Dedications". You must delete all sections Entitled "Endorsements."
You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.
You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.
A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an "aggregate" if the copyright resulting from the compilation is not used to limit the legal rights of the compilation's users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document.
If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document's Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate.
Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail.
If a section in the Document is Entitled "Acknowledgements", "Dedications", or "History", the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title.
You may not copy, modify, sublicense, or distribute the Document except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense, or distribute it is void, and will automatically terminate your rights under this License.
However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently, if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessation.
Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice.
Termination of your rights under this section does not terminate the licenses of parties who have received copies or rights from you under this License. If your rights have been terminated and not permanently reinstated, receipt of a copy of some or all of the same material does not give you any rights to use it.
The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.
Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License "or any later version" applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation. If the Document specifies that a proxy can decide which future versions of this License can be used, that proxy's public statement of acceptance of a version permanently authorizes you to choose that version for the Document.
"Massive Multiauthor Collaboration Site" (or "MMC Site") means any World Wide Web server that publishes copyrightable works and also provides prominent facilities for anybody to edit those works. A public wiki that anybody can edit is an example of such a server. A "Massive Multiauthor Collaboration" (or "MMC") contained in the site means any set of copyrightable works thus published on the MMC site.
"CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 license published by Creative Commons Corporation, a not-for-profit corporation with a principal place of business in San Francisco, California, as well as future copyleft versions of that license published by that same organization.
"Incorporate" means to publish or republish a Document, in whole or in part, as part of another Document.
An MMC is "eligible for relicensing" if it is licensed under this License, and if all works that were first published under this License somewhere other than this MMC, and subsequently incorporated in whole or in part into the MMC, (1) had no cover texts or invariant sections, and (2) were thus incorporated prior to November 1, 2008.
The operator of an MMC Site may republish an MMC contained in the site under CC-BY-SA on the same site at any time before August 1, 2009, provided the MMC is eligible for relicensing.
To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:
Copyright (C) year your name. 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 included in the section entitled ``GNU Free Documentation License''.
If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the "with…Texts." line with this:
with the Invariant Sections being list their titles, with the Front-Cover Texts being list, and with the Back-Cover Texts being list.
If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation.
If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.
Previous: Copyright Notice, Up: Top [Contents][Index]
|Jump to:
|Index Entry
|01 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 Text Mode:
|Text Mode
|03.01.03 Interactive Mode:
|Interactive Mode
|03.01.04 Invoking idpp:
|Invoking idpp
|03.01.05 Interface Logic:
|Interface Logic
|03.01.06 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 Enumerated Lists:
|Enumerated 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 Command:
|Verbatim Command
|04.05.07 Misc Block Modifiers:
|Misc Block Modifiers
|04.05.08 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 InfoTOC Structure:
|InfoTOC Structure
|04.11 Misc Formatting:
|Misc Formatting
|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
|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
|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
|body text:
|Basic Tests
|browsers, testing done with:
|CSS Definition File
|character type and style:
|Font Modification
|commands for data blocks:
|Block Commands
|comparison chart for block commands:
|Comparison Chart
|contact info:
|Technical Support
|contact information:
|Technical Support
|Texinfo Build Options
|default HTML styles:
|Default Style Set
|display command:
|Display Commands
|enumerate command, texinfo:
|Enumerated Lists
|environments, blocks:
|Block Commands
|example command:
|Example Commands
|font, modifying:
|Font Modification
|format command:
|Format Commands
|global document commands, Texinfo:
|Texinfo HTML Options
|Basic Tests
|HTML automatic post-processor:
|Infodoc Post-processor
|HTML customization variables:
|Texinfo HTML Options
|idpp command line arguments:
|Invoking idpp
|include CSS in texi source:
|Including Entire CSS File
|indentedblock command:
|Indentedblock Commands
|indicators, object-type:
|Object Indicators
|introduction to Infodoc:
|invoking idpp:
|Invoking idpp
|itemize command, texinfo:
|Itemized Lists
|lisp command:
|Example 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
|main menu:
|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 command:
|Table and Multitable
|nuclear annihilation:
|Adjusting Style Definitions
|object-type indicator:
|Object Indicators
|ol lists:
|Enumerated Lists
|operational overview:
|optional post-processing:
|Other Manual Processing
|ordered lists:
|Enumerated Lists
|other projects:
|Technical Support
|overview of CSS definitions:
|Summary of CSS Definitions
|overview of testing:
|Testing Overview
|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
|quotation command:
|Quotation Commands
|raw HTML output:
|Post-processing Notes
|response file:
|Interface Logic
|smalldisplay command:
|Display Commands
|smallexample command:
|Example Commands
|smallformat command:
|Format Commands
|smallindentedblock command:
|Indentedblock Commands
|smalllisp command:
|Example Commands
|smallquotation command:
|Quotation Commands
|smallverbatim command:
|Verbatim Command
|style definitions, adjusting:
|Adjusting Style Definitions
|style stubs:
|Default Style Set
|Technical Support
|switches, idpp command line:
|Invoking idpp
|table of contents, Texinfo:
|InfoTOC Structure
|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:
|Enumerated Lists
|Texinfo global document commands:
|Texinfo HTML Options
|texinfo itemize command:
|Itemized Lists
|Texinfo menus:
|InfoMenu Structure
|Texinfo table of contents:
|InfoTOC Structure
|translate menus to HTML:
|InfoMenu Structure
|translate TOC to HTML:
|InfoTOC Structure
|ul lists:
|Itemized Lists
|unordered lists:
|Itemized Lists
|variables, HTML customization:
|Texinfo HTML Options
|verbatim command:
|Verbatim Command
|Jump to:
The generated index looks really good in HTML without any modification at all. There are only two things we do to style the Index: 1) We define the 'a.summary-letter' class just as it is defined in the raw HTML output. (This prevents the summary letters from being underlined.) 2) We define the 'table.index-cp' class which is called out in the auto-generated Index but never defined. This definition really isn't necessary because the existing table definition works fine. We define 'index-cp' anyway because in our experience, things that work correctly by coincidence will eventually return to leave toothmarks on your fanny. There is, however, one small artifact in the index which is caused by our redefinition of the HTML
 element to support the @multitable command (see Multitable Command). Our definition causes the  (table header) element to be underlined. This in turn causes the 	 rows of the 'Jump to' tables in the index to be underlined as well. This is very minor, but it is handled automatically by the 'idpp' automatic post-processor. Please refer to see Post-processor Overview for details.