Re: [PATCH v2 1/2] doc: add an option to have Asciidoctor build man pages directly

From: Felipe Contreras <felipe.contreras@gmail.com>
Date: May 14, 2021, 19:57 UTC
Message-ID: <609ed62a3ad1d_4312720825@natae.notmuch>
In-Reply-To: <xmqqbl9e7yqz.fsf@gitster.g>

Junio C Hamano wrote:

Show 29 quoted lines

> > diff --git a/Documentation/Makefile b/Documentation/Makefile
> > index 2aae4c9cbb..891181c0f3 100644
> > --- a/Documentation/Makefile
> > +++ b/Documentation/Makefile
> > @@ -192,10 +192,16 @@ ASCIIDOC_HTML = xhtml5
> >  ASCIIDOC_DOCBOOK = docbook5
> >  ASCIIDOC_EXTRA += -acompat-mode -atabsize=8
> >  ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions
> > -ASCIIDOC_EXTRA += -alitdd='&\#x2d;&\#x2d;'
> > +TXT_TO_HTML += -alitdd='&\#x2d;&\#x2d;'
> > +TXT_TO_XML  += -alitdd='&\#x2d;&\#x2d;'
> >  DBLATEX_COMMON =
> >  XMLTO_EXTRA += --skip-validation
> >  XMLTO_EXTRA += -x manpage.xsl
> > +ifdef USE_ASCIIDOCTOR_MANPAGE
> > +TXT_TO_MAN = $(ASCIIDOC_COMMON) -b manpage
> > +TXT_TO_MAN += -aplus='+'
> > +TXT_TO_MAN += -alitdd='\--'
> > +endif
> >  endif
> 
> This hunk is wholly inside USE_ASCIIDOCTOR and deals with {litdd}
> and {plus}, which are defined in asciidoc.conf that is not read by
> Asciidoctor, so we'd need to be careful to keep these three places
> (i.e. TXT_TO_HTML, TXT_TO_XML and TXT_TO_MAN) in sync with the
> asciidoct.conf file.
> 
> It is curious that {plus} for Asciidoctor is deffined only for
> manpages and HTML/XML side lacks the definition.  Intended?

Yes. It is a temporary workaround for a bug in asciidoctor. Eventually we don't want to do this.

It's much more clearer in my patch, that contains the hack to a single place inside asciidoctor-extensions.rb [1].

[1] https://lore.kernel.org/git/20210514121435.504423-8-felipe.contreras@gmail.com/T/#u

-- 
Felipe Contreras