[PATCH] INSTALL: note on using Asciidoctor to build doc

[PATCH] INSTALL: note on using Asciidoctor to build doc

[Bagas Sanjaya]

Note on using Asciidoctor to build documentation suite, with example
for build documentation in html format.

Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 INSTALL | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/INSTALL b/INSTALL
index 8474ad01bf..3a67f335e0 100644
--- a/INSTALL
+++ b/INSTALL
@@ -239,3 +239,9 @@ Issues of note:
          http://www.oasis-open.org/docbook/xml/4.5/xsl/current \
          /usr/share/sgml/docbook/xml-dtd-4.5 \
      /etc/xml/catalog
+
+ - Alternatively, if you have Asciidoctor installed (requires Ruby),
+   you can pass USE_ASCIIDOCTOR=1 to use it to build documentation.
+   For example, to build documentation in html format:
+
+       $ make USE_ASCIIDOCTOR=1 html
-- 
2.25.1

Re: [PATCH] INSTALL: note on using Asciidoctor to build doc

[Junio C Hamano]

Bagas Sanjaya <bagasdotme@gmail.com> writes:

> Note on using Asciidoctor to build documentation suite, with example
> for build documentation in html format.
>
> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
> ---
>  INSTALL | 6 ++++++
>  1 file changed, 6 insertions(+)

Thanks.  This patch means well, but ...

> diff --git a/INSTALL b/INSTALL
> index 8474ad01bf..3a67f335e0 100644
> --- a/INSTALL
> +++ b/INSTALL
> @@ -239,3 +239,9 @@ Issues of note:
>           http://www.oasis-open.org/docbook/xml/4.5/xsl/current \
>           /usr/share/sgml/docbook/xml-dtd-4.5 \
>       /etc/xml/catalog
> +
> + - Alternatively, if you have Asciidoctor installed (requires Ruby),
> +   you can pass USE_ASCIIDOCTOR=1 to use it to build documentation.
> +   For example, to build documentation in html format:
> +
> +       $ make USE_ASCIIDOCTOR=1 html

Mention of asciidoctor may be a good idea, but this gives an
impression that everything between this new paragraph and the line
that says 

	"All formats require at least asciidoc 8.4.1."

are irrelevant if you choose to use asciidoctor.  Is that really the
case (e.g. is docbook-xsl unneeded with asciidoctor)?

If not, then wouldn't it make the result easier to follow if you did
something along this line instead?


 INSTALL | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git c/INSTALL w/INSTALL
index 9ba33e6a14..d8e75a7c59 100644
--- c/INSTALL
+++ w/INSTALL
@@ -198,7 +198,9 @@ Issues of note:
    Building and installing the pdf file additionally requires
    dblatex.  Version >= 0.2.7 is known to work.
 
-   All formats require at least asciidoc 8.4.1.
+   All formats require at least asciidoc 8.4.1.  Alternatively, you
+   can use AsciiDoctor by passing USE_ASCIIDOCTOR=YesPlease to make.
+   You need at least asciidoctor verison X.Y.Z.
 
    There are also "make quick-install-doc", "make quick-install-man"
    and "make quick-install-html" which install preformatted man pages

Re: [PATCH] INSTALL: note on using Asciidoctor to build doc

[brian m. carlson]

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

On 2021-03-18 at 20:05:35, Junio C Hamano wrote:
> Mention of asciidoctor may be a good idea, but this gives an
> impression that everything between this new paragraph and the line
> that says
> 
> 	"All formats require at least asciidoc 8.4.1."
> 
> are irrelevant if you choose to use asciidoctor.  Is that really the
> case (e.g. is docbook-xsl unneeded with asciidoctor)?

No, we use Asciidoctor in the same way as AsciiDoc, which is to generate
the DocBook (v5 with Asciidoctor, v4 with AsciiDoc) and then convert.
While Asciidoctor can generate PDFs with an extension and manpages and
HTML with a built-in converter, it doesn't natively know how to generate
other formats, such as Texinfo, so we need to generate DocBook anyway
and it makes sense to make the two processes as similar as possible.

> If not, then wouldn't it make the result easier to follow if you did
> something along this line instead?
> 
> 
>  INSTALL | 4 +++-
>  1 file changed, 3 insertions(+), 1 deletion(-)
> 
> diff --git c/INSTALL w/INSTALL
> index 9ba33e6a14..d8e75a7c59 100644
> --- c/INSTALL
> +++ w/INSTALL
> @@ -198,7 +198,9 @@ Issues of note:
>     Building and installing the pdf file additionally requires
>     dblatex.  Version >= 0.2.7 is known to work.
> 
> -   All formats require at least asciidoc 8.4.1.
> +   All formats require at least asciidoc 8.4.1.  Alternatively, you
> +   can use AsciiDoctor by passing USE_ASCIIDOCTOR=YesPlease to make.
> +   You need at least asciidoctor verison X.Y.Z.

This seems fine as an approach.  I think 1.0 is probably sufficient, but
I always use Debian sid, so the oldest version I'm confident that works
is 1.5, since that's the oldest version I've used recently.

Debian 9, which came out in 2017, and Ubuntu 16.04, which came out in
2016, both ship with 1.5.4, so it's probably safe to just say 1.5.
-- 
brian m. carlson (he/him or they/them)
Houston, Texas, US

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