[PATCH] Add epub output for documentation

[PATCH] Add epub output for documentation

[Fejfighter]

[-- Attachment #1.1: Type: text/plain, Size: 485 bytes --]

Hi,

Attached is a patch that uses the newly added support for producing epub in
Texinfo.


TESTING:

I have built and viewed the epub on calibre and everything appears to work
well.

I have also tested building with an older version of texinfo and it does
not interfere with normal docs building.


FSF COPYRIGHT:

I'm not sure if this is over the threshold for exemption, but I have
completed paperwork for emacs and I am happy to do so again for GDB if
needed


Thanks,

Jeff Walsh

[-- Attachment #2: 0001-Add-support-for-epub-documentation-output.patch --]
[-- Type: text/x-patch, Size: 3229 bytes --]

From 44fdc332ff8f41258bd6d7dd5dc520af71ca770f Mon Sep 17 00:00:00 2001
From: Jeff Walsh <fejfighter@gmail.com>
Date: Wed, 9 Nov 2022 16:59:43 +1100
Subject: [PATCH] Add support for epub documentation output

Texinfo 7.0 added support for outputting texinfo documentation as an
epub, a popular format for e-readers. Add epub targets for the manuals
and relevent cleanup targets.
---
 gdb/doc/Makefile.in | 21 ++++++++++++++++++++-
 1 file changed, 20 insertions(+), 1 deletion(-)

diff --git a/gdb/doc/Makefile.in b/gdb/doc/Makefile.in
index 741da0eb812..d7d03274d43 100644
--- a/gdb/doc/Makefile.in
+++ b/gdb/doc/Makefile.in
@@ -60,6 +60,9 @@ MAKEINFO_CMD = $(MAKEINFO) $(MAKEINFOFLAGS) $(MAKEINFO_EXTRA_FLAGS)
 MAKEHTML = $(MAKEINFO_CMD) --html
 MAKEHTMLFLAGS =
 
+MAKEEPUB = $(MAKEINFO_CMD) --epub
+MAKEEPUBFLAGS =
+
 # where to find texi2roff, ditto
 TEXI2ROFF=texi2roff
 
@@ -92,6 +95,9 @@ PDFFILES = gdb.pdf stabs.pdf refcard.pdf annotate.pdf
 # Files which should be generated via 'html' and installed by 'install-html'
 HTMLFILES =  gdb/index.html stabs/index.html annotate/index.html
 HTMLFILES_INSTALL = gdb stabs annotate
+# Files which should be generated via 'epub' and installed by 'install-epub'
+EPUBFILES = gdb.epub stabs.epub annotate.epub
+
 
 # There may be alternate predefined collections of switches to configure
 # the GDB manual.  Normally this is not done in synch with the software
@@ -190,6 +196,7 @@ info: $(INFO_DEPS)
 dvi: gdb.dvi stabs.dvi refcard.dvi annotate.dvi
 ps: gdb.ps stabs.ps refcard.ps annotate.ps
 html: $(HTMLFILES)
+epub: $(EPUBFILES)
 pdf: $(PDFFILES)
 man: $(MANS)
 
@@ -566,6 +573,10 @@ gdb.mm: $(GDB_DOC_FILES) links2roff
 gdb/index.html: ${GDB_DOC_FILES}
 	$(MAKEHTML) $(MAKEHTMLFLAGS) $(READLINE_TEXI_INCFLAG) -I ${GDBMI_DIR} -I $(srcdir) $(srcdir)/gdb.texinfo
 
+# GDB MANUAL: EPUB file
+gdb.epub: ${GDB_DOC_FILES}
+	$(MAKEEPUB) $(MAKEEPUBFLAGS) $(READLINE_TEXI_INCFLAG) -I ${GDBMI_DIR} -I $(srcdir) $(srcdir)/gdb.texinfo
+
 stabs.info: $(STABS_DOC_FILES)
 	$(MAKEINFO_CMD) -I $(srcdir) -o stabs.info $(srcdir)/stabs.texinfo
 
@@ -574,6 +585,11 @@ stabs.info: $(STABS_DOC_FILES)
 stabs/index.html: $(STABS_DOC_FILES)
 	$(MAKEHTML) $(MAKEHTMLFLAGS) -I $(srcdir) $(srcdir)/stabs.texinfo
 
+# STABS DOCUMENTATION: EPUB file
+
+stabs.epub: $(STABS_DOC_FILES)
+	$(MAKEEPUB) $(MAKEEPUBFLAGS) -I $(srcdir) $(srcdir)/stabs.texinfo
+
 # Clean these up before each run.  Avoids a catch 22 with not being
 # able to re-generate these files (to fix a corruption) because these
 # files contain a corruption.
@@ -616,6 +632,9 @@ annotate.info: $(ANNOTATE_DOC_FILES)
 annotate/index.html: $(ANNOTATE_DOC_FILES)
 	$(MAKEHTML) $(MAKEHTMLFLAGS) -I $(srcdir) $(srcdir)/annotate.texinfo
 
+annotate.epub: $(ANNOTATE_DOC_FILES)
+	$(MAKEEPUB) $(MAKEEPUBFLAGS) -I $(srcdir) $(srcdir)/annotate.texinfo
+
 # Man pages
 gdb.1: $(GDB_DOC_FILES)
 	touch $@
@@ -679,7 +698,7 @@ distclean: clean
 # "clean" or "distclean".  Use maintainer-clean to remove them.
 
 maintainer-clean realclean: distclean
-	rm -f GDBvn.texi version.subst *.info* *.dvi *.ps *.html *.pdf $(MANS)
+	rm -f GDBvn.texi version.subst *.info* *.dvi *.ps *.html *.pdf *.epub $(MANS)
 
 install: install-info install-man
 
-- 
2.38.1

Re: [PATCH] Add epub output for documentation

[Eli Zaretskii]

> Date: Wed, 9 Nov 2022 18:54:51 +1100
> From: Fejfighter via Gdb-patches <gdb-patches@sourceware.org>
> 
> Attached is a patch that uses the newly added support for producing epub in
> Texinfo.

Thanks, this is fine with me.

Re: [PATCH] Add epub output for documentation

[Simon Marchi]

On 11/9/22 07:38, Eli Zaretskii via Gdb-patches wrote:
>> Date: Wed, 9 Nov 2022 18:54:51 +1100
>> From: Fejfighter via Gdb-patches <gdb-patches@sourceware.org>
>>
>> Attached is a patch that uses the newly added support for producing epub in
>> Texinfo.
> 
> Thanks, this is fine with me.

Fine with me too.  Would you like me to push it?

Simon

Re: [PATCH] Add epub output for documentation

[Eli Zaretskii]

> Date: Wed, 9 Nov 2022 08:21:36 -0500
> Cc: gdb-patches@sourceware.org
> From: Simon Marchi <simark@simark.ca>
> 
> 
> 
> On 11/9/22 07:38, Eli Zaretskii via Gdb-patches wrote:
> >> Date: Wed, 9 Nov 2022 18:54:51 +1100
> >> From: Fejfighter via Gdb-patches <gdb-patches@sourceware.org>
> >>
> >> Attached is a patch that uses the newly added support for producing epub in
> >> Texinfo.
> > 
> > Thanks, this is fine with me.
> 
> Fine with me too.  Would you like me to push it?

Yes, please.

Re: [PATCH] Add epub output for documentation

[Simon Marchi]

On 11/9/22 08:22, Eli Zaretskii wrote:
>> Date: Wed, 9 Nov 2022 08:21:36 -0500
>> Cc: gdb-patches@sourceware.org
>> From: Simon Marchi <simark@simark.ca>
>>
>>
>>
>> On 11/9/22 07:38, Eli Zaretskii via Gdb-patches wrote:
>>>> Date: Wed, 9 Nov 2022 18:54:51 +1100
>>>> From: Fejfighter via Gdb-patches <gdb-patches@sourceware.org>
>>>>
>>>> Attached is a patch that uses the newly added support for producing epub in
>>>> Texinfo.
>>>
>>> Thanks, this is fine with me.
>>
>> Fine with me too.  Would you like me to push it?
> 
> Yes, please.

Actually, I have one comment.  The comment (copied from the html rule)
says:

    and installed by 'install-epub'

But there is no install-epub.  Should there be one?

Simon

Re: [PATCH] Add epub output for documentation

[Eli Zaretskii]

> Date: Wed, 9 Nov 2022 08:41:18 -0500
> Cc: fejfighter@gmail.com, gdb-patches@sourceware.org
> From: Simon Marchi <simark@simark.ca>
> 
> >>> Thanks, this is fine with me.
> >>
> >> Fine with me too.  Would you like me to push it?
> > 
> > Yes, please.
> 
> Actually, I have one comment.  The comment (copied from the html rule)
> says:
> 
>     and installed by 'install-epub'
> 
> But there is no install-epub.  Should there be one?

I don't know how this should be integrated with "make install", this
is a question for Joel, I think.

Re: [PATCH] Add epub output for documentation

[Simon Marchi]

On 11/9/22 08:44, Eli Zaretskii wrote:
>> Date: Wed, 9 Nov 2022 08:41:18 -0500
>> Cc: fejfighter@gmail.com, gdb-patches@sourceware.org
>> From: Simon Marchi <simark@simark.ca>
>>
>>>>> Thanks, this is fine with me.
>>>>
>>>> Fine with me too.  Would you like me to push it?
>>>
>>> Yes, please.
>>
>> Actually, I have one comment.  The comment (copied from the html rule)
>> says:
>>
>>     and installed by 'install-epub'
>>
>> But there is no install-epub.  Should there be one?
> 
> I don't know how this should be integrated with "make install", this
> is a question for Joel, I think.

"make install" only installs the man pages and the info version of the
manual.  The pdf or html versions of the manual are only installed with
explicit "install-pdf" and "install-html" rules.  So I presume that epub
would be the same as pdf and html.

Simon

Re: [PATCH] Add epub output for documentation

[Tom Tromey]

>>>>> "Simon" == Simon Marchi via Gdb-patches <gdb-patches@sourceware.org> writes:

Simon> "make install" only installs the man pages and the info version of the
Simon> manual.  The pdf or html versions of the manual are only installed with
Simon> explicit "install-pdf" and "install-html" rules.  So I presume that epub
Simon> would be the same as pdf and html.

I think so too.  Is there a typical GNU directory for where exactly
these should be installed?

Tom

Re: [PATCH] Add epub output for documentation

[Simon Marchi]

On 11/9/22 10:48, Tom Tromey wrote:
>>>>>> "Simon" == Simon Marchi via Gdb-patches <gdb-patches@sourceware.org> writes:
> 
> Simon> "make install" only installs the man pages and the info version of the
> Simon> manual.  The pdf or html versions of the manual are only installed with
> Simon> explicit "install-pdf" and "install-html" rules.  So I presume that epub
> Simon> would be the same as pdf and html.
> 
> I think so too.  Is there a typical GNU directory for where exactly
> these should be installed?

Autoconf doesn't specify an "epubdir" like there is an "htmldir" and a
"pdfdir".  I think we could just install it in docdir instead (htmldir
and pdfdir default do that).

Simon

Re: [PATCH] Add epub output for documentation

[Eli Zaretskii]

> From: Tom Tromey <tom@tromey.com>
> Cc: Eli Zaretskii <eliz@gnu.org>,  Joel Brobecker <brobecker@adacore.com>,
>   Simon Marchi <simark@simark.ca>,  fejfighter@gmail.com
> Date: Wed, 09 Nov 2022 08:48:41 -0700
> 
> Simon> "make install" only installs the man pages and the info version of the
> Simon> manual.  The pdf or html versions of the manual are only installed with
> Simon> explicit "install-pdf" and "install-html" rules.  So I presume that epub
> Simon> would be the same as pdf and html.
> 
> I think so too.  Is there a typical GNU directory for where exactly
> these should be installed?

No, we are on our own.

I think it would be good to tell the Texinfo maintainers to start
thinking about a standard directory for EPUB format, because more and
more projects will bump into this issue.

Re: [PATCH] Add epub output for documentation

[Mike Frysinger]

[-- Attachment #1: Type: text/plain, Size: 1434 bytes --]

On 09 Nov 2022 11:15, Simon Marchi via Gdb-patches wrote:
> On 11/9/22 10:48, Tom Tromey wrote:
> >>>>>> "Simon" == Simon Marchi via Gdb-patches <gdb-patches@sourceware.org> writes:
> > 
> > Simon> "make install" only installs the man pages and the info version of the
> > Simon> manual.  The pdf or html versions of the manual are only installed with
> > Simon> explicit "install-pdf" and "install-html" rules.  So I presume that epub
> > Simon> would be the same as pdf and html.
> > 
> > I think so too.  Is there a typical GNU directory for where exactly
> > these should be installed?
> 
> Autoconf doesn't specify an "epubdir" like there is an "htmldir" and a
> "pdfdir".  I think we could just install it in docdir instead (htmldir
> and pdfdir default do that).

all the random file formats go into $docdir, so using that sounds fine

that said, having an "install-epub" rule in gdb alone (and in the doc/
subdir at that) seems pretty questionable.  seems like someone who is
interested in moving the epub needle should spend the time pushing it
through all the GNU parts, assuming the texinfo people aren't already.

there's certainly autoconf as you highlight, but also the GNU standards,
and the GCC top-level, and binutils/gdb top-level, and automake, and the
binutils/gdb release scripts so things get published to the websites.
that's off the top of my head, but i'm sure there's more.
-mike

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH] Add epub output for documentation

[Eli Zaretskii]

> Date: Wed, 9 Nov 2022 23:53:32 +0700
> From: Mike Frysinger <vapier@gentoo.org>
> Cc: Tom Tromey <tom@tromey.com>,
> 	Simon Marchi via Gdb-patches <gdb-patches@sourceware.org>,
> 	Eli Zaretskii <eliz@gnu.org>,
> 	Joel Brobecker <brobecker@adacore.com>, fejfighter@gmail.com
> 
> that said, having an "install-epub" rule in gdb alone (and in the doc/
> subdir at that) seems pretty questionable.  seems like someone who is
> interested in moving the epub needle should spend the time pushing it
> through all the GNU parts, assuming the texinfo people aren't already.
> 
> there's certainly autoconf as you highlight, but also the GNU standards,
> and the GCC top-level, and binutils/gdb top-level, and automake, and the
> binutils/gdb release scripts so things get published to the websites.
> that's off the top of my head, but i'm sure there's more.

Right, I wrote to the Texinfo list about that.