groff .ft command use in asciidoc

groff .ft command use in asciidoc

[Andi Kleen]

Hi,

The git manpages on my opensuse 11.3 (git 1.7.1-1.14)
frequently use the .ft command the opensuse groff does not 
render.

For example from the final output of "man git-commit":

           .ft C
           $ edit hello.c
           $ git rm goodbye.c
           $ git add hello.c
           $ git commit
           .ft


So the .ft commands are visible.  It's really a cosmetic issue 
only, but looks ugly and irritates me every time I 
look something up in the man pages.

I double checked against current git.git and the problem 
is still there, because .ft C is configured in 
Documentation/asciidoc.conf

Not sure what the best solution is. Stop using .ft
and change asciidocs configuration?


-Andi 


-- 
ak@linux.intel.com -- Speaking for myself only.

Re: groff .ft command use in asciidoc

[Jonathan Nieder]

Hi,

Andi Kleen wrote:

> The git manpages on my opensuse 11.3 (git 1.7.1-1.14)
> frequently use the .ft command the opensuse groff does not 
> render.
> 
> For example from the final output of "man git-commit":
> 
>            .ft C
>            $ edit hello.c
>            $ git rm goodbye.c
>            $ git add hello.c
>            $ git commit
>            .ft

This is in my opinion a bug: unless you use ASCIIDOC_NO_ROFF, git's
asciidoc.conf will include raw roff directives in the docbook markup
it generates.  And then docbook will escape the periods, producing
the output you see.

The workaround is very simple: set ASCIIDOC_NO_ROFF to nonempty
when you build documentation.

I think the only reason this is not the default is that no one has
tested it with old DocBook XSL versions, but I'm not sure.
Documentation/Makefile has some notes about this.

Hope that helps,
Jonathan

Re: groff .ft command use in asciidoc

[Andi Kleen]

> This is in my opinion a bug: unless you use ASCIIDOC_NO_ROFF, git's
> asciidoc.conf will include raw roff directives in the docbook markup
> it generates.  And then docbook will escape the periods, producing
> the output you see.

I see. Thanks for the explanation.

> 
> The workaround is very simple: set ASCIIDOC_NO_ROFF to nonempty
> when you build documentation.

I will suggest to the opensuse git maintainers to set that variable.
 
> I think the only reason this is not the default is that no one has
> tested it with old DocBook XSL versions, but I'm not sure.
> Documentation/Makefile has some notes about this.

It would be nice if that worked out of the box.

-Andi

-- 
ak@linux.intel.com -- Speaking for myself only.

Re: groff .ft command use in asciidoc

[Jeff King]

On Wed, Nov 17, 2010 at 04:15:16AM -0600, Jonathan Nieder wrote:

> This is in my opinion a bug: unless you use ASCIIDOC_NO_ROFF, git's
> asciidoc.conf will include raw roff directives in the docbook markup
> it generates.  And then docbook will escape the periods, producing
> the output you see.

IIRC, that depends very much on the versions of asciidoc and docbook you
have. Once upon a time, not setting ASCIIDOC_NO_ROFF was required for
sane output.

Andi, I would be curious to hear which asciidoc and docbook-xsl versions
you are using.

> I think the only reason this is not the default is that no one has
> tested it with old DocBook XSL versions, but I'm not sure.
> Documentation/Makefile has some notes about this.

At the time those knobs came into being, the defaults were set for
then-current versions of the software. I suspect ASCIIDOC8 and
ASCIIDOC_NO_ROFF should be the default these days.

-Peff

Re: groff .ft command use in asciidoc

[Andi Kleen]

On Wed, Nov 17, 2010 at 09:38:55AM -0500, Jeff King wrote:
> On Wed, Nov 17, 2010 at 04:15:16AM -0600, Jonathan Nieder wrote:
> Andi, I would be curious to hear which asciidoc and docbook-xsl versions
> you are using.

I see this with the git rpms in opensuse 11.3 which I didn't build.
But presumably it's built with asciidoc 8.4.5-5.1 and 1.75.2-7.1

-Andi 

