branch master updated: EPUB Conformance issues documentation, workarounds and TODO

[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 e142a9015c EPUB Conformance issues documentation, workarounds and TODO
e142a9015c is described below

commit e142a9015c7b403b10207f77acacad72a88d01ef
Author: Patrice Dumas <pertusus@free.fr>
AuthorDate: Fri Aug 23 10:18:19 2024 +0200

    EPUB Conformance issues documentation, workarounds and TODO
    
    * TODO, doc/texinfo.texi (EPUB Conformance),
    contrib/EPUB_conformance/*.patch, contrib/EPUB_conformance/README:
    document that EPUB generated is not conformant.  Add patches from
    Daniel Cerqueira in contrib/EPUB_conformance/ that cannot be applied
    as is, but are necessary for EPUB conformance.  Add TODO entries that
    should allow to fix more permanently this issue.
---
 ChangeLog                                          | 11 ++++
 TODO                                               | 19 +++++++
 ...Convert-HTML.pm-Fix-EPUB-validity-on-tabl.patch | 30 +++++++++++
 ....pm-add-mandatory-tag-of-dcterms-modified.patch | 60 ++++++++++++++++++++++
 contrib/EPUB_conformance/README                    |  1 +
 doc/texinfo.texi                                   | 11 ++++
 6 files changed, 132 insertions(+)

diff --git a/ChangeLog b/ChangeLog
index 261eb44204..2eb1031980 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,14 @@
+2024-08-23  Patrice Dumas  <pertusus@free.fr>
+
+       EPUB Conformance issues documentation, workarounds and TODO
+
+       * TODO, doc/texinfo.texi (EPUB Conformance),
+       contrib/EPUB_conformance/*.patch, contrib/EPUB_conformance/README:
+       document that EPUB generated is not conformant.  Add patches from
+       Daniel Cerqueira in contrib/EPUB_conformance/ that cannot be applied
+       as is, but are necessary for EPUB conformance.  Add TODO entries that
+       should allow to fix more permanently this issue.
+
 2024-08-22  Gavin Smith <gavinsmith0123@gmail.com>
 
        * util/htmlxref.cnf: Add eglot.  Report from Eli.
diff --git a/TODO b/TODO
index da803905a3..4a8ec8f1c6 100644
--- a/TODO
+++ b/TODO
@@ -32,6 +32,19 @@ If you are interested in working on any of these, email 
bug-texinfo@gnu.org.
      * add metadata on last modification date (needed in EPUB)
      * make it easier to gather author metadata
      * short information on licence
+    For modification dates, it could be relevant to have two dates in
+    one for publication (this one would be used in EPUB for example)
+    and a date of modification of the Texinfo manual (what is
+    currectly set with automake and accessible as @value{UPDATED}).
+
+    For the publication date, what the user would put in the metadata
+    would take precedence, and if there is none the publication date as
+    implemented in Daniel Cerqueira patch in contrib/EPUB_conformance.
+
+    For the manual change date, what the user would put in the metadata
+    would take precedence, and if there is none the modification timestamp
+    of the main texinfo file (or the newest for the main and all @include'd
+    files) would be the default.
   - unique identifiers/way to disambiguate manuals with the same name?
   - reflection on guide/topic document structure and pluggable content
     for extensible documents (Mallard format ideas)
@@ -40,6 +53,12 @@ If you are interested in working on any of these, email 
bug-texinfo@gnu.org.
   - HTML: support thumbnails.
   - HTML: have a library of different CSS styles.
     http://mail.gnu.org/archive/html/bug-texinfo/2004-01/msg00025.html
+  - HTML: use CSS for <table> border.  Also for cellpadding and similar
+    if someone knows what should be done as now it seems to be
+    properties of the cells.
+  - EPUB: add a customization variable that sets the output to be different
+    from the HTML default output, if needed, to attain full epubcheck
+    conformance, as it seems to be asked for by some publishers.
   - Support output formats retaining the tree structure of Texinfo documents
     as parsed by the Parser.  A lisp-like format for GUILE? Maybe JSON?
   - Support other graphical documentation browsers like GNOME DevHelp
diff --git 
a/contrib/EPUB_conformance/0001-tp-Texinfo-Convert-HTML.pm-Fix-EPUB-validity-on-tabl.patch
 
b/contrib/EPUB_conformance/0001-tp-Texinfo-Convert-HTML.pm-Fix-EPUB-validity-on-tabl.patch
new file mode 100644
index 0000000000..61227b2a60
--- /dev/null
+++ 
b/contrib/EPUB_conformance/0001-tp-Texinfo-Convert-HTML.pm-Fix-EPUB-validity-on-tabl.patch
@@ -0,0 +1,30 @@
+From a6855aac641d78a781ed720cf070c2b5f07bc449 Mon Sep 17 00:00:00 2001
+From: Daniel Cerqueira <dan.git@lispclub.com>
+Date: Tue, 20 Aug 2024 21:51:19 +0100
+Subject: [PATCH] tp/Texinfo/Convert/HTML.pm: Fix EPUB validity on table border
+
+ - fix `epubchecker` error thrown on checking for validity of an EPUB
+ file. This addresses the index <table ... border=...> element and
+ property.
+
+Signed-off-by: Daniel Cerqueira <dan.git@lispclub.com>
+---
+ tp/Texinfo/Convert/HTML.pm | 2 +-
+ 1 file changed, 1 insertion(+), 1 deletion(-)
+
+diff --git a/tp/Texinfo/Convert/HTML.pm b/tp/Texinfo/Convert/HTML.pm
+index 5901e0db53..81435076d9 100644
+--- a/tp/Texinfo/Convert/HTML.pm
++++ b/tp/Texinfo/Convert/HTML.pm
+@@ -5978,7 +5978,7 @@ sub _convert_printindex_command($$$$)
+   # now format the index entries
+   $result
+    .= $self->html_attribute_class('table', ["$index_name-entries-$cmdname"])
+-    ." border=\"0\">\n" . '<tr><td></td>'
++    ." border=\"1\">\n" . '<tr><td></td>'
+     . $self->html_attribute_class('th', ["entries-header-$cmdname"]).'>'
+       # TRANSLATORS: index entries column header in index formatting
+     . $self->convert_tree($self->gdt('Index Entry')) .'</th>'
+-- 
+2.45.2
+
diff --git 
a/contrib/EPUB_conformance/0001-tp-ext-epub.pm-add-mandatory-tag-of-dcterms-modified.patch
 
b/contrib/EPUB_conformance/0001-tp-ext-epub.pm-add-mandatory-tag-of-dcterms-modified.patch
new file mode 100644
index 0000000000..c45bdb65ab
--- /dev/null
+++ 
b/contrib/EPUB_conformance/0001-tp-ext-epub.pm-add-mandatory-tag-of-dcterms-modified.patch
@@ -0,0 +1,60 @@
+From f2fe59894c86e72939b42749a5e479a96c1795c5 Mon Sep 17 00:00:00 2001
+From: Daniel Cerqueira <dan.git@lispclub.com>
+Date: Tue, 20 Aug 2024 21:08:10 +0100
+Subject: [PATCH 1/2] tp/ext/epub.pm: add mandatory tag of dcterms:modified
+
+ - fix validity of EPUB file, adding the mandatory dcterms:modified
+ meta tag
+
+Signed-off-by: Daniel Cerqueira <dan.git@lispclub.com>
+---
+ tp/ext/epub3.pm | 17 +++++++----------
+ 1 file changed, 7 insertions(+), 10 deletions(-)
+
+diff --git a/tp/ext/epub3.pm b/tp/ext/epub3.pm
+index d2bf751ff8..8ba930fc96 100644
+--- a/tp/ext/epub3.pm
++++ b/tp/ext/epub3.pm
+@@ -98,6 +98,9 @@ use Texinfo::Common;
+ use Texinfo::Convert::Utils;
+ use Texinfo::Convert::Text;
+ 
++# for the meta dcterms:modified tag
++use Time::Piece;
++
+ # try to load here, but only complain and return an error later
+ # when the customization variables are known.
+ eval { require Archive::Zip; };
+@@ -754,16 +757,9 @@ EOT
+   my $unique_uid = 'texi-uid';
+   # TODO to discuss on bug-texinfo
+   my $identifier = 'texinfo:'.$document_name;
+-  # FIXME the dcterms:modified is mandatory, and it is also mandatory that it 
is a date:
+-  #  each Rendition MUST include exactly one [DCTERMS] modified property 
containing its last modification date. The value of this property MUST be an 
[XMLSCHEMA-2] dateTime conformant date of the form:
+-
+-  # CCYY-MM-DDThh:mm:ssZ
+-  #
+-  # The last modification date MUST be expressed in Coordinated Universal 
Time (UTC) and MUST be terminated by the "Z" (Zulu) time zone indicator.
+-  #
+-  # <meta property="dcterms:modified">2012-03-05T12:47:00Z</meta>
+-  # to discuss
+-  # <dc:rights>
++  # the [XMLSCHEMA-2] dateTime ( CCYY-MM-DDThh:mm:ssZ )
++  my $datetime_zulu = gmtime()->strftime("%Y-%m-%dT%TZ");
++
+   my $opf_file_path_name = File::Spec->catfile($epub_destination_directory,
+                                         $epub_document_dir_name, 
$opf_filename);
+   my ($encoded_opf_file_path_name, $opf_path_encoding)
+@@ -784,6 +780,7 @@ EOT
+    <metadata xmlns:dc="http://purl.org/dc/elements/1.1/";>
+       <dc:identifier id="$unique_uid">$identifier</dc:identifier>
+       <dc:title>$title</dc:title>
++      <meta property="dcterms:modified">$datetime_zulu</meta>
+ EOT
+   my @relevant_commands = ('author', 'documentlanguage');
+   my $collected_commands = Texinfo::Common::collect_commands_list_in_tree(
+
+base-commit: 01c47c76d65aa86dbd38d8bb969b1a511b7258d8
+-- 
+2.45.2
+
diff --git a/contrib/EPUB_conformance/README b/contrib/EPUB_conformance/README
new file mode 100644
index 0000000000..d9c0709a95
--- /dev/null
+++ b/contrib/EPUB_conformance/README
@@ -0,0 +1 @@
+Patches to improve EPUB conformance by Daniel Cerqueira.
diff --git a/doc/texinfo.texi b/doc/texinfo.texi
index 3b4fc420b4..71a34c32ae 100644
--- a/doc/texinfo.texi
+++ b/doc/texinfo.texi
@@ -17394,6 +17394,17 @@ missing cross-references information.  If these 
warnings are unwanted,
 set @code{CHECK_HTMLXREF} to 0.
 
 
+@node EPUB Conformance
+@subsection Unresolved EPUB Conformance Issues
+
+Strict conformance of EPUB generated from Texinfo is still a work in
+progress.  In particular, the last modified date @samp{dcterms:modified}
+property is not generated and conformance checkers flag @code{border="0"}
+HTML table element attribute as invalid.  Before these issues are
+definitively fixed, patches in the Texinfo source directory
+@file{contrib/EPUB_conformance/} can be applied to workaround those issues.
+
+
 @node EPUB HTML
 @nodedescription Variables set internally.
 @subsection HTML Generated for EPUB