[6015] explain more about the goal for our HTML output

[karl]

Revision: 6015
          http://svn.sv.gnu.org/viewvc/?view=rev&root=texinfo&revision=6015
Author:   karl
Date:     2015-01-02 00:53:27 +0000 (Fri, 02 Jan 2015)
Log Message:
-----------
explain more about the goal for our HTML output

Modified Paths:
--------------
    trunk/ChangeLog
    trunk/doc/texinfo.texi

Modified: trunk/ChangeLog
===================================================================
--- trunk/ChangeLog     2015-01-01 19:32:00 UTC (rev 6014)
+++ trunk/ChangeLog     2015-01-02 00:53:27 UTC (rev 6015)
@@ -1,5 +1,9 @@
 2015-01-01  Karl Berry  <address@hidden>
 
+       * doc/texinfo.texi (Output Formats, Generating HTML): be rather
+       forceful in our overall goal for the HTML output (namely, be
+       widely usable rather than fancy).
+
        * info/info-utils.c,
        * info/nodes.c,
        * info/nodes.h: 2015.

Modified: trunk/doc/texinfo.texi
===================================================================
--- trunk/doc/texinfo.texi      2015-01-01 19:32:00 UTC (rev 6014)
+++ trunk/doc/texinfo.texi      2015-01-02 00:53:27 UTC (rev 6015)
@@ -868,11 +868,11 @@
 typesetting system) with the normal features of a book, including
 chapters, sections, cross references, and indices.  From the same
 Texinfo source file, you can create an Info file with special features
-to make documentation browsing easy.  You can also create from that
-same source file an HTML output file suitable for use with a web
+to make documentation browsing easy.  Also from that same source file,
+you can create an HTML output file suitable for use with a web
 browser, a Docbook file, or a transliteration in XML format.  See the
-next section (@pxref{Output Formats}) for details and sample commands
-to generate output from the source.
+next section for details and sample commands to generate output from
+the source (@pxref{Output Formats}).
 
 @TeX{} works with virtually all printers; Info works with virtually
 all computer terminals; the HTML output works with virtually all web
@@ -928,10 +928,14 @@
 Text Markup Language, has become the most commonly used language for
 writing documents on the World Wide Web.  Web browsers, such as
 Mozilla, Lynx, and Emacs-W3, can render this language online.  There
-are many versions of HTML; @command{makeinfo} tries to use a subset of
-the language that can be interpreted by any common browser.  For
-details of the HTML language and much related information, see
address@hidden://www.w3.org/MarkUp/}.  @xref{Generating HTML}.
+are many versions of HTML, both different standards and
+browser-specific variations.  @command{makeinfo} tries to use a subset
+of the language that can be interpreted by any common browser,
+intentionally not using many newer or less widely-supported tags.
+Although the native output is thus rather plain, it can be customized
+at various levels, if desired.  For details of the HTML language and
+much related information, see @uref{http://www.w3.org/MarkUp/}.
address@hidden HTML}.
 
 @item DVI
 @cindex DVI output, overview
@@ -15843,11 +15847,11 @@
 
 @itemize @minus
 @item
-Create or update @strong{all} the `Next', `Previous', and `Up' pointers
+Create or update @emph{all} the `Next', `Previous', and `Up' pointers
 of all the included files.
 
 @item
-Create or update @strong{all} the menus of all the included
+Create or update @emph{all} the menus of all the included
 files.
 
 @item
@@ -15865,7 +15869,7 @@
 prefix argument, just @address@hidden, the
 @code{texinfo-multiple-files-update} command inserts a master menu;
 with a numeric prefix argument, such as @kbd{C-u 8}, the command
-updates @strong{every} pointer and menu in @strong{all} the files and
+updates @emph{every} pointer and menu in @emph{all} the files and
 then inserts a master menu.
 
 
@@ -19766,47 +19770,96 @@
 @node HTML Translation
 @section HTML Translation
 
address@hidden will include segments of Texinfo source between
address@hidden@@ifhtml} and @code{@@end ifhtml} in the HTML output (but not
-any of the other conditionals, by default).  Source between
address@hidden@@html} and @code{@@end html} is passed without change to the
-output (i.e., suppressing the normal escaping of input @samp{<},
address@hidden>} and @samp{&} characters which have special significance in
-HTML).  @xref{Conditional Commands}.
address@hidden HTML translation
 
