| Message ID | 20210514003104.94644-1-sandals@crustytoothpaste.net (mailing list archive) |
|---|---|
| Headers | show |
| Series | Asciidoctor native manpage builds | expand |
brian m. carlson wrote: > @@ Documentation/asciidoctor-extensions.rb: module Git > elsif parent.document.basebackend? 'html' > %(<a href="#{prefix}#{target}.html">#{target}(#{attrs[1]})</a>) > + elsif parent.document.basebackend? 'manpage' > -+ %(\\fB#{target}\\fP\\fR(#{attrs[1]})\\fP) > ++ %(\e\\fB#{target}\e\\fP\e\\fR(#{attrs[1]})\e\\fP) > elsif parent.document.basebackend? 'docbook' > "<citerefentry>\n" \ > "<refentrytitle>#{target}</refentrytitle>" \ Huh? Didn't you say \e was not needed? You are doing basically the same thing thing my patches now, except in a more convoluted way.
On 2021-05-14 at 19:07:06, Felipe Contreras wrote: > brian m. carlson wrote: > > @@ Documentation/asciidoctor-extensions.rb: module Git > > elsif parent.document.basebackend? 'html' > > %(<a href="#{prefix}#{target}.html">#{target}(#{attrs[1]})</a>) > > + elsif parent.document.basebackend? 'manpage' > > -+ %(\\fB#{target}\\fP\\fR(#{attrs[1]})\\fP) > > ++ %(\e\\fB#{target}\e\\fP\e\\fR(#{attrs[1]})\e\\fP) > > elsif parent.document.basebackend? 'docbook' > > "<citerefentry>\n" \ > > "<refentrytitle>#{target}</refentrytitle>" \ > > Huh? Didn't you say \e was not needed? Yes, but I believe in that case my build was broken and I was incorrect. > You are doing basically the same thing thing my patches now, except in a > more convoluted way. The way your patches do it, if someone adds a line like this: _abc linkgit:git-update-index[1] def_ the latter part (def) is not italicized. In my version, it is, which is the correct behavior.
brian m. carlson wrote: > On 2021-05-14 at 19:07:06, Felipe Contreras wrote: > > brian m. carlson wrote: > > > @@ Documentation/asciidoctor-extensions.rb: module Git > > > elsif parent.document.basebackend? 'html' > > > %(<a href="#{prefix}#{target}.html">#{target}(#{attrs[1]})</a>) > > > + elsif parent.document.basebackend? 'manpage' > > > -+ %(\\fB#{target}\\fP\\fR(#{attrs[1]})\\fP) > > > ++ %(\e\\fB#{target}\e\\fP\e\\fR(#{attrs[1]})\e\\fP) > > > elsif parent.document.basebackend? 'docbook' > > > "<citerefentry>\n" \ > > > "<refentrytitle>#{target}</refentrytitle>" \ > > > > Huh? Didn't you say \e was not needed? > > Yes, but I believe in that case my build was broken and I was incorrect. I see. If it helps you I'm using this script [1] to run the specific version of asciidoctor of a git repository (their wrapper is wrong). > > You are doing basically the same thing thing my patches now, except in a > > more convoluted way. > > The way your patches do it, if someone adds a line like this: > > _abc linkgit:git-update-index[1] def_ > > the latter part (def) is not italicized. In my version, it is, which is > the correct behavior. Right, but my version is precisely what asciidoc+docbook generates in the simplest case. I agree your version is superior (although I wouldn't do the second \fR \fP). But that belongs in a separate patch IMO. Cheers. [1] https://dpaste.com/3AEDTFCSK
This series introduces native support for building manual pages with Asciidoctor, which is faster and somewhat easier than building with the DocBook toolchain. The first patch in the series is based on one by Felipe Contreras but differs from his in that we default to the old behavior, in addition to some additional functionality and a more verbose commit message. The second patch drops support for GNU_ROFF, which is now supported in a more robust way by both the Asciidoctor and DocBook toolchains. Changes from v1: * Rephrase commit messages and Makefile text for both patches to clarify and avoid ambiguity. * Avoid using XML-style escapes in man pages, which are not XML- or HTML-based. * Clarify that USE_ASCIIDOCTOR_MANPAGE requires USE_ASCIIDOCTOR to be functional. * Escape linkgit macro output to avoid backslashes being needlessly converted. * Remove leftover reference to GNU_ROFF. brian m. carlson (2): doc: add an option to have Asciidoctor build man pages directly doc: remove GNU_ROFF option Documentation/Makefile | 25 +++++++++++++++---------- Documentation/asciidoctor-extensions.rb | 2 ++ Documentation/manpage-quote-apos.xsl | 16 ---------------- Makefile | 8 ++++---- 4 files changed, 21 insertions(+), 30 deletions(-) delete mode 100644 Documentation/manpage-quote-apos.xsl Diff-intervalle contre v1 : 1: 9ba34d9ec9 ! 1: 0d5f8f1b80 doc: add an option to have Asciidoctor build man pages directly @@ ## Metadata ## -Author: Felipe Contreras <felipe.contreras@gmail.com> +Author: brian m. carlson <sandals@crustytoothpaste.net> ## Commit message ## doc: add an option to have Asciidoctor build man pages directly @@ Commit message by the GNU_ROFF option. This option for the DocBook toolchain, as well as newer versions of Asciidoctor, makes groff output an ASCII apostrophe instead of a Unicode apostrophe in text, so as to make copy and pasting - commands easier. These newer versions of Asciidoctor detect groff and - do the right thing in all cases, so the GNU_ROFF option is obsolete in - this case. + commands easier. These newer versions of Asciidoctor (1.5.3 and above) + detect groff and do the right thing in all cases, so the GNU_ROFF option + is obsolete in this case. We also need to update the code that tells Asciidoctor how to format our linkgit macros so that it can output proper code for man pages. Be careful to reset the font to the previous after the change. In order to do so, we must reset to the previous after each font change so the previous state at the end is the state before our inserted text, since - troff only remembers one previous font. + troff only remembers one previous font. We insert \e before each + font-change backslash so Asciidoctor doesn't convert them into \*(rs, + the reverse solidus character, and instead leaves them as we wanted + them. + + Additionally, we don't want to use XML-style escapes for the litdd and + plus macros, so let's only use the XML-style escapes in HTML and XML and + use something different for our man pages. Because Asciidoctor versions before 2.0 had a few problems with man page output, let's default this to off for now, since some common distros are @@ Commit message Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net> ## Documentation/Makefile ## -@@ Documentation/Makefile: ASCIIDOC_EXTRA += -alitdd='&\#x2d;&\#x2d;' +@@ Documentation/Makefile: 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 SHELL_PATH ?= $(SHELL) +@@ Documentation/Makefile: mergetools-list.made: ../git-mergetool--lib.sh $(wildcard ../mergetools/*) + show_tool_names can_merge "* " || :' >mergetools-merge.txt && \ + date >$@ + +-TRACK_ASCIIDOCFLAGS = $(subst ','\'',$(ASCIIDOC_COMMON):$(ASCIIDOC_HTML):$(ASCIIDOC_DOCBOOK)) ++TRACK_ASCIIDOCFLAGS = $(subst ','\'',$(ASCIIDOC_COMMON):$(ASCIIDOC_HTML):$(ASCIIDOC_DOCBOOK):$(USE_ASCIIDOCTOR_MANPAGE)) + + GIT-ASCIIDOCFLAGS: FORCE + @FLAGS='$(TRACK_ASCIIDOCFLAGS)'; \ @@ Documentation/Makefile: $(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)|" $< > $@ @@ Documentation/asciidoctor-extensions.rb: module Git elsif parent.document.basebackend? 'html' %(<a href="#{prefix}#{target}.html">#{target}(#{attrs[1]})</a>) + elsif parent.document.basebackend? 'manpage' -+ %(\\fB#{target}\\fP\\fR(#{attrs[1]})\\fP) ++ %(\e\\fB#{target}\e\\fP\e\\fR(#{attrs[1]})\e\\fP) elsif parent.document.basebackend? 'docbook' "<citerefentry>\n" \ "<refentrytitle>#{target}</refentrytitle>" \ @@ Makefile: all:: # documentation. # +# Define USE_ASCIIDOCTOR_MANPAGE to use Asciidoctor's manual page backend -+# instead of building manual pages from DocBook. ++# instead of building manual pages from DocBook (using xmlto). Has no effect ++# unless USE_ASCIIDOCTOR is set. +# # Define ASCIIDOCTOR_EXTENSIONS_LAB to point to the location of the Asciidoctor # Extensions Lab if you have it available. 2: c0a21dd700 ! 2: b12a068f5b doc: remove GNU_ROFF option @@ Commit message GNU_ROFF code. Additionally, this functionality was implemented in 2010. Since nobody - is shipping security support for an operating system that old anymore, - we can just safely assume that the user has upgraded their system in the - past decade and remove the GNU_ROFF option and its corresponding - stylesheet altogether. + is shipping a mainstream Linux distribution with security support that + old anymore, we can just safely assume that the user has upgraded their + system in the past decade and remove the GNU_ROFF option and its + corresponding stylesheet altogether. Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net> @@ Documentation/manpage-quote-apos.xsl (deleted) -</xsl:template> - -</xsl:stylesheet> + + ## Makefile ## +@@ Makefile: all:: + # Define NO_ST_BLOCKS_IN_STRUCT_STAT if your platform does not have st_blocks + # field that counts the on-disk footprint in 512-byte blocks. + # +-# Define GNU_ROFF if your target system uses GNU groff. This forces +-# apostrophes to be ASCII so that cut&pasting examples to the shell +-# will work. +-# + # Define USE_ASCIIDOCTOR to use Asciidoctor instead of AsciiDoc to build the + # documentation. + #