branch master updated: Document EPUB in more details

[Patrice Dumas]

This is an automated email from the git hooks/post-receive script.

pertusus pushed a commit to branch master
in repository texinfo.

The following commit(s) were added to refs/heads/master by this push:
     new bc862337ce Document EPUB in more details
bc862337ce is described below

commit bc862337ceb9cb4b7ba4f1c88f3e5ec8025f405c
Author: Patrice Dumas <pertusus@free.fr>
AuthorDate: Sun Jul 31 00:15:26 2022 +0200

    Document EPUB in more details
    
    * doc/texinfo.texi (Generating EPUB, EPUB Output File and Directory)
    (EPUB HTML): document in more details the generation of EPUB.
    (Invoking @command{texi2any}): explain how --output directory is
    used in EPUB.
    
    * tp/Texinfo/Common.pm, tp/ext/epub3.pm: rename
    EPUB_CREATE_CONTAINER as EPUB_CREATE_CONTAINER_FILE.
    
    * doc/texinfo.texi (@code{@@documentdescription}): move
    before HTML Xref.
---
 ChangeLog                         |  15 ++++
 doc/texinfo.texi                  | 150 +++++++++++++++++++++++++++++---------
 tp/Texinfo/Common.pm              |   2 +-
 tp/ext/epub3.pm                   |   6 +-
 tp/tests/formatting/list-of-tests |   2 +-
 tp/tests/layout/list-of-tests     |   4 +-
 6 files changed, 137 insertions(+), 42 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 1ff0a513f9..78025ff7e4 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,18 @@
+2022-07-30  Patrice Dumas  <pertusus@free.fr>
+
+       Document EPUB in more details
+
+       * doc/texinfo.texi (Generating EPUB, EPUB Output File and Directory)
+       (EPUB HTML): document in more details the generation of EPUB.
+       (Invoking @command{texi2any}): explain how --output directory is
+       used in EPUB.
+
+       * tp/Texinfo/Common.pm, tp/ext/epub3.pm: rename
+       EPUB_CREATE_CONTAINER as EPUB_CREATE_CONTAINER_FILE.
+
+       * doc/texinfo.texi (@code{@@documentdescription}): move
+       before HTML Xref.
+
 2022-07-30  Patrice Dumas  <pertusus@free.fr>
 
        Distinguish output and converted format, case of epub3/html
diff --git a/doc/texinfo.texi b/doc/texinfo.texi
index 2e0e0f75a5..85f95d25ef 100644
--- a/doc/texinfo.texi
+++ b/doc/texinfo.texi
@@ -570,8 +570,14 @@ Generating HTML
 * HTML Translation::       Details of the HTML output.
 * HTML Splitting::         How HTML output is split.
 * HTML CSS::               Influencing HTML output with Cascading Style Sheets.
-* HTML Xref::              Cross-references in HTML output.
 * @code{@@documentdescription}::   Document summary for the HTML output.
+* Generating EPUB::        Details on the EPUB output.
+* HTML Xref::              Cross-references in HTML output.
+
+Generating EPUB
+
+* EPUB Output File and Directory::
+* EPUB HTML::
 
 HTML Cross-references
 
@@ -15832,6 +15838,12 @@ name for the directory into which all files are 
written.  For example,
 @samp{texi2any -o bar --html foo.texi} will write
 @file{bar/index.html}, among other files.
 