-- 
ak@linux.intel.com -- Speaking for myself only.

Re: groff .ft command use in asciidoc

[Jeff King]

On Wed, Nov 17, 2010 at 04:48:29PM +0100, Andi Kleen wrote:

> On Wed, Nov 17, 2010 at 09:38:55AM -0500, Jeff King wrote:
> > On Wed, Nov 17, 2010 at 04:15:16AM -0600, Jonathan Nieder wrote:
> > Andi, I would be curious to hear which asciidoc and docbook-xsl versions
> > you are using.
> 
> I see this with the git rpms in opensuse 11.3 which I didn't build.
> But presumably it's built with asciidoc 8.4.5-5.1 and 1.75.2-7.1

Thanks. I think technically that is a bug in opensuse's packaging, as
they are not setting the right knobs for their version. However, I think
these days we can make it easier for them. Perhaps it is time to apply
this:

-- >8 --
Subject: [PATCH] docs: default to more modern toolset

When the ASCIIDOC8 and ASCIIDOC_NO_ROFF knobs were built,
many people were still on asciidoc 7 and using older
versions of docbook-xsl. These days, even the almost
2-year-old Debian stable needs these knobs turned.

So let's turn them by default. The new knobs ASCIIDOC7 and
ASCIIDOC_ROFF can be used to get the old behavior if people
are on older systems.

Signed-off-by: Jeff King <peff@peff.net>
---
These defaults work on Debian stable and further. It sounds like
opensuse 11.3, too. I don't know about Fedora, but I suspect they are at
least as far along as Debian stable.

RHEL5 has asciidoc8, but docbook-xsl 1.69, which means it still needs
ASCIIDOC_ROFF enabled. RHEL6 is just out last week. So we are
technically breaking at least RHEL5 people (along with anybody with
ancient systems) until they tweak their knobs.

However, I think it is worth it to avoid the hassle for the vast
majority of people on modern systems.

 Documentation/Makefile           |   23 ++++++++---------------
 Documentation/RelNotes/1.7.4.txt |    4 ++++
 INSTALL                          |    5 +++--
 Makefile                         |   10 +++++-----
 config.mak.in                    |    2 +-
 configure.ac                     |   12 ++++++------
 6 files changed, 27 insertions(+), 29 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index e117bc4..36989b7 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -63,35 +63,28 @@ endif
 
 #
 # For asciidoc ...
-#	-7.1.2,	no extra settings are needed.
-#	8.0-,	set ASCIIDOC8.
+#	-7.1.2,	set ASCIIDOC7
+#	8.0-,	no extra settings are needed
 #
 
 #
 # For docbook-xsl ...
-#	-1.68.1,	set ASCIIDOC_NO_ROFF? (based on changelog from 1.73.0)
-#	1.69.0,		no extra settings are needed?
+#	-1.68.1,	no extra settings are needed?
+#	1.69.0,		set ASCIIDOC_ROFF?
 #	1.69.1-1.71.0,	set DOCBOOK_SUPPRESS_SP?
-#	1.71.1,		no extra settings are needed?
+#	1.71.1,		set ASCIIDOC_ROFF?
 #	1.72.0,		set DOCBOOK_XSL_172.
-#	1.73.0-,	set ASCIIDOC_NO_ROFF
+#	1.73.0-,	no extra settings are needed
 #
 
-#
-# If you had been using DOCBOOK_XSL_172 in an attempt to get rid
-# of 'the ".ft C" problem' in your generated manpages, and you
-# instead ended up with weird characters around callouts, try
-# using ASCIIDOC_NO_ROFF instead (it works fine with ASCIIDOC8).
-#
-
-ifdef ASCIIDOC8
+ifndef ASCIIDOC7
 ASCIIDOC_EXTRA += -a asciidoc7compatible -a no-inline-literal
 endif
 ifdef DOCBOOK_XSL_172
 ASCIIDOC_EXTRA += -a git-asciidoc-no-roff
 MANPAGE_XSL = manpage-1.72.xsl
 else
