* [PATCH 00/23] doc: cleanups and asciidoctor direct man pages
@ 2021-06-21 16:30 Felipe Contreras
2021-06-21 16:30 ` [PATCH 01/23] doc: remove GNU troff workaround Felipe Contreras
` (23 more replies)
0 siblings, 24 replies; 28+ messages in thread
From: Felipe Contreras @ 2021-06-21 16:30 UTC (permalink / raw)
To: git
Cc: Martin Ågren, Ævar Arnfjörð Bjarmason,
Bagas Sanjaya, Jeff King, Junio C Hamano, brian m . carlson,
Felipe Contreras
I already sent the first part of this series separately multiple times,
the last one is 4 simple obviously correct patches [1], but since the
maintainer has admitted he has no problem ignoring valid work
entirely due to personal animus [2], I'm sending the whole chain.
There's no point in carefully selecting multiple series of patches to be
merged one by one when all of them are going to be ignored. So I'm
sending all 3 series at once.
Hopefully by sending it all at once some people will be able to realize
that:
1. They are valid
2. They are helpful
3. They make the code more maintainable
4. They enable new features
5. They enable the new features to be easily tested
6. They reduce the doc-diff of the new feature, as well as others
7. They are superior to the competing series currently in seen
8. They include work of multiple contributors
Any fair and impartial maintainer would attempt to pick them up.
Cheers.
[1] https://lore.kernel.org/git/20210618215231.796592-1-felipe.contreras@gmail.com/
[2] https://lore.kernel.org/git/xmqqmtrmjpa8.fsf@gitster.g/
Felipe Contreras (21):
doc: remove GNU troff workaround
doc: use --stringparam in xmlto
doc: simplify version passing
doc: asciidoc: remove unnecessary attribute
doc: asciidoctor: remove unnecessary require
doc: asciidoctor: remove cruft
doc: asciidoctor: reorganize extensions
doc: asciidoctor: use html-prefix only for html
doc: asciidoctor: refactor macro registration
doc: asciidoctor: improve string handling
doc: asciidoctor: split the format from the code
doc: asciidoctor: specify name of our group
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/.gitignore | 1 -
Documentation/Makefile | 32 ++++----
Documentation/asciidoc.conf | 20 -----
Documentation/asciidoctor-extensions.rb | 103 +++++++++++++++---------
Documentation/doc-diff | 38 ++++-----
Documentation/manpage-base-url.xsl.in | 10 ---
Documentation/manpage-quote-apos.xsl | 16 ----
Makefile | 8 +-
8 files changed, 104 insertions(+), 124 deletions(-)
delete mode 100644 Documentation/manpage-base-url.xsl.in
delete mode 100644 Documentation/manpage-quote-apos.xsl
--
2.32.0
^ permalink raw reply [flat|nested] 28+ messages in thread
* [PATCH 01/23] doc: remove GNU troff workaround
2021-06-21 16:30 [PATCH 00/23] doc: cleanups and asciidoctor direct man pages Felipe Contreras
@ 2021-06-21 16:30 ` Felipe Contreras
2021-06-21 16:30 ` [PATCH 02/23] doc: use --stringparam in xmlto Felipe Contreras
` (22 subsequent siblings)
23 siblings, 0 replies; 28+ messages in thread
From: Felipe Contreras @ 2021-06-21 16:30 UTC (permalink / raw)
To: git
Cc: Martin Ågren, Ævar Arnfjörð Bjarmason,
Bagas Sanjaya, Jeff King, Junio C Hamano, brian m . carlson,
Felipe Contreras
In 2007 the docbook project made the mistake of converting ' to \' for
man pages [1]. It's a problem because groff interprets \' as acute
accent which is rendered as ' in ASCII, but as ´ in utf-8.
This started a cascade of bug reports in git [2], debian [3], Arch Linux
[4], docbook itself [5], and probably many others.
A solution was to use the correct groff character: \(aq, which is always
rendered as ', but the problem is that such character doesn't work in
other troff programs.
A portable solution required the use of a conditional character that is
\(aq in groff, but ' in all others:
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
The proper solution took time to be implemented in docbook, but in 2010
they did it [6]. So the docbook man page stylesheets were broken from
1.73 to 1.76.
Unfortunately by that point many workarounds already existed. In the
case of git GNU_ROFF was introduced, and in the case of Arch Linux
a mappig from \' to ' was added to groff's man.local. Other
distributions might have done the same, or similar workarounds.
Since 2010 there is not need for this workaround, which is fixed
elsewhere not just in docbook, but other layers as well.
Let's remove it.
Also, it's GNU troff, not GNU roff.
[1] https://github.com/docbook/xslt10-stylesheets/commit/ea2a0bac56c56eec1892ac3d9254dca89f7c5746
[2] https://lore.kernel.org/git/20091012102926.GA3937@debian.b2j/
[3] https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=507673#65
[4] https://bugs.archlinux.org/task/9643
[5] https://sourceforge.net/p/docbook/bugs/1022/
[6] https://github.com/docbook/xslt10-stylesheets/commit/fb553434265906ed81edc6d5f533d0b08d200046
Inspired-by: brian m. carlson <sandals@crustytoothpaste.net>
Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
Documentation/Makefile | 8 --------
Documentation/manpage-quote-apos.xsl | 16 ----------------
Makefile | 4 ----
3 files changed, 28 deletions(-)
delete mode 100644 Documentation/manpage-quote-apos.xsl
diff --git a/Documentation/Makefile b/Documentation/Makefile
index f5605b7767..bf1f66b3eb 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -178,14 +178,6 @@ MAN_BASE_URL = file://$(htmldir)/
endif
XMLTO_EXTRA += -m manpage-base-url.xsl
-# If your target system uses GNU groff, it may try to render
-# apostrophes as a "pretty" apostrophe using unicode. This breaks
-# cut&paste, so you should set GNU_ROFF to force them to be ASCII
-# apostrophes. Unfortunately does not work with non-GNU roff.
-ifdef GNU_ROFF
-XMLTO_EXTRA += -m manpage-quote-apos.xsl
-endif
-
ifdef USE_ASCIIDOCTOR
ASCIIDOC = asciidoctor
ASCIIDOC_CONF =
diff --git a/Documentation/manpage-quote-apos.xsl b/Documentation/manpage-quote-apos.xsl
deleted file mode 100644
index aeb8839f33..0000000000
--- a/Documentation/manpage-quote-apos.xsl
+++ /dev/null
@@ -1,16 +0,0 @@
-<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
- version="1.0">
-
-<!-- work around newer groff/man setups using a prettier apostrophe
- that unfortunately does not quote anything when cut&pasting
- examples to the shell -->
-<xsl:template name="escape.apostrophe">
- <xsl:param name="content"/>
- <xsl:call-template name="string.subst">
- <xsl:with-param name="string" select="$content"/>
- <xsl:with-param name="target">'</xsl:with-param>
- <xsl:with-param name="replacement">\(aq</xsl:with-param>
- </xsl:call-template>
-</xsl:template>
-
-</xsl:stylesheet>
diff --git a/Makefile b/Makefile
index c3565fc0f8..7588c43f05 100644
--- a/Makefile
+++ b/Makefile
@@ -278,10 +278,6 @@ 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.
#
--
2.32.0
^ permalink raw reply related [flat|nested] 28+ messages in thread
* [PATCH 02/23] doc: use --stringparam in xmlto
2021-06-21 16:30 [PATCH 00/23] doc: cleanups and asciidoctor direct man pages Felipe Contreras
2021-06-21 16:30 ` [PATCH 01/23] doc: remove GNU troff workaround Felipe Contreras
@ 2021-06-21 16:30 ` Felipe Contreras
2021-06-21 16:30 ` [PATCH 03/23] doc: simplify version passing Felipe Contreras
` (21 subsequent siblings)
23 siblings, 0 replies; 28+ messages in thread
From: Felipe Contreras @ 2021-06-21 16:30 UTC (permalink / raw)
To: git
Cc: Martin Ågren, Ævar Arnfjörð Bjarmason,
Bagas Sanjaya, Jeff King, Junio C Hamano, brian m . carlson,
Felipe Contreras
Commit 50d9bbba92 (Documentation: Avoid use of xmlto --stringparam,
2009-12-04) introduced manpage-base-url.xsl because ancient versions of
xmlto did not have --stringparam.
However, that was more than ten years ago, no need for that complexity
anymore.
Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
Documentation/.gitignore | 1 -
Documentation/Makefile | 8 ++------
Documentation/manpage-base-url.xsl.in | 10 ----------
3 files changed, 2 insertions(+), 17 deletions(-)
delete mode 100644 Documentation/manpage-base-url.xsl.in
diff --git a/Documentation/.gitignore b/Documentation/.gitignore
index 9022d48355..e9f8d693b1 100644
--- a/Documentation/.gitignore
+++ b/Documentation/.gitignore
@@ -10,7 +10,6 @@ howto-index.txt
doc.dep
cmds-*.txt
mergetools-*.txt
-manpage-base-url.xsl
SubmittingPatches.txt
tmp-doc-diff/
GIT-ASCIIDOCFLAGS
diff --git a/Documentation/Makefile b/Documentation/Makefile
index bf1f66b3eb..84643a34e9 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -176,7 +176,7 @@ endif
ifndef MAN_BASE_URL
MAN_BASE_URL = file://$(htmldir)/
endif
-XMLTO_EXTRA += -m manpage-base-url.xsl
+XMLTO_EXTRA += --stringparam man.base.url.for.relative.links='$(MAN_BASE_URL)'
ifdef USE_ASCIIDOCTOR
ASCIIDOC = asciidoctor
@@ -342,7 +342,6 @@ clean:
$(RM) technical/*.html technical/api-index.txt
$(RM) SubmittingPatches.txt
$(RM) $(cmds_txt) $(mergetools_txt) *.made
- $(RM) manpage-base-url.xsl
$(RM) GIT-ASCIIDOCFLAGS
$(MAN_HTML): %.html : %.txt $(ASCIIDOC_DEPS)
@@ -351,10 +350,7 @@ $(MAN_HTML): %.html : %.txt $(ASCIIDOC_DEPS)
$(OBSOLETE_HTML): %.html : %.txto $(ASCIIDOC_DEPS)
$(QUIET_ASCIIDOC)$(TXT_TO_HTML) -o $@ $<
-manpage-base-url.xsl: manpage-base-url.xsl.in
- $(QUIET_GEN)sed "s|@@MAN_BASE_URL@@|$(MAN_BASE_URL)|" $< > $@
-
-%.1 %.5 %.7 : %.xml manpage-base-url.xsl $(wildcard manpage*.xsl)
+%.1 %.5 %.7 : %.xml $(wildcard manpage*.xsl)
$(QUIET_XMLTO)$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<
%.xml : %.txt $(ASCIIDOC_DEPS)
diff --git a/Documentation/manpage-base-url.xsl.in b/Documentation/manpage-base-url.xsl.in
deleted file mode 100644
index e800904df3..0000000000
--- a/Documentation/manpage-base-url.xsl.in
+++ /dev/null
@@ -1,10 +0,0 @@
-<!-- manpage-base-url.xsl:
- special settings for manpages rendered from newer docbook -->
-<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
- version="1.0">
-
-<!-- set a base URL for relative links -->
-<xsl:param name="man.base.url.for.relative.links"
- >@@MAN_BASE_URL@@</xsl:param>
-
-</xsl:stylesheet>
--
2.32.0
^ permalink raw reply related [flat|nested] 28+ messages in thread
* [PATCH 03/23] doc: simplify version passing
2021-06-21 16:30 [PATCH 00/23] doc: cleanups and asciidoctor direct man pages Felipe Contreras
2021-06-21 16:30 ` [PATCH 01/23] doc: remove GNU troff workaround Felipe Contreras
2021-06-21 16:30 ` [PATCH 02/23] doc: use --stringparam in xmlto Felipe Contreras
@ 2021-06-21 16:30 ` Felipe Contreras
2021-06-21 16:30 ` [PATCH 04/23] doc: asciidoc: remove unnecessary attribute Felipe Contreras
` (20 subsequent siblings)
23 siblings, 0 replies; 28+ messages in thread
From: Felipe Contreras @ 2021-06-21 16:30 UTC (permalink / raw)
To: git
Cc: Martin Ågren, Ævar Arnfjörð Bjarmason,
Bagas Sanjaya, Jeff King, Junio C Hamano, brian m . carlson,
Felipe Contreras
The code to pass the version of the man page comes from 2007:
7ef195ba3e (Documentation: Add version information to man pages,
2007-03-25). However, both asciidoc and asciidoctor already do this by
default.
Asciidoctor doesn't read manversion, but there's no need since both
tools just join mansource and manversion.
Let's do that ourselves and get rid of a bunch of code.
Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
Documentation/Makefile | 3 +--
Documentation/asciidoc.conf | 19 -------------------
Documentation/asciidoctor-extensions.rb | 17 -----------------
3 files changed, 1 insertion(+), 38 deletions(-)
diff --git a/Documentation/Makefile b/Documentation/Makefile
index 84643a34e9..47053c78f8 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -137,8 +137,7 @@ ASCIIDOC_HTML = xhtml11
ASCIIDOC_DOCBOOK = docbook
ASCIIDOC_CONF = -f asciidoc.conf
ASCIIDOC_COMMON = $(ASCIIDOC) $(ASCIIDOC_EXTRA) $(ASCIIDOC_CONF) \
- -amanversion=$(GIT_VERSION) \
- -amanmanual='Git Manual' -amansource='Git'
+ -amanmanual='Git Manual' -amansource='Git $(GIT_VERSION)'
ASCIIDOC_DEPS = asciidoc.conf GIT-ASCIIDOCFLAGS
TXT_TO_HTML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_HTML)
TXT_TO_XML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_DOCBOOK)
diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf
index 3e4c13971b..60f76f43ed 100644
--- a/Documentation/asciidoc.conf
+++ b/Documentation/asciidoc.conf
@@ -51,25 +51,6 @@ ifdef::doctype-manpage[]
endif::doctype-manpage[]
endif::backend-docbook[]
-ifdef::doctype-manpage[]
-ifdef::backend-docbook[]
-[header]
-template::[header-declarations]
-<refentry>
-<refmeta>
-<refentrytitle>{mantitle}</refentrytitle>
-<manvolnum>{manvolnum}</manvolnum>
-<refmiscinfo class="source">{mansource}</refmiscinfo>
-<refmiscinfo class="version">{manversion}</refmiscinfo>
-<refmiscinfo class="manual">{manmanual}</refmiscinfo>
-</refmeta>
-<refnamediv>
- <refname>{manname}</refname>
- <refpurpose>{manpurpose}</refpurpose>
-</refnamediv>
-endif::backend-docbook[]
-endif::doctype-manpage[]
-
ifdef::backend-xhtml11[]
[attributes]
git-relative-html-prefix=
diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb
index d906a00803..70a0956663 100644
--- a/Documentation/asciidoctor-extensions.rb
+++ b/Documentation/asciidoctor-extensions.rb
@@ -23,26 +23,9 @@ module Git
end
end
end
-
- class DocumentPostProcessor < Asciidoctor::Extensions::Postprocessor
- def process document, output
- if document.basebackend? 'docbook'
- mansource = document.attributes['mansource']
- manversion = document.attributes['manversion']
- manmanual = document.attributes['manmanual']
- new_tags = "" \
- "<refmiscinfo class=\"source\">#{mansource}</refmiscinfo>\n" \
- "<refmiscinfo class=\"version\">#{manversion}</refmiscinfo>\n" \
- "<refmiscinfo class=\"manual\">#{manmanual}</refmiscinfo>\n"
- output = output.sub(/<\/refmeta>/, new_tags + "</refmeta>")
- end
- output
- end
- end
end
end
Asciidoctor::Extensions.register do
inline_macro Git::Documentation::LinkGitProcessor, :linkgit
- postprocessor Git::Documentation::DocumentPostProcessor
end
--
2.32.0
^ permalink raw reply related [flat|nested] 28+ messages in thread
* [PATCH 04/23] doc: asciidoc: remove unnecessary attribute
2021-06-21 16:30 [PATCH 00/23] doc: cleanups and asciidoctor direct man pages Felipe Contreras
` (2 preceding siblings ...)
2021-06-21 16:30 ` [PATCH 03/23] doc: simplify version passing Felipe Contreras
@ 2021-06-21 16:30 ` Felipe Contreras
2021-06-21 16:30 ` [PATCH 05/23] doc: asciidoctor: remove unnecessary require Felipe Contreras
` (19 subsequent siblings)
23 siblings, 0 replies; 28+ messages in thread
From: Felipe Contreras @ 2021-06-21 16:30 UTC (permalink / raw)
To: git
Cc: Martin Ågren, Ævar Arnfjörð Bjarmason,
Bagas Sanjaya, Jeff King, Junio C Hamano, brian m . carlson,
Felipe Contreras
It's part of asciidoc global configuration since 2012.
Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
Documentation/asciidoc.conf | 1 -
1 file changed, 1 deletion(-)
diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf
index 60f76f43ed..f7908f9dea 100644
--- a/Documentation/asciidoc.conf
+++ b/Documentation/asciidoc.conf
@@ -12,7 +12,6 @@
[attributes]
asterisk=*
-plus=+
caret=^
startsb=[
endsb=]
--
2.32.0
^ permalink raw reply related [flat|nested] 28+ messages in thread
* [PATCH 05/23] doc: asciidoctor: remove unnecessary require
2021-06-21 16:30 [PATCH 00/23] doc: cleanups and asciidoctor direct man pages Felipe Contreras
` (3 preceding siblings ...)
2021-06-21 16:30 ` [PATCH 04/23] doc: asciidoc: remove unnecessary attribute Felipe Contreras
@ 2021-06-21 16:30 ` Felipe Contreras
2021-06-21 16:30 ` [PATCH 06/23] doc: asciidoctor: remove cruft Felipe Contreras
` (18 subsequent siblings)
23 siblings, 0 replies; 28+ messages in thread
From: Felipe Contreras @ 2021-06-21 16:30 UTC (permalink / raw)
To: git
Cc: Martin Ågren, Ævar Arnfjörð Bjarmason,
Bagas Sanjaya, Jeff King, Junio C Hamano, brian m . carlson,
Felipe Contreras
This file is loaded by asciidoctor, the module is already loaded.
In addition to being less redundant this fixes a problem while trying
use a development version of asciidoctor when the gem is available:
$GEM_HOME/gems/asciidoctor-2.0.15/lib/asciidoctor.rb:51:
warning: already initialized constant Asciidoctor::RUBY_ENGINE
$HOME/asciidoctor/lib/asciidoctor.rb:52:
warning: previous definition of RUBY_ENGINE was here
...
That's a bug in asciidoctor, but there's no need to trigger it.
Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
Documentation/asciidoctor-extensions.rb | 1 -
1 file changed, 1 deletion(-)
diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb
index 70a0956663..423450392d 100644
--- a/Documentation/asciidoctor-extensions.rb
+++ b/Documentation/asciidoctor-extensions.rb
@@ -1,4 +1,3 @@
-require 'asciidoctor'
require 'asciidoctor/extensions'
module Git
--
2.32.0
^ permalink raw reply related [flat|nested] 28+ messages in thread
* [PATCH 06/23] doc: asciidoctor: remove cruft
2021-06-21 16:30 [PATCH 00/23] doc: cleanups and asciidoctor direct man pages Felipe Contreras
` (4 preceding siblings ...)
2021-06-21 16:30 ` [PATCH 05/23] doc: asciidoctor: remove unnecessary require Felipe Contreras
@ 2021-06-21 16:30 ` Felipe Contreras
2021-06-21 16:30 ` [PATCH 07/23] doc: asciidoctor: reorganize extensions Felipe Contreras
` (17 subsequent siblings)
23 siblings, 0 replies; 28+ messages in thread
From: Felipe Contreras @ 2021-06-21 16:30 UTC (permalink / raw)
To: git
Cc: Martin Ågren, Ævar Arnfjörð Bjarmason,
Bagas Sanjaya, Jeff King, Junio C Hamano, brian m . carlson,
Felipe Contreras
These were probably copy-pasted from other extensions. The name is
already defined (:linkgit), and we are not using the DSL mode.
Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
Documentation/asciidoctor-extensions.rb | 4 ----
1 file changed, 4 deletions(-)
diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb
index 423450392d..3dea106d00 100644
--- a/Documentation/asciidoctor-extensions.rb
+++ b/Documentation/asciidoctor-extensions.rb
@@ -3,10 +3,6 @@ require 'asciidoctor/extensions'
module Git
module Documentation
class LinkGitProcessor < Asciidoctor::Extensions::InlineMacroProcessor
- use_dsl
-
- named :chrome
-
def process(parent, target, attrs)
prefix = parent.document.attr('git-relative-html-prefix')
if parent.document.doctype == 'book'
--
2.32.0
^ permalink raw reply related [flat|nested] 28+ messages in thread
* [PATCH 07/23] doc: asciidoctor: reorganize extensions
2021-06-21 16:30 [PATCH 00/23] doc: cleanups and asciidoctor direct man pages Felipe Contreras
` (5 preceding siblings ...)
2021-06-21 16:30 ` [PATCH 06/23] doc: asciidoctor: remove cruft Felipe Contreras
@ 2021-06-21 16:30 ` Felipe Contreras
2021-06-21 16:30 ` [PATCH 08/23] doc: asciidoctor: use html-prefix only for html Felipe Contreras
` (16 subsequent siblings)
23 siblings, 0 replies; 28+ messages in thread
From: Felipe Contreras @ 2021-06-21 16:30 UTC (permalink / raw)
To: git
Cc: Martin Ågren, Ævar Arnfjörð Bjarmason,
Bagas Sanjaya, Jeff King, Junio C Hamano, brian m . carlson,
Felipe Contreras
There's no need to create verbose classes, we can do the same with a
simple block.
Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
Documentation/asciidoctor-extensions.rb | 34 +++++++++++--------------
1 file changed, 15 insertions(+), 19 deletions(-)
diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb
index 3dea106d00..f998a42249 100644
--- a/Documentation/asciidoctor-extensions.rb
+++ b/Documentation/asciidoctor-extensions.rb
@@ -1,26 +1,22 @@
require 'asciidoctor/extensions'
-module Git
- module Documentation
- class LinkGitProcessor < Asciidoctor::Extensions::InlineMacroProcessor
- def process(parent, target, attrs)
- prefix = parent.document.attr('git-relative-html-prefix')
- if parent.document.doctype == 'book'
- "<ulink url=\"#{prefix}#{target}.html\">" \
- "#{target}(#{attrs[1]})</ulink>"
- elsif parent.document.basebackend? 'html'
- %(<a href="#{prefix}#{target}.html">#{target}(#{attrs[1]})</a>)
- elsif parent.document.basebackend? 'docbook'
- "<citerefentry>\n" \
- "<refentrytitle>#{target}</refentrytitle>" \
- "<manvolnum>#{attrs[1]}</manvolnum>\n" \
- "</citerefentry>"
- end
+Asciidoctor::Extensions.register do
+
+ inline_macro :linkgit do
+ process do |parent, target, attrs|
+ prefix = parent.document.attr('git-relative-html-prefix')
+ if parent.document.doctype == 'book'
+ "<ulink url=\"#{prefix}#{target}.html\">" \
+ "#{target}(#{attrs[1]})</ulink>"
+ elsif parent.document.basebackend? 'html'
+ %(<a href="#{prefix}#{target}.html">#{target}(#{attrs[1]})</a>)
+ elsif parent.document.basebackend? 'docbook'
+ "<citerefentry>\n" \
+ "<refentrytitle>#{target}</refentrytitle>" \
+ "<manvolnum>#{attrs[1]}</manvolnum>\n" \
+ "</citerefentry>"
end
end
end
-end
-Asciidoctor::Extensions.register do
- inline_macro Git::Documentation::LinkGitProcessor, :linkgit
end
--
2.32.0
^ permalink raw reply related [flat|nested] 28+ messages in thread
* [PATCH 08/23] doc: asciidoctor: use html-prefix only for html
2021-06-21 16:30 [PATCH 00/23] doc: cleanups and asciidoctor direct man pages Felipe Contreras
` (6 preceding siblings ...)
2021-06-21 16:30 ` [PATCH 07/23] doc: asciidoctor: reorganize extensions Felipe Contreras
@ 2021-06-21 16:30 ` Felipe Contreras
2021-06-21 16:30 ` [PATCH 09/23] doc: asciidoctor: refactor macro registration Felipe Contreras
` (15 subsequent siblings)
23 siblings, 0 replies; 28+ messages in thread
From: Felipe Contreras @ 2021-06-21 16:30 UTC (permalink / raw)
To: git
Cc: Martin Ågren, Ævar Arnfjörð Bjarmason,
Bagas Sanjaya, Jeff King, Junio C Hamano, brian m . carlson,
Felipe Contreras
This is what asciidoc.conf does.
Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
Documentation/asciidoctor-extensions.rb | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb
index f998a42249..c77b6de350 100644
--- a/Documentation/asciidoctor-extensions.rb
+++ b/Documentation/asciidoctor-extensions.rb
@@ -4,11 +4,11 @@ Asciidoctor::Extensions.register do
inline_macro :linkgit do
process do |parent, target, attrs|
- prefix = parent.document.attr('git-relative-html-prefix')
if parent.document.doctype == 'book'
- "<ulink url=\"#{prefix}#{target}.html\">" \
+ "<ulink url=\"#{target}.html\">" \
"#{target}(#{attrs[1]})</ulink>"
elsif parent.document.basebackend? 'html'
+ prefix = parent.document.attr('git-relative-html-prefix')
%(<a href="#{prefix}#{target}.html">#{target}(#{attrs[1]})</a>)
elsif parent.document.basebackend? 'docbook'
"<citerefentry>\n" \
--
2.32.0
^ permalink raw reply related [flat|nested] 28+ messages in thread
* [PATCH 09/23] doc: asciidoctor: refactor macro registration
2021-06-21 16:30 [PATCH 00/23] doc: cleanups and asciidoctor direct man pages Felipe Contreras
` (7 preceding siblings ...)
2021-06-21 16:30 ` [PATCH 08/23] doc: asciidoctor: use html-prefix only for html Felipe Contreras
@ 2021-06-21 16:30 ` Felipe Contreras
2021-06-21 16:30 ` [PATCH 10/23] doc: asciidoctor: improve string handling Felipe Contreras
` (14 subsequent siblings)
23 siblings, 0 replies; 28+ messages in thread
From: Felipe Contreras @ 2021-06-21 16:30 UTC (permalink / raw)
To: git
Cc: Martin Ågren, Ævar Arnfjörð Bjarmason,
Bagas Sanjaya, Jeff King, Junio C Hamano, brian m . carlson,
Felipe Contreras
There is no need to execute extra code every time the process block is
called.
In Ruby the lexical scope is shared, so we can define variables in the
register block scope, and all the rest will inherit those variables.
Based on the doctype and basebackend one of three blocks is selected for
the inline_macro. However, the conditionals will be run only once.
In the end Ruby will only run the code between `process do end`, nothing
else.
Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
Documentation/asciidoctor-extensions.rb | 16 +++++++++++-----
1 file changed, 11 insertions(+), 5 deletions(-)
diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb
index c77b6de350..a678704e17 100644
--- a/Documentation/asciidoctor-extensions.rb
+++ b/Documentation/asciidoctor-extensions.rb
@@ -2,15 +2,21 @@ require 'asciidoctor/extensions'
Asciidoctor::Extensions.register do
+ doc = document
+
inline_macro :linkgit do
- process do |parent, target, attrs|
- if parent.document.doctype == 'book'
+ if doc.doctype == 'book'
+ process do |parent, target, attrs|
"<ulink url=\"#{target}.html\">" \
"#{target}(#{attrs[1]})</ulink>"
- elsif parent.document.basebackend? 'html'
- prefix = parent.document.attr('git-relative-html-prefix')
+ end
+ elsif doc.basebackend? 'html'
+ prefix = doc.attr('git-relative-html-prefix')
+ process do |parent, target, attrs|
%(<a href="#{prefix}#{target}.html">#{target}(#{attrs[1]})</a>)
- elsif parent.document.basebackend? 'docbook'
+ end
+ elsif doc.basebackend? 'docbook'
+ process do |parent, target, attrs|
"<citerefentry>\n" \
"<refentrytitle>#{target}</refentrytitle>" \
"<manvolnum>#{attrs[1]}</manvolnum>\n" \
--
2.32.0
^ permalink raw reply related [flat|nested] 28+ messages in thread
* [PATCH 10/23] doc: asciidoctor: improve string handling
2021-06-21 16:30 [PATCH 00/23] doc: cleanups and asciidoctor direct man pages Felipe Contreras
` (8 preceding siblings ...)
2021-06-21 16:30 ` [PATCH 09/23] doc: asciidoctor: refactor macro registration Felipe Contreras
@ 2021-06-21 16:30 ` Felipe Contreras
2021-06-21 16:30 ` [PATCH 11/23] doc: asciidoctor: split the format from the code Felipe Contreras
` (13 subsequent siblings)
23 siblings, 0 replies; 28+ messages in thread
From: Felipe Contreras @ 2021-06-21 16:30 UTC (permalink / raw)
To: git
Cc: Martin Ågren, Ævar Arnfjörð Bjarmason,
Bagas Sanjaya, Jeff King, Junio C Hamano, brian m . carlson,
Felipe Contreras
Using printf style formatting (more familiar to git developers), and
also here document.
Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
Documentation/asciidoctor-extensions.rb | 14 +++++++-------
1 file changed, 7 insertions(+), 7 deletions(-)
diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb
index a678704e17..3282d59a48 100644
--- a/Documentation/asciidoctor-extensions.rb
+++ b/Documentation/asciidoctor-extensions.rb
@@ -7,20 +7,20 @@ Asciidoctor::Extensions.register do
inline_macro :linkgit do
if doc.doctype == 'book'
process do |parent, target, attrs|
- "<ulink url=\"#{target}.html\">" \
- "#{target}(#{attrs[1]})</ulink>"
+ '<ulink url="%1$s.html">%1$s(%2$s)</ulink>' % [target, attrs[1]]
end
elsif doc.basebackend? 'html'
prefix = doc.attr('git-relative-html-prefix')
process do |parent, target, attrs|
- %(<a href="#{prefix}#{target}.html">#{target}(#{attrs[1]})</a>)
+ %(<a href="#{prefix}%1$s.html">%1$s(%2$s)</a>) % [target, attrs[1]]
end
elsif doc.basebackend? 'docbook'
process do |parent, target, attrs|
- "<citerefentry>\n" \
- "<refentrytitle>#{target}</refentrytitle>" \
- "<manvolnum>#{attrs[1]}</manvolnum>\n" \
- "</citerefentry>"
+ <<~EOF.chomp % [target, attrs[1]]
+ <citerefentry>
+ <refentrytitle>%s</refentrytitle><manvolnum>%s</manvolnum>
+ </citerefentry>
+ EOF
end
end
end
--
2.32.0
^ permalink raw reply related [flat|nested] 28+ messages in thread
* [PATCH 11/23] doc: asciidoctor: split the format from the code
2021-06-21 16:30 [PATCH 00/23] doc: cleanups and asciidoctor direct man pages Felipe Contreras
` (9 preceding siblings ...)
2021-06-21 16:30 ` [PATCH 10/23] doc: asciidoctor: improve string handling Felipe Contreras
@ 2021-06-21 16:30 ` Felipe Contreras
2021-06-21 16:30 ` [PATCH 12/23] doc: asciidoctor: specify name of our group Felipe Contreras
` (12 subsequent siblings)
23 siblings, 0 replies; 28+ messages in thread
From: Felipe Contreras @ 2021-06-21 16:30 UTC (permalink / raw)
To: git
Cc: Martin Ågren, Ævar Arnfjörð Bjarmason,
Bagas Sanjaya, Jeff King, Junio C Hamano, brian m . carlson,
Felipe Contreras
This way we don't have to specify the block to execute on every
conditional.
Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
Documentation/asciidoctor-extensions.rb | 26 ++++++++++++-------------
1 file changed, 13 insertions(+), 13 deletions(-)
diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb
index 3282d59a48..51981af13c 100644
--- a/Documentation/asciidoctor-extensions.rb
+++ b/Documentation/asciidoctor-extensions.rb
@@ -6,22 +6,22 @@ Asciidoctor::Extensions.register do
inline_macro :linkgit do
if doc.doctype == 'book'
- process do |parent, target, attrs|
- '<ulink url="%1$s.html">%1$s(%2$s)</ulink>' % [target, attrs[1]]
- end
+ format = '<ulink url="%1$s.html">%1$s(%2$s)</ulink>'
elsif doc.basebackend? 'html'
prefix = doc.attr('git-relative-html-prefix')
- process do |parent, target, attrs|
- %(<a href="#{prefix}%1$s.html">%1$s(%2$s)</a>) % [target, attrs[1]]
- end
+ format = %(<a href="#{prefix}%1$s.html">%1$s(%2$s)</a>)
elsif doc.basebackend? 'docbook'
- process do |parent, target, attrs|
- <<~EOF.chomp % [target, attrs[1]]
- <citerefentry>
- <refentrytitle>%s</refentrytitle><manvolnum>%s</manvolnum>
- </citerefentry>
- EOF
- end
+ format = <<~EOF.chomp
+ <citerefentry>
+ <refentrytitle>%s</refentrytitle><manvolnum>%s</manvolnum>
+ </citerefentry>
+ EOF
+ else
+ return
+ end
+
+ process do |_, target, attrs|
+ format % [target, attrs[1]]
end
end
--
2.32.0
^ permalink raw reply related [flat|nested] 28+ messages in thread
* [PATCH 12/23] doc: asciidoctor: specify name of our group
2021-06-21 16:30 [PATCH 00/23] doc: cleanups and asciidoctor direct man pages Felipe Contreras
` (10 preceding siblings ...)
2021-06-21 16:30 ` [PATCH 11/23] doc: asciidoctor: split the format from the code Felipe Contreras
@ 2021-06-21 16:30 ` Felipe Contreras
2021-06-21 16:31 ` [PATCH 13/23] doc: doc-diff: set docdate manually Felipe Contreras
` (11 subsequent siblings)
23 siblings, 0 replies; 28+ messages in thread
From: Felipe Contreras @ 2021-06-21 16:30 UTC (permalink / raw)
To: git
Cc: Martin Ågren, Ævar Arnfjörð Bjarmason,
Bagas Sanjaya, Jeff King, Junio C Hamano, brian m . carlson,
Felipe Contreras
Doesn't do anything, but otherwise we get a random name.
Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
Documentation/asciidoctor-extensions.rb | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb
index 51981af13c..b36317e4d2 100644
--- a/Documentation/asciidoctor-extensions.rb
+++ b/Documentation/asciidoctor-extensions.rb
@@ -1,6 +1,6 @@
require 'asciidoctor/extensions'
-Asciidoctor::Extensions.register do
+Asciidoctor::Extensions.register :git do
doc = document
--
2.32.0
^ permalink raw reply related [flat|nested] 28+ messages in thread
* [PATCH 13/23] doc: doc-diff: set docdate manually
2021-06-21 16:30 [PATCH 00/23] doc: cleanups and asciidoctor direct man pages Felipe Contreras
` (11 preceding siblings ...)
2021-06-21 16:30 ` [PATCH 12/23] doc: asciidoctor: specify name of our group Felipe Contreras
@ 2021-06-21 16:31 ` Felipe Contreras
2021-06-21 16:31 ` [PATCH 14/23] doc-diff: drop --cut-footer switch Felipe Contreras
` (10 subsequent siblings)
23 siblings, 0 replies; 28+ messages in thread
From: Felipe Contreras @ 2021-06-21 16:31 UTC (permalink / raw)
To: git
Cc: Martin Ågren, Ævar Arnfjörð Bjarmason,
Bagas Sanjaya, Jeff King, Junio C Hamano, brian m . carlson,
Felipe Contreras
In order to minimize the differences in the footer.
Asciidoc automatically generates a date with format '%Y-%m-%d', while
asciidoctor '%F'.
I personally prefer the latter, so only modify it for diff purposes.
Fixes tons of these:
-Git omitted 01/01/1970 GIT-ADD(1)
+Git omitted 1970-01-01 GIT-ADD(1)
Note that we have to add quotes when passing around $makemanflags, as it
now may contain whitespace due to multiple arguments (but the
dereference inside render_tree must remain unquoted, because it wants to perform
whitespace splitting to get the individual arguments back).
Comments-by: Jeff King <peff@peff.net>
Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
Documentation/Makefile | 2 +-
Documentation/doc-diff | 6 +++---
2 files changed, 4 insertions(+), 4 deletions(-)
diff --git a/Documentation/Makefile b/Documentation/Makefile
index 47053c78f8..b68ab57239 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -136,7 +136,7 @@ ASCIIDOC_EXTRA =
ASCIIDOC_HTML = xhtml11
ASCIIDOC_DOCBOOK = docbook
ASCIIDOC_CONF = -f asciidoc.conf
-ASCIIDOC_COMMON = $(ASCIIDOC) $(ASCIIDOC_EXTRA) $(ASCIIDOC_CONF) \
+ASCIIDOC_COMMON = $(ASCIIDOC) $(ASCIIDOC_EXTRA) $(ASCIIDOC_FLAGS) $(ASCIIDOC_CONF) \
-amanmanual='Git Manual' -amansource='Git $(GIT_VERSION)'
ASCIIDOC_DEPS = asciidoc.conf GIT-ASCIIDOCFLAGS
TXT_TO_HTML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_HTML)
diff --git a/Documentation/doc-diff b/Documentation/doc-diff
index 1694300e50..c11b90a6ef 100755
--- a/Documentation/doc-diff
+++ b/Documentation/doc-diff
@@ -111,7 +111,7 @@ construct_makemanflags () {
echo USE_ASCIIDOCTOR=
elif test "$1" = "-asciidoctor"
then
- echo USE_ASCIIDOCTOR=YesPlease
+ echo USE_ASCIIDOCTOR=YesPlease ASCIIDOC_FLAGS='-adocdate="01/01/1970"'
fi
}
@@ -181,6 +181,6 @@ render_tree () {
fi
}
-render_tree $from_oid $from_dir $from_makemanflags &&
-render_tree $to_oid $to_dir $to_makemanflags &&
+render_tree $from_oid $from_dir "$from_makemanflags" &&
+render_tree $to_oid $to_dir "$to_makemanflags" &&
git -C $tmp/rendered diff --no-index "$@" $from_dir $to_dir
--
2.32.0
^ permalink raw reply related [flat|nested] 28+ messages in thread
* [PATCH 14/23] doc-diff: drop --cut-footer switch
2021-06-21 16:30 [PATCH 00/23] doc: cleanups and asciidoctor direct man pages Felipe Contreras
` (12 preceding siblings ...)
2021-06-21 16:31 ` [PATCH 13/23] doc: doc-diff: set docdate manually Felipe Contreras
@ 2021-06-21 16:31 ` Felipe Contreras
2021-06-21 16:31 ` [PATCH 15/23] doc: use asciidoctor to build man pages directly Felipe Contreras
` (9 subsequent siblings)
23 siblings, 0 replies; 28+ messages in thread
From: Felipe Contreras @ 2021-06-21 16:31 UTC (permalink / raw)
To: git
Cc: Martin Ågren, Ævar Arnfjörð Bjarmason,
Bagas Sanjaya, Jeff King, Junio C Hamano, brian m . carlson,
Felipe Contreras
From: Martin Ågren <martin.agren@gmail.com>
Now that our doc-diff convinces Asciidoctor to insert the exact same
formatted dummy date as AsciiDoc, we can drop the --cut-footer switch.
It has been useful to ignore this difference between the two tools, but
it's effectively a no-op now. Similar to when we repurposed this from
--cut-header-footer in 83b0b8953e ("doc-diff: replace
--cut-header-footer with --cut-footer", 2019-09-16), just drop it
without worrying about any kind of backwards compatibility or user-base.
Signed-off-by: Martin Ågren <martin.agren@gmail.com>
Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
Documentation/doc-diff | 18 ++----------------
1 file changed, 2 insertions(+), 16 deletions(-)
diff --git a/Documentation/doc-diff b/Documentation/doc-diff
index c11b90a6ef..6b6bb444ac 100755
--- a/Documentation/doc-diff
+++ b/Documentation/doc-diff
@@ -21,7 +21,6 @@ asciidoc use asciidoc with both commits
to-asciidoc use asciidoc with the 'to'-commit
to-asciidoctor use asciidoctor with the 'to'-commit
asciidoctor use asciidoctor with both commits
-cut-footer cut away footer
"
SUBDIRECTORY_OK=1
. "$(git --exec-path)/git-sh-setup"
@@ -31,7 +30,6 @@ force=
clean=
from_program=
to_program=
-cut_footer=
while test $# -gt 0
do
case "$1" in
@@ -55,8 +53,6 @@ do
--asciidoc)
from_program=-asciidoc
to_program=-asciidoc ;;
- --cut-footer)
- cut_footer=-cut-footer ;;
--)
shift; break ;;
*)
@@ -118,8 +114,8 @@ construct_makemanflags () {
from_makemanflags=$(construct_makemanflags "$from_program") &&
to_makemanflags=$(construct_makemanflags "$to_program") &&
-from_dir=$from_oid$from_program$cut_footer &&
-to_dir=$to_oid$to_program$cut_footer &&
+from_dir=$from_oid$from_program &&
+to_dir=$to_oid$to_program &&
# generate_render_makefile <srcdir> <dstdir>
generate_render_makefile () {
@@ -168,16 +164,6 @@ render_tree () {
"$tmp/rendered/$dname+" |
make -j$parallel -f - &&
mv "$tmp/rendered/$dname+" "$tmp/rendered/$dname"
-
- if test "$cut_footer" = "-cut-footer"
- then
- for f in $(find "$tmp/rendered/$dname" -type f)
- do
- head -n -2 "$f" | sed -e '${/^$/d}' >"$f+" &&
- mv "$f+" "$f" ||
- return 1
- done
- fi
fi
}
--
2.32.0
^ permalink raw reply related [flat|nested] 28+ messages in thread
* [PATCH 15/23] doc: use asciidoctor to build man pages directly
2021-06-21 16:30 [PATCH 00/23] doc: cleanups and asciidoctor direct man pages Felipe Contreras
` (13 preceding siblings ...)
2021-06-21 16:31 ` [PATCH 14/23] doc-diff: drop --cut-footer switch Felipe Contreras
@ 2021-06-21 16:31 ` Felipe Contreras
2021-06-22 5:23 ` Bagas Sanjaya
2021-06-21 16:31 ` [PATCH 16/23] doc-diff: support asciidoctor man pages Felipe Contreras
` (8 subsequent siblings)
23 siblings, 1 reply; 28+ messages in thread
From: Felipe Contreras @ 2021-06-21 16:31 UTC (permalink / raw)
To: git
Cc: Martin Ågren, Ævar Arnfjörð Bjarmason,
Bagas Sanjaya, Jeff King, Junio C Hamano, brian m . carlson,
Felipe Contreras
There's no need to use xmlto to build the man pages when modern
asciidoctor can do it by itself.
This new mode will be active only when both USE_ASCIIDOCTOR and
USE_ASCIIDOCTOR_MANPAGE are set.
Suggested-by: Bagas Sanjaya <bagasdotme@gmail.com>
Suggestions-by: Jeff King <peff@peff.net>
Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
Documentation/Makefile | 10 +++++++++-
Makefile | 4 ++++
2 files changed, 13 insertions(+), 1 deletion(-)
diff --git a/Documentation/Makefile b/Documentation/Makefile
index b68ab57239..e6af1848cc 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -189,6 +189,9 @@ ASCIIDOC_DEPS = asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS
DBLATEX_COMMON =
XMLTO_EXTRA += --skip-validation
XMLTO_EXTRA += -x manpage.xsl
+ifdef USE_ASCIIDOCTOR_MANPAGE
+TXT_TO_MAN = $(ASCIIDOC_COMMON) -b manpage
+endif
endif
SHELL_PATH ?= $(SHELL)
@@ -324,7 +327,7 @@ 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)'; \
@@ -349,8 +352,13 @@ $(MAN_HTML): %.html : %.txt $(ASCIIDOC_DEPS)
$(OBSOLETE_HTML): %.html : %.txto $(ASCIIDOC_DEPS)
$(QUIET_ASCIIDOC)$(TXT_TO_HTML) -o $@ $<
+ifdef TXT_TO_MAN
+%.1 %.5 %.7 : %.txt $(ASCIIDOC_DEPS)
+ $(QUIET_ASCIIDOC)$(TXT_TO_MAN) -o $@ $<
+else
%.1 %.5 %.7 : %.xml $(wildcard manpage*.xsl)
$(QUIET_XMLTO)$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<
+endif
%.xml : %.txt $(ASCIIDOC_DEPS)
$(QUIET_ASCIIDOC)$(TXT_TO_XML) -d manpage -o $@ $<
diff --git a/Makefile b/Makefile
index 7588c43f05..ab3fa362b7 100644
--- a/Makefile
+++ b/Makefile
@@ -281,6 +281,10 @@ all::
# Define USE_ASCIIDOCTOR to use Asciidoctor instead of AsciiDoc to build the
# documentation.
#
+# Define USE_ASCIIDOCTOR_MANPAGE to use Asciidoctor's manual page backend
+# 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.32.0
^ permalink raw reply related [flat|nested] 28+ messages in thread
* [PATCH 16/23] doc-diff: support asciidoctor man pages
2021-06-21 16:30 [PATCH 00/23] doc: cleanups and asciidoctor direct man pages Felipe Contreras
` (14 preceding siblings ...)
2021-06-21 16:31 ` [PATCH 15/23] doc: use asciidoctor to build man pages directly Felipe Contreras
@ 2021-06-21 16:31 ` Felipe Contreras
2021-06-21 16:31 ` [PATCH 17/23] doc: asciidoctor: add linkgit macros in " Felipe Contreras
` (7 subsequent siblings)
23 siblings, 0 replies; 28+ messages in thread
From: Felipe Contreras @ 2021-06-21 16:31 UTC (permalink / raw)
To: git
Cc: Martin Ågren, Ævar Arnfjörð Bjarmason,
Bagas Sanjaya, Jeff King, Junio C Hamano, brian m . carlson,
Felipe Contreras
From: Jeff King <peff@peff.net>
The new option enables both asciidoctor as well as its direct-to-manpage
mode that skips xmlto. This lets you view the rendered difference
between the two pipelines with something like:
./doc-diff --from-asciidoctor --to-asciidoctor-direct HEAD HEAD
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
Documentation/doc-diff | 14 ++++++++++++++
1 file changed, 14 insertions(+)
diff --git a/Documentation/doc-diff b/Documentation/doc-diff
index 6b6bb444ac..bbfeaa213b 100755
--- a/Documentation/doc-diff
+++ b/Documentation/doc-diff
@@ -17,10 +17,13 @@ f force rebuild; do not rely on cached results
c,clean cleanup temporary working files
from-asciidoc use asciidoc with the 'from'-commit
from-asciidoctor use asciidoctor with the 'from'-commit
+from-asciidoctor-direct use asciidoctor without xmlto for 'from'-commit
asciidoc use asciidoc with both commits
to-asciidoc use asciidoc with the 'to'-commit
to-asciidoctor use asciidoctor with the 'to'-commit
+to-asciidoctor-direct use asciidoctor without xmlto for 'to'-commit
asciidoctor use asciidoctor with both commits
+asciidoctor-direct use asciidoctor without xml for both commits
"
SUBDIRECTORY_OK=1
. "$(git --exec-path)/git-sh-setup"
@@ -53,6 +56,13 @@ do
--asciidoc)
from_program=-asciidoc
to_program=-asciidoc ;;
+ --from-asciidoctor-direct)
+ from_program=-asciidoctor-direct ;;
+ --to-asciidoctor-direct)
+ to_program=-asciidoctor-direct ;;
+ --asciidoctor-direct)
+ from_program=-asciidoctor-direct
+ to_program=-asciidoctor-direct ;;
--)
shift; break ;;
*)
@@ -108,6 +118,10 @@ construct_makemanflags () {
elif test "$1" = "-asciidoctor"
then
echo USE_ASCIIDOCTOR=YesPlease ASCIIDOC_FLAGS='-adocdate="01/01/1970"'
+ elif test "$1" = "-asciidoctor-direct"
+ then
+ echo USE_ASCIIDOCTOR=YesPlease ASCIIDOC_FLAGS='-adocdate="01/01/1970"'
+ echo USE_ASCIIDOCTOR_MANPAGE=YesPlease
fi
}
--
2.32.0
^ permalink raw reply related [flat|nested] 28+ messages in thread
* [PATCH 17/23] doc: asciidoctor: add linkgit macros in man pages
2021-06-21 16:30 [PATCH 00/23] doc: cleanups and asciidoctor direct man pages Felipe Contreras
` (15 preceding siblings ...)
2021-06-21 16:31 ` [PATCH 16/23] doc-diff: support asciidoctor man pages Felipe Contreras
@ 2021-06-21 16:31 ` Felipe Contreras
2021-06-21 16:31 ` [PATCH 18/23] doc: add man pages workaround for asciidoctor Felipe Contreras
` (6 subsequent siblings)
23 siblings, 0 replies; 28+ messages in thread
From: Felipe Contreras @ 2021-06-21 16:31 UTC (permalink / raw)
To: git
Cc: Martin Ågren, Ævar Arnfjörð Bjarmason,
Bagas Sanjaya, Jeff King, Junio C Hamano, brian m . carlson,
Felipe Contreras
Fixes the doc-diff:
- Please see git-commit(1) for alternative ways to add content to a
- commit.
+ Please see for alternative ways to add content to a commit.
Comments-by: brian m. carlson <sandals@crustytoothpaste.net>
Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
Documentation/asciidoctor-extensions.rb | 2 ++
1 file changed, 2 insertions(+)
diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb
index b36317e4d2..6c4153f628 100644
--- a/Documentation/asciidoctor-extensions.rb
+++ b/Documentation/asciidoctor-extensions.rb
@@ -10,6 +10,8 @@ Asciidoctor::Extensions.register :git do
elsif doc.basebackend? 'html'
prefix = doc.attr('git-relative-html-prefix')
format = %(<a href="#{prefix}%1$s.html">%1$s(%2$s)</a>)
+ elsif doc.basebackend? 'manpage'
+ format = "\e\\fB%s\e\\fP(%s)"
elsif doc.basebackend? 'docbook'
format = <<~EOF.chomp
<citerefentry>
--
2.32.0
^ permalink raw reply related [flat|nested] 28+ messages in thread
* [PATCH 18/23] doc: add man pages workaround for asciidoctor
2021-06-21 16:30 [PATCH 00/23] doc: cleanups and asciidoctor direct man pages Felipe Contreras
` (16 preceding siblings ...)
2021-06-21 16:31 ` [PATCH 17/23] doc: asciidoctor: add linkgit macros in " Felipe Contreras
@ 2021-06-21 16:31 ` Felipe Contreras
2021-06-21 16:31 ` [PATCH 19/23] doc: asciidoctor: add hack for xrefs Felipe Contreras
` (5 subsequent siblings)
23 siblings, 0 replies; 28+ messages in thread
From: Felipe Contreras @ 2021-06-21 16:31 UTC (permalink / raw)
To: git
Cc: Martin Ågren, Ævar Arnfjörð Bjarmason,
Bagas Sanjaya, Jeff King, Junio C Hamano, brian m . carlson,
Felipe Contreras
Currently asciidoctor doesn't convert number character references
(&#xx;) correctly for man pages.
This hack fixes the issue with minimum changes elsewhere so it's easy to
remove when fixed.
Fixes doc-diffs like:
so line count cannot be shown) and there is no difference between
indexed copy and the working tree version (if the working tree
version were also different, binary would have been shown in place
- of nothing). The other file, git-add--interactive.perl, has 403
- lines added and 35 lines deleted if you commit what is in the
- index, but working tree file has further modifications (one
+ of nothing). The other file, git-add--interactive.perl,
+ has 403 lines added and 35 lines deleted if you commit what is in
+ the index, but working tree file has further modifications (one
addition and one deletion).
https://github.com/asciidoctor/asciidoctor/issues/4059
Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
Documentation/asciidoctor-extensions.rb | 6 ++++++
1 file changed, 6 insertions(+)
diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb
index 6c4153f628..954acb3e7d 100644
--- a/Documentation/asciidoctor-extensions.rb
+++ b/Documentation/asciidoctor-extensions.rb
@@ -4,6 +4,12 @@ Asciidoctor::Extensions.register :git do
doc = document
+ # Override attributes for man pages.
+ # https://github.com/asciidoctor/asciidoctor/issues/4059
+ if doc.backend == 'manpage'
+ doc.attributes.merge!({ 'litdd' => '\--', 'plus' => '+' })
+ end
+
inline_macro :linkgit do
if doc.doctype == 'book'
format = '<ulink url="%1$s.html">%1$s(%2$s)</ulink>'
--
2.32.0
^ permalink raw reply related [flat|nested] 28+ messages in thread
* [PATCH 19/23] doc: asciidoctor: add hack for xrefs
2021-06-21 16:30 [PATCH 00/23] doc: cleanups and asciidoctor direct man pages Felipe Contreras
` (17 preceding siblings ...)
2021-06-21 16:31 ` [PATCH 18/23] doc: add man pages workaround for asciidoctor Felipe Contreras
@ 2021-06-21 16:31 ` Felipe Contreras
2021-06-21 16:31 ` [PATCH 20/23] doc: asciidoctor: add hack to improve links Felipe Contreras
` (4 subsequent siblings)
23 siblings, 0 replies; 28+ messages in thread
From: Felipe Contreras @ 2021-06-21 16:31 UTC (permalink / raw)
To: git
Cc: Martin Ågren, Ævar Arnfjörð Bjarmason,
Bagas Sanjaya, Jeff King, Junio C Hamano, brian m . carlson,
Felipe Contreras
The docbook manpage stylesheets convert cross-references with format the
'section called “%t”'. I personally prefer the asciidoctor version, but
for now add a hack to minimize the diff.
Thanks to the extensibility of Ruby we can override corresponding method
in the man page converter.
This fixes doc-diffs like:
--worktree-attributes
Look for attributes in .gitattributes files in the working tree as
- well (see the section called “ATTRIBUTES”).
+ well (see ATTRIBUTES).
This can easily be removed later once we are confortable with the
asciidoctor version.
Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
Documentation/asciidoctor-extensions.rb | 18 ++++++++++++++++++
1 file changed, 18 insertions(+)
diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb
index 954acb3e7d..7561973df6 100644
--- a/Documentation/asciidoctor-extensions.rb
+++ b/Documentation/asciidoctor-extensions.rb
@@ -1,4 +1,22 @@
require 'asciidoctor/extensions'
+require 'asciidoctor/converter/manpage'
+
+module Asciidoctor
+ class Converter::ManPageConverter
+ alias orig_convert_inline_anchor convert_inline_anchor
+ def convert_inline_anchor(node)
+ case node.type
+ when :xref
+ return node.text if node.text
+ refid = node.attributes['refid']
+ 'the section called “%s”' % refid.gsub('_', ' ')
+ else
+ orig_convert_inline_anchor(node)
+ end
+ end
+ alias inline_anchor convert_inline_anchor # For old versions of asciidoctor
+ end
+end
Asciidoctor::Extensions.register :git do
--
2.32.0
^ permalink raw reply related [flat|nested] 28+ messages in thread
* [PATCH 20/23] doc: asciidoctor: add hack to improve links
2021-06-21 16:30 [PATCH 00/23] doc: cleanups and asciidoctor direct man pages Felipe Contreras
` (18 preceding siblings ...)
2021-06-21 16:31 ` [PATCH 19/23] doc: asciidoctor: add hack for xrefs Felipe Contreras
@ 2021-06-21 16:31 ` Felipe Contreras
2021-06-21 16:31 ` [PATCH 21/23] doc: asciidoctor: add support for baseurl Felipe Contreras
` (3 subsequent siblings)
23 siblings, 0 replies; 28+ messages in thread
From: Felipe Contreras @ 2021-06-21 16:31 UTC (permalink / raw)
To: git
Cc: Martin Ågren, Ævar Arnfjörð Bjarmason,
Bagas Sanjaya, Jeff King, Junio C Hamano, brian m . carlson,
Felipe Contreras
The way asciidoctor handles links is very primitive compared to docbook.
Links are simply presented in the format "#{text} <#{target}>", which
may not be all that bad for the future, but pollutes the doc-diff.
By adding another modification to convert_inline_anchor() we can present
links in a form very similar to docbook, diminishing the doc-diff.
This significantly reduces the doc-diff:
From:
abysmal performance). These safety and performance issues cannot be
backward compatibly fixed and as such, its use is not recommended.
Please use an alternative history filtering tool such as git
- filter-repo[1]. If you still need to use git filter-branch, please
- carefully read the section called “SAFETY” (and the section called
- “PERFORMANCE”) to learn about the land mines of filter-branch, and then
- vigilantly avoid as many of the hazards listed there as reasonably
- possible.
+ <https://github.com/newren/git-filter-repo/> filter-repo" . If you
+ still need to use git filter-branch, please carefully read the section
+ called “SAFETY” (and the section called “PERFORMANCE”) to learn about
+ the land mines of filter-branch, and then vigilantly avoid as many of
+ the hazards listed there as reasonably possible.
-NOTES
- 1. git filter-repo
- https://github.com/newren/git-filter-repo/
-
- 2. filter-lamely
- https://github.com/newren/git-filter-repo/blob/master/contrib/filter-repo-demos/filter-lamely
-
To:
NOTES
- 1. git filter-repo
+ [1] git filter-repo
https://github.com/newren/git-filter-repo/
Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
Documentation/asciidoctor-extensions.rb | 13 +++++++++++++
1 file changed, 13 insertions(+)
diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb
index 7561973df6..914e6f64c8 100644
--- a/Documentation/asciidoctor-extensions.rb
+++ b/Documentation/asciidoctor-extensions.rb
@@ -10,6 +10,19 @@ module Asciidoctor
return node.text if node.text
refid = node.attributes['refid']
'the section called “%s”' % refid.gsub('_', ' ')
+ when :link
+ return node.target if node.text == node.target
+ doc = node.document
+
+ footnote = doc.footnotes.find { |e| e.id == node.target }
+ if !footnote
+ footnote_text = "%s\n\e.RS\n\e\\%%%s\n\e.RE" % [node.text, node.target]
+ index = doc.counter('footnote-number')
+ footnote = Document::Footnote.new(index, node.target, footnote_text)
+ doc.register(:footnotes, footnote)
+ end
+
+ "\e\\fB%s\e\\fR[%d]" % [node.text, footnote.index]
else
orig_convert_inline_anchor(node)
end
--
2.32.0
^ permalink raw reply related [flat|nested] 28+ messages in thread
* [PATCH 21/23] doc: asciidoctor: add support for baseurl
2021-06-21 16:30 [PATCH 00/23] doc: cleanups and asciidoctor direct man pages Felipe Contreras
` (19 preceding siblings ...)
2021-06-21 16:31 ` [PATCH 20/23] doc: asciidoctor: add hack to improve links Felipe Contreras
@ 2021-06-21 16:31 ` Felipe Contreras
2021-06-21 16:31 ` [PATCH 22/23] doc: asciidoctor: cleanup man page hack Felipe Contreras
` (2 subsequent siblings)
23 siblings, 0 replies; 28+ messages in thread
From: Felipe Contreras @ 2021-06-21 16:31 UTC (permalink / raw)
To: git
Cc: Martin Ågren, Ævar Arnfjörð Bjarmason,
Bagas Sanjaya, Jeff King, Junio C Hamano, brian m . carlson,
Felipe Contreras
So that we can present relative links correctly.
Reduces the doc-diff:
NOTES
- 1. “Understanding history: What is a branch?”
- file:///$HOME/share/doc/git-doc/user-manual.html#what-is-a-branch
+ [1] “Understanding history: What is a branch?”
+ user-manual.html#what-is-a-branch
NOTES
- 1. “Understanding history: What is a branch?”
+ [1] “Understanding history: What is a branch?”
file:///$HOME/share/doc/git-doc/user-manual.html#what-is-a-branch
Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
Documentation/Makefile | 1 +
Documentation/asciidoctor-extensions.rb | 4 +++-
2 files changed, 4 insertions(+), 1 deletion(-)
diff --git a/Documentation/Makefile b/Documentation/Makefile
index e6af1848cc..dea0f2d859 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -185,6 +185,7 @@ ASCIIDOC_DOCBOOK = docbook5
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
diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb
index 914e6f64c8..8856f2febd 100644
--- a/Documentation/asciidoctor-extensions.rb
+++ b/Documentation/asciidoctor-extensions.rb
@@ -16,7 +16,9 @@ module Asciidoctor
footnote = doc.footnotes.find { |e| e.id == node.target }
if !footnote
- footnote_text = "%s\n\e.RS\n\e\\%%%s\n\e.RE" % [node.text, node.target]
+ target = node.target
+ target = doc.attributes['baseurl'] + target unless target.include? ':'
+ footnote_text = "%s\n\e.RS\n\e\\%%%s\n\e.RE" % [node.text, target]
index = doc.counter('footnote-number')
footnote = Document::Footnote.new(index, node.target, footnote_text)
doc.register(:footnotes, footnote)
--
2.32.0
^ permalink raw reply related [flat|nested] 28+ messages in thread
* [PATCH 22/23] doc: asciidoctor: cleanup man page hack
2021-06-21 16:30 [PATCH 00/23] doc: cleanups and asciidoctor direct man pages Felipe Contreras
` (20 preceding siblings ...)
2021-06-21 16:31 ` [PATCH 21/23] doc: asciidoctor: add support for baseurl Felipe Contreras
@ 2021-06-21 16:31 ` Felipe Contreras
2021-06-21 16:31 ` [PATCH 23/23] doc: asciidoctor: add hack for old versions Felipe Contreras
2021-06-22 5:35 ` [PATCH 00/23] doc: cleanups and asciidoctor direct man pages Bagas Sanjaya
23 siblings, 0 replies; 28+ messages in thread
From: Felipe Contreras @ 2021-06-21 16:31 UTC (permalink / raw)
To: git
Cc: Martin Ågren, Ævar Arnfjörð Bjarmason,
Bagas Sanjaya, Jeff King, Junio C Hamano, brian m . carlson,
Felipe Contreras
There's basically nothing we need from the original
orig_convert_inline_anchor(), so let's remove calls to it.
Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
Documentation/asciidoctor-extensions.rb | 5 +++--
1 file changed, 3 insertions(+), 2 deletions(-)
diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb
index 8856f2febd..e48a381b8f 100644
--- a/Documentation/asciidoctor-extensions.rb
+++ b/Documentation/asciidoctor-extensions.rb
@@ -3,7 +3,6 @@ require 'asciidoctor/converter/manpage'
module Asciidoctor
class Converter::ManPageConverter
- alias orig_convert_inline_anchor convert_inline_anchor
def convert_inline_anchor(node)
case node.type
when :xref
@@ -25,8 +24,10 @@ module Asciidoctor
end
"\e\\fB%s\e\\fR[%d]" % [node.text, footnote.index]
+ when :ref, :bibref
+ ''
else
- orig_convert_inline_anchor(node)
+ nil
end
end
alias inline_anchor convert_inline_anchor # For old versions of asciidoctor
--
2.32.0
^ permalink raw reply related [flat|nested] 28+ messages in thread
* [PATCH 23/23] doc: asciidoctor: add hack for old versions
2021-06-21 16:30 [PATCH 00/23] doc: cleanups and asciidoctor direct man pages Felipe Contreras
` (21 preceding siblings ...)
2021-06-21 16:31 ` [PATCH 22/23] doc: asciidoctor: cleanup man page hack Felipe Contreras
@ 2021-06-21 16:31 ` Felipe Contreras
2021-06-22 5:35 ` [PATCH 00/23] doc: cleanups and asciidoctor direct man pages Bagas Sanjaya
23 siblings, 0 replies; 28+ messages in thread
From: Felipe Contreras @ 2021-06-21 16:31 UTC (permalink / raw)
To: git
Cc: Martin Ågren, Ævar Arnfjörð Bjarmason,
Bagas Sanjaya, Jeff King, Junio C Hamano, brian m . carlson,
Felipe Contreras
\\ gets converted erroneously.
[1] https://github.com/asciidoctor/asciidoctor/issues/3456
Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
Documentation/asciidoctor-extensions.rb | 13 +++++++++++--
1 file changed, 11 insertions(+), 2 deletions(-)
diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb
index e48a381b8f..3ab669dad8 100644
--- a/Documentation/asciidoctor-extensions.rb
+++ b/Documentation/asciidoctor-extensions.rb
@@ -38,10 +38,19 @@ Asciidoctor::Extensions.register :git do
doc = document
- # Override attributes for man pages.
- # https://github.com/asciidoctor/asciidoctor/issues/4059
if doc.backend == 'manpage'
+ # Override attributes for man pages.
+ # https://github.com/asciidoctor/asciidoctor/issues/4059
doc.attributes.merge!({ 'litdd' => '\--', 'plus' => '+' })
+
+ # Fix bug with \\
+ if Asciidoctor::VERSION < '2.0.11'
+ postprocessor do
+ process do |_, output|
+ output.gsub("\\(rs\\\\", "\\(rs\\(rs\\")
+ end
+ end
+ end
end
inline_macro :linkgit do
--
2.32.0
^ permalink raw reply related [flat|nested] 28+ messages in thread
* Re: [PATCH 15/23] doc: use asciidoctor to build man pages directly
2021-06-21 16:31 ` [PATCH 15/23] doc: use asciidoctor to build man pages directly Felipe Contreras
@ 2021-06-22 5:23 ` Bagas Sanjaya
2021-06-23 1:35 ` Felipe Contreras
0 siblings, 1 reply; 28+ messages in thread
From: Bagas Sanjaya @ 2021-06-22 5:23 UTC (permalink / raw)
To: Felipe Contreras, git
Cc: Martin Ågren, Ævar Arnfjörð Bjarmason,
Jeff King, Junio C Hamano, brian m . carlson
On 21/06/21 23.31, Felipe Contreras wrote:
> +# Define USE_ASCIIDOCTOR_MANPAGE to use Asciidoctor's manual page backend
> +# instead of building manual pages from DocBook (using xmlto). Has no effect
> +# unless USE_ASCIIDOCTOR is set.
> +#
Why not just USE_ASCIIDOCTOR_MANPAGE implies USE_ASCIIDOCTOR?
--
An old man doll... just what I always wanted! - Clara
^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [PATCH 00/23] doc: cleanups and asciidoctor direct man pages
2021-06-21 16:30 [PATCH 00/23] doc: cleanups and asciidoctor direct man pages Felipe Contreras
` (22 preceding siblings ...)
2021-06-21 16:31 ` [PATCH 23/23] doc: asciidoctor: add hack for old versions Felipe Contreras
@ 2021-06-22 5:35 ` Bagas Sanjaya
2021-06-23 1:37 ` Felipe Contreras
23 siblings, 1 reply; 28+ messages in thread
From: Bagas Sanjaya @ 2021-06-22 5:35 UTC (permalink / raw)
To: Felipe Contreras, git
Cc: Martin Ågren, Ævar Arnfjörð Bjarmason,
Jeff King, Junio C Hamano, brian m . carlson
On 21/06/21 23.30, Felipe Contreras wrote:
> I already sent the first part of this series separately multiple times,
> the last one is 4 simple obviously correct patches [1], but since the
> maintainer has admitted he has no problem ignoring valid work
> entirely due to personal animus [2], I'm sending the whole chain.
>
> There's no point in carefully selecting multiple series of patches to be
> merged one by one when all of them are going to be ignored. So I'm
> sending all 3 series at once.
>
> Hopefully by sending it all at once some people will be able to realize
> that:
>
> 1. They are valid
> 2. They are helpful
> 3. They make the code more maintainable
> 4. They enable new features
> 5. They enable the new features to be easily tested
> 6. They reduce the doc-diff of the new feature, as well as others
> 7. They are superior to the competing series currently in seen
> 8. They include work of multiple contributors
>
> Any fair and impartial maintainer would attempt to pick them up.
>
> Cheers.
>
I think the next step after this patch series is to add asciidoctor
direct man pages generation option to ./configure script (maybe
--enable-asciidoctor-manpage?). But before that, we need to add
--enable-asciidoctor option, which sets USE_ASCIIDOCTOR=YesPlease.
--
An old man doll... just what I always wanted! - Clara
^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [PATCH 15/23] doc: use asciidoctor to build man pages directly
2021-06-22 5:23 ` Bagas Sanjaya
@ 2021-06-23 1:35 ` Felipe Contreras
0 siblings, 0 replies; 28+ messages in thread
From: Felipe Contreras @ 2021-06-23 1:35 UTC (permalink / raw)
To: Bagas Sanjaya, Felipe Contreras, git
Cc: Martin Ågren, Ævar Arnfjörð Bjarmason,
Jeff King, Junio C Hamano, brian m . carlson
Bagas Sanjaya wrote:
> On 21/06/21 23.31, Felipe Contreras wrote:
> > +# Define USE_ASCIIDOCTOR_MANPAGE to use Asciidoctor's manual page backend
> > +# instead of building manual pages from DocBook (using xmlto). Has no effect
> > +# unless USE_ASCIIDOCTOR is set.
> > +#
>
> Why not just USE_ASCIIDOCTOR_MANPAGE implies USE_ASCIIDOCTOR?
Personally I don't see the point of USE_ASCIIDOCTOR_MANPAGE at all. The
only reason I added it was because Martin requested it [1].
It would be nice of you and Martin could make a decision about this, and
I would just implement what you decide (or other people willing to
collaborate on this).
I don't have an opinion on this.
If no decision is reached, I'll make USE_ASCIIDOCTOR_MANPAGE imply
USE_ASCIIDOCTOR as you suggest.
Cheers.
[1] https://lore.kernel.org/git/CAN0heSpX53tK8Z4XSx4sp79b+XWKZg5+ABW8pmzBSHPZ+qy+oQ@mail.gmail.com/
--
Felipe Contreras
^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [PATCH 00/23] doc: cleanups and asciidoctor direct man pages
2021-06-22 5:35 ` [PATCH 00/23] doc: cleanups and asciidoctor direct man pages Bagas Sanjaya
@ 2021-06-23 1:37 ` Felipe Contreras
0 siblings, 0 replies; 28+ messages in thread
From: Felipe Contreras @ 2021-06-23 1:37 UTC (permalink / raw)
To: Bagas Sanjaya, Felipe Contreras, git
Cc: Martin Ågren, Ævar Arnfjörð Bjarmason,
Jeff King, Junio C Hamano, brian m . carlson
Bagas Sanjaya wrote:
> On 21/06/21 23.30, Felipe Contreras wrote:
> > I already sent the first part of this series separately multiple times,
> > the last one is 4 simple obviously correct patches [1], but since the
> > maintainer has admitted he has no problem ignoring valid work
> > entirely due to personal animus [2], I'm sending the whole chain.
> >
> > There's no point in carefully selecting multiple series of patches to be
> > merged one by one when all of them are going to be ignored. So I'm
> > sending all 3 series at once.
> >
> > Hopefully by sending it all at once some people will be able to realize
> > that:
> >
> > 1. They are valid
> > 2. They are helpful
> > 3. They make the code more maintainable
> > 4. They enable new features
> > 5. They enable the new features to be easily tested
> > 6. They reduce the doc-diff of the new feature, as well as others
> > 7. They are superior to the competing series currently in seen
> > 8. They include work of multiple contributors
> >
> > Any fair and impartial maintainer would attempt to pick them up.
> >
> > Cheers.
> >
>
> I think the next step after this patch series is to add asciidoctor
> direct man pages generation option to ./configure script (maybe
> --enable-asciidoctor-manpage?). But before that, we need to add
> --enable-asciidoctor option, which sets USE_ASCIIDOCTOR=YesPlease.
Maybe. I don't use ./configure, so perhaps somebody that does should
take charge of this.
--
Felipe Contreras
^ permalink raw reply [flat|nested] 28+ messages in thread
end of thread, other threads:[~2021-06-23 1:37 UTC | newest]
Thread overview: 28+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-06-21 16:30 [PATCH 00/23] doc: cleanups and asciidoctor direct man pages Felipe Contreras
2021-06-21 16:30 ` [PATCH 01/23] doc: remove GNU troff workaround Felipe Contreras
2021-06-21 16:30 ` [PATCH 02/23] doc: use --stringparam in xmlto Felipe Contreras
2021-06-21 16:30 ` [PATCH 03/23] doc: simplify version passing Felipe Contreras
2021-06-21 16:30 ` [PATCH 04/23] doc: asciidoc: remove unnecessary attribute Felipe Contreras
2021-06-21 16:30 ` [PATCH 05/23] doc: asciidoctor: remove unnecessary require Felipe Contreras
2021-06-21 16:30 ` [PATCH 06/23] doc: asciidoctor: remove cruft Felipe Contreras
2021-06-21 16:30 ` [PATCH 07/23] doc: asciidoctor: reorganize extensions Felipe Contreras
2021-06-21 16:30 ` [PATCH 08/23] doc: asciidoctor: use html-prefix only for html Felipe Contreras
2021-06-21 16:30 ` [PATCH 09/23] doc: asciidoctor: refactor macro registration Felipe Contreras
2021-06-21 16:30 ` [PATCH 10/23] doc: asciidoctor: improve string handling Felipe Contreras
2021-06-21 16:30 ` [PATCH 11/23] doc: asciidoctor: split the format from the code Felipe Contreras
2021-06-21 16:30 ` [PATCH 12/23] doc: asciidoctor: specify name of our group Felipe Contreras
2021-06-21 16:31 ` [PATCH 13/23] doc: doc-diff: set docdate manually Felipe Contreras
2021-06-21 16:31 ` [PATCH 14/23] doc-diff: drop --cut-footer switch Felipe Contreras
2021-06-21 16:31 ` [PATCH 15/23] doc: use asciidoctor to build man pages directly Felipe Contreras
2021-06-22 5:23 ` Bagas Sanjaya
2021-06-23 1:35 ` Felipe Contreras
2021-06-21 16:31 ` [PATCH 16/23] doc-diff: support asciidoctor man pages Felipe Contreras
2021-06-21 16:31 ` [PATCH 17/23] doc: asciidoctor: add linkgit macros in " Felipe Contreras
2021-06-21 16:31 ` [PATCH 18/23] doc: add man pages workaround for asciidoctor Felipe Contreras
2021-06-21 16:31 ` [PATCH 19/23] doc: asciidoctor: add hack for xrefs Felipe Contreras
2021-06-21 16:31 ` [PATCH 20/23] doc: asciidoctor: add hack to improve links Felipe Contreras
2021-06-21 16:31 ` [PATCH 21/23] doc: asciidoctor: add support for baseurl Felipe Contreras
2021-06-21 16:31 ` [PATCH 22/23] doc: asciidoctor: cleanup man page hack Felipe Contreras
2021-06-21 16:31 ` [PATCH 23/23] doc: asciidoctor: add hack for old versions Felipe Contreras
2021-06-22 5:35 ` [PATCH 00/23] doc: cleanups and asciidoctor direct man pages Bagas Sanjaya
2021-06-23 1:37 ` Felipe Contreras
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.