branch master updated: Update README and little change in comments

[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 e16f1569f4 Update README and little change in comments
e16f1569f4 is described below

commit e16f1569f4af019b6a903c6c3e30d4993b58a05c
Author: Patrice Dumas <pertusus@free.fr>
AuthorDate: Mon Oct 24 11:16:33 2022 +0200

    Update README and little change in comments
---
 tp/README       | 19 +++++++++----------
 tp/ext/epub3.pm |  5 +++--
 tp/t/README     | 45 ++++++++++++++++++++++++++-------------------
 3 files changed, 38 insertions(+), 31 deletions(-)

diff --git a/tp/README b/tp/README
index 518ddff341..4283f08b39 100644
--- a/tp/README
+++ b/tp/README
@@ -1,6 +1,6 @@
 texinfo/tp/README
 
-  Copyright 2011-2019 Free Software Foundation, Inc.
+  Copyright 2011-2022 Free Software Foundation, Inc.
 
   Copying and distribution of this file, with or without modification,
   are permitted in any medium without royalty provided the copyright
@@ -8,7 +8,7 @@ texinfo/tp/README
 
 Texinfo::Parser (hence the directory name tp) is a Perl module for
 parsing Texinfo code into a tree representing the Texinfo code
-structure.
+structure and converting the tree to diverse output formats.
 
 These other modules and libraries are required (all have been standard
 parts of Perl for years, at least since 5.7.3):
@@ -20,6 +20,11 @@ It also uses the less widely-available modules:
 For these, internal versions are included, and are installed and used as
 part of Texinfo (not disturbing the Perl installation at all).
 
+Archive::Zip is needed for the EPUB output format final file creation.
+It is not included in Texinfo, it is detected at runtime and an error is
+issued if it cannot be loaded.
+
+
 To run the tests you also need:
   Test::More, Data::Compare, Test::Deep
 On Debian-based distros, Test::More is part of perl-modules and thus 
@@ -31,12 +36,6 @@ The tests are in the subdirectories t/ and test/.  The tests 
in t/ test
 the Perl modules used by the makeinfo command, and the tests in test/ 
 test the command itself.
 
-This module is part of GNU Texinfo.  A standalone Perl module may also be
-produced from within the the Texinfo tree, using 
-  ./maintain/prepare_perl_standalone_module_archive.sh
-The resulting module, although standalone, should always be regenerated
-from the sources in Texinfo, to avoid divergence of sources.
-
 
 If you want to delve into making a new backend, the documentation in
 tp/Texinfo/Convert/Converter.pm is a good starting point, as it
@@ -44,8 +43,8 @@ describes the existing backends and other places to look.  To 
do a good
 job, expect to spend a lot of time making it do the right thing with the
 existing tests.
 
-tp builds a complicated parse tree.  It can output a lot of debug
-information about the tree, and what it's doing generally.  For example,
+The Texinfo parser builds a complicated parse tree.  It can output a lot of
+debug information about the tree, and what it's doing generally.  For example,
 these commands output the tree (in different forms):
   makeinfo -c DUMP_TREE=1 -c TEXINFO_OUTPUT_FORMAT=parse document.texi
   makeinfo -c TEXINFO_OUTPUT_FORMAT=debugtree document.texi
diff --git a/tp/ext/epub3.pm b/tp/ext/epub3.pm
index 068e1e5e13..985fb22cf6 100644
--- a/tp/ext/epub3.pm
+++ b/tp/ext/epub3.pm
@@ -68,11 +68,12 @@
 # to refer to a manual in an epub container, and to a specific file in
 # that container.
 # Collections of epub manunals for local browsing would be an interesting
-# feature, but for now cannot be achieved because of those limitations..
+# feature, but for now cannot be achieved because of those limitations.
 # If references to other EPUB files were possible, NODE_FILES would
 # probably need to be set.
 # For now, external manuals not found in htmlxref are resolved
-# to a path that makes no sense:
+# to a path that makes no sense, for example for a reference to the
+# Pod-Simple-Texinfo manual:
 # EPUB/Pod-Simple-Texinfo_epub3/index.html
 
 use strict;
diff --git a/tp/t/README b/tp/t/README
index 0869cc9de7..a11221f75a 100644
--- a/tp/t/README
+++ b/tp/t/README
@@ -1,6 +1,6 @@
 texinfo/tp/t/README
 
-  Copyright 2010-2019 Free Software Foundation, Inc.
+  Copyright 2010-2022 Free Software Foundation, Inc.
 
   Copying and distribution of this README file, with or without
   modification, are permitted in any medium without royalty provided the
@@ -28,12 +28,13 @@ Another way to run a test out-source is:
   srcdir=$s ../pre-inst-env perl -w $s/t/92formatting.t empty
 
 where s is the path to the srcdir.  This allows you to run a single
-sub-test.
+sub-test, here the sub-test with name "empty".
 
 Most test files use a testing infrastructure from t/test_utils.pl.
 The run_all function from that file runs the tests that have been
 specified.
 
+
 In that case the reference output files for the test of a test category
 $test_category.t file are in t/results/$test_category/.  For example, if
 after running "make check" test-suite.log contains a line like:
@@ -52,7 +53,7 @@ change any of the output, one way to check this would be to 
run "make
 check" and then "grep FAIL test-suite.log | grep -v 'tree$'".
 
 The tests output on STDERR are not checked, it is possible to look
-for surious output on STDERR in addition to the header and
+for spurious output on STDERR in addition to the header and
 information after "make check" with:
 
  grep -v -e '^ok [0-9]\+' -e '^PASS:' -e '^SKIP:' -e '1\.\.[0-9]\+$' t/*.log
@@ -65,6 +66,15 @@ To review all the differences for one of the *.t test files, 
you can do:
   for f in t/results/coverage_braces/*.pl; do echo --------; echo \
   Differences in $f; diff $f{,.new}; done | less
 
+For some tests, as well as a .pl file as usual in results/*/, actual
+output files are generated.  For those tests, there are directories with
+reference test results (with names prefixed with res_), and directories
+with the obtained results (with names prefixed with out_).  For example,
+many of the tests whose results are in the 'results/indices' directory
+follow this format.  (The same convention is used by the test suite in
+../tests.)
+
+
 The reference files are regenerated with the -g option given to the .t
 file, as in
 
@@ -76,18 +86,20 @@ files for the "test_image" test within 
t/03.coverage_braces.t, run
 
   perl -w t/03coverage_braces.t -g test_image
 
+Another way to overwrite the reference test results with the obtained
+results from the last test run when not actual output file are generated
+is to use a command like
+
+  for f in t/results/*/*.pl.new ; do cp ${f%.new} $f ; done
+
+
 Some tests under this directory use input files in the 'input_files'
 subdirectory.  When adding a test that uses an input file, add its path
 to tp/Makefile.am.
 
+Customization files from the tp/init and tp/t/init directories can
+be used in tests.
 
-For some tests, as well as a .pl file as usual in results/*/, actual
-output files are generated.  For those tests, there are directories with
-reference test results (with names prefixed with res_), and directories
-with the obtained results (with names prefixed with out_).  For example,
-many of the tests whose results are in the 'results/indices' directory
-follow this format.  (The same convention is used by the test suite in
-../tests.)
 
 Tests can be managed using the script in ./maintain/all_tests.sh.  For
 example, "./maintain/all_tests.sh generate" regenerates all of the
@@ -95,18 +107,13 @@ reference test results (run from the upper-level 
directory), and
 "./maintain/all_tests.sh diff" makes a diff of all resulting files
 against references.
 
-Another way to overwrite the reference test results with the obtained
-results from the last test run is to use a command like
-
-  for f in t/results/*/*.pl.new ; do cp ${f%.new} $f ; done
-
-From the top directory, you can also create texinfo files corresponding to
-tests by running something along the lines of:
+From the top directory, you can also create Texinfo files corresponding to
+tests in t_texis/$test_category/ by running something along the lines of:
 
   perl -w t/60macro.t -c
 
-to create a file for each of the tests in t/60macro.t, or for a specific
-test, here arg_body_expansion_order:
+to create a Texinfo file for each of the tests in t/60macro.t, or for a
+specific test, here arg_body_expansion_order:
 
   perl -w t/60macro.t -c arg_body_expansion_order