address@hidden HTML output, browser compatibility of
+First, the HTML generated by @command{makeinfo} is standard
address@hidden  It also tries to be as compatible as possible with
+earlier standards (e.g., address@hidden, RFC-1866).  Thus, please
+report output from an error-free run of @code{makeinfo} which has
+practical browser portability problems as a bug (@pxref{Reporting
+Bugs}).
+
address@hidden html32.pm
+Some known exceptions to address@hidden (using
address@hidden produces strict address@hidden output;
address@hidden @t{texi2any}}):
+
address@hidden
address@hidden
address@hidden tables are generated for the @code{@@multitable} command
+(@pxref{Multi-column Tables}), but they should degrade reasonably in
+browsers without table support.
+
address@hidden
+The address@hidden @samp{lang} attribute on the @samp{<html>} attribute
+is used.
+
address@hidden
+Entities that are not in the address@hidden standard are also used.
+
address@hidden
+CSS is used (@pxref{HTML CSS}).
+
address@hidden
+A few address@hidden elements are used: @code{thead}, @code{abbr},
address@hidden
+
address@hidden enumerate
+
+To achieve maximum portability and accessibility among browsers (both
+graphical and text-based), systems, and users, the HTML output is
+intentionally quite plain and generic.  It has always been our goal
+for users to be able to customize the output to their wishes via CSS
+(@pxref{HTML CSS}) or other means (@pxref{Customization Variables}.
+If you cannot accomplish a reasonable customization, feel free to
+report that.
+
+However, we do not wish to depart from our basic goal of widest
+readability for the core output.  For example, using fancy CSS may
+make it possible for the HTML output to more closely resemble the
address@hidden output in some details, but this result is not even close to
+being worth the ensuing difficulties.
+
+It is also intentionally not our goal, and not even possible, to pass
+through every conceivable validation test without any diagnostics.
+Different validation tests have different goals, often about pedantic
+enforcement of some standard or another.  Our overriding goal is to
+help users, not blindly comply with standards.
+
+To repeat what was said at the top: please report output from an
+error-free run of @code{makeinfo} which has @emph{practical} browser
+portability problems as a bug (@pxref{Reporting Bugs}).
+
+A few other general points about the HTML output follow.
+
 @cindex Navigation bar, in HTML output
-By default, a navigation bar is inserted at the start of each node,
-analogous to Info output.  If the @samp{--no-headers} option is used,
-the navigation bar is only inserted at the beginning of split files.
-Header @code{<link>} elements in split output can support Info-like
-navigation with browsers like Lynx and @w{Emacs W3} which implement
-this address@hidden feature.
address@hidden bar:} By default, a navigation bar is inserted at the
+start of each node, analogous to Info output.  If the
address@hidden option is used, the navigation bar is only
+inserted at the beginning of split files.  Header @code{<link>}
+elements in split output can support Info-like navigation with
+browsers like Lynx and @w{Emacs W3} which implement this address@hidden
+feature.
 
 @cindex Footnote styles, in HTML
-In HTML, when the footnote style is @samp{end}, or if the output is
-not split, footnotes are put at the end of the output.  If set to
address@hidden, and the output is split, they are placed in a
-separate file.  @xref{Footnote Styles}.
address@hidden:} for HTML, when the footnote style is @samp{end},
+or if the output is not split, footnotes are put at the end of the
+output.  If the footnoet style is set to @samp{separate}, and the
+output is split, they are placed in a separate file.  @xref{Footnote
+Styles}.
 
address@hidden HTML output, browser compatibility of
-The HTML generated is standard address@hidden  It also tries to be as
-compatible as possible with earlier standards (e.g., address@hidden,
-RFC-1866).  Some minor exceptions: 1)@address@hidden tables are
-generated for the @code{@@multitable} command (@pxref{Multi-column
-Tables}), but they should degrade reasonably in browsers without table
-support; 2)@tie{}The address@hidden @samp{lang} attribute on the
address@hidden<html>} attribute is used; 3)@tie{} Entities that are not in the
address@hidden standard are also used. 4)@tie{} CSS is used
-(@pxref{HTML CSS}). 5)@tie{} A few address@hidden elements are used
-(@code{thead}, @code{abbr}, @code{acronym}).
address@hidden Escaping to HTML
address@hidden Raw HTML
address@hidden HTML}: @command{makeinfo} will include segments of Texinfo
+source between @code{@@ifhtml} and @code{@@end ifhtml} in the HTML
+output (but not any of the other conditionals, by default).  Source
+between @code{@@html} and @code{@@end html} is passed without change
+to the output (i.e., suppressing the normal escaping of input
address@hidden<}, @samp{>} and @samp{&} characters which have special
+significance in HTML).  @xref{Conditional Commands}.
 
-Using @samp{--init-file=html32.pm} produces strict address@hidden
-output (@pxref{Invoking @t{texi2any}}).
 
-Please report output from an error-free run of @code{makeinfo} which
-has browser portability problems as a bug (@pxref{Reporting Bugs}).
-
-
 @node HTML Splitting
 @section HTML Splitting
 @cindex Split HTML output