RFC: default version of the documentation tool chain (git 1.7)

RFC: default version of the documentation tool chain (git 1.7)

[Michael J Gruber]

The current defaults for building the documentation are so that asciidoc
up to 7.1.2 and docbook-xsl 1.69.0 and 1.71.1 need no extra settings,
whereas all other versions need extra options (1 or more of ASCIIDOC8,
ASCIIDOC_NO_ROFF, DOCBOOK_XSL_172, DOCBOOK_SUPPRESS_SP), see below. This
basically means that all current distros need extra options.

I suggest changing the defaults for the git-1.7 cycle. Below I list the
package versions in current mainstream distros, without using third
party repositories, but including the leading edge which foreshadows
upcoming versions.

Based on that, I suggest the following defaults for the git-1.7
documentation build file:
- ASCIIDOC8=yes. Caters for everything non-EOLed (8.0 and above)
- ASCIIDOC_NO_ROFF=yes. Caters for everything non-EOLed (1.73 and above,
1.68.1 and below)

[I'm not sure RHEL is EOLed but I don't think we need to care.]

It would be helpful if people with newer versions (asciidoc 8.4,
docbook-xsl 1.75) could test building the git documentation, in order to
verify "and above" ;)
Also, I don't know about the two proprietary OSes we support.

Cheers,
Michael

Current mainstream versions of asciidoc are:
Debian Etch (EOLed): 7.1.2
Debian Lenny: 8.2.7
Debian Squeeze: 8.4.4
Debian Sid: 8.4.4
Ubuntu Dapper (EOLed): 7.0.2
Ubuntu Hardy: 8.2.2
Ubuntu Intrepid: 8.2.6
Ubuntu Jaunty: 8.2.7
Ubuntu Karmic: 8.4.4
Fedora 9 (EOLed): 8.2.5
Fedora 10: 8.2.5
Fedora 11: 8.2.5
Fedora rawhide: 8.2.5
Fedora Koji (12): 8.4.5
Redhat EL4 extras: 7.0.2
Redhat EL5 extras: 8.1.0
OpenSUSE 10: 8.2.1
OpenSUSE 11: 8.2.7
OpenSUSE factory: 8.4.5
OpenBSD 4.3: 8.2.5
OpenBSD 4.4: 8.2.6
OpenBSD 4.5: 8.2.7

Current mainstream versions of docbook-xsl are:
Debian Etch (EOLed): 1.71.0
Debian Lenny: 1.73.2
Debian Squeeze: 1.75.2
Debian Sid: 1.75.2
Ubuntu Dapper (EOLed): 1.68.1
Ubuntu Hardy: 1.73.2
Ubuntu Intrepid: 1.73.2
Ubuntu Jaunty: 1.73.2
Ubuntu Karmic: 1.75.1
Fedora 9 (EOLed): 1.73.2
Fedora 10: 1.74.0
Fedora 11: 1.74.3
Fedora rawhide: 1.75.2
Fedora Koji (12): 1.75.2
Redhat EL4: 1.65.1
OpenSUSE 11: 1.74.0
OpenSUSE factory: 1.75.2
OpenBSD 4.3: 1.68
OpenBSD 4.4: 1.68
OpenBSD 4.5: 1.68

>From Documentation/Makefile:

#
# For asciidoc ...
#       -7.1.2, no extra settings are needed.
#       8.0-,   set ASCIIDOC8.
#

#
# 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.69.1-1.71.0,  set DOCBOOK_SUPPRESS_SP?
#       1.71.1,         no extra settings are needed?
#       1.72.0,         set DOCBOOK_XSL_172.
#       1.73.0-,        set ASCIIDOC_NO_ROFF
#

#
# 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).
#

Re: RFC: default version of the documentation tool chain (git 1.7)

[Junio C Hamano]

Michael J Gruber <git@drmicha.warpmail.net> writes:

> The current defaults for building the documentation are so that asciidoc
> up to 7.1.2 and docbook-xsl 1.69.0 and 1.71.1 need no extra settings,
> whereas all other versions need extra options (1 or more of ASCIIDOC8,
> ASCIIDOC_NO_ROFF, DOCBOOK_XSL_172, DOCBOOK_SUPPRESS_SP), see below. This
> basically means that all current distros need extra options.
>
> I suggest changing the defaults for the git-1.7 cycle.

Do you mean that people with older asciidoc would set a new option, say
ASCIIDOC7, instead of not setting ASCIIDOC8?

> Based on that, I suggest the following defaults for the git-1.7
> documentation build file:
> - ASCIIDOC8=yes. Caters for everything non-EOLed (8.0 and above)
> - ASCIIDOC_NO_ROFF=yes. Caters for everything non-EOLed (1.73 and above,
> 1.68.1 and below)

I would say that is a sensible default.