+When generating EPUB a container directory for the files and directories needed
+for the EPUB format is created, as well as the EPUB output file.  If @var{file}
+corresponds to a directory, the container directory is placed within 
@var{file}.
+The EPUB output file is never put in this directory.  If @var{file} corresponds
+to a file, it is used for the EPUB output file name.
+
 @item --output-indent=@var{val}
 @opindex --outputindent
 This option now does nothing, but remains for compatibility.  (It used
@@ -15992,7 +16004,7 @@ Generate Texinfo XML output (rather than Info).
 overridden by a command line option.  The value should be one of:
 
 @example
-docbook  dvi  dvipdf  html  info  latex  pdf  plaintext  ps  xml
+docbook  dvi  dvipdf  epub3  html  info  latex  pdf  plaintext  ps  xml
 @end example
 
 If not set or otherwise specified, Info output is the default.
@@ -16250,6 +16262,7 @@ forms:
 @item docbook
 @itemx dvi
 @itemx dvipdf
+@itemx epub3
 @itemx html
 @itemx info
 @itemx pdf
@@ -18078,8 +18091,9 @@ manual.  @xref{,,,customization_api,GNU Texinfo 
@command{texi2any} Output Custom
 * HTML Translation::       Details of the HTML output.
 * HTML Splitting::         How HTML output is split.
 * HTML CSS::               Influencing HTML output with Cascading Style Sheets.
-* HTML Xref::              Cross-references in HTML output.
 * @code{@@documentdescription}::   Document summary for the HTML output.
+* Generating EPUB::        Details on the EPUB output.
+* HTML Xref::              Cross-references in HTML output.
 @end menu
 
 
@@ -18290,6 +18304,104 @@ has many user-definable customization variables with 
which you can
 influence the HTML output.  @xref{Customization Variables}.
 
 
+@node @code{@@documentdescription}
+@section @code{@@documentdescription}: Summary Text
+@anchor{documentdescription}@c old name
+
+@cindex Document description
+@cindex Description of document
+@cindex Summary of document
+@cindex Abstract of document
+@cindex @code{<meta>} HTML tag, and document description
+@findex documentdescription
+
+When producing HTML output for a document, a @samp{<meta>} element
+is written in the @samp{<head>} to give some idea of the
+content of the document.  By default, this @dfn{description} is the
+title of the document, taken from the @code{@@settitle} command
+(@pxref{@code{@@settitle}}).  To change this, use the
+@code{@@documentdescription} environment, as in:
+
+@example
+@@documentdescription
+descriptive text.
+@@end documentdescription
+@end example
+
+@noindent
+This will produce the following output in the @samp{<head>} of the HTML:
+
+@example
+<meta name=description content="descriptive text.">
+@end example
+
+
+@node Generating EPUB
+@section Generating EPUB
+
+@cindex EPUB, generating
+@cindex Generating EPUB
+@cindex Outputting EPUB
+
+EPUB is a format designed for reading electronic books on portable
+devices.  @command{texi2any} generated EPUB 3.2 in 2022.  An EPUB
+file is a ZIP archive container, holding informative files as
+well as the manual rendered in HTML.
+
+@node EPUB Output File and Directory
+@subsection Container Directory and Output Files
+A directory containing the files and directories needed for the
+EPUB format is created when outputting EPUB.  The name of this
+container directory is derived from the base name (that is, any
+extension is removed), with @code{_epub_package} postpended.
+If an output directory is specified, with @option{--output},
+or with the @code{SUBDIR} customization function,
+the container directory is created in that directory instead of
+the current directory.  At the beginning of a new run, the container
+directory and all its contents are removed.  The container directory
+is not removed even after the final EPUB file has been generated,
+such as to be able to look at what is archived in the EPUB output file.
+
+The HTML files produced from the Texinfo manual are output in subdirectories
+of the container directory.  Image files referred to from the Texinfo manual,
+if found, are copied to subdirectories of the container directory.
+
+The EPUB output file is a ZIP archive of the container directory.
+The file name is derived from the base name, with the @code{.epub}
+extension postpended.  If an output file is specified, with
+@option{--output}, or with the @code{OUTFILE} customization function,
+this file name is used instead.  The output EPUB file is never placed
+in the directory specified by @option{--output} or @code{SUBDIR},
+the container directory only is placed there as explained just above.  The EPUB
+output file is not generated if the customization variable
+@code{EPUB_CREATE_CONTAINER_FILE} is set to 0.
+
+@xref{Invoking @command{texi2any}}.
+
+
+@node EPUB HTML
+@subsection HTML Generated for EPUB
+
+The HTML generated for EPUB is XHTML conformant, UTF-8 encoded,
+formatted without the usual HTML navigation headers.  Most of
+these features are set with customization variables, such as
+@code{USE_XML_SYNTAX} or @code{OUTPUT_FILE_NAME_ENCODING}.  Some
+features of printed output are used in EPUB.  In particular, the Top
+node does not appear in the EPUB output, while a title page is
+generated.  This is obtained by setting @code{NO_TOP_NODE_OUTPUT}.
+
+The @code{OUTFILE} and @code{SUBDIR} that correspond initially
+to the EPUB directory container and/or the EPUB output file
+(@pxref{EPUB Output File and Directory}) are unset or reset to the
+locations in the container directory where the XHTML files are output
+for the HTML generation.  Resetting customization variables
+is unusual, this is why it is reported, however, the variables
+reset are used internally for the conversion, and should not
+interact with user set customization.
+
+@xref{HTML Customization Variables}.
+
+
 @node HTML Xref
 @section HTML Cross-references
 @cindex HTML cross-references
@@ -18802,38 +18914,6 @@ usual.  You can get the latest version from
 @url{http://ftpmirror.gnu.org/@/texinfo/@/htmlxref.cnf}.
 
 
-@node @code{@@documentdescription}
-@section @code{@@documentdescription}: Summary Text
-@anchor{documentdescription}@c old name
-
-@cindex Document description
-@cindex Description of document
-@cindex Summary of document
-@cindex Abstract of document
-@cindex @code{<meta>} HTML tag, and document description
-@findex documentdescription
-
-When producing HTML output for a document, a @samp{<meta>} element
-is written in the @samp{<head>} to give some idea of the
-content of the document.  By default, this @dfn{description} is the
-title of the document, taken from the @code{@@settitle} command
-(@pxref{@code{@@settitle}}).  To change this, use the
-@code{@@documentdescription} environment, as in:
-
-@example
-@@documentdescription
-descriptive text.
-@@end documentdescription
-@end example
-
-@noindent
-This will produce the following output in the @samp{<head>} of the HTML:
-
-@example
-<meta name=description content="descriptive text.">
-@end example
-
-
 @node @@-Command Details
 @appendix @@-Command Details
 
diff --git a/tp/Texinfo/Common.pm b/tp/Texinfo/Common.pm
index d9d0020650..a58ee53a63 100644
--- a/tp/Texinfo/Common.pm
+++ b/tp/Texinfo/Common.pm
@@ -291,7 +291,7 @@ my @variable_string_settables = (
 'DOC_ENCODING_FOR_INPUT_FILE_NAME',
 'DOC_ENCODING_FOR_OUTPUT_FILE_NAME',
 'DOCTYPE',
-'EPUB_CREATE_CONTAINER', # for ext/epub3.pm
+'EPUB_CREATE_CONTAINER_FILE', # for ext/epub3.pm
 'EXTENSION',
 'EXTERNAL_CROSSREF_EXTENSION',
 'EXTERNAL_CROSSREF_SPLIT',
diff --git a/tp/ext/epub3.pm b/tp/ext/epub3.pm
index eaa4d39275..066d1f449f 100644
--- a/tp/ext/epub3.pm
+++ b/tp/ext/epub3.pm
@@ -50,7 +50,7 @@ use File::Basename;
 use Encode qw(decode);
 
 # the Archive::Zip module is required below only if needed, that is
-# if EPUB_CREATE_CONTAINER is set.
+# if EPUB_CREATE_CONTAINER_FILE is set.
 #use Archive::Zip;
 
 # also for __(
@@ -61,7 +61,7 @@ use Texinfo::Convert::Text;
 my $epub_format_version = '3.2';
 
 # used in tests to avoid creating the .epub file.
-texinfo_set_from_init_file('EPUB_CREATE_CONTAINER', 1);
+texinfo_set_from_init_file('EPUB_CREATE_CONTAINER_FILE', 1);
 
 texinfo_set_format_from_init_file('html');
 
@@ -710,7 +710,7 @@ EOT
     return 0;
   }
 
-  if ($self->get_conf('EPUB_CREATE_CONTAINER')) {
+  if ($self->get_conf('EPUB_CREATE_CONTAINER_FILE')) {
     require Archive::Zip;
 
     # this is needed if there are non ascii file names, otherwise, for instance
diff --git a/tp/tests/formatting/list-of-tests 
b/tp/tests/formatting/list-of-tests
index a04f0e1bd3..1abd4cf9fa 100644
--- a/tp/tests/formatting/list-of-tests
+++ b/tp/tests/formatting/list-of-tests
@@ -22,7 +22,7 @@ cpp_lines ../../t/input_files/cpp_lines.texi -c 
MESSAGE_ENCODING=UTF-8
 non_ascii_command_line osé_utf8.texi -c COMMAND_LINE_ENCODING=UTF-8 -c 
MESSAGE_ENCODING=UTF-8 -c OUTPUT_FILE_NAME_ENCODING=UTF-8 --html 
--split=Mekanïk --document-language=Destruktïw -c 'Kommandöh vâl' -D TÛT -D 
'vùr ké' -U ôndef -c 'FORMAT_MENU mînù' 
--macro-expand=@OUT_DIR@osé-texinfo.texi --internal-links=@OUT_DIR@intérnal.txt 
--css-include çss.css --css-include cêss.css --css-ref=rëf --css-ref=öref
 
 # test for the copying of image with non ascii characters for epub
-non_ascii_test_epub osé_utf8.texi -c COMMAND_LINE_ENCODING=UTF-8 -c 
MESSAGE_ENCODING=UTF-8 -c OUTPUT_FILE_NAME_ENCODING=UTF-8 --init epub3.pm -c 
'EPUB_CREATE_CONTAINER 0'
+non_ascii_test_epub osé_utf8.texi -c COMMAND_LINE_ENCODING=UTF-8 -c 
MESSAGE_ENCODING=UTF-8 -c OUTPUT_FILE_NAME_ENCODING=UTF-8 --init epub3.pm -c 
'EPUB_CREATE_CONTAINER_FILE 0'
 
 # check that the output is right when based on @setfilename
 non_ascii_test_rawtext osé_utf8.texi -c COMMAND_LINE_ENCODING=UTF-8 -c 
MESSAGE_ENCODING=UTF-8 -c OUTPUT_FILE_NAME_ENCODING=UTF-8 -c 
INPUT_FILE_NAME_ENCODING=UTF-8 -c TEXINFO_OUTPUT_FORMAT=rawtext
diff --git a/tp/tests/layout/list-of-tests b/tp/tests/layout/list-of-tests
index 45b635e77a..9c9e320d84 100644
--- a/tp/tests/layout/list-of-tests
+++ b/tp/tests/layout/list-of-tests
@@ -39,8 +39,8 @@ formatting_exotic formatting.texi --split section --no-header 
--no-number-sectio
 formatting_inline_css formatting.texi -c 'INLINE_CSS_STYLE 1' -c 
DOCTYPE='<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 
"http://www.w3.org/TR/html4/loose.dtd";>'
 formatting_fr_icons formatting.texi --document-language fr --init icons.init
 formatting_chm formatting.texi -c FORMAT_MENU=nomenu --init chm.pm
-formatting_epub formatting.texi --epub3 -c 'EPUB_CREATE_CONTAINER 0'
-formatting_epub_nodes formatting.texi --split node --init epub3.pm -c 
'EPUB_CREATE_CONTAINER 0' -c INFO_JS_DIR=js
+formatting_epub formatting.texi --epub3 -c 'EPUB_CREATE_CONTAINER_FILE 0'
+formatting_epub_nodes formatting.texi --split node --init epub3.pm -c 
'EPUB_CREATE_CONTAINER_FILE 0' -c INFO_JS_DIR=js
 formatting formatting.texi 
--internal-links=@OUT_DIR@internal_links_formatting.txt
 
 #lightweight_markups_mediawiki lightweight_markups.texi --init mediawiki.pm