| Message ID | 20210521224452.530852-1-felipe.contreras@gmail.com (mailing list archive) |
|---|---|
| Headers | show |
| Series | doc: asciidoctor: direct man page creation and fixes | expand |
Felipe Contreras wrote: > This patch series enables direct man page creation with asciidoctor, but in addition tries to > minimize the difference with asciidoc+docbook. > > I fixed as many issues as I could, and now the doc-diff looks very sensible. I could not find any > major issues, however, some minor ones still remain. > > On the other hand the asciidoc method has issues as well, so it's not clear which method is superior > at this point; both have advantages and disadvantages. > > At the very least the man pages with pure asciidoctor should be quite usable now. > > This series builds on top of my previous cleanups [1]. I forgot to mention what changed since v1: * The option USE_ASCIIDOCTOR_MANPAGE was added * Jeff's patch for *asciidoctor-direct optiosn to doc-diff was added * Martin Ågren's patch to remove -cut-footer was added * The format of linkgit was updated to be closer to brian's version (though not quite the same) * A few tiny cleanups
This patch series enables direct man page creation with asciidoctor, but in addition tries to minimize the difference with asciidoc+docbook. I fixed as many issues as I could, and now the doc-diff looks very sensible. I could not find any major issues, however, some minor ones still remain. On the other hand the asciidoc method has issues as well, so it's not clear which method is superior at this point; both have advantages and disadvantages. At the very least the man pages with pure asciidoctor should be quite usable now. This series builds on top of my previous cleanups [1]. [1] https://lore.kernel.org/git/20210521223701.526547-1-felipe.contreras@gmail.com/ Felipe Contreras (9): doc: doc-diff: set docdate manually doc: use asciidoctor to build man pages directly doc: asciidoctor: add linkgit macros in man pages doc: add man pages workaround for asciidoctor doc: asciidoctor: add hack for xrefs doc: asciidoctor: add hack to improve links doc: asciidoctor: add support for baseurl doc: asciidoctor: cleanup man page hack doc: asciidoctor: add hack for old versions Jeff King (1): doc-diff: support asciidoctor man pages Martin Ågren (1): doc-diff: drop --cut-footer switch Documentation/Makefile | 15 ++++++-- Documentation/asciidoctor-extensions.rb | 51 +++++++++++++++++++++++++ Documentation/doc-diff | 35 +++++++++-------- 3 files changed, 82 insertions(+), 19 deletions(-) Range-diff against v1: 1: de0ecf9c0e < -: ---------- doc: allow the user to provide ASCIIDOC_EXTRA 2: 22a35efa3f < -: ---------- doc: doc-diff: allow more than one flag 3: a8ad5c703a < -: ---------- doc: doc-diff: set docdate manually 4: 4d0266a3a1 < -: ---------- doc: use asciidoctor to build man pages directly 5: 5efb19348b < -: ---------- doc: asciidoctor: add linkgit macros in man pages 6: d5d006298e < -: ---------- doc: join mansource and manversion 7: 7c8b502df9 < -: ---------- doc: add man pages workaround for asciidoctor -: ---------- > 1: a2f85f4b05 doc: doc-diff: set docdate manually -: ---------- > 2: 13085a13b6 doc-diff: drop --cut-footer switch -: ---------- > 3: f0b3576d77 doc: use asciidoctor to build man pages directly -: ---------- > 4: 8b3bb9e9f4 doc-diff: support asciidoctor man pages -: ---------- > 5: 3f9859b223 doc: asciidoctor: add linkgit macros in man pages -: ---------- > 6: df27fcb9a2 doc: add man pages workaround for asciidoctor 8: 5d5e9d99ac ! 7: 5f0ae41e3e doc: asciidoctor: add hack for xrefs @@ Commit message ## Documentation/asciidoctor-extensions.rb ## @@ - require 'asciidoctor' require 'asciidoctor/extensions' +require 'asciidoctor/converter/manpage' + @@ Documentation/asciidoctor-extensions.rb + orig_convert_inline_anchor(node) + end + end ++ alias inline_anchor convert_inline_anchor # For old versions of asciidoctor + end +end - module Git - module Documentation + Asciidoctor::Extensions.register :git do + 9: f4a4f1394e = 8: a8fb29d893 doc: asciidoctor: add hack to improve links 10: 894802bfbb ! 9: 272e6e8551 doc: asciidoctor: add support for baseurl @@ Commit message ## Documentation/Makefile ## @@ Documentation/Makefile: ASCIIDOC_DOCBOOK = docbook5 - override ASCIIDOC_EXTRA += -acompat-mode -atabsize=8 - override ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions - override ASCIIDOC_EXTRA += -alitdd='&\#x2d;&\#x2d;' -+override ASCIIDOC_EXTRA += -abaseurl='$(MAN_BASE_URL)' + ASCIIDOC_EXTRA += -acompat-mode -atabsize=8 + ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions + ASCIIDOC_EXTRA += -alitdd='&\#x2d;&\#x2d;' ++ASCIIDOC_EXTRA += -abaseurl='$(MAN_BASE_URL)' ASCIIDOC_DEPS = asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS DBLATEX_COMMON = XMLTO_EXTRA += --skip-validation 11: d3b6899ed8 ! 10: 928a632038 doc: asciidoctor: cleanup man page hack @@ Documentation/asciidoctor-extensions.rb: module Asciidoctor + nil end end - end + alias inline_anchor convert_inline_anchor # For old versions of asciidoctor -: ---------- > 11: 758e5be3b7 doc: asciidoctor: add hack for old versions