-	ifdef ASCIIDOC_NO_ROFF
+	ifndef ASCIIDOC_ROFF
 	# docbook-xsl after 1.72 needs the regular XSL, but will not
 	# pass-thru raw roff codes from asciidoc.conf, so turn them off.
 	ASCIIDOC_EXTRA += -a git-asciidoc-no-roff
diff --git a/Documentation/RelNotes/1.7.4.txt b/Documentation/RelNotes/1.7.4.txt
index 05e8a43..87629c6 100644
--- a/Documentation/RelNotes/1.7.4.txt
+++ b/Documentation/RelNotes/1.7.4.txt
@@ -32,6 +32,10 @@ Updates since v1.7.3
    git-only login over ssh as login shell, with custom set of
    commands.
 
+ * The documentation Makefile now assumes by default asciidoc 8 and
+   docbook-xsl >= 1.73. If you have older versions, you can set
+   ASCIIDOC7 and ASCIIDOC_ROFF, respectively.
+
 Also contains various documentation updates.
 
 
diff --git a/INSTALL b/INSTALL
index 10a1cba..16e45f1 100644
--- a/INSTALL
+++ b/INSTALL
@@ -122,8 +122,9 @@ Issues of note:
    Building and installing the pdf file additionally requires
    dblatex.  Version 0.2.7 with asciidoc >= 8.2.7 is known to work.
 
-   The documentation is written for AsciiDoc 7, but "make
-   ASCIIDOC8=YesPlease doc" will let you format with AsciiDoc 8.
+   The documentation is written for AsciiDoc 7, but by default
+   uses some compatibility wrappers to work on AsciiDoc 8. If you have
+   AsciiDoc 7, try "make ASCIIDOC7=YesPlease".
 
    Alternatively, pre-formatted documentation is available in
    "html" and "man" branches of the git repository itself.  For
diff --git a/Makefile b/Makefile
index 1f1ce04..9ddcae9 100644
--- a/Makefile
+++ b/Makefile
@@ -162,13 +162,13 @@ 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 ASCIIDOC8 if you want to format documentation with AsciiDoc 8
+# Define ASCIIDOC7 if you want to format documentation with AsciiDoc 7
 #
 # Define DOCBOOK_XSL_172 if you want to format man pages with DocBook XSL v1.72
 # (not v1.73 or v1.71).
 #
-# Define ASCIIDOC_NO_ROFF if your DocBook XSL escapes raw roff directives
-# (versions 1.72 and later and 1.68.1 and earlier).
+# Define ASCIIDOC_ROFF if your DocBook XSL does not escape raw roff directives
+# (versions 1.68.1 through v1.72).
 #
 # Define GNU_ROFF if your target system uses GNU groff.  This forces
 # apostrophes to be ASCII so that cut&pasting examples to the shell
@@ -1518,8 +1518,8 @@ ifndef V
 endif
 endif
 
-ifdef ASCIIDOC8
-	export ASCIIDOC8
+ifdef ASCIIDOC7
+	export ASCIIDOC7
 endif
 
 # Shell quote (do not use $(call) to accommodate ancient setups);
diff --git a/config.mak.in b/config.mak.in
index a0c34ee..55dcd30 100644
--- a/config.mak.in
+++ b/config.mak.in
@@ -27,7 +27,7 @@ VPATH = @srcdir@
 export exec_prefix mandir
 export srcdir VPATH
 
-ASCIIDOC8=@ASCIIDOC8@
+ASCIIDOC7=@ASCIIDOC7@
 NEEDS_SSL_WITH_CRYPTO=@NEEDS_SSL_WITH_CRYPTO@
 NO_OPENSSL=@NO_OPENSSL@
 NO_CURL=@NO_CURL@
diff --git a/configure.ac b/configure.ac
index cc55b6d..e9ca117 100644
--- a/configure.ac
+++ b/configure.ac
@@ -398,21 +398,21 @@ if test -n "$ASCIIDOC"; then
 	AC_MSG_CHECKING([for asciidoc version])
 	asciidoc_version=`$ASCIIDOC --version 2>/dev/null`
 	case "${asciidoc_version}" in
