Hi Todd, On Sun, 17 Mar 2019 at 20:44, Todd Zullinger <tmz@xxxxxxxxx> wrote: > > Hi Martin, > > Martin Ågren wrote: > > That is, we miss out on the `<refmiscinfo/>` tags. As a result, the > > header of each man page doesn't say "Git Manual", but "git-foo(1)" > > instead. Worse, the footers don't give the Git version number and > > instead provide the fairly ugly "[FIXME: source]". > > > > That Asciidoctor ignores asciidoc.conf is nothing new. This is why we > > implement the `linkgit:` macro in asciidoc.conf *and* in > > asciidoctor-extensions.rb. Follow suit and provide these tags in > > asciidoctor-extensions.rb, using a "postprocessor" extension. > > > We may consider a few alternatives: > > > > * Provide the `mansource` attribute to Asciidoctor. This attribute > > looks promising until one realizes that it can only be given inside > > the source file (the .txt file in our case), *not* on the command > > line using `-a mansource=foobar`. I toyed with the idea of injecting > > this attribute while feeding Asciidoctor the input on stdin, but it > > didn't feel like it was worth the complexity in the Makefile. > > I played with this direction before. Using Asciidoctor we > can convert directly from .txt to man without docbook > and xmlto. That does have some other issues which need to > be worked out though. Here's what I had as a start: > > -- 8< -- > Subject: [PATCH] WIP: doc: improve asciidoctor manpage generation > > Avoid 'FIXME: Source' by setting mansource. Skip xmlto step and render > manpages directly with asciidoctor. > > TODO: > - apply to all man pages > - fix links to html docs, like user-manual.html in git.1 (currently > it is listed in brackets inline rather than as a footnote) > > Reference: > https://lore.kernel.org/lkml/20180424150456.17353-1-tiwai@xxxxxxx/ > Signed-off-by: Todd Zullinger <tmz@xxxxxxxxx> > --- > Documentation/Makefile | 8 ++++++++ > Documentation/asciidoctor-extensions.rb | 2 ++ > 2 files changed, 10 insertions(+) > > diff --git a/Documentation/Makefile b/Documentation/Makefile > index a9697f5146..494f8c9464 100644 > --- a/Documentation/Makefile > +++ b/Documentation/Makefile > @@ -197,6 +197,7 @@ ASCIIDOC_DOCBOOK = docbook45 > ASCIIDOC_EXTRA += -acompat-mode -atabsize=8 > ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions > ASCIIDOC_EXTRA += -alitdd='&\#x2d;&\#x2d;' > +ASCIIDOC_EXTRA += -a mansource="Git $(GIT_VERSION)" -a manmanual="Git Manual" > DBLATEX_COMMON = > endif > > @@ -354,9 +355,16 @@ $(OBSOLETE_HTML): %.html : %.txto asciidoc.conf > manpage-base-url.xsl: manpage-base-url.xsl.in > $(QUIET_GEN)sed "s|@@MAN_BASE_URL@@|$(MAN_BASE_URL)|" $< > $@ > > +ifndef USE_ASCIIDOCTOR > %.1 %.5 %.7 : %.xml manpage-base-url.xsl $(wildcard manpage*.xsl) > $(QUIET_XMLTO)$(RM) $@ && \ > $(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $< > +else > +%.1 %.5 %.7 : %.txt > + $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ > + $(ASCIIDOC_COMMON) -b manpage -d manpage -o $@+ $< && \ > + mv $@+ $@ > +endif > > %.xml : %.txt asciidoc.conf asciidoctor-extensions.rb > $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ > diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb > index f7a5982f8b..ebb078807a 100644 > --- a/Documentation/asciidoctor-extensions.rb > +++ b/Documentation/asciidoctor-extensions.rb > @@ -12,6 +12,8 @@ module Git > if parent.document.basebackend? 'html' > prefix = parent.document.attr('git-relative-html-prefix') > %(<a href="#{prefix}#{target}.html">#{target}(#{attrs[1]})</a>\n) > + elsif parent.document.basebackend? 'manpage' > + "#{target}(#{attrs[1]})" > elsif parent.document.basebackend? 'docbook' > "<citerefentry>\n" \ > "<refentrytitle>#{target}</refentrytitle>" \ > -- 8< -- > > That was based on ma/asciidoctor-extensions, but it may be > missing other recent improvements you've made to the make > targets. It's been a month or so since I worked on it. > > I munged up doc-diff to set MANDWIDTH=1000 and set one > branch to default to asciidoctor to compare. (Your other > recent series looks like it'll make doing asciidoc and > asciidoctor comparisons easier.) > > There were a number of differences that I didn't work > through though. Most importantly was the change in the > links noted in the commit message. Your approach looks like the correct one long term, at least. I'll try to play with this to see if I can figure out the differences. That will have to wait until tomorrow though. Thanks for sharing your progress. Martin
