git@vger.kernel.org list mirror (unofficial, one of many)
 help / color / mirror / code / Atom feed
From: "brian m. carlson" <sandals@crustytoothpaste.net>
To: Felipe Contreras <felipe.contreras@gmail.com>
Cc: Bagas Sanjaya <bagasdotme@gmail.com>, Git Users <git@vger.kernel.org>
Subject: Re: [RFC suggestion] Generate manpage directly with Asciidoctor
Date: Fri, 7 May 2021 23:57:32 +0000	[thread overview]
Message-ID: <YJXT7AaqCeCV4WcZ@camp.crustytoothpaste.net> (raw)
In-Reply-To: <6095ceb984401_cfc7208b9@natae.notmuch>

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

On 2021-05-07 at 23:35:21, Felipe Contreras wrote:
> I don't think it would be that complicated.
> 
> This patch seems to do the trick here:
> 
> diff --git a/Documentation/Makefile b/Documentation/Makefile
> index c2baad0bd8..8fa4896d22 100644
> --- a/Documentation/Makefile
> +++ b/Documentation/Makefile
> @@ -189,6 +189,7 @@ ASCIIDOC_EXTRA += -alitdd='&\#x2d;&\#x2d;'
>  DBLATEX_COMMON =
>  XMLTO_EXTRA += --skip-validation
>  XMLTO_EXTRA += -x manpage.xsl
> +TXT_TO_MAN = $(ASCIIDOC_COMMON) -b manpage
>  endif
>  
>  SHELL_PATH ?= $(SHELL)
> @@ -360,9 +361,16 @@ $(OBSOLETE_HTML): %.html : %.txto asciidoc.conf asciidoctor-extensions.rb GIT-AS
>  manpage-base-url.xsl: manpage-base-url.xsl.in
>  	$(QUIET_GEN)sed "s|@@MAN_BASE_URL@@|$(MAN_BASE_URL)|" $< > $@
>  
> +ifdef TXT_TO_MAN
> +%.1 %.5 %.7 : %.txt asciidoc.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS
> +	$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
> +	$(TXT_TO_MAN) -o $@+ $< && \
> +	mv $@+ $@
> +else
>  %.1 %.5 %.7 : %.xml manpage-base-url.xsl $(wildcard manpage*.xsl)
>  	$(QUIET_XMLTO)$(RM) $@ && \
>  	$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<
> +endif
>  
>  %.xml : %.txt asciidoc.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS
>  	$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
> 
> I'm sure this can be improved with some knowledge about intermediary
> rules.

It's not quite that simple.  It requires changes to
asciidoctor-extensions.rb and we also need to consider
NO_MAN_BOLD_LITERAL and GNU_ROFF.  The latter especially is likely to be
inconvenient, since according to the Makefile, it's impossible to write
man output that works across troff versions.

We will also want to preserve the ability to use xmlto because we
currently have doc-diff which helps us find divergences in the behavior
of AsciiDoc and Asciidoctor, many of which affect all formats, and that
will be completely useless if we use two different rendering toolchains.

So, yes, this is a good start, but it's not quite as trivial as it seems.

> > It also doesn't help if you're generating more than just the manual
> > pages, since generating the PDFs will definitely require xmlto and
> > either dblatex or fop.  I personally prefer fop over dblatex, but folks
> > have different opinions.
> 
> Huh? user-manual.pdf seems to require DBLATEX, not XMLTO.

Ah, yes, because we do it manually instead of using xmlto.
-- 
brian m. carlson (he/him or they/them)
Houston, Texas, US

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

  reply	other threads:[~2021-05-08  0:02 UTC|newest]

Thread overview: 38+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-05-07  6:06 Bagas Sanjaya
2021-05-07 12:02 ` Randall S. Becker
2021-05-07 22:55   ` Felipe Contreras
2021-05-07 22:57   ` brian m. carlson
2021-05-08  1:42     ` Randall S. Becker
2021-05-07 12:27 ` Đoàn Trần Công Danh
2021-05-07 12:47   ` Bagas Sanjaya
2021-05-07 23:03   ` Felipe Contreras
2021-05-08  4:27     ` Bagas Sanjaya
2021-05-07 20:25 ` brian m. carlson
2021-05-07 22:19   ` Jeff King
2021-05-08  4:22     ` Bagas Sanjaya
2021-05-09  8:20     ` Martin Ågren
2021-05-09 18:46       ` Felipe Contreras
2021-05-10 18:43         ` Martin Ågren
2021-05-10 22:24       ` Jeff King
2021-05-11  4:27         ` Felipe Contreras
2021-05-11  6:13           ` Jeff King
2021-05-11  8:03             ` Felipe Contreras
2021-05-11 12:44               ` Ævar Arnfjörð Bjarmason
2021-05-11 19:00                 ` Felipe Contreras
2021-05-11 19:09                   ` Jeff King
2021-05-11 20:22                     ` Felipe Contreras
2021-05-11 23:14           ` brian m. carlson
2021-05-12  1:44             ` Felipe Contreras
2021-05-11 18:45         ` Martin Ågren
2021-05-11 19:07           ` Jeff King
2021-05-11 19:11             ` Martin Ågren
2021-05-11 20:14             ` Felipe Contreras
2021-05-11  9:04       ` Jean-Noël Avila
2021-05-11 18:54         ` Martin Ågren
2021-05-07 23:35   ` Felipe Contreras
2021-05-07 23:57     ` brian m. carlson [this message]
2021-05-08  3:10       ` Jeff King
2021-05-08  3:23         ` Jeff King
2021-05-09  0:22         ` brian m. carlson
2021-05-09  8:29     ` Martin Ågren
2021-05-07 22:48 ` Felipe Contreras

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: http://vger.kernel.org/majordomo-info.html

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=YJXT7AaqCeCV4WcZ@camp.crustytoothpaste.net \
    --to=sandals@crustytoothpaste.net \
    --cc=bagasdotme@gmail.com \
    --cc=felipe.contreras@gmail.com \
    --cc=git@vger.kernel.org \
    --subject='Re: [RFC suggestion] Generate manpage directly with Asciidoctor' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

Code repositories for project(s) associated with this inbox:

	https://80x24.org/mirrors/git.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).