-	asciidoc' '8*)
-		ASCIIDOC8=YesPlease
+	asciidoc' '7*)
+		ASCIIDOC7=YesPlease
 		AC_MSG_RESULT([${asciidoc_version} > 7])
 		;;
-	asciidoc' '7*)
-		ASCIIDOC8=
+	asciidoc' '8*)
+		ASCIIDOC7=
 		AC_MSG_RESULT([${asciidoc_version}])
 		;;
 	*)
-		ASCIIDOC8=
+		ASCIIDOC7=
 		AC_MSG_RESULT([${asciidoc_version} (unknown)])
 		;;
 	esac
 fi
-AC_SUBST(ASCIIDOC8)
+AC_SUBST(ASCIIDOC7)
 
 
 ## Checks for libraries.
-- 
1.7.3.2.510.g24900

Re: groff .ft command use in asciidoc

[Jonathan Nieder]

Jeff King wrote:

> --- a/Documentation/Makefile
> +++ b/Documentation/Makefile
> @@ -63,35 +63,28 @@ endif
[...]
> -#	-1.68.1,	set ASCIIDOC_NO_ROFF? (based on changelog from 1.73.0)
> -#	1.69.0,		no extra settings are needed?
> +#	-1.68.1,	no extra settings are needed?
> +#	1.69.0,		set ASCIIDOC_ROFF?
>  #	1.69.1-1.71.0,	set DOCBOOK_SUPPRESS_SP?
> -#	1.71.1,		no extra settings are needed?
> +#	1.71.1,		set ASCIIDOC_ROFF?

I would like to see these question marks go away.  I believe the
initial introduction of ASCIIDOC_NO_ROFF happened conservatively:
i.e., do not change anything unless this particular toolset
requires the change.  Which is a shame, because it means it is not
obvious what ASCIIDOC_ROFF is working around.

*does some digging*

The story begins with v1.3.0-rc1~45^2 (Tweak asciidoc to work with
broken docbook-xsl, 2006-03-05).  The [listingblock] style, used
for listings like:

--------------------
$ ls
foo
bar
baz
--------------------

is meant to be rendered with the <screen> tag, but apparently DocBook
XSL 1.68.1 does not and 1.70.1 does treat <screen> as a
verbatim environment as it should.  See <http://bugs.debian.org/375503>.
The patch swapped in another verbatim environment, <literallayout>.

The result is a regression in another aspect from <screen>: namely,
<screen> uses monospace text.  v1.5.2.5~6 (Force listingblocks to be
monospaced in manpages, 2007-07-18) worked around that by introducing
some raw nroff, since this codepath is only used for manpages anyway.

The rest is history.  docbook-xsl 1.72 broke the traditional method
for passing raw roff through.  It had a hole that let you do it some
other way.  Later versions of docbook-xsl forbid passing through raw
roff escapes altogether.

Given all that, I suspect (but haven't checked) that the only knob we
would need to cover all historically supported versions of DocBook is

	DOCBOOK_MESSES_UP_SCREEN_TAG = YesUnfortunately

to be set with docbook versions in the 1.68 series.  Everyone else
can use <screen>, with the <literallayout> fixup to add some space
after it.

> However, I think it is worth it to avoid the hassle for the vast
> majority of people on modern systems.

Yes!  Your patch takes care of that, so ack.

Thanks,
Jonathan

Re: groff .ft command use in asciidoc

[Jeff King]

On Fri, Nov 19, 2010 at 12:22:30PM -0600, Jonathan Nieder wrote:

> Jeff King wrote:
> 
> > --- a/Documentation/Makefile
> > +++ b/Documentation/Makefile
> > @@ -63,35 +63,28 @@ endif
> [...]
> > -#	-1.68.1,	set ASCIIDOC_NO_ROFF? (based on changelog from 1.73.0)
> > -#	1.69.0,		no extra settings are needed?
> > +#	-1.68.1,	no extra settings are needed?
> > +#	1.69.0,		set ASCIIDOC_ROFF?
> >  #	1.69.1-1.71.0,	set DOCBOOK_SUPPRESS_SP?
> > -#	1.71.1,		no extra settings are needed?
> > +#	1.71.1,		set ASCIIDOC_ROFF?
> 
> I would like to see these question marks go away.

I would, too, but not enough to put work into building and testing
various combinations of software that hopefully nobody is using anymore.

> I believe the
> initial introduction of ASCIIDOC_NO_ROFF happened conservatively:
> i.e., do not change anything unless this particular toolset
> requires the change.  Which is a shame, because it means it is not
> obvious what ASCIIDOC_ROFF is working around.

Yeah, the name ASCIIDOC_ROFF is kind of awful. I tried to make this
patch as dirt-simple as possible: just switch the defaults around (it
would be nice if we could simply set ASCIIDOC8=Yes, but because we use
"ifdef" and not "if" in the makefile, it has to be a separate variable).

I suspect there could really be some cleanup in this area, and you seem
to, too...

> Given all that, I suspect (but haven't checked) that the only knob we
> would need to cover all historically supported versions of DocBook is
> 
> 	DOCBOOK_MESSES_UP_SCREEN_TAG = YesUnfortunately
> 
> to be set with docbook versions in the 1.68 series.  Everyone else
> can use <screen>, with the <literallayout> fixup to add some space
> after it.

Yeah, that would be great and much simpler if it works. I encourage you
to test it. :)

> > However, I think it is worth it to avoid the hassle for the vast
> > majority of people on modern systems.
> 
> Yes!  Your patch takes care of that, so ack.

Thanks.

-Peff

Re: groff .ft command use in asciidoc

[Drew Northup]

On Fri, 2010-11-19 at 12:54 -0500, Jeff King wrote:
> On Wed, Nov 17, 2010 at 04:48:29PM +0100, Andi Kleen wrote:
> 
> > On Wed, Nov 17, 2010 at 09:38:55AM -0500, Jeff King wrote:
> > > On Wed, Nov 17, 2010 at 04:15:16AM -0600, Jonathan Nieder wrote:
> > > Andi, I would be curious to hear which asciidoc and docbook-xsl versions
> > > you are using.
> > 
> > I see this with the git rpms in opensuse 11.3 which I didn't build.
> > But presumably it's built with asciidoc 8.4.5-5.1 and 1.75.2-7.1
> 
> Thanks. I think technically that is a bug in opensuse's packaging, as
> they are not setting the right knobs for their version. However, I think
> these days we can make it easier for them. Perhaps it is time to apply
> this:
> 
> -- >8 --
> Subject: [PATCH] docs: default to more modern toolset
> 
> When the ASCIIDOC8 and ASCIIDOC_NO_ROFF knobs were built,
> many people were still on asciidoc 7 and using older
> versions of docbook-xsl. These days, even the almost
> 2-year-old Debian stable needs these knobs turned.
> 
> So let's turn them by default. The new knobs ASCIIDOC7 and
> ASCIIDOC_ROFF can be used to get the old behavior if people
> are on older systems.
> 
> Signed-off-by: Jeff King <peff@peff.net>
> ---
> These defaults work on Debian stable and further. It sounds like
> opensuse 11.3, too. I don't know about Fedora, but I suspect they are at
> least as far along as Debian stable.
> 
> RHEL5 has asciidoc8, but docbook-xsl 1.69, which means it still needs
> ASCIIDOC_ROFF enabled. RHEL6 is just out last week. So we are
> technically breaking at least RHEL5 people (along with anybody with
> ancient systems) until they tweak their knobs.

Once I imported the DocBook XML XSL 4.5 files into my local cache it
seemed to make the man pages just fine on my RHEL5 machine even with the
posted patch applied.

[root@host ~]# rpm -qi asciidoc
Name        : asciidoc                     Relocations: (not relocatable)
Version     : 8.6.3                             Vendor: Dag Apt Repository, http://dag.wieers.com/apt/
Release     : 1.el5.rf                      Build Date: Thu 18 Nov 2010 08:35:22 AM EST
...
[root@host ~]# rpm -qi docbook-utils
Name        : docbook-utils                Relocations: (not relocatable)
Version     : 0.6.14                            Vendor: Red Hat, Inc.
Release     : 5.1                           Build Date: Wed 12 Jul 2006 03:55:00 AM EDT

I didn't inspect each and every one for errors, but I didn't see any
problems in the ones I did look at.


-- 
-Drew Northup N1XIM
   AKA RvnPhnx on OPN
________________________________________________
"As opposed to vegetable or mineral error?"
-John Pescatore, SANS NewsBites Vol. 12 Num. 59

Re: groff .ft command use in asciidoc

[Jeff King]

On Fri, Nov 19, 2010 at 03:34:53PM -0500, Drew Northup wrote:

> > RHEL5 has asciidoc8, but docbook-xsl 1.69, which means it still needs
> > ASCIIDOC_ROFF enabled. RHEL6 is just out last week. So we are
> > technically breaking at least RHEL5 people (along with anybody with
> > ancient systems) until they tweak their knobs.
> 
> Once I imported the DocBook XML XSL 4.5 files into my local cache it
> seemed to make the man pages just fine on my RHEL5 machine even with the
> posted patch applied.
> 
> [root@host ~]# rpm -qi asciidoc
> Name        : asciidoc                     Relocations: (not relocatable)
> Version     : 8.6.3                             Vendor: Dag Apt Repository, http://dag.wieers.com/apt/
> Release     : 1.el5.rf                      Build Date: Thu 18 Nov 2010 08:35:22 AM EST
> ...
> [root@host ~]# rpm -qi docbook-utils
> Name        : docbook-utils                Relocations: (not relocatable)
> Version     : 0.6.14                            Vendor: Red Hat, Inc.
> Release     : 5.1                           Build Date: Wed 12 Jul 2006 03:55:00 AM EDT
> 
> I didn't inspect each and every one for errors, but I didn't see any
> problems in the ones I did look at.

I think the updated XSL files are what's making it work. The stock
docbook xsl files are:

  $ yum list | grep docbook-style-xsl
  docbook-style-xsl.noarch   1.69.1-5.1 rhel-x86_64-server-5

and I don't know that we can assume anyone has updated them. However, I
don't actually build git on my RHEL machines, so I could might be wrong.

All that being said, I am willing to accept RHEL5 as collateral damage
if the new defaults Just Work for the majority of other platforms.

-Peff

Re: groff .ft command use in asciidoc

[Drew Northup]

On Fri, 2010-11-19 at 15:40 -0500, Jeff King wrote:
> On Fri, Nov 19, 2010 at 03:34:53PM -0500, Drew Northup wrote:
> 
> > > RHEL5 has asciidoc8, but docbook-xsl 1.69, which means it still needs
> > > ASCIIDOC_ROFF enabled. RHEL6 is just out last week. So we are
> > > technically breaking at least RHEL5 people (along with anybody with
> > > ancient systems) until they tweak their knobs.
> > 
> > Once I imported the DocBook XML XSL 4.5 files into my local cache it
> > seemed to make the man pages just fine on my RHEL5 machine even with the
> > posted patch applied.
> > 
> > [root@host ~]# rpm -qi asciidoc
> > Name        : asciidoc                     Relocations: (not relocatable)
> > Version     : 8.6.3                             Vendor: Dag Apt Repository, http://dag.wieers.com/apt/
> > Release     : 1.el5.rf                      Build Date: Thu 18 Nov 2010 08:35:22 AM EST
> > ...
> > [root@host ~]# rpm -qi docbook-utils
> > Name        : docbook-utils                Relocations: (not relocatable)
> > Version     : 0.6.14                            Vendor: Red Hat, Inc.
> > Release     : 5.1                           Build Date: Wed 12 Jul 2006 03:55:00 AM EDT
> > 
> > I didn't inspect each and every one for errors, but I didn't see any
> > problems in the ones I did look at.
> 
> I think the updated XSL files are what's making it work. The stock
> docbook xsl files are:
> 
>   $ yum list | grep docbook-style-xsl
>   docbook-style-xsl.noarch   1.69.1-5.1 rhel-x86_64-server-5

Interestingly enough, without the updated XSL files it seemed to be
working ok, it was just ungodly slow and kicking up a ton of warnings
(it was trying to fetch them off of the hosting web server at such a
high rate it was being limited out).

> and I don't know that we can assume anyone has updated them. However, I
> don't actually build git on my RHEL machines, so I could might be wrong.
> 
> All that being said, I am willing to accept RHEL5 as collateral damage
> if the new defaults Just Work for the majority of other platforms.
> 
> -Peff

I don't personally see this as a stopper. After all, asciidoc wasn't a
default install either.

-- 
-Drew Northup N1XIM
   AKA RvnPhnx on OPN
________________________________________________
"As opposed to vegetable or mineral error?"
-John Pescatore, SANS NewsBites Vol. 12 Num. 59

Re: groff .ft command use in asciidoc

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> I think the updated XSL files are what's making it work. The stock
> docbook xsl files are:
>
>   $ yum list | grep docbook-style-xsl
>   docbook-style-xsl.noarch   1.69.1-5.1 rhel-x86_64-server-5
>
> and I don't know that we can assume anyone has updated them. However, I
> don't actually build git on my RHEL machines, so I could might be wrong.
>
> All that being said, I am willing to accept RHEL5 as collateral damage
> if the new defaults Just Work for the majority of other platforms.

Thanks.  I usually am fairly cautious when changing the default, but I
think this particular one is not such a big deal.  I agree that the end of
the year release would probably be a good time to switch.

I think people on RHEL5 would also be ok; they have paid support for this
kind of thing, no ;-)?

Re: groff .ft command use in asciidoc

[Todd Zullinger]

[-- Attachment #1: Type: text/plain, Size: 1482 bytes --]

Junio C Hamano wrote:
> Thanks.  I usually am fairly cautious when changing the default, but
> I think this particular one is not such a big deal.  I agree that
> the end of the year release would probably be a good time to switch.
>
> I think people on RHEL5 would also be ok; they have paid support for
> this kind of thing, no ;-)?

Sadly, git isn't in RHEL5 officially.  We package it in EPEL though.
Currently, it's at the ancient 1.5.5.6 mile marker.  I have taken care
to ensure that the Fedora rpm's build cleanly for EPEL-5 (and 4 last I
checked), albeit with the lack of emacs support¹.

I haven't tested this patch, but I am confident that removing the
ASCIIDOC knobs where appropriate won't cause us any grief in Fedora,
EPEL, or RHEL (where git-1.7.x is now officially supported, finally!).  

¹ Incidentally, if anyone here is a strong user of emacs vcs mode and
could help work out what we need to do to make git-1.7.x work with the
emacs-21.4 shipped in RHEL, please let me know.  That's the only
impediment (that I know of) keeping us from moving EPEL to a more
modern git, with all the fabulous advantages the fine folks here have
made since 1.5.x.

-- 
Todd        OpenPGP -> KeyID: 0xBEAF0CE3 | URL: www.pobox.com/~tmz/pgp
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Happiness, n.: An agreeable sensation arising from contemplating the
misery of another.
    -- Ambrose Bierce, "The Devil's Dictionary"


[-- Attachment #2: Type: application/pgp-signature, Size: 542 bytes --]

Re: groff .ft command use in asciidoc

[Alejandro Riveira Fernández]

On Wed, 17 Nov 2010 04:15:16 -0600, Jonathan Nieder wrote:


> 
> This is in my opinion a bug: unless you use ASCIIDOC_NO_ROFF, git's
> asciidoc.conf will include raw roff directives in the docbook markup it
> generates.  And then docbook will escape the periods, producing the
> output you see.
> 
> The workaround is very simple: set ASCIIDOC_NO_ROFF to nonempty when you
> build documentation.

 I use make quick-install-man which, afaik, installs man pages 
"prerendered" from the man branch and i see the same artifact.
 
 So can those man pages be rendered with this workaraound?
 
 Thanks



> Hope that helps,
> Jonathan

Re: groff .ft command use in asciidoc

[Drew Northup]

On Thu, 2010-11-18 at 17:47 +0000, Alejandro Riveira Fernández wrote:
> On Wed, 17 Nov 2010 04:15:16 -0600, Jonathan Nieder wrote:
 
> > This is in my opinion a bug: unless you use ASCIIDOC_NO_ROFF, git's
> > asciidoc.conf will include raw roff directives in the docbook markup it
> > generates.  And then docbook will escape the periods, producing the
> > output you see.
> > 
> > The workaround is very simple: set ASCIIDOC_NO_ROFF to nonempty when you
> > build documentation.
> 
>  I use make quick-install-man which, afaik, installs man pages 
> "prerendered" from the man branch and i see the same artifact.
>  
>  So can those man pages be rendered with this workaraound?
>  
>  Thanks

Out of curiosity I went ahead and ran that make script. I then ran the
following in the directory that the manpage directories were written out
to (an alternate DESTDIR):

[dnorthup@drew-northup man]$ grep -R "\.ft" *
[dnorthup@drew-northup man]$ 

Note that it returned nothing. This is based on the current git.git. (I
just pulled to be sure of that...)

As noted, all that make script essentially does is write out the
manpages found in origin/man--so it matters not what my current platform
is.

Run "man git-commit" in one terminal open up a second and run "ps ax |
grep man" and report on the results. 

-- 
-Drew Northup N1XIM
   AKA RvnPhnx on OPN
________________________________________________
"As opposed to vegetable or mineral error?"
-John Pescatore, SANS NewsBites Vol. 12 Num. 59

Re: groff .ft command use in asciidoc

[Alejandro Riveira Fernández]

El Thu, 18 Nov 2010 16:11:11 -0500
Drew Northup <drew.northup@maine.edu> escribió:

> 
> On Thu, 2010-11-18 at 17:47 +0000, Alejandro Riveira Fernández wrote:
> > On Wed, 17 Nov 2010 04:15:16 -0600, Jonathan Nieder wrote:
>  
> > > This is in my opinion a bug: unless you use ASCIIDOC_NO_ROFF, git's
> > > asciidoc.conf will include raw roff directives in the docbook markup it
> > > generates.  And then docbook will escape the periods, producing the
> > > output you see.
> > > 
> > > The workaround is very simple: set ASCIIDOC_NO_ROFF to nonempty when you
> > > build documentation.
> > 
> >  I use make quick-install-man which, afaik, installs man pages 
> > "prerendered" from the man branch and i see the same artifact.
> >  
> >  So can those man pages be rendered with this workaraound?
> >  
> >  Thanks
> 
> Out of curiosity I went ahead and ran that make script. I then ran the
> following in the directory that the manpage directories were written out
> to (an alternate DESTDIR):

 Doh! ... the problem was between chair and keyboard. i used alternate DESTDIR
 with the make all and make install but with quick.-install-man i forgot to set 
 it; so the man pages were old versions from when i actually builded the man
 pages myself
 Sorry for the wasted time ...

> 
> [dnorthup@drew-northup man]$ grep -R "\.ft" *
> [dnorthup@drew-northup man]$ 
> 
 After correcting the above
 $ grep -R "\.ft" *
 man3/private-Error.3pm:.ft CW
 man3/private-Error.3pm:.ft R
 man3/Git.3pm:.ft CW
 man3/Git.3pm:.ft R
 
 Which are probably letfovers from previous builds ...
   
> Note that it returned nothing. This is based on the current git.git. (I
> just pulled to be sure of that...)

 Thanks for checking and again. Sorry

> 
> As noted, all that make script essentially does is write out the
> manpages found in origin/man--so it matters not what my current platform
> is.
> 
> Run "man git-commit" in one terminal open up a second and run "ps ax |
> grep man" and report on the results. 

 For the sake of completeness
  $ ps ax | grep man
    585 ?        S<     0:00 [kondemand]
   4994 ?        S      0:00 gnome-power-manager
  32649 pts/2    S+     0:00 man git-commit
  32690 pts/4    S+     0:00 grep man

 Bye.