From: Felipe Contreras <hidden> Date: 2021-05-11 22:28:56
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 USE_ASCIIDOCTOR is set.
Suggested-by: Bagas Sanjaya <redacted>
Signed-off-by: Felipe Contreras <redacted>
---
Documentation/Makefile | 8 ++++++++
1 file changed, 8 insertions(+)
From: brian m. carlson <hidden> Date: 2021-05-11 23:27:04
On 2021-05-11 at 22:27:54, Felipe Contreras wrote:
quoted hunk
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 USE_ASCIIDOCTOR is set.
Suggested-by: Bagas Sanjaya <redacted>
Signed-off-by: Felipe Contreras <redacted>
---
Documentation/Makefile | 8 ++++++++
1 file changed, 8 insertions(+)
As I mentioned elsewhere, this breaks the linkgit functionality since we
don't have a patch for the asciidoctor-extensions.rb file and it also
doesn't honor GNU_ROFF, which means that copying and pasting from manual
pages is problematic on systems which use groff.
I'd prefer if we put this behind an option so that just because someone
like me who builds with Asciidoctor doesn't have to get this behavior.
We may by default enable that option if the issues I mentioned above are
addressed, but it would still be nice to have an option to enable the
legacy behavior, if only for those people who may be using older
versions of Asciidoctor.
--
brian m. carlson (he/him or they/them)
Houston, Texas, US
From: Felipe Contreras <hidden> Date: 2021-05-12 00:58:20
brian m. carlson wrote:
On 2021-05-11 at 22:27:54, Felipe Contreras wrote:
quoted
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 USE_ASCIIDOCTOR is set.
Suggested-by: Bagas Sanjaya <redacted>
Signed-off-by: Felipe Contreras <redacted>
---
Documentation/Makefile | 8 ++++++++
1 file changed, 8 insertions(+)
and it also doesn't honor GNU_ROFF, which means that copying and
pasting from manual pages is problematic on systems which use groff.
My system uses groff, I don't see any issues copy-pasting from manual
pages.
How exactly can I reproduce this issue?
I'd prefer if we put this behind an option so that just because someone
like me who builds with Asciidoctor doesn't have to get this behavior.
We may by default enable that option if the issues I mentioned above are
addressed, but it would still be nice to have an option to enable the
legacy behavior, if only for those people who may be using older
versions of Asciidoctor.
Sure, that would be nice, but that's not not an itch I personally have
right now.
At the moment I'm finding too many areas of improvement with the
documentation build system. Perhaps, I'll do this after I've addressed
those. Or somebody else could volunteer.
Cheers.
--
Felipe Contreras
From: brian m. carlson <hidden> Date: 2021-05-12 02:11:51
From: Felipe Contreras <redacted>
Asciidoctor contains a converter to generate man pages. In some
environments, where building only the manual pages and not the other
documentation is desired, installing a toolchain for building
DocBook-based manual pages may be burdensome, and using Asciidoctor
directly may be easier, so let's add an option to build manual pages
using Asciidoctor without the DocBook toolchain.
We generally require Asciidoctor 1.5, but versions before 1.5.3 didn't
contain proper handling of the apostrophe, which is controlled normally
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.
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.
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
still on 1.5. If users are using a more modern toolchain or don't care
about the rendering issues, they can enable the option.
Suggested-by: Bagas Sanjaya <redacted>
Signed-off-by: Felipe Contreras <redacted>
Signed-off-by: brian m. carlson <redacted>
---
I've preserved Felipe's authorship on this patch because much of it is
his work. However, I have made some substantial changes here with which
I suspect he will disagree, in addition to expanding on the commit
message, so if he would prefer, I can reroll with the authorship
changed. I have no preference myself.
Documentation/Makefile | 10 ++++++++++
Documentation/asciidoctor-extensions.rb | 2 ++
Makefile | 3 +++
3 files changed, 15 insertions(+)
@@ -285,6 +285,9 @@ 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.+## Define ASCIIDOCTOR_EXTENSIONS_LAB to point to the location of the Asciidoctor# Extensions Lab if you have it available.#
From: brian m. carlson <hidden> Date: 2021-05-12 02:11:51
By default, groff converts apostrophes in troff source to Unicode
apostrophes. This is helpful and desirable when being used as a
typesetter, since it makes the output much cleaner and more readable,
but it is a problem in manual pages, since apostrophes are often used
around shell commands and these should remain in their ASCII form for
compatibility with the shell.
Fortunately, the DocBook stylesheets contain a workaround for this case:
they detect the special .g number register, which is set only when using
groff, and they define a special macro for apostrophes based on whether
or not it is set and use that macro to write out the proper character.
As a result, the DocBook stylesheets handle all cases correctly
automatically, whether the user is using groff or not, unlike our
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.
---
Documentation/Makefile | 8 --------
Documentation/manpage-quote-apos.xsl | 16 ----------------
2 files changed, 24 deletions(-)
delete mode 100644 Documentation/manpage-quote-apos.xsl
@@ -177,14 +177,6 @@ MAN_BASE_URL = file://$(htmldir)/endifXMLTO_EXTRA+=-mmanpage-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+=-mmanpage-quote-apos.xsl-endif-ifdef USE_ASCIIDOCTORASCIIDOC=asciidoctorASCIIDOC_CONF=
@@ -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>
From: Eric Sunshine <hidden> Date: 2021-05-12 02:19:10
On Tue, May 11, 2021 at 10:11 PM brian m. carlson
[off-list ref] wrote:
By default, groff converts apostrophes in troff source to Unicode
apostrophes. This is helpful and desirable when being used as a
typesetter, since it makes the output much cleaner and more readable,
but it is a problem in manual pages, since apostrophes are often used
around shell commands and these should remain in their ASCII form for
compatibility with the shell.
Fortunately, the DocBook stylesheets contain a workaround for this case:
they detect the special .g number register, which is set only when using
groff, and they define a special macro for apostrophes based on whether
or not it is set and use that macro to write out the proper character.
As a result, the DocBook stylesheets handle all cases correctly
automatically, whether the user is using groff or not, unlike our
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.
---
From: brian m. carlson <hidden> Date: 2021-05-12 02:28:18
On 2021-05-12 at 02:18:54, Eric Sunshine wrote:
On Tue, May 11, 2021 at 10:11 PM brian m. carlson
[off-list ref] wrote:
quoted
By default, groff converts apostrophes in troff source to Unicode
apostrophes. This is helpful and desirable when being used as a
typesetter, since it makes the output much cleaner and more readable,
but it is a problem in manual pages, since apostrophes are often used
around shell commands and these should remain in their ASCII form for
compatibility with the shell.
Fortunately, the DocBook stylesheets contain a workaround for this case:
they detect the special .g number register, which is set only when using
groff, and they define a special macro for apostrophes based on whether
or not it is set and use that macro to write out the proper character.
As a result, the DocBook stylesheets handle all cases correctly
automatically, whether the user is using groff or not, unlike our
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.
---
Missing sign-off.
Thanks. I'll add it below and if I do a reroll, I'll send out a fixed
patch.
Signed-off-by: brian m. carlson <redacted>
--
brian m. carlson (he/him or they/them)
Houston, Texas, US
From: Felipe Contreras <hidden> Date: 2021-05-12 04:46:01
brian m. carlson wrote:
By default, groff converts apostrophes in troff source to Unicode
apostrophes. This is helpful and desirable when being used as a
typesetter, since it makes the output much cleaner and more readable,
but it is a problem in manual pages, since apostrophes are often used
around shell commands and these should remain in their ASCII form for
compatibility with the shell.
Fortunately, the DocBook stylesheets contain a workaround for this case:
they detect the special .g number register, which is set only when using
groff, and they define a special macro for apostrophes based on whether
or not it is set and use that macro to write out the proper character.
As a result, the DocBook stylesheets handle all cases correctly
automatically, whether the user is using groff or not, unlike our
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.
I'm not sure of all that, but my machine uses Arch Linux, it ships with
groff, I've never used GNU_ROFF=1, and I can copy text with apostrophes
from the genrated man pages just fine.
So this is probably fine.
--
Felipe Contreras
From: brian m. carlson <hidden> Date: 2021-05-14 00:12:00
On 2021-05-12 at 04:45:53, Felipe Contreras wrote:
brian m. carlson wrote:
quoted
By default, groff converts apostrophes in troff source to Unicode
apostrophes. This is helpful and desirable when being used as a
typesetter, since it makes the output much cleaner and more readable,
but it is a problem in manual pages, since apostrophes are often used
around shell commands and these should remain in their ASCII form for
compatibility with the shell.
Fortunately, the DocBook stylesheets contain a workaround for this case:
they detect the special .g number register, which is set only when using
groff, and they define a special macro for apostrophes based on whether
or not it is set and use that macro to write out the proper character.
As a result, the DocBook stylesheets handle all cases correctly
automatically, whether the user is using groff or not, unlike our
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.
I'm not sure of all that, but my machine uses Arch Linux, it ships with
groff, I've never used GNU_ROFF=1, and I can copy text with apostrophes
from the genrated man pages just fine.
I'll rephrase to be clearer. Solaris 10 is still security supported,
but no major Linux distro is, and I think we'll be both be fine dropping
support for OSes shipped in 2005.
I'm glad to hear confirmation that things work for you, though.
--
brian m. carlson (he/him or they/them)
Houston, Texas, US
From: Felipe Contreras <hidden> Date: 2021-05-15 13:30:29
brian m. carlson wrote:
On 2021-05-12 at 04:45:53, Felipe Contreras wrote:
quoted
I'm not sure of all that, but my machine uses Arch Linux, it ships with
groff, I've never used GNU_ROFF=1, and I can copy text with apostrophes
from the genrated man pages just fine.
I'll rephrase to be clearer. Solaris 10 is still security supported,
but no major Linux distro is, and I think we'll be both be fine dropping
support for OSes shipped in 2005.
I'm glad to hear confirmation that things work for you, though.
I took at deep-dive and it turns Arch Linux configures groff to convert
\' to ', so even if git was doing something wrong, I wouldn't have
noticed.
Docbook fixed their problem in 2010, and I just sent a patch for
asciidoctor to properly fix their code as well. It should work on groff
though.
The configuration is in: `/usr/share/groff/site-tmac/man.local`, if you
want to check what your system is doing.
Cheers.
--
Felipe Contreras
From: Martin Ågren <hidden> Date: 2021-05-13 13:12:00
On Wed, 12 May 2021 at 04:11, brian m. carlson
[off-list ref] wrote:
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.
---
Documentation/Makefile | 8 --------
Documentation/manpage-quote-apos.xsl | 16 ----------------
2 files changed, 24 deletions(-)
Thanks for dropping this cruft. There's a blurb about GNU_ROFF in the
top-level Makefile as well. We should lose it here.
Martin
From: Felipe Contreras <redacted>
Asciidoctor contains a converter to generate man pages. In some
environments, where building only the manual pages and not the other
documentation is desired, installing a toolchain for building
DocBook-based manual pages may be burdensome, and using Asciidoctor
directly may be easier, so let's add an option to build manual pages
using Asciidoctor without the DocBook toolchain.
I have concern: I currently generate manpages with Asciidoctor+xmlto. Does
this change affects people using xmlto?
We generally require Asciidoctor 1.5, but versions before 1.5.3 didn't
contain proper handling of the apostrophe, which is controlled normally
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.
At what version of Asciidoctor the apostrophe handling is corrected?
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.
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
still on 1.5. If users are using a more modern toolchain or don't care
about the rendering issues, they can enable the option.
Maybe when distros upgraded shipped Asciidoctor version to 2.0, we can
bump the version requirement.
quoted hunk
Suggested-by: Bagas Sanjaya <redacted>
Signed-off-by: Felipe Contreras <redacted>
Signed-off-by: brian m. carlson <redacted>
---
I've preserved Felipe's authorship on this patch because much of it is
his work. However, I have made some substantial changes here with which
I suspect he will disagree, in addition to expanding on the commit
message, so if he would prefer, I can reroll with the authorship
changed. I have no preference myself.
Documentation/Makefile | 10 ++++++++++
Documentation/asciidoctor-extensions.rb | 2 ++
Makefile | 3 +++
3 files changed, 15 insertions(+)
@@ -285,6 +285,9 @@ 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.+#
The wording should be "...instead of building manual pages from DocBook with
xmlto".
# Define ASCIIDOCTOR_EXTENSIONS_LAB to point to the location of the Asciidoctor
# Extensions Lab if you have it available.
#
Thanks for my review.
--
An old man doll... just what I always wanted! - Clara
From: Felipe Contreras <hidden> Date: 2021-05-12 05:03:17
Bagas Sanjaya wrote:
On 12/05/21 09.11, brian m. carlson wrote:
quoted
From: Felipe Contreras <redacted>
Asciidoctor contains a converter to generate man pages. In some
environments, where building only the manual pages and not the other
documentation is desired, installing a toolchain for building
DocBook-based manual pages may be burdensome, and using Asciidoctor
directly may be easier, so let's add an option to build manual pages
using Asciidoctor without the DocBook toolchain.
I have concern: I currently generate manpages with Asciidoctor+xmlto. Does
this change affects people using xmlto?
His proposed change: no, but mine does.
quoted
We generally require Asciidoctor 1.5, but versions before 1.5.3 didn't
contain proper handling of the apostrophe, which is controlled normally
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.
At what version of Asciidoctor the apostrophe handling is corrected?
I will look into this, but in my opinion it's not worth complicating the
doc toolchain for ancient distributions.
The only time people are going to notice something is when:
1. They build git with USE_ASCIIDOCTOR=YesPlease
USE_ASCIIDOCTOR_MANPAGE=YesPlease
2. They use an ancient distribution
3. They use the ancient distribution's asciidoctor packages, instead of
Ruby's asciidoctor gem
4. They open a manpage generated by this process
5. They select text that specifically has an apostrophe
6. They copy this text
7. They paste this text somewhere else
Then, they *might* see some issue.
Yeah, let's not worry about about this *too much*.
quoted
Suggested-by: Bagas Sanjaya <redacted>
Signed-off-by: Felipe Contreras <redacted>
Signed-off-by: brian m. carlson <redacted>
---
I've preserved Felipe's authorship on this patch because much of it is
his work. However, I have made some substantial changes here with which
I suspect he will disagree, in addition to expanding on the commit
message, so if he would prefer, I can reroll with the authorship
changed. I have no preference myself.
Documentation/Makefile | 10 ++++++++++
Documentation/asciidoctor-extensions.rb | 2 ++
Makefile | 3 +++
3 files changed, 15 insertions(+)
I think "ASCIIDOCTOR_TO_MAN" would be good alternative name here, since
this command generates manpage from asciidoctor.
All the current TXT_TO_* definitions use asciidoc.
Moreover, I'm currently working on some cleanup patches to make
TXT_TO_MAN work with asciidoc + xmlto, so this is future-proof.
quoted
--- a/Makefile+++ b/Makefile
@@ -285,6 +285,9 @@ 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.+#
The wording should be "...instead of building manual pages from DocBook with
xmlto".
That's why in my opinion it should be the other way around:
USE_ASCIIDOCTOR_XMLTO=No.
Then the expalantion is not even needed, because you can deduce it from
the name of the configuration variable.
Cheers.
--
Felipe Contreras
From: brian m. carlson <hidden> Date: 2021-05-13 23:24:56
On 2021-05-12 at 02:48:59, Bagas Sanjaya wrote:
On 12/05/21 09.11, brian m. carlson wrote:
quoted
From: Felipe Contreras <redacted>
Asciidoctor contains a converter to generate man pages. In some
environments, where building only the manual pages and not the other
documentation is desired, installing a toolchain for building
DocBook-based manual pages may be burdensome, and using Asciidoctor
directly may be easier, so let's add an option to build manual pages
using Asciidoctor without the DocBook toolchain.
I have concern: I currently generate manpages with Asciidoctor+xmlto. Does
this change affects people using xmlto?
This change adds an option to allow not using xmlto at all but instead
using just Asciidoctor to generate manual pages. If you do nothing,
you'll continue to use xmlto as before.
quoted
We generally require Asciidoctor 1.5, but versions before 1.5.3 didn't
contain proper handling of the apostrophe, which is controlled normally
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.
At what version of Asciidoctor the apostrophe handling is corrected?
The first released version is 1.5.3.
quoted
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.
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
still on 1.5. If users are using a more modern toolchain or don't care
about the rendering issues, they can enable the option.
Maybe when distros upgraded shipped Asciidoctor version to 2.0, we can
bump the version requirement.
My general policy, which need not be Git's policy (but I think is
reasonable), is that I will support the previous version of Debian and
Ubuntu LTS for a year after the new one comes out. Under that policy,
we'd wait until a year after Debian 11 (bullseye) is released.
@@ -285,6 +285,9 @@ 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.+#
The wording should be "...instead of building manual pages from DocBook with
xmlto".
I can make that change. We're not using DocBook either way, with xmlto
or other tooling (e.g., a plain xsltproc), so what we have here is
accurate.
--
brian m. carlson (he/him or they/them)
Houston, Texas, US
From: Felipe Contreras <hidden> Date: 2021-05-14 12:58:11
brian m. carlson wrote:
On 2021-05-12 at 02:48:59, Bagas Sanjaya wrote:
quoted
Maybe when distros upgraded shipped Asciidoctor version to 2.0, we can
bump the version requirement.
My general policy, which need not be Git's policy (but I think is
reasonable), is that I will support the previous version of Debian and
Ubuntu LTS for a year after the new one comes out. Under that policy,
we'd wait until a year after Debian 11 (bullseye) is released.
Under that policy the supported version would be Debian 10 (buster),
which ships with Ruby 2.5. It's more than capable of running
asciidoctor.
The CI of asciidoctor tests versionof Ruby as old as 2.3, so Debian 10
is safe.
In fact, I would bet you that asciidoctor works fine in Ruby 2.1 shipped
with Debian 8 (jessie) released in 2015. Maybe users of Debian 7 would
have trouble... *maybe*... It's hard to tell because Debian doesn't
even provide package information about that release.
@@ -285,6 +285,9 @@ 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.+#
The wording should be "...instead of building manual pages from DocBook with
xmlto".
I can make that change. We're not using DocBook either way, with xmlto
or other tooling (e.g., a plain xsltproc), so what we have here is
accurate.
From: Felipe Contreras <hidden> Date: 2021-05-15 13:26:02
brian m. carlson wrote:
On 2021-05-12 at 02:48:59, Bagas Sanjaya wrote:
quoted
On 12/05/21 09.11, brian m. carlson wrote:
quoted
We generally require Asciidoctor 1.5, but versions before 1.5.3 didn't
contain proper handling of the apostrophe, which is controlled normally
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.
At what version of Asciidoctor the apostrophe handling is corrected?
The first released version is 1.5.3.
I just went ahead to check that, and from the very first commit [1]
asciidoctor generated quotes compatible with groff:
git filter\-branch \-\-tree\-filter \(aqrm filename\(aq HEAD
So it has *always* worked.
You can see it from the code:
gsub('\'', '\\(aq'). # apostrophe-quote
In fact, they never changed that, so it should fail in Solaris, or
anything that doesn't use groff.
I've sent them a fix [2].
What are these "newever versions" that do the right thing in all cases?
[1] https://github.com/asciidoctor/asciidoctor/commit/7bddc416c92ff9d16c721b03bda7ed80c1e4c45f
[2] https://github.com/asciidoctor/asciidoctor/pull/4060
--
Felipe Contreras
From: Felipe Contreras <hidden> Date: 2021-05-12 04:41:51
brian m. carlson wrote:
From: Felipe Contreras <redacted>
Asciidoctor contains a converter to generate man pages. In some
environments, where building only the manual pages and not the other
documentation is desired, installing a toolchain for building
DocBook-based manual pages may be burdensome, and using Asciidoctor
directly may be easier, so let's add an option to build manual pages
using Asciidoctor without the DocBook toolchain.
We generally require Asciidoctor 1.5, but versions before 1.5.3 didn't
contain proper handling of the apostrophe, which is controlled normally
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.
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.
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 > still on 1.5.
Are "some common distros" namely Debian stable *exclusively*?
If so, I would consider flipping the default the other way around,
espececially since it's only te default shipped by the Debian stable
packages (easily fixed by `gem install asciidoctor`).
If users are using a more modern toolchain or don't care
about the rendering issues, they can enable the option.
The other way around: if users are using an ancient distribution they
can disable the option.
Suggested-by: Bagas Sanjaya <redacted>
Signed-off-by: Felipe Contreras <redacted>
Signed-off-by: brian m. carlson <redacted>
Commit-message-by: brian m. carlson [off-list ref]
I certainly would not want to pretend to have written the text above.
---
I've preserved Felipe's authorship on this patch because much of it is
his work. However, I have made some substantial changes here with which
I suspect he will disagree, in addition to expanding on the commit
message, so if he would prefer, I can reroll with the authorship
changed. I have no preference myself.
Hard to tell in this frankenstein commit. I'd be fine with a
Commit-message-by line.
I still prefer my original version, especially since:
1. I suspect most git developers are familiar with printf directives:
%s.
2. Where is that \\fP coming from? I don't see that with xmlto, nor the
publicly genrated man pages[1].
3. Doesn't work on my machine without my original \e; I see
"\fBgittutorial\fR(7)".
I don't see any way this is an improvement.
Cheers.
[1] https://git.kernel.org/pub/scm/git/git-manpages.git/tree/man1/git.1
--
Felipe Contreras
From: brian m. carlson <hidden> Date: 2021-05-13 23:38:39
On 2021-05-12 at 04:41:41, Felipe Contreras wrote:
brian m. carlson wrote:
quoted
From: Felipe Contreras <redacted>
Asciidoctor contains a converter to generate man pages. In some
environments, where building only the manual pages and not the other
documentation is desired, installing a toolchain for building
DocBook-based manual pages may be burdensome, and using Asciidoctor
directly may be easier, so let's add an option to build manual pages
using Asciidoctor without the DocBook toolchain.
We generally require Asciidoctor 1.5, but versions before 1.5.3 didn't
contain proper handling of the apostrophe, which is controlled normally
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.
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.
Because Asciidoctor versions before 2.0 had a few problems with man page
output, let's default this to off for now,
quoted
since some common distros are > still on 1.5.
Are "some common distros" namely Debian stable *exclusively*?
If so, I would consider flipping the default the other way around,
espececially since it's only te default shipped by the Debian stable
packages (easily fixed by `gem install asciidoctor`).
CentOS 7 and Ubuntu 18.04 also ship 1.5. CentOS 8 does not appear to
ship Asciidoctor at all.
quoted
If users are using a more modern toolchain or don't care
about the rendering issues, they can enable the option.
The other way around: if users are using an ancient distribution they
can disable the option.
Debian stable is not ancient. It is less than two years old, which for
a Linux distro or any operating system distribution, is not at all
considered even reasonably old.
I am not going to propose or give my approval to a change that causes
problems building Git with the distro packages on Debian stable or the
latest Ubuntu LTS, in any way, shape, or form. People should be able to
use the distro packages if that's most convenient.
quoted
Suggested-by: Bagas Sanjaya <redacted>
Signed-off-by: Felipe Contreras <redacted>
Signed-off-by: brian m. carlson <redacted>
Commit-message-by: brian m. carlson [off-list ref]
I certainly would not want to pretend to have written the text above.
I still prefer my original version, especially since:
1. I suspect most git developers are familiar with printf directives:
%s.
2. Where is that \\fP coming from? I don't see that with xmlto, nor the
publicly genrated man pages[1].
That's coming from my knowledge of troff, having used it extensively
over the years, and my general hesitance to affect global state.
3. Doesn't work on my machine without my original \e; I see
"\fBgittutorial\fR(7)".
Works just fine on my system using Asciidoctor 2.0.12. The \e would
insert an additional escape character and shouldn't be needed unless
we're in copy mode (which we should not be here).
--
brian m. carlson (he/him or they/them)
Houston, Texas, US
From: Felipe Contreras <hidden> Date: 2021-05-14 19:03:07
brian m. carlson wrote:
On 2021-05-12 at 04:41:41, Felipe Contreras wrote:
quoted
brian m. carlson wrote:
quoted
since some common distros are > still on 1.5.
Are "some common distros" namely Debian stable *exclusively*?
If so, I would consider flipping the default the other way around,
espececially since it's only te default shipped by the Debian stable
packages (easily fixed by `gem install asciidoctor`).
CentOS 7 and Ubuntu 18.04 also ship 1.5. CentOS 8 does not appear to
ship Asciidoctor at all.
I does not matter what version of asciidoctor they *ship* with.... At all.
I happen to have accesss to an Ubuntu 18.04 machine...
time gem install --user-install asciidoctor
real 0m3.179s
It took me 3 seconds to get asciidoctor-2.0.15.
Ubuntu 18.04 ships with ruby 2.5.1p57 (2018-03-29 revision 63029). And
that's all you need.
quoted
quoted
If users are using a more modern toolchain or don't care
about the rendering issues, they can enable the option.
The other way around: if users are using an ancient distribution they
can disable the option.
Debian stable is not ancient. It is less than two years old, which for
a Linux distro or any operating system distribution, is not at all
considered even reasonably old.
I guess your definition of what's "old" and mine are *very* different.
But the problem doesn't come from when the distribution was released,
but when the packages *inside* the distribution were released.
I am not going to propose or give my approval to a change that causes
problems building Git with the distro packages on Debian stable or the
latest Ubuntu LTS, in any way, shape, or form. People should be able to
use the distro packages if that's most convenient.
My proposed changes do not cause any problems building Git with any
distro package on Debian stable or the latest Ubuntu LTS in any way,
shape or form.
quoted
quoted
Suggested-by: Bagas Sanjaya <redacted>
Signed-off-by: Felipe Contreras <redacted>
Signed-off-by: brian m. carlson <redacted>
Commit-message-by: brian m. carlson [off-list ref]
I certainly would not want to pretend to have written the text above.
I still prefer my original version, especially since:
1. I suspect most git developers are familiar with printf directives:
%s.
2. Where is that \\fP coming from? I don't see that with xmlto, nor the
publicly genrated man pages[1].
That's coming from my knowledge of troff, having used it extensively
over the years, and my general hesitance to affect global state.
Good. Send it as a *separate* patch.
Most people in the mailing list are trying to **minimize** the diff
between asciidoc+docbook and asciidoctor, not piggyback improvements.
If you want to flex your troff knowledge do it as a separate patch,
without my authorship, or s-o-b line.
quoted
3. Doesn't work on my machine without my original \e; I see
"\fBgittutorial\fR(7)".
Works just fine on my system using Asciidoctor 2.0.12. The \e would
insert an additional escape character and shouldn't be needed unless
we're in copy mode (which we should not be here).
I fail to see how that could work since asciidoctor replaces '\'
with '\(rs'.
This is a simple test that reproduces the issue:
ruby -r asciidoctor <<\EOF | groff -Tascii -man | less
puts Asciidoctor.convert("This is a \\fBtest\\fR.", backend: :manpage)
EOF
Those that work in your machine?
This happens both with v2.0.12 and the latest master (2.0.16.dev).
Cheers.
--
Felipe Contreras
Another review below.
On 12/05/21 09.11, brian m. carlson wrote:
From: Felipe Contreras <redacted>
quoted
Asciidoctor contains a converter to generate man pages. In some
environments, where building only the manual pages and not the other
documentation is desired, installing a toolchain for building
DocBook-based manual pages may be burdensome, and using Asciidoctor
directly may be easier, so let's add an option to build manual pages
using Asciidoctor without the DocBook toolchain.
quoted
We generally require Asciidoctor 1.5, but versions before 1.5.3 didn't
contain proper handling of the apostrophe, which is controlled normally
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.
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.
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
still on 1.5. If users are using a more modern toolchain or don't care
about the rendering issues, they can enable the option.
Suggested-by: Bagas Sanjaya <redacted>
Signed-off-by: Felipe Contreras <redacted>
Signed-off-by: brian m. carlson <redacted>
---
It is customary for multi-patches patch series to have a cover letter.
For example, when I send a patch that add corrections to an existing
patch series, I can add permalink of that series' cover letter to be
clear that my patch is applied on top of another patch series.
@@ -285,6 +285,9 @@ 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.+#
Does USE_ASCIIDOCTOR_MANPAGE imply USE_ASCIIDOCTOR?
# Define ASCIIDOCTOR_EXTENSIONS_LAB to point to the location of the Asciidoctor
# Extensions Lab if you have it available.
#
Thanks.
--
An old man doll... just what I always wanted! - Clara
From: brian m. carlson <hidden> Date: 2021-05-13 23:54:42
On 2021-05-12 at 04:43:14, Bagas Sanjaya wrote:
It is customary for multi-patches patch series to have a cover letter.
For example, when I send a patch that add corrections to an existing
patch series, I can add permalink of that series' cover letter to be
clear that my patch is applied on top of another patch series.
I often send one, but I didn't think one was necessary in this case.
I'll send one for v2, since I need to reroll.
@@ -285,6 +285,9 @@ 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.+#
Does USE_ASCIIDOCTOR_MANPAGE imply USE_ASCIIDOCTOR?
It does not, any more than ASCIIDOCTOR_EXTENSIONS_LAB implies that. I
will update the documentation.
--
brian m. carlson (he/him or they/them)
Houston, Texas, US
This depends on GIT-ASCIIDOCFLAGS, which is good. But I think we'd also
want to tell that file whether we are using the direct backend or not.
Otherwise, doing:
make USE_ASCIIDOCTOR=1 git.1
make USE_ASCIIDOCTOR=1 USE_ASCIIDOCTOR_MANPAGE=1 git.1
gets confused. Because git.1 is more recent than git.txt, it things
there is nothing to build in the second case. I think you want:
Unfortunately, this doesn't seem to work. Diffing the rendered docs
between regular asciidoctor-then-xmlto and direct-to-manpage shows a lot
of hunks like:
For more details about the <pathspec> syntax, see the pathspec
- entry in gitglossary(7).
+ entry in \fBgitglossary\fP\fR(7)\fP.
-Peff
From: Jeff King <hidden> Date: 2021-05-12 06:30:27
On Wed, May 12, 2021 at 02:22:06AM -0400, Jeff King wrote:
With that change, plus a patch I'll send in a minute, it's easy to run
doc-diff on the result.
And here that is (note that if you don't apply the flags fix I showed,
then doc-diff gets confused, because it expects back-to-back runs of
"make" to handle the changed flags correctly).
Feel free to add it to your series if it helps (I had originally thought
it would just be a one-off to look at the output, but there are enough
changes, both correctness and style, that it may be useful to have this
option around).
-- >8 --
Subject: [PATCH] doc-diff: support --asciidoctor-direct mode
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
Note that we have to add quotes when passing around $makemanflags, as it
now may contain whitespace due to multiple arguments (but the deference
inside render_tree must remain unquoted, because it wants to perform
whitespace splitting to get the individual arguments back).
Signed-off-by: Jeff King <redacted>
---
Documentation/doc-diff | 18 ++++++++++++++++--
1 file changed, 16 insertions(+), 2 deletions(-)
@@ -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 cut-footer cut away footer " SUBDIRECTORY_OK=1
From: Jeff King <hidden> Date: 2021-05-12 06:59:38
On Wed, May 12, 2021 at 02:30:20AM -0400, Jeff King wrote:
On Wed, May 12, 2021 at 02:22:06AM -0400, Jeff King wrote:
quoted
With that change, plus a patch I'll send in a minute, it's easy to run
doc-diff on the result.
And here that is (note that if you don't apply the flags fix I showed,
then doc-diff gets confused, because it expects back-to-back runs of
"make" to handle the changed flags correctly).
Feel free to add it to your series if it helps (I had originally thought
it would just be a one-off to look at the output, but there are enough
changes, both correctness and style, that it may be useful to have this
option around).
Adding in the "\e" to the extensions string fixes many problems. Just
skimming over the remaining changes (from asciidoctor+xmlto to
asciidoctor direct), here are some things I see:
Both of the xmlto pipelines seem to insert extra space before a literal.
The direct version fixes that. E.g.:
- Files to add content from. Fileglobs (e.g. *.c) can be given to
[...]
+ Files to add content from. Fileglobs (e.g. *.c) can be given to add
So that's good. But what you can't see in the doc-diff rendered version
is that we've lost the bolding on literals (this is from the <pathspec>
option in git-add.1).
Another is that the direct version is less willing to break linkgit
targets across lines:
- explained for the configuration variable core.quotePath (see git-
- config(1)). See also --pathspec-file-nul and global
+ explained for the configuration variable core.quotePath (see
+ git-config(1)). See also --pathspec-file-nul and global
That seems fine to me, though it unfortunately does make the diff quite
noisy.
We seem to have a problem with some escape codes. E.g.:
- 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
and:
- Added content is represented by lines beginning with "+". You can
- prevent staging any addition lines by deleting them.
+ Added content is represented by lines beginning with "+". You
+ can prevent staging any addition lines by deleting them.
which is a pretty bad regression.
The trailer misses the version field:
-Git omitted 1970-01-01 GIT-ADD(1)
+Git 1970-01-01 GIT-ADD(1)
The "omitted" is part of doc-diff's attempt to reduce noise in the
diff. But you can see that it's missing entirely in the direct version.
There are lots of whitespace changes for lists. They mostly seem fine
either way. It also formats numbered lists differently:
- 1. Delete the remote-tracking branches "todo", "html" and
+ (1) Delete the remote-tracking branches "todo", "html" and
"man". The next fetch or pull will create them again
unless you configure them not to. See git-fetch(1).
- 2. Delete the "test" branch even if the "master" branch (or
+ (2) Delete the "test" branch even if the "master" branch (or
whichever branch is currently checked out) does not have
all commits from the test branch.
I prefer the original, but could live with the latter (IIRC, this is
something that can be configured via asciidoctor, but I didn't dig).
This one is quite curious (from gitworkflows(7)):
- Example 1. Merge upwards
+ Rule: Merge upwards
The source looks like this:
.Merge upwards
[caption="Rule: "]
So it looks like it takes the caption, rather than the phrase "example"
that I guess is coming from deep within the bowls of docbook. Both
asciidoc and asciidoctor produce the "Example" text when going through
xmlto, but both produce "Rule" when generating HTML. So I imagine the
latter was the intent, and this is a fix.
Links are a bit harder to read. E.g.:
SEE ALSO
git-check-ref-format(1), git-fetch(1), git-remote(1), “Understanding
- history: What is a branch?”[1] in the Git User’s Manual.
+ history: What is <user-manual.html#what-is-a-branch> a branch?”" in the
+ Git User’s Manual.
There may be more lurking, but it's hard to tell given how noisy the
diff is.
-Peff
From: Felipe Contreras <hidden> Date: 2021-05-12 20:36:41
Jeff King wrote:
We seem to have a problem with some escape codes. E.g.:
- 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
and:
- Added content is represented by lines beginning with "+". You can
- prevent staging any addition lines by deleting them.
+ Added content is represented by lines beginning with "+". You
+ can prevent staging any addition lines by deleting them.
which is a pretty bad regression.
Is it? At leat in my system both are rendered correctly.
The trailer misses the version field:
-Git omitted 1970-01-01 GIT-ADD(1)
+Git 1970-01-01 GIT-ADD(1)
The "omitted" is part of doc-diff's attempt to reduce noise in the
diff. But you can see that it's missing entirely in the direct version.
This is indeed a limitation of asciidoctor: manversion is ignored.
I have a fix for that. I'll send it to the asciidoctor project.
There are lots of whitespace changes for lists. They mostly seem fine
either way. It also formats numbered lists differently:
- 1. Delete the remote-tracking branches "todo", "html" and
+ (1) Delete the remote-tracking branches "todo", "html" and
"man". The next fetch or pull will create them again
unless you configure them not to. See git-fetch(1).
- 2. Delete the "test" branch even if the "master" branch (or
+ (2) Delete the "test" branch even if the "master" branch (or
whichever branch is currently checked out) does not have
all commits from the test branch.
I prefer the original, but could live with the latter (IIRC, this is
something that can be configured via asciidoctor, but I didn't dig).
It is not a numbered list, it is a reference. I actually prefer the (n)
version.
Links are a bit harder to read. E.g.:
SEE ALSO
git-check-ref-format(1), git-fetch(1), git-remote(1), “Understanding
- history: What is a branch?”[1] in the Git User’s Manual.
+ history: What is <user-manual.html#what-is-a-branch> a branch?”" in the
+ Git User’s Manual.
That indeed looks weird. I'm not exactly sure how to fix that properly.
--
Felipe Contreras
From: Martin Ågren <hidden> Date: 2021-05-13 17:30:28
On Wed, 12 May 2021 at 08:59, Jeff King [off-list ref] wrote:
We seem to have a problem with some escape codes. E.g.:
- 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
and:
- Added content is represented by lines beginning with "+". You can
- prevent staging any addition lines by deleting them.
+ Added content is represented by lines beginning with "+". You
+ can prevent staging any addition lines by deleting them.
which is a pretty bad regression.
ASCIIDOC_EXTRA += -aplus='+'
ASCIIDOC_EXTRA += -alitdd='\--'
seems to have done the trick for me at one point, but Todd had some
concerns [1] that it interacted badly with the html build, so we might
need to use a less aggressive choice of makefile variable to only affect
the direct manpage generation.
[1] https://lore.kernel.org/git/20190323192756.GK4047@pobox.com/
Martin
From: Felipe Contreras <hidden> Date: 2021-05-13 22:37:21
Martin Ågren wrote:
On Wed, 12 May 2021 at 08:59, Jeff King [off-list ref] wrote:
quoted
We seem to have a problem with some escape codes. E.g.:
- 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
and:
- Added content is represented by lines beginning with "+". You can
- prevent staging any addition lines by deleting them.
+ Added content is represented by lines beginning with "+". You
+ can prevent staging any addition lines by deleting them.
which is a pretty bad regression.
ASCIIDOC_EXTRA += -aplus='+'
ASCIIDOC_EXTRA += -alitdd='\--'
seems to have done the trick for me at one point, but Todd had some
concerns [1] that it interacted badly with the html build, so we might
need to use a less aggressive choice of makefile variable to only affect
the direct manpage generation.
I don't see a point of complicating the Makefile more if we are already
passing `-r ourstuff.rb`.
One advantage of Ruby is that everything can be overriden, so we can
override the initialization of the Document object:
module Asciidoctor
class Document
alias old_initialize initialize
def initialize(data = nil, options = {})
attributes = options[:attributes]
case attributes['backend']
when 'manpage'
attributes['litdd'] = '\--'
attributes['plus'] = '+'
when 'xhtml5'
attributes['litdd'] = '--'
end
old_initialize(data, options)
end
end
end
This does the trick for me for both backends, and it simplifies the
Makefile.
However, it's a hack for what seems to be a bug in asciidoctor. I'll
report the issue.
Cheers.
--
Felipe Contreras
From: Eric Sunshine <hidden> Date: 2021-05-12 20:45:24
On Wed, May 12, 2021 at 2:30 AM Jeff King [off-list ref] wrote:
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
Note that we have to add quotes when passing around $makemanflags, as it
now may contain whitespace due to multiple arguments (but the deference
I suppose you meant s/deference/dereference/ ?
inside render_tree must remain unquoted, because it wants to perform
whitespace splitting to get the individual arguments back).
Signed-off-by: Jeff King <redacted>
From: Jeff King <hidden> Date: 2021-05-12 23:28:01
On Wed, May 12, 2021 at 03:53:09PM -0400, Eric Sunshine wrote:
On Wed, May 12, 2021 at 2:30 AM Jeff King [off-list ref] wrote:
quoted
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
Note that we have to add quotes when passing around $makemanflags, as it
now may contain whitespace due to multiple arguments (but the deference
From: Martin Ågren <hidden> Date: 2021-05-14 15:35:11
On Wed, 12 May 2021 at 08:30, Jeff King [off-list ref] wrote:
On Wed, May 12, 2021 at 02:22:06AM -0400, Jeff King wrote:
quoted
With that change, plus a patch I'll send in a minute, it's easy to run
doc-diff on the result.
Feel free to add it to your series if it helps (I had originally thought
it would just be a one-off to look at the output, but there are enough
changes, both correctness and style, that it may be useful to have this
option around).
I agree that this would be useful to have longer-term.
-- >8 --
Subject: [PATCH] doc-diff: support --asciidoctor-direct mode
From: brian m. carlson <hidden> Date: 2021-05-14 00:31:15
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 [off-list ref]
+Author: brian m. carlson [off-list ref]
## 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 [off-list ref]
## 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 [off-list ref]
@@ 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.
+ #
From: brian m. carlson <hidden> Date: 2021-05-14 00:31:15
Asciidoctor contains a converter to generate man pages. In some
environments, where building only the manual pages and not the other
documentation is desired, installing a toolchain for building
DocBook-based manual pages may be burdensome, and using Asciidoctor
directly may be easier, so let's add an option to build manual pages
using Asciidoctor without the DocBook toolchain.
We generally require Asciidoctor 1.5, but versions before 1.5.3 didn't
contain proper handling of the apostrophe, which is controlled normally
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 (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. 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
still on 1.5. If users are using a more modern toolchain or don't care
about the rendering issues, they can enable the option.
Suggested-by: Bagas Sanjaya <redacted>
Signed-off-by: Felipe Contreras <redacted>
Signed-off-by: brian m. carlson <redacted>
---
Documentation/Makefile | 17 +++++++++++++++--
Documentation/asciidoctor-extensions.rb | 2 ++
Makefile | 4 ++++
3 files changed, 21 insertions(+), 2 deletions(-)
@@ -285,6 +285,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.#
From: Felipe Contreras <hidden> Date: 2021-05-14 19:53:18
brian m. carlson wrote:
Asciidoctor contains a converter to generate man pages. In some
environments, where building only the manual pages and not the other
documentation is desired, installing a toolchain for building
DocBook-based manual pages may be burdensome, and using Asciidoctor
directly may be easier, so let's add an option to build manual pages
using Asciidoctor without the DocBook toolchain.
We generally require Asciidoctor 1.5, but versions before 1.5.3 didn't
contain proper handling of the apostrophe, which is controlled normally
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 (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.
I don't see what that paragraph has to do with the patch below.
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.
Yes, but why shove it in this patch? Now this is is doing *two*
logically-independent changes.
Be careful to reset the font to the previous after the change.
This is a third change, since the current man pages already don't do
this:
% zcat /usr/share/man/man1/git-add.1.gz | grep '\fB'
you must use the \fBadd\fR command
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.
Right. So my patch was correct: it is neecessary.
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.
That's a fourth change now, and one that complicates the Makefile even
more, when I've been trying to simplify it.
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
still on 1.5.
Can you point what problems are those? I did a doc-diff with my patches
on asciidoctor 1.5.8 and I did not see any major problems.
If users are using a more modern toolchain or don't care
about the rendering issues, they can enable the option.
What rendering issues?
Also, the many should not suffer because of the few.
If a few people doing USE_ASCIIDOCTOR=YesPlease have issues (because of
ancient packages in their distribution, and their reluctance to type
`gem install`), then *they* can disable USE_ASCIIDOCTOR_MANPAGE (or just
disable USE_ASCIIDOCTOR altogether). Most people doing
USE_ASCIIDOCTOR=YesPlease should not suffer because of a
minority.
Signed-off-by: Felipe Contreras <redacted>
I most definitely do not sign off this.
--
Felipe Contreras
From: brian m. carlson <hidden> Date: 2021-05-14 20:17:09
On 2021-05-14 at 19:53:13, Felipe Contreras wrote:
brian m. carlson wrote:
quoted
Asciidoctor contains a converter to generate man pages. In some
environments, where building only the manual pages and not the other
documentation is desired, installing a toolchain for building
DocBook-based manual pages may be burdensome, and using Asciidoctor
directly may be easier, so let's add an option to build manual pages
using Asciidoctor without the DocBook toolchain.
We generally require Asciidoctor 1.5, but versions before 1.5.3 didn't
contain proper handling of the apostrophe, which is controlled normally
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 (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.
I don't see what that paragraph has to do with the patch below.
It's relevant because it explains why it's acceptable to discount that
feature that we're not supporting as part of the patch.
quoted
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.
Yes, but why shove it in this patch? Now this is is doing *two*
logically-independent changes.
This is one logical change: implementing Asciidoctor native support for
man pages.
quoted
Be careful to reset the font to the previous after the change.
This is a third change, since the current man pages already don't do
this:
% zcat /usr/share/man/man1/git-add.1.gz | grep '\fB'
you must use the \fBadd\fR command
As explained downthread, we don't know in the manual pages what font
styling we're in. troff has font-change commands, not nesting begin-end
pairs, for italics and bold. If the linkgit macro appears in the middle
of a passage in italics, by not using \fP, we'll force the rest of the
text which is to be italicized into roman.
The toolchain, whether Asciidoctor or the XSLT stylesheets, _does_ have
this context and therefore can explicitly move between bold and roman,
but our extensions do not.
quoted
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.
Right. So my patch was correct: it is neecessary.
Yes, I agree that it's necessary. As I stated downthread, it appears my
branch was in a broken state.
quoted
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.
That's a fourth change now, and one that complicates the Makefile even
more, when I've been trying to simplify it.
I'm sorry that this complicates work you'd like to do, but
unfortunately, the other option is broken rendering.
quoted
If users are using a more modern toolchain or don't care
about the rendering issues, they can enable the option.
What rendering issues?
They were mentioned upthread.
Also, the many should not suffer because of the few.
If a few people doing USE_ASCIIDOCTOR=YesPlease have issues (because of
ancient packages in their distribution, and their reluctance to type
`gem install`), then *they* can disable USE_ASCIIDOCTOR_MANPAGE (or just
disable USE_ASCIIDOCTOR altogether). Most people doing
USE_ASCIIDOCTOR=YesPlease should not suffer because of a
minority.
I don't believe we're going to agree on this. I believe we should
choose defaults that work with the most popular Linux distributions, and
you don't. I think your approach is unnecessarily hostile to ordinary
users and developers and understates the value that people derive from
distributions.
quoted
Signed-off-by: Felipe Contreras <redacted>
I most definitely do not sign off this.
This sign-off is not an approval of the patch. This is the statement
that this patch is based on your work which is subject to the license
specified in the file and that you agreed that your original
contribution (now modified) could be distributed with your sign-off. In
no portion of the DCO does it state that a sign-off means you think the
patch is a good idea or that you approve of it in any way.
I do want to be clear that I'm aware you don't approve of this patch and
that's why I submitted a counterproposal: because I don't approve of
your patch and you seem unwilling to make changes to it. I would love
nothing more than to remove your name from it entirely, but
unfortunately, that's not possible with the DCO.
--
brian m. carlson (he/him or they/them)
Houston, Texas, US
From: Felipe Contreras <hidden> Date: 2021-05-14 23:31:17
brian m. carlson wrote:
On 2021-05-14 at 19:53:13, Felipe Contreras wrote:
quoted
brian m. carlson wrote:
quoted
We generally require Asciidoctor 1.5, but versions before 1.5.3 didn't
contain proper handling of the apostrophe, which is controlled normally
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 (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.
I don't see what that paragraph has to do with the patch below.
It's relevant because it explains why it's acceptable to discount that
feature that we're not supporting as part of the patch.
It's easier to first drop that feature, and then you don't have to
explain anything.
quoted
quoted
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.
Yes, but why shove it in this patch? Now this is is doing *two*
logically-independent changes.
This is one logical change: implementing Asciidoctor native support for
man pages.
By that logic all patch series can be a "logical change": "implement
SHA-256 support".
quoted
quoted
Be careful to reset the font to the previous after the change.
This is a third change, since the current man pages already don't do
this:
% zcat /usr/share/man/man1/git-add.1.gz | grep '\fB'
you must use the \fBadd\fR command
As explained downthread, we don't know in the manual pages what font
styling we're in. troff has font-change commands, not nesting begin-end
pairs, for italics and bold. If the linkgit macro appears in the middle
of a passage in italics, by not using \fP, we'll force the rest of the
text which is to be italicized into roman.
The toolchain, whether Asciidoctor or the XSLT stylesheets, _does_ have
this context and therefore can explicitly move between bold and roman,
but our extensions do not.
Indeed but it's rare (there's probably zero instances), and it increases
the delta. Yes, it's more correct, but it trades a hypothetical benefit
for a real disadvantage.
Either way I see no point in arguing about this. If you feel strongly
about this I can include it in my version.
quoted
quoted
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.
That's a fourth change now, and one that complicates the Makefile even
more, when I've been trying to simplify it.
I'm sorry that this complicates work you'd like to do, but
unfortunately, the other option is broken rendering.
Clean and maintainable code is a benefit to the project, not just me.
And the Makefile is code too.
Forget about me, a clean and simple Makefile is better than a cluttered
and complex Makefile. That is the point.
Yes, the rendering is "broken" without the change (that's loaded
language, but OK), we want to know precisely how, and how it got fixed.
We don't wan to sneak in all the fixes in the world in the first patch.
Moreover, there's no dicotomy here; we can fix the "broken" state in
other ways that don't complicate the Makefile, as I did in my patch
series [1].
But in fact, I have an even simpler version now:
Asciidoctor::Extensions.register do
+ # Override attributes for man pages.
+ # https://github.com/asciidoctor/asciidoctor/issues/4059
+ if document.backend == 'manpage'
+ document.attributes.merge!({ 'litdd' => '\--', 'plus' => '+' })
+ end
+
inline_macro Git::Documentation::LinkGitProcessor, :linkgit
postprocessor Git::Documentation::DocumentPostProcessor
end
quoted
quoted
If users are using a more modern toolchain or don't care
about the rendering issues, they can enable the option.
What rendering issues?
They were mentioned upthread.
No. Pepole mentioned issues they *think* existed, nobody pointed out an
actual reproducible issue.
As you experienced with the \e setback, the issue could have been with
their build, or it could be present in v1.5.7, but not v1.5.8. It's hard
to know if nobody spells out what the issue is.
So... What rendering issues?
quoted
Also, the many should not suffer because of the few.
If a few people doing USE_ASCIIDOCTOR=YesPlease have issues (because of
ancient packages in their distribution, and their reluctance to type
`gem install`), then *they* can disable USE_ASCIIDOCTOR_MANPAGE (or just
disable USE_ASCIIDOCTOR altogether). Most people doing
USE_ASCIIDOCTOR=YesPlease should not suffer because of a
minority.
I don't believe we're going to agree on this. I believe we should
choose defaults that work with the most popular Linux distributions, and
you don't.
Untrue.
`make USE_ASCIIDOCTOR= doc` works perfectly fine on Debian stable with
my patches, and that's the default, nobody is changing that.
And so does this:
gem install asciidoctor && make USE_ASCIIDOCTOR=1 doc
But in fact, so does `make USE_ASCIIDOCTOR=1 doc`, because asciidoctor
1.5.8 works just fine. I just did a doc-diff with v1.5.8, and I
checked everything without finding any serious issue (not present in
2.0.15).
The only issue is that \\ was not handled correctly, but I now have a
workaround for that:
if document.basebackend?('manpage') and Asciidoctor::VERSION < '2.0.11'
postprocessor do
process do |document, output|
output.gsub("\\(rs\\\\", "\\(rs\\(rs\\")
end
end
end
I think your approach is unnecessarily hostile to ordinary
users and developers and understates the value that people derive from
distributions.
Please tell me exactly how my patches are hostile to "ordinary
developers" (who are not ordinary at all).
1. Will they be able to build the documentation with default flags?
Yes
2. Will they be able to build with USE_ASCIIDOCTOR=1?
Yes
3. Will they be able to see a reasonable output?
Yes
4. Will they be forced to install a gem?
No
So where exactly is the hostility?
quoted
quoted
Signed-off-by: Felipe Contreras <redacted>
I most definitely do not sign off this.
This sign-off is not an approval of the patch.
Yes it is. According to the Developer Certificate of Origin [2] I must:
agree that a record of the contribution (including my sign-off) is
maintained indefinitely
Which I don't.
Feel free to disregard my lack of agreement, but I'm stating it for the
record.
I do want to be clear that I'm aware you don't approve of this patch and
that's why I submitted a counterproposal: because I don't approve of
your patch
That happens.
and you seem unwilling to make changes to it.
Just because I disagree with your changes doesn't mean I'm unwilling to
make changes to my patch, especially since I already agreed on making
changes to my patch.
I would love nothing more than to remove your name from it entirely,
but unfortunately, that's not possible with the DCO.
From: brian m. carlson <hidden> Date: 2021-05-14 00:31:44
By default, groff converts apostrophes in troff source to Unicode
apostrophes. This is helpful and desirable when being used as a
typesetter, since it makes the output much cleaner and more readable,
but it is a problem in manual pages, since apostrophes are often used
around shell commands and these should remain in their ASCII form for
compatibility with the shell.
Fortunately, the DocBook stylesheets contain a workaround for this case:
they detect the special .g number register, which is set only when using
groff, and they define a special macro for apostrophes based on whether
or not it is set and use that macro to write out the proper character.
As a result, the DocBook stylesheets handle all cases correctly
automatically, whether the user is using groff or not, unlike our
GNU_ROFF code.
Additionally, this functionality was implemented in 2010. Since nobody
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 <redacted>
---
Documentation/Makefile | 8 --------
Documentation/manpage-quote-apos.xsl | 16 ----------------
Makefile | 4 ----
3 files changed, 28 deletions(-)
delete mode 100644 Documentation/manpage-quote-apos.xsl
@@ -177,14 +177,6 @@ MAN_BASE_URL = file://$(htmldir)/endifXMLTO_EXTRA+=-mmanpage-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+=-mmanpage-quote-apos.xsl-endif-ifdef USE_ASCIIDOCTORASCIIDOC=asciidoctorASCIIDOC_CONF=
@@ -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>
@@ -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.#
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.
--
Felipe Contreras
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 (he/him or they/them)
Houston, Texas, US
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).
quoted
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
--
Felipe Contreras