[PATCH] xfsdocs: add epub output

[PATCH] xfsdocs: add epub output

[Csaba Henk]

---
 .gitignore                               |  1 +
 admin/Makefile                           | 13 +++++++++++--
 admin/XFS_Performance_Tuning/Makefile    | 13 +++++++++++--
 design/Makefile                          | 13 +++++++++++--
 design/XFS_Filesystem_Structure/Makefile | 13 +++++++++++--
 5 files changed, 45 insertions(+), 8 deletions(-)

diff --git a/.gitignore b/.gitignore
index a2e10b4..412ff1c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,4 @@
 *.html
 *.pdf
 *.css
+*.epub
diff --git a/admin/Makefile b/admin/Makefile
index de27f3b..dcffc63 100644
--- a/admin/Makefile
+++ b/admin/Makefile
@@ -11,6 +11,7 @@ DOCFILES=$(wildcard *.asciidoc)
 
 HTML_TARGETS=$(addsuffix .html, $(basename $(DOCFILES)))
 PDF_TARGETS=$(addsuffix .pdf, $(basename $(DOCFILES)))
+EPUB_TARGETS=$(addsuffix .epub, $(basename $(DOCFILES)))
 
 %.html: %.asciidoc
 	@echo "[html] $*"
@@ -20,7 +21,11 @@ PDF_TARGETS=$(addsuffix .pdf, $(basename $(DOCFILES)))
 	@echo "[pdf] $*"
 	$(Q)a2x -f pdf $<
 
-default: html pdf $(SUBDIRS)
+%.epub: %.asciidoc
+	@echo "[epub] $*"
+	$(Q)a2x -f epub $<
+
+default: html pdf epub $(SUBDIRS)
 
 $(SUBDIRS):
 	@echo "Building $@"
@@ -30,14 +35,18 @@ html: $(HTML_TARGETS)
 
 pdf: $(PDF_TARGETS)
 
+epub: $(EPUB_TARGETS)
+
 # manually construct build dependencies for target builds so that modification
 # of individual files will trigger a rebuild of the document correctly.
 $(PDF_TARGETS): $(DOCFILES)
 
 $(HTML_TARGETS): $(DOCFILES)
 
+$(EPUB_TARGETS): $(DOCFILES)
+
 clean: $(addsuffix -clean, $(SUBDIRS))
-	$(Q)rm -f *.html *.pdf *.css
+	$(Q)rm -f *.html *.pdf *.css *.epub
 
 %-clean:
 	@echo "Cleaning $*"
diff --git a/admin/XFS_Performance_Tuning/Makefile b/admin/XFS_Performance_Tuning/Makefile
index 06451f1..2b929a4 100644
--- a/admin/XFS_Performance_Tuning/Makefile
+++ b/admin/XFS_Performance_Tuning/Makefile
@@ -8,8 +8,9 @@ DOCFILES=$(wildcard *.asciidoc) \
 
 HTML_TARGET=$(addsuffix .html, $(TARGET))
 PDF_TARGET=$(addsuffix .pdf, $(TARGET))
+EPUB_TARGET=$(addsuffix .epub, $(TARGET))
 
-default: html pdf
+default: html pdf epub
 
 %.html: %.asciidoc
 	@echo "[html] $*"
@@ -19,16 +20,24 @@ default: html pdf
 	@echo "[pdf] $*"
 	$(Q)a2x -f pdf -d book $<
 
+%.epub: %.asciidoc
+	@echo "[epub] $*"
+	$(Q)a2x -f epub -d book $<
+
 html: $(HTML_TARGET)
 
 pdf: $(PDF_TARGET)
 
+epub: $(EPUB_TARGET)
+
 # manually construct build dependencies for target builds so that modification
 # of individual files will trigger a rebuild of the document correctly.
 $(PDF_TARGET): $(DOCFILES)
 
 $(HTML_TARGET): $(DOCFILES)
 
+$(EPUB_TARGET): $(DOCFILES)
+
 clean:
-	$(Q)rm -f *.html *.pdf *.css
+	$(Q)rm -f *.html *.pdf *.css *.epub
 
diff --git a/design/Makefile b/design/Makefile
index 0879470..0847896 100644
--- a/design/Makefile
+++ b/design/Makefile
@@ -11,6 +11,7 @@ DOCFILES=$(wildcard *.asciidoc)
 
 HTML_TARGETS=$(addsuffix .html, $(basename $(DOCFILES)))
 PDF_TARGETS=$(addsuffix .pdf, $(basename $(DOCFILES)))
+EPUB_TARGETS=$(addsuffix .epub, $(basename $(DOCFILES)))
 
 %.html: %.asciidoc
 	@echo "[html] $*"
@@ -20,7 +21,11 @@ PDF_TARGETS=$(addsuffix .pdf, $(basename $(DOCFILES)))
 	@echo "[pdf] $*"
 	$(Q)a2x -f pdf --dblatex-opts "-P latex.output.revhistory=0" $<
 
-default: html pdf $(SUBDIRS)
+%.epub: %.asciidoc
+	@echo "[epub] $*"
+	$(Q)a2x -f epub $<
+
+default: html pdf epub $(SUBDIRS)
 
 $(SUBDIRS):
 	@echo "Building $@"
@@ -30,14 +35,18 @@ html: $(HTML_TARGETS)
 
 pdf: $(PDF_TARGETS)
 
+epub: $(EPUB_TARGETS)
+
 # manually construct build dependencies for target builds so that modification
 # of individual files will trigger a rebuild of the document correctly.
 $(PDF_TARGETS): $(DOCFILES)
 
 $(HTML_TARGETS): $(DOCFILES)
 
+$(EPUB_TARGETS): $(DOCFILES)
+
 clean: $(addsuffix -clean, $(SUBDIRS))
-	$(Q)rm -f *.html *.pdf *.css
+	$(Q)rm -f *.html *.pdf *.css *.epub
 
 %-clean:
 	@echo "Cleaning $*"
diff --git a/design/XFS_Filesystem_Structure/Makefile b/design/XFS_Filesystem_Structure/Makefile
index 359dd98..be78a75 100644
--- a/design/XFS_Filesystem_Structure/Makefile
+++ b/design/XFS_Filesystem_Structure/Makefile
@@ -8,8 +8,9 @@ DOCFILES=$(wildcard *.asciidoc) \
 
 HTML_TARGET=$(addsuffix .html, $(TARGET))
 PDF_TARGET=$(addsuffix .pdf, $(TARGET))
+EPUB_TARGET=$(addsuffix .epub, $(TARGET))
 
-default: html pdf
+default: html pdf epub
 
 %.html: %.asciidoc
 	@echo "[html] $*"
@@ -19,16 +20,24 @@ default: html pdf
 	@echo "[pdf] $*"
 	$(Q)a2x -f pdf -d book $<
 
+%.epub: %.asciidoc
+	@echo "[epub] $*"
+	$(Q)a2x -f epub -d book $<
+
 html: $(HTML_TARGET)
 
 pdf: $(PDF_TARGET)
 
+epub: $(EPUB_TARGET)
+
 # manually construct build dependencies for target builds so that modification
 # of individual files will trigger a rebuild of the document correctly.
 $(PDF_TARGET): $(DOCFILES)
 
 $(HTML_TARGET): $(DOCFILES)
 
+$(EPUB_TARGET): $(DOCFILES)
+
 clean:
-	$(Q)rm -f *.html *.pdf *.css
+	$(Q)rm -f *.html *.pdf *.css *.epub
 
-- 
2.39.0

Re: [PATCH] xfsdocs: add epub output

[Dave Chinner]

On Wed, Jan 11, 2023 at 09:15:57AM +0100, Csaba Henk wrote:
> ---
>  .gitignore                               |  1 +
>  admin/Makefile                           | 13 +++++++++++--
>  admin/XFS_Performance_Tuning/Makefile    | 13 +++++++++++--
>  design/Makefile                          | 13 +++++++++++--
>  design/XFS_Filesystem_Structure/Makefile | 13 +++++++++++--
>  5 files changed, 45 insertions(+), 8 deletions(-)

The change looks fine, but why do we need to build documentation in
epub format? Empty commit messages are generally considered a bad
thing - the commit message should explain to us why building epub
format documentation is desired, what problem it solves, what new
dependencies it introduces (e.g. build tools), how we should
determine that the generated documentation is good, etc so that have
some basis from which to evaluate the change from.

Cheers,

Dave.
-- 
Dave Chinner
david@fromorbit.com

Re: [PATCH] xfsdocs: add epub output

[Csaba Henk]

On 23-01-12 09:10:27, Dave Chinner wrote:
> On Wed, Jan 11, 2023 at 09:15:57AM +0100, Csaba Henk wrote:
> > ---
> >  .gitignore                               |  1 +
> >  admin/Makefile                           | 13 +++++++++++--
> >  admin/XFS_Performance_Tuning/Makefile    | 13 +++++++++++--
> >  design/Makefile                          | 13 +++++++++++--
> >  design/XFS_Filesystem_Structure/Makefile | 13 +++++++++++--
> >  5 files changed, 45 insertions(+), 8 deletions(-)
> 
> The change looks fine, but why do we need to build documentation in
> epub format? Empty commit messages are generally considered a bad

Well, we don't *need*; I just found we *can* (a2x spits it out in a
split second).

My perception is that epub has become the de facto standard portable
publication format for on-screen reading. So I thought it would be
beneficial to make it available.

If this is not a consensual stance, it's also a possibility to add
the epub target, but do not include it in default. Ie. make it
available on demand.

> thing - the commit message should explain to us why building epub
> format documentation is desired, what problem it solves, what new
> dependencies it introduces (e.g. build tools), how we should
> determine that the generated documentation is good, etc so that have
> some basis from which to evaluate the change from.

Sorry; I thought a mere subject suffices if it's obvious what's the
impact of the patch. I agree that giving context / rationale would be
useful. I'll add that, according to the approach we settle with (ie.
whether to include it in default).

Regards,
Csaba

Re: [PATCH] xfsdocs: add epub output

[Darrick J. Wong]

On Thu, Jan 12, 2023 at 02:44:01AM +0100, Csaba Henk wrote:
> On 23-01-12 09:10:27, Dave Chinner wrote:
> > On Wed, Jan 11, 2023 at 09:15:57AM +0100, Csaba Henk wrote:
> > > ---
> > >  .gitignore                               |  1 +
> > >  admin/Makefile                           | 13 +++++++++++--
> > >  admin/XFS_Performance_Tuning/Makefile    | 13 +++++++++++--
> > >  design/Makefile                          | 13 +++++++++++--
> > >  design/XFS_Filesystem_Structure/Makefile | 13 +++++++++++--
> > >  5 files changed, 45 insertions(+), 8 deletions(-)
> > 
> > The change looks fine, but why do we need to build documentation in
> > epub format? Empty commit messages are generally considered a bad
> 
> Well, we don't *need*; I just found we *can* (a2x spits it out in a
> split second).
> 
> My perception is that epub has become the de facto standard portable
> publication format for on-screen reading. So I thought it would be
> beneficial to make it available.
> 
> If this is not a consensual stance, it's also a possibility to add
> the epub target, but do not include it in default. Ie. make it
> available on demand.

Does epub support add more dependencies that I have to install?

Not opposed, just curious.

> > thing - the commit message should explain to us why building epub
> > format documentation is desired, what problem it solves, what new
> > dependencies it introduces (e.g. build tools), how we should
> > determine that the generated documentation is good, etc so that have
> > some basis from which to evaluate the change from.
> 
> Sorry; I thought a mere subject suffices if it's obvious what's the
> impact of the patch. I agree that giving context / rationale would be
> useful. I'll add that, according to the approach we settle with (ie.
> whether to include it in default).

Yes please. :)

--D

> Regards,
> Csaba
> 

Re: [PATCH] xfsdocs: add epub output

[Csaba Henk]

On 23-01-11 17:56:20, Darrick J. Wong wrote:
> Does epub support add more dependencies that I have to install?
> 
> Not opposed, just curious.

The to_epub function in a2x:

https://github.com/asciidoc-py/asciidoc-py/blob/10.2.0/asciidoc/a2x.py#L811-L861

utilizes docbook / xslt tooling. Which tooling is already among asciidoc
dependencies, so nothing in addition is needed.

Another concern that came to my mind is whether epub production will be
supported in all environments which are likely be used to build the docs.
I think we can be reassured fairly safely in this regard, as support for
epub was added in 2009, by the following commit:

https://github.com/asciidoc-py/asciidoc-py/commit/27749467

Regards,
Csaba