* [PATCH v2 1/5] compat: add qsort_s()
From: René Scharfe @ 2017-01-22 17:51 UTC (permalink / raw)
To: Git List; +Cc: Jeff King, Junio C Hamano, Johannes Schindelin
In-Reply-To: <67ac53cd-3fc0-8bd0-30f4-129281c3090f@web.de>
The function qsort_s() was introduced with C11 Annex K; it provides the
ability to pass a context pointer to the comparison function, supports
the convention of using a NULL pointer for an empty array and performs a
few safety checks.
Add an implementation based on compat/qsort.c for platforms that lack a
native standards-compliant qsort_s() (i.e. basically everyone). It
doesn't perform the full range of possible checks: It uses size_t
instead of rsize_t and doesn't check nmemb and size against RSIZE_MAX
because we probably don't have the restricted size type defined. For
the same reason it returns int instead of errno_t.
Signed-off-by: Rene Scharfe <l.s.r@web.de>
---
Makefile | 8 +++++++
compat/qsort_s.c | 69 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
git-compat-util.h | 6 +++++
3 files changed, 83 insertions(+)
create mode 100644 compat/qsort_s.c
diff --git a/Makefile b/Makefile
index 27afd0f378..53ecc84e28 100644
--- a/Makefile
+++ b/Makefile
@@ -279,6 +279,9 @@ all::
# is a simplified version of the merge sort used in glibc. This is
# recommended if Git triggers O(n^2) behavior in your platform's qsort().
#
+# Define HAVE_ISO_QSORT_S if your platform provides a qsort_s() that's
+# compatible with the one described in C11 Annex K.
+#
# Define UNRELIABLE_FSTAT if your system's fstat does not return the same
# information on a not yet closed file that lstat would return for the same
# file after it was closed.
@@ -1418,6 +1421,11 @@ ifdef INTERNAL_QSORT
COMPAT_CFLAGS += -DINTERNAL_QSORT
COMPAT_OBJS += compat/qsort.o
endif
+ifdef HAVE_ISO_QSORT_S
+ COMPAT_CFLAGS += -DHAVE_ISO_QSORT_S
+else
+ COMPAT_OBJS += compat/qsort_s.o
+endif
ifdef RUNTIME_PREFIX
COMPAT_CFLAGS += -DRUNTIME_PREFIX
endif
diff --git a/compat/qsort_s.c b/compat/qsort_s.c
new file mode 100644
index 0000000000..52d1f0a73d
--- /dev/null
+++ b/compat/qsort_s.c
@@ -0,0 +1,69 @@
+#include "../git-compat-util.h"
+
+/*
+ * A merge sort implementation, simplified from the qsort implementation
+ * by Mike Haertel, which is a part of the GNU C Library.
+ * Added context pointer, safety checks and return value.
+ */
+
+static void msort_with_tmp(void *b, size_t n, size_t s,
+ int (*cmp)(const void *, const void *, void *),
+ char *t, void *ctx)
+{
+ char *tmp;
+ char *b1, *b2;
+ size_t n1, n2;
+
+ if (n <= 1)
+ return;
+
+ n1 = n / 2;
+ n2 = n - n1;
+ b1 = b;
+ b2 = (char *)b + (n1 * s);
+
+ msort_with_tmp(b1, n1, s, cmp, t, ctx);
+ msort_with_tmp(b2, n2, s, cmp, t, ctx);
+
+ tmp = t;
+
+ while (n1 > 0 && n2 > 0) {
+ if (cmp(b1, b2, ctx) <= 0) {
+ memcpy(tmp, b1, s);
+ tmp += s;
+ b1 += s;
+ --n1;
+ } else {
+ memcpy(tmp, b2, s);
+ tmp += s;
+ b2 += s;
+ --n2;
+ }
+ }
+ if (n1 > 0)
+ memcpy(tmp, b1, n1 * s);
+ memcpy(b, t, (n - n2) * s);
+}
+
+int git_qsort_s(void *b, size_t n, size_t s,
+ int (*cmp)(const void *, const void *, void *), void *ctx)
+{
+ const size_t size = st_mult(n, s);
+ char buf[1024];
+
+ if (!n)
+ return 0;
+ if (!b || !cmp)
+ return -1;
+
+ if (size < sizeof(buf)) {
+ /* The temporary array fits on the small on-stack buffer. */
+ msort_with_tmp(b, n, s, cmp, buf, ctx);
+ } else {
+ /* It's somewhat large, so malloc it. */
+ char *tmp = xmalloc(size);
+ msort_with_tmp(b, n, s, cmp, tmp, ctx);
+ free(tmp);
+ }
+ return 0;
+}
diff --git a/git-compat-util.h b/git-compat-util.h
index 87237b092b..f706744e6a 100644
--- a/git-compat-util.h
+++ b/git-compat-util.h
@@ -988,6 +988,12 @@ static inline void sane_qsort(void *base, size_t nmemb, size_t size,
qsort(base, nmemb, size, compar);
}
+#ifndef HAVE_ISO_QSORT_S
+int git_qsort_s(void *base, size_t nmemb, size_t size,
+ int (*compar)(const void *, const void *, void *), void *ctx);
+#define qsort_s git_qsort_s
+#endif
+
#ifndef REG_STARTEND
#error "Git requires REG_STARTEND support. Compile with NO_REGEX=NeedsStartEnd"
#endif
--
2.11.0
^ permalink raw reply related
* [PATCH v2 0/5] string-list: make string_list_sort() reentrant
From: René Scharfe @ 2017-01-22 17:47 UTC (permalink / raw)
To: Git List; +Cc: Jeff King, Junio C Hamano, Johannes Schindelin
Use qsort_s() from C11 Annex K to make string_list_sort() safer, in
particular when called from parallel threads.
Changes from v1:
* Renamed HAVE_QSORT_S to HAVE_ISO_QSORT_S in Makefile to disambiguate.
* Added basic perf test (patch 3).
* Converted a second caller to QSORT_S, in ref-filter.c (patch 5).
compat: add qsort_s()
add QSORT_S
perf: add basic sort performance test
string-list: use QSORT_S in string_list_sort()
ref-filter: use QSORT_S in ref_array_sort()
Makefile | 8 ++++++
compat/qsort_s.c | 69 +++++++++++++++++++++++++++++++++++++++++++++
git-compat-util.h | 11 ++++++++
ref-filter.c | 6 ++--
string-list.c | 13 ++++-----
t/helper/test-string-list.c | 25 ++++++++++++++++
t/perf/p0071-sort.sh | 26 +++++++++++++++++
7 files changed, 146 insertions(+), 12 deletions(-)
create mode 100644 compat/qsort_s.c
create mode 100755 t/perf/p0071-sort.sh
--
2.11.0
^ permalink raw reply
* RE: [PATCH] git-p4: Fix git-p4.mapUser on Windows
From: George Vanburgh @ 2017-01-22 14:14 UTC (permalink / raw)
To: 'Luke Diamand'
Cc: 'Lars Schneider', 'Git mailing list'
In-Reply-To: <CAE5ih7_+Vc9oqKdjo8h2vgZPup4pto9wd=sBb=W6hCs4tuW2Jg@mail.gmail.com>
> On 22 Jan 2017, at 13:05, Luke Diamand <luke@diamand.org>
>
> I'm confused....see below.
That now makes two of us!
I think I've figured out where I messed up, see below.
>
> On 21 January 2017 at 15:21, George Vanburgh <george@vanburgh.me>
> wrote:
> >> On 21 Jan 2017, at 13:33, Lars Schneider <larsxschneider@gmail.com>
> >> > On 21 Jan 2017, at 13:02, George Vanburgh <george@vanburgh.me>
> >> wrote:
> >> >
> >> > From: George Vanburgh <gvanburgh@bloomberg.net>
> >> >
> >> > When running git-p4 on Windows, with multiple git-p4.mapUser
> >> > entries in git config - no user mappings are applied to the
> >> > generated
> > repository.
> >> >
> >> > Reproduction Steps:
> >> >
> >> > 1. Add multiple git-p4.mapUser entries to git config on a Windows
> >> > machine
> >> > 2. Attempt to clone a p4 repository
> >> >
> >> > None of the user mappings will be applied.
> >> >
> >> > This issue is caused by the fact that gitConfigList, uses
> >> > split(os.linesep) to convert the output of git config --get-all
> >> > into a list.
> >> >
> >> > On Windows, os.linesep is equal to '\r\n' - however git.exe returns
> >> > configuration with a line seperator of '\n'. This leads to the list
> >> > returned by gitConfigList containing only one element - which
> >> > contains the full output of git config --get-all in string form.
> >> > This causes problems for the code introduced to
> >> > getUserMapFromPerforceServer in 10d08a1.
> >> >
> >> > This issue should be caught by the test introduced in 10d08a1, and
> >> > would require running on Windows to reproduce. When running inside
> >> > MinGW/Cygwin, however, os.linesep correctly returns '\n', and
> >> > everything works as expected.
> >>
> >> This surprises me. I would expect `\r\n` in a MinGW env...
> >> Nevertheless, I wouldn't have caught that as I don't run the git-p4
> >> tests
> > on
> >> Windows...
> >
> > It appears I was mistaken - the successful tests I ran were actually
> > under the Ubuntu subsystem for Windows, which (obviously) passed.
> >
> > Just did a quick experiment:
> >
> > Git Bash (MinGW):
> > georg@TEMPEST MINGW64 ~
> > $ python -c "import os
> > print(repr(os.linesep))"
> > '\r\n'
> >
> > Powershell:
> > PS C:\Users\georg> python -c "import os
> >>> print(repr(os.linesep))"
> > '\r\n'
> >
> > Ubuntu subsystem for Windows:
> > george@TEMPEST:~$ python -c "import os print(repr(os.linesep))"
> > '\n'
> >
> > So this issue applies to git-p4 running under both PowerShell and MinGW.
> >
> >>
> >>
> >> > The simplest fix for this issue would be to convert the line split
> >> > logic inside gitConfigList to use splitlines(), which splits on any
> >> > standard line delimiter. However, this function was only introduced
> >> > in Python 2.7, and would mean a bump in the minimum required
> >> > version of Python required to run git-p4. The alternative fix,
> >> > implemented here, is to use '\n' as a delimiter, which git.exe
> >> > appears to output consistently on Windows anyway.
>
> Have you tried a 2.6 Python with splitlines? I just tried this code and it seems
> fine.
>
> > val = s.strip().splitlines()
> > print("splitlines:", val)
>
> Tried with 2.7 and 2.6, and bot print out an array of strings returned from
> read_pipe().
>
> And 'grep -r splitlines' on the Python2.6 source has lots of hits.
Ah - it appears I was looking in the wrong part of the Python
documentation - which is what lead me to think this.
From the Python 2.4 documentation:
https://docs.python.org/release/2.4/lib/string-methods.html
Splitlines is a built-in method, not part of the string class.
> george@TEMPEST:~# /home/george/.pyenv/versions/2.4.1/bin/python -c 'import string
> print("test1\ntest2\r\ntest3".splitlines())'
> ['test1', 'test2', 'test3']
>
> >>
> >> Well, that also means if we ever use splitlines() then your fix below
> > would
> >> brake the code, right?
> >>
> >> Python 2.7 was released 7 years ago in 2010.
> >
> > Now I feel old...
>
> :-)
>
> >
> >> Therefore, I would vote to
> >> bump the minimum version. But that's just my opinion :-)
> >
> > I feel like splitlines is the better/safer fix - but figured bumping
> > the minimum Python version was probably part of a wider discussion. If
> > it's something people are comfortable with - I'd be happy to rework
> > the fix to use splitlines.
> > Luke - do you have any thoughts on this?
>
> I agree that we have to stop supporting 2.6 at some point (and start
> supporting 3.x, but that's another world of hurt). But does 2.6 really not have
> splitlines?
The minimum supported version is currently Python 2.4, no?
>
> If you send a patch with splitlines I can try it out (although I guess it could be
> broken under Windows).
Given that there doesn't _actually_ seem to be an issue with using splitlines in
2.4 (sorry for the confusion!) - I'll test out a patch using splitlines on
Windows, and resubmit =]
>
> Luke
^ permalink raw reply
* Re: [PATCH] git-p4: Fix git-p4.mapUser on Windows
From: Luke Diamand @ 2017-01-22 13:04 UTC (permalink / raw)
To: George Vanburgh; +Cc: Lars Schneider, Git mailing list
In-Reply-To: <000f01d273fa$05358ee0$0fa0aca0$@vanburgh.me>
I'm confused....see below.
On 21 January 2017 at 15:21, George Vanburgh <george@vanburgh.me> wrote:
>> On 21 Jan 2017, at 13:33, Lars Schneider <larsxschneider@gmail.com>
>> > On 21 Jan 2017, at 13:02, George Vanburgh <george@vanburgh.me>
>> wrote:
>> >
>> > From: George Vanburgh <gvanburgh@bloomberg.net>
>> >
>> > When running git-p4 on Windows, with multiple git-p4.mapUser entries
>> > in git config - no user mappings are applied to the generated
> repository.
>> >
>> > Reproduction Steps:
>> >
>> > 1. Add multiple git-p4.mapUser entries to git config on a Windows
>> > machine
>> > 2. Attempt to clone a p4 repository
>> >
>> > None of the user mappings will be applied.
>> >
>> > This issue is caused by the fact that gitConfigList, uses
>> > split(os.linesep) to convert the output of git config --get-all into a
>> > list.
>> >
>> > On Windows, os.linesep is equal to '\r\n' - however git.exe returns
>> > configuration with a line seperator of '\n'. This leads to the list
>> > returned by gitConfigList containing only one element - which contains
>> > the full output of git config --get-all in string form. This causes
>> > problems for the code introduced to getUserMapFromPerforceServer in
>> > 10d08a1.
>> >
>> > This issue should be caught by the test introduced in 10d08a1, and
>> > would require running on Windows to reproduce. When running inside
>> > MinGW/Cygwin, however, os.linesep correctly returns '\n', and
>> > everything works as expected.
>>
>> This surprises me. I would expect `\r\n` in a MinGW env...
>> Nevertheless, I wouldn't have caught that as I don't run the git-p4 tests
> on
>> Windows...
>
> It appears I was mistaken - the successful tests I ran were actually under
> the Ubuntu subsystem for Windows, which (obviously) passed.
>
> Just did a quick experiment:
>
> Git Bash (MinGW):
> georg@TEMPEST MINGW64 ~
> $ python -c "import os
> print(repr(os.linesep))"
> '\r\n'
>
> Powershell:
> PS C:\Users\georg> python -c "import os
>>> print(repr(os.linesep))"
> '\r\n'
>
> Ubuntu subsystem for Windows:
> george@TEMPEST:~$ python -c "import os
> print(repr(os.linesep))"
> '\n'
>
> So this issue applies to git-p4 running under both PowerShell and MinGW.
>
>>
>>
>> > The simplest fix for this issue would be to convert the line split
>> > logic inside gitConfigList to use splitlines(), which splits on any
>> > standard line delimiter. However, this function was only introduced in
>> > Python 2.7, and would mean a bump in the minimum required version of
>> > Python required to run git-p4. The alternative fix, implemented here,
>> > is to use '\n' as a delimiter, which git.exe appears to output
>> > consistently on Windows anyway.
Have you tried a 2.6 Python with splitlines? I just tried this code
and it seems fine.
> val = s.strip().splitlines()
> print("splitlines:", val)
Tried with 2.7 and 2.6, and bot print out an array of strings returned
from read_pipe().
And 'grep -r splitlines' on the Python2.6 source has lots of hits.
>>
>> Well, that also means if we ever use splitlines() then your fix below
> would
>> brake the code, right?
>>
>> Python 2.7 was released 7 years ago in 2010.
>
> Now I feel old...
:-)
>
>> Therefore, I would vote to
>> bump the minimum version. But that's just my opinion :-)
>
> I feel like splitlines is the better/safer fix - but figured bumping the
> minimum
> Python version was probably part of a wider discussion. If it's something
> people
> are comfortable with - I'd be happy to rework the fix to use splitlines.
> Luke - do you have any thoughts on this?
I agree that we have to stop supporting 2.6 at some point (and start
supporting 3.x, but that's another world of hurt). But does 2.6 really
not have splitlines?
If you send a patch with splitlines I can try it out (although I guess
it could be broken under Windows).
Luke
^ permalink raw reply
* [PATCH 2/2] git-prompt.sh: rework of submodule indicator
From: Benjamin Fuchs @ 2017-01-22 9:07 UTC (permalink / raw)
To: git; +Cc: szeder.dev, sbeller, email
Rework of the first patch. The prompt now will look like this:
(+name:master). I tried to considere all suggestions.
Tests still missing.
---
contrib/completion/git-prompt.sh | 49 ++++++++++++++++++++--------------------
1 file changed, 24 insertions(+), 25 deletions(-)
diff --git a/contrib/completion/git-prompt.sh b/contrib/completion/git-prompt.sh
index 4c82e7f..c44b9a2 100644
--- a/contrib/completion/git-prompt.sh
+++ b/contrib/completion/git-prompt.sh
@@ -95,8 +95,10 @@
# repository level by setting bash.hideIfPwdIgnored to "false".
#
# If you would like __git_ps1 to indicate that you are in a submodule,
-# set GIT_PS1_SHOWSUBMODULE. In this case a "sub:" will be added before
-# the branch name.
+# set GIT_PS1_SHOWSUBMODULE to a nonempty value. In this case the name
+# of the submodule will be prepended to the branch name (e.g. module:master).
+# The name will be prepended by "+" if the currently checked out submodule
+# commit does not match the SHA-1 found in the index of the containing repository.
# check whether printf supports -v
__git_printf_supports_v=
@@ -288,30 +290,27 @@ __git_eread ()
test -r "$f" && read "$@" <"$f"
}
-# __git_is_submodule
-# Based on:
-# http://stackoverflow.com/questions/7359204/git-command-line-know-if-in-submodule
-__git_is_submodule ()
-{
- local git_dir parent_git module_name path
- # Find the root of this git repo, then check if its parent dir is also a repo
- git_dir="$(git rev-parse --show-toplevel)"
- module_name="$(basename "$git_dir")"
- parent_git="$(cd "$git_dir/.." && git rev-parse --show-toplevel 2> /dev/null)"
- if [[ -n $parent_git ]]; then
- # List all the submodule paths for the parent repo
- while read path
- do
- if [[ "$path" != "$module_name" ]]; then continue; fi
- if [[ -d "$git_dir/../$path" ]]; then return 0; fi
- done < <(cd $parent_git && git submodule --quiet foreach 'echo $path' 2> /dev/null)
- fi
- return 1
-}
-
+# __git_ps1_submodule
+#
+# $1 - git_dir path
+#
+# Returns the name of the submodule if we are currently inside one. The name
+# will be prepended by "+" if the currently checked out submodule commit does
+# not match the SHA-1 found in the index of the containing repository.
+# NOTE: git_dir looks like in a ...
+# - submodule: "GIT_PARENT/.git/modules/PATH_TO_SUBMODULE"
+# - parent: "GIT_PARENT/.git" (exception "." in .git)
__git_ps1_submodule ()
{
- __git_is_submodule && printf "sub:"
+ local git_dir="$1"
+ local submodule_name="$(basename "$git_dir")"
+ if [ "$submodule_name" != ".git" ] && [ "$submodule_name" != "." ]; then
+ local parent_top="${git_dir%.git*}"
+ local submodule_top="${git_dir#*modules}"
+ local status=""
+ git diff -C "$parent_top" --no-ext-diff --ignore-submodules=dirty --quiet -- "$submodule_top" 2>/dev/null || status="+"
+ printf "$status$submodule_name:"
+ fi
}
# __git_ps1 accepts 0 or 1 arguments (i.e., format string)
@@ -545,7 +544,7 @@ __git_ps1 ()
local sub=""
if [ -n "${GIT_PS1_SHOWSUBMODULE}" ]; then
- sub="$(__git_ps1_submodule)"
+ sub="$(__git_ps1_submodule $g)"
fi
local f="$w$i$s$u"
--
2.7.4
^ permalink raw reply related
* Draft of Git Rev News edition 23
From: Christian Couder @ 2017-01-22 7:59 UTC (permalink / raw)
To: git
Cc: Thomas Ferris Nicolaisen, Jakub Narebski, Markus Jansen,
Junio C Hamano, Johannes Schindelin, Jeff King, Stefan Beller,
Jacob Keller, Eric Wong, Eduardo Habkost, Pranit Bauva,
Andreas Schwab, Javantea, Aneesh Kumar K.V, Philip Oakley
Hi,
A draft of a new Git Rev News edition is available here:
https://github.com/git/git.github.io/blob/master/rev_news/drafts/edition-23.md
Everyone is welcome to contribute in any section either by editing the
above page on GitHub and sending a pull request, or by commenting on
this GitHub issue:
https://github.com/git/git.github.io/issues/209
You can also reply to this email.
In general all kinds of contribution, for example proofreading,
suggestions for articles or links, help on the issues in GitHub, and
so on, are very much appreciated.
I tried to cc everyone who appears in this edition but maybe I missed
some people, sorry about that.
Thomas, Jakub, Markus and myself plan to publish this edition on
Wednesday January 25.
Thanks,
Christian.
^ permalink raw reply
* Re: [PATCH] difftool.c: mark a file-local symbol with static
From: David Aguilar @ 2017-01-22 5:26 UTC (permalink / raw)
To: Jeff King
Cc: Junio C Hamano, Ramsay Jones, Johannes Schindelin,
GIT Mailing-list
In-Reply-To: <20161201185056.eso5rhec7izlbywa@sigill.intra.peff.net>
On Thu, Dec 01, 2016 at 01:50:57PM -0500, Jeff King wrote:
> On Thu, Dec 01, 2016 at 10:20:50AM -0800, Junio C Hamano wrote:
> > I also still think that any_printf_like_function("%s", "") looks
> > silly. I know that we've already started moving in that direction
> > and we stopped at a place we do not want to be in, but perhaps it
> > was a mistake to move in that direction in the first place. I am
> > tempted to say we should do something like the attached, but that
> > may not fly well, as I suspect that -Wno-format-zero-length may be a
> > lot more exotic than the -Wall compiler option.
>
> Yeah, I think portability concerns are what caused us not to go down
> that road in the first place.
> makes it harder to disable if your compiler doesn't like it.
>
> > An obvious second
> > best option would be to drop -Wall from the "everybody" CFLAGS and
> > move it to DEVELOPER_CFLAGS instead.
>
> Yeah, though that doesn't help the example above.
>
> As ugly as warning("%s", "") is, I think it may be the thing that annoys
> the smallest number of people.
>
> -Peff
How about using warning(" ") instead?
For difftool.c specifically, the following is a fine solution,
and doesn't require that we change our warning flags just for
this one file.
--
David
--- 8< ---
From 28bdc381202ced35399cfdf4899a019b0000c7a0 Mon Sep 17 00:00:00 2001
From: David Aguilar <davvid@gmail.com>
Date: Sat, 21 Jan 2017 21:21:09 -0800
Subject: [PATCH] difftool: avoid zero-length format string
The purpose of the warning("") line is to add an empty line to
improve the readability of the message.
Use warning(" ") instead to avoid zero-length format string
warnings while retaining the desired behavior.
Signed-off-by: David Aguilar <davvid@gmail.com>
---
builtin/difftool.c | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/builtin/difftool.c b/builtin/difftool.c
index 42ad9e804a..d9f8ada291 100644
--- a/builtin/difftool.c
+++ b/builtin/difftool.c
@@ -567,7 +567,7 @@ static int run_dir_diff(const char *extcmd, int symlinks, const char *prefix,
warning(_("both files modified: '%s' and '%s'."),
wtdir.buf, rdir.buf);
warning(_("working tree file has been left."));
- warning("");
+ warning(" ");
err = 1;
} else if (unlink(wtdir.buf) ||
copy_file(wtdir.buf, rdir.buf, st.st_mode))
--
2.11.0.747.g28bdc38120
^ permalink raw reply related
* [PATCH v2 5/7] Documentation: add XSLT to fix DocBook for Texinfo
From: brian m. carlson @ 2017-01-22 2:41 UTC (permalink / raw)
To: git; +Cc: Johannes Schindelin, Jeff King
In-Reply-To: <20170122024156.284180-1-sandals@crustytoothpaste.net>
There are two ways to create a section in a reference document (i.e.,
manpage) in DocBook 4: refsection elements and refsect, refsect2, and
refsect3 elements. Either form is acceptable as of DocBook 4.2, but
they cannot be mixed. Prior to DocBook 4.2, only the numbered forms
were acceptable.
docbook2texi only accepts the numbered forms, and this has not generally
been a problem, since AsciiDoc produces the numbered forms.
Asciidoctor, on the other hand, uses a shared backend for DocBook 4 and
5, and uses the unnumbered refsection elements instead.
If we don't convert the unnumbered form to the numbered form,
docbook2texi omits section headings, which is undesirable. Add an XSLT
stylesheet to transform the unnumbered forms to the numbered forms
automatically, and preprocess the DocBook XML as part of the
transformation to Texinfo format.
Note that this transformation is only necessary for Texinfo, since
docbook2texi provides its own stylesheets. The DocBook stylesheets,
which we use for other formats, provide the full range of DocBook 4 and
5 compatibility, and don't have this issue.
Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
---
Documentation/Makefile | 7 ++++---
Documentation/texi.xsl | 26 ++++++++++++++++++++++++++
2 files changed, 30 insertions(+), 3 deletions(-)
create mode 100644 Documentation/texi.xsl
diff --git a/Documentation/Makefile b/Documentation/Makefile
index 6e6c82409..76be7017c 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -371,10 +371,11 @@ user-manual.pdf: user-manual.xml
$(DBLATEX) -o $@+ -p $(ASCIIDOC_DBLATEX_DIR)/asciidoc-dblatex.xsl -s $(ASCIIDOC_DBLATEX_DIR)/asciidoc-dblatex.sty $< && \
mv $@+ $@
-gitman.texi: $(MAN_XML) cat-texi.perl
+gitman.texi: $(MAN_XML) cat-texi.perl texi.xsl
$(QUIET_DB2TEXI)$(RM) $@+ $@ && \
- ($(foreach xml,$(sort $(MAN_XML)),$(DOCBOOK2X_TEXI) --encoding=UTF-8 \
- --to-stdout $(xml) &&) true) > $@++ && \
+ ($(foreach xml,$(sort $(MAN_XML)),xsltproc -o $(xml)+ texi.xsl $(xml) && \
+ $(DOCBOOK2X_TEXI) --encoding=UTF-8 --to-stdout $(xml)+ && \
+ rm $(xml)+ &&) true) > $@++ && \
$(PERL_PATH) cat-texi.perl $@ <$@++ >$@+ && \
rm $@++ && \
mv $@+ $@
diff --git a/Documentation/texi.xsl b/Documentation/texi.xsl
new file mode 100644
index 000000000..0f8ff07ec
--- /dev/null
+++ b/Documentation/texi.xsl
@@ -0,0 +1,26 @@
+<!-- texi.xsl:
+ convert refsection elements into refsect elements that docbook2texi can
+ understand -->
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+ version="1.0">
+
+<xsl:output method="xml"
+ encoding="UTF-8"
+ doctype-public="-//OASIS//DTD DocBook XML V4.5//EN"
+ doctype-system="http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" />
+
+<xsl:template match="//refsection">
+ <xsl:variable name="element">refsect<xsl:value-of select="count(ancestor-or-self::refsection)" /></xsl:variable>
+ <xsl:element name="{$element}">
+ <xsl:apply-templates select="@*|node()" />
+ </xsl:element>
+</xsl:template>
+
+<!-- Copy all other nodes through. -->
+<xsl:template match="node()|@*">
+ <xsl:copy>
+ <xsl:apply-templates select="@*|node()" />
+ </xsl:copy>
+</xsl:template>
+
+</xsl:stylesheet>
^ permalink raw reply related
* [PATCH v2 7/7] Makefile: add a knob to enable the use of Asciidoctor
From: brian m. carlson @ 2017-01-22 2:41 UTC (permalink / raw)
To: git; +Cc: Johannes Schindelin, Jeff King
In-Reply-To: <20170122024156.284180-1-sandals@crustytoothpaste.net>
While Git has traditionally built its documentation using AsciiDoc, some
people wish to use Asciidoctor for speed or other reasons. Add a
Makefile knob, USE_ASCIIDOCTOR, that sets various options in order to
produce acceptable output. For HTML output, XHTML5 was chosen, since
the AsciiDoc options also produce XHTML, albeit XHTML 1.1.
Asciidoctor does not have built-in support for the linkgit macro, but it
is available using the Asciidoctor Extensions Lab. Add a macro to
enable the use of this extension if it is available. Without it, the
linkgit macros are emitted into the output.
Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
---
Documentation/Makefile | 12 ++++++++++++
Makefile | 6 ++++++
2 files changed, 18 insertions(+)
diff --git a/Documentation/Makefile b/Documentation/Makefile
index d95002e62..19c42eb60 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -174,6 +174,18 @@ ifdef GNU_ROFF
XMLTO_EXTRA += -m manpage-quote-apos.xsl
endif
+ifdef USE_ASCIIDOCTOR
+ASCIIDOC = asciidoctor
+ASCIIDOC_CONF =
+ASCIIDOC_HTML = xhtml5
+ASCIIDOC_DOCBOOK = docbook45
+ifdef ASCIIDOCTOR_EXTENSIONS_LAB
+ASCIIDOC_EXTRA = -I$(ASCIIDOCTOR_EXTENSIONS_LAB) -rasciidoctor/extensions -rman-inline-macro
+endif
+ASCIIDOC_EXTRA += -alitdd='&\#x2d;&\#x2d;'
+DBLATEX_COMMON =
+endif
+
SHELL_PATH ?= $(SHELL)
# Shell quote;
SHELL_PATH_SQ = $(subst ','\'',$(SHELL_PATH))
diff --git a/Makefile b/Makefile
index 27afd0f37..7ed9d4d4b 100644
--- a/Makefile
+++ b/Makefile
@@ -250,6 +250,12 @@ all::
# 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.
+#
+# Define ASCIIDOCTOR_EXTENSIONS_LAB to point to the location of the Asciidoctor
+# Extensions Lab if you have it available.
+#
# Define PERL_PATH to the path of your Perl binary (usually /usr/bin/perl).
#
# Define NO_PERL_MAKEMAKER if you cannot use Makefiles generated by perl's
^ permalink raw reply related
* [PATCH v2 6/7] Documentation: move dblatex arguments into variable
From: brian m. carlson @ 2017-01-22 2:41 UTC (permalink / raw)
To: git; +Cc: Johannes Schindelin, Jeff King
In-Reply-To: <20170122024156.284180-1-sandals@crustytoothpaste.net>
Our dblatex invocation uses several style components from the AsciiDoc
distribution, but those components are not available when building with
Asciidoctor. Move the command line arguments into a variable so it can
be overridden by the user or makefile configuration options.
Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
---
Documentation/Makefile | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)
diff --git a/Documentation/Makefile b/Documentation/Makefile
index 76be7017c..d95002e62 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -120,6 +120,7 @@ INSTALL_INFO = install-info
DOCBOOK2X_TEXI = docbook2x-texi
DBLATEX = dblatex
ASCIIDOC_DBLATEX_DIR = /etc/asciidoc/dblatex
+DBLATEX_COMMON = -p $(ASCIIDOC_DBLATEX_DIR)/asciidoc-dblatex.xsl -s $(ASCIIDOC_DBLATEX_DIR)/asciidoc-dblatex.sty
ifndef PERL_PATH
PERL_PATH = /usr/bin/perl
endif
@@ -368,7 +369,7 @@ user-manual.texi: user-manual.xml
user-manual.pdf: user-manual.xml
$(QUIET_DBLATEX)$(RM) $@+ $@ && \
- $(DBLATEX) -o $@+ -p $(ASCIIDOC_DBLATEX_DIR)/asciidoc-dblatex.xsl -s $(ASCIIDOC_DBLATEX_DIR)/asciidoc-dblatex.sty $< && \
+ $(DBLATEX) -o $@+ $(DBLATEX_COMMON) $< && \
mv $@+ $@
gitman.texi: $(MAN_XML) cat-texi.perl texi.xsl
^ permalink raw reply related
* [PATCH v2 2/7] Documentation: modernize cat-texi.perl
From: brian m. carlson @ 2017-01-22 2:41 UTC (permalink / raw)
To: git; +Cc: Johannes Schindelin, Jeff King
In-Reply-To: <20170122024156.284180-1-sandals@crustytoothpaste.net>
Good style for Perl includes using the strict and warnings pragmas, and
preferring lexical file handles over bareword file handles. Using
lexical file handles necessitates being explicit when $_ is printed, so
that Perl does not get confused and instead print the glob ref.
The benefit of this modernization is that a formerly obscured bug is now
visible, which will be fixed in a followup patch.
Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
---
Documentation/cat-texi.perl | 15 +++++++++------
1 file changed, 9 insertions(+), 6 deletions(-)
diff --git a/Documentation/cat-texi.perl b/Documentation/cat-texi.perl
index b1fe52e8b..1bc84d3c7 100755
--- a/Documentation/cat-texi.perl
+++ b/Documentation/cat-texi.perl
@@ -1,9 +1,12 @@
#!/usr/bin/perl -w
+use strict;
+use warnings;
+
my @menu = ();
my $output = $ARGV[0];
-open TMP, '>', "$output.tmp";
+open my $tmp, '>', "$output.tmp";
while (<STDIN>) {
next if (/^\\input texinfo/../\@node Top/);
@@ -13,9 +16,9 @@ while (<STDIN>) {
}
s/\(\@pxref\{\[(URLS|REMOTES)\]}\)//;
s/\@anchor\{[^{}]*\}//g;
- print TMP;
+ print $tmp $_;
}
-close TMP;
+close $tmp;
printf '\input texinfo
@setfilename gitman.info
@@ -34,10 +37,10 @@ for (@menu) {
print "* ${_}::\n";
}
print "\@end menu\n";
-open TMP, '<', "$output.tmp";
-while (<TMP>) {
+open $tmp, '<', "$output.tmp";
+while (<$tmp>) {
print;
}
-close TMP;
+close $tmp;
print "\@bye\n";
unlink "$output.tmp";
^ permalink raw reply related
* [PATCH v2 3/7] Documentation: remove unneeded argument in cat-texi.perl
From: brian m. carlson @ 2017-01-22 2:41 UTC (permalink / raw)
To: git; +Cc: Johannes Schindelin, Jeff King
In-Reply-To: <20170122024156.284180-1-sandals@crustytoothpaste.net>
The newly-added use of the warnings pragma exposes that the $menu[0]
argument to printf has long been silently ignored, since there is no
format specifier for it. It doesn't appear that the argument is
actually needed, either: there is no reason to insert the name of one
particular documentation page anywhere in the header that's being
generated.
Remove the unused argument, and since the format specification
functionality is no longer needed, convert the printf to a simple print.
Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
---
Documentation/cat-texi.perl | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/Documentation/cat-texi.perl b/Documentation/cat-texi.perl
index 1bc84d3c7..14d2f8341 100755
--- a/Documentation/cat-texi.perl
+++ b/Documentation/cat-texi.perl
@@ -20,7 +20,7 @@ while (<STDIN>) {
}
close $tmp;
-printf '\input texinfo
+print '\input texinfo
@setfilename gitman.info
@documentencoding UTF-8
@dircategory Development
@@ -31,7 +31,7 @@ printf '\input texinfo
@top Git Manual Pages
@documentlanguage en
@menu
-', $menu[0];
+';
for (@menu) {
print "* ${_}::\n";
^ permalink raw reply related
* [PATCH v2 4/7] Documentation: sort sources for gitman.texi
From: brian m. carlson @ 2017-01-22 2:41 UTC (permalink / raw)
To: git; +Cc: Johannes Schindelin, Jeff King
In-Reply-To: <20170122024156.284180-1-sandals@crustytoothpaste.net>
Sorting the sources makes it easier to compare the output using diff.
In addition, it aids groups creating reproducible builds, as the order
of the files is no longer dependent on the file system or other
irrelevant factors.
Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
---
Documentation/Makefile | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/Documentation/Makefile b/Documentation/Makefile
index a9fb497b8..6e6c82409 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -373,7 +373,7 @@ user-manual.pdf: user-manual.xml
gitman.texi: $(MAN_XML) cat-texi.perl
$(QUIET_DB2TEXI)$(RM) $@+ $@ && \
- ($(foreach xml,$(MAN_XML),$(DOCBOOK2X_TEXI) --encoding=UTF-8 \
+ ($(foreach xml,$(sort $(MAN_XML)),$(DOCBOOK2X_TEXI) --encoding=UTF-8 \
--to-stdout $(xml) &&) true) > $@++ && \
$(PERL_PATH) cat-texi.perl $@ <$@++ >$@+ && \
rm $@++ && \
^ permalink raw reply related
* [PATCH v2 0/7] Macros for Asciidoctor support
From: brian m. carlson @ 2017-01-22 2:41 UTC (permalink / raw)
To: git; +Cc: Johannes Schindelin, Jeff King
There are two major processors of AsciiDoc: AsciiDoc itself, and Asciidoctor.
Both have advantages and disadvantages, but traditionally the documentation has
been built with AsciiDoc, leading to some surprising breakage when building with
Asciidoctor. Partially, this is due to the need to specify a significant number
of macros on the command line when building with Asciidoctor.
This series cleans up some issues building the documentation with Asciidoctor
and provides two knobs, USE_ASCIIDOCTOR, which controls building with
Asciidoctor, and ASCIIDOCTOR_EXTENSIONS_LAB, which controls the location of the
Asciidoctor Extensions Lab, which is necessary to expand the linkgit macro.
The need for the extensions could be replaced with a small amount of Ruby code,
if that's considered desirable. Previous opinions on doing so were negative,
however.
In the process, I found several issues with cat-texi.perl, which have been
fixed. It has also been modernized to use strict, warnings, and lexical file
handles. I also made an attempt to produce more diffable texi files; I may
follow up with additional series along this line to make the documentation build
reproducibly.
Changes from v1:
* Fix a brown-paper-bag bug.
brian m. carlson (7):
Documentation: fix warning in cat-texi.perl
Documentation: modernize cat-texi.perl
Documentation: remove unneeded argument in cat-texi.perl
Documentation: sort sources for gitman.texi
Documentation: add XSLT to fix DocBook for Texinfo
Documentation: move dblatex arguments into variable
Makefile: add a knob to enable the use of Asciidoctor
Documentation/Makefile | 22 ++++++++++++++++++----
Documentation/cat-texi.perl | 21 ++++++++++++---------
Documentation/texi.xsl | 26 ++++++++++++++++++++++++++
Makefile | 6 ++++++
4 files changed, 62 insertions(+), 13 deletions(-)
create mode 100644 Documentation/texi.xsl
^ permalink raw reply
* [PATCH v2 1/7] Documentation: fix warning in cat-texi.perl
From: brian m. carlson @ 2017-01-22 2:41 UTC (permalink / raw)
To: git; +Cc: Johannes Schindelin, Jeff King
In-Reply-To: <20170122024156.284180-1-sandals@crustytoothpaste.net>
Newer versions of Perl produce the warning "Unescaped left brace in
regex is deprecated, passed through in regex" when an unescaped left
brace occurs in a regex. Escape the brace to avoid this warning.
Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
---
Documentation/cat-texi.perl | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/Documentation/cat-texi.perl b/Documentation/cat-texi.perl
index 87437f8a9..b1fe52e8b 100755
--- a/Documentation/cat-texi.perl
+++ b/Documentation/cat-texi.perl
@@ -11,7 +11,7 @@ while (<STDIN>) {
if (s/^\@top (.*)/\@node $1,,,Top/) {
push @menu, $1;
}
- s/\(\@pxref{\[(URLS|REMOTES)\]}\)//;
+ s/\(\@pxref\{\[(URLS|REMOTES)\]}\)//;
s/\@anchor\{[^{}]*\}//g;
print TMP;
}
^ permalink raw reply related
* Re: [PATCH 6/7] Documentation: move dblatex arguments into variable
From: Øyvind A. Holm @ 2017-01-22 1:03 UTC (permalink / raw)
To: brian m. carlson; +Cc: git, Johannes Schindelin, Jeff King
In-Reply-To: <20170121215912.246691-7-sandals@crustytoothpaste.net>
[-- Attachment #1: Type: text/plain, Size: 920 bytes --]
On 2017-01-21 21:59:11, brian m. carlson wrote:
> Our dblatex invocation uses several style components from the AsciiDoc
> distribution, but those components are not available when building with
> Asciidoctor. Move the command line arguments into a variable so it can
> be overridden by the user or makefile configuration options.
> [...]
> - $(DBLATEX) -o $@+ -p $(ASCIIDOC_DBLATEX_DIR)/asciidoc-dblatex.xsl -s $(ASCIIDOC_DBLATEX_DIR)/asciidoc-dblatex.sty $< && \
> + $(DBLATEX) $-o $@+ (DBLATEX_COMMON) $< && \
It looks as the dollar sign is in the wrong place, should be in front of
(DBLATEX_COMMON).
Regards,
Øyvind
+-| Øyvind A. Holm <sunny@sunbase.org> - N 60.37604° E 5.33339° |-+
| OpenPGP: 0xFB0CBEE894A506E5 - http://www.sunbase.org/pubkey.asc |
| Fingerprint: A006 05D6 E676 B319 55E2 E77E FB0C BEE8 94A5 06E5 |
+------------| 61815930-e03e-11e6-b4f4-db5caa6d21d3 |-------------+
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 181 bytes --]
^ permalink raw reply
* Re: [PATCH 1/3] Documentation/stash: remove mention of git reset --hard
From: Øyvind A. Holm @ 2017-01-22 1:27 UTC (permalink / raw)
To: Thomas Gummerer; +Cc: git
In-Reply-To: <20170121200804.19009-2-t.gummerer@gmail.com>
[-- Attachment #1: Type: text/plain, Size: 712 bytes --]
On 2017-01-21 20:08:02, Thomas Gummerer wrote:
> Don't mention git reset --hard in the documentation for git stash save.
> It's an implementation detail that doesn't matter to the end user and
> thus shouldn't be exposed to them.
> [...]
> + Save your local modifications to a new 'stash', and revert the
> + the changes in the working tree to match the index.
The patch contains a duplicated "the".
Regards,
Øyvind
+-| Øyvind A. Holm <sunny@sunbase.org> - N 60.37604° E 5.33339° |-+
| OpenPGP: 0xFB0CBEE894A506E5 - http://www.sunbase.org/pubkey.asc |
| Fingerprint: A006 05D6 E676 B319 55E2 E77E FB0C BEE8 94A5 06E5 |
+------------| 42073b1c-e041-11e6-bae1-db5caa6d21d3 |-------------+
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 181 bytes --]
^ permalink raw reply
* Re: Idea: Add a filter option to 'git rebase'
From: Philip Oakley @ 2017-01-21 23:18 UTC (permalink / raw)
To: Git List, Thomas Braun; +Cc: Johannes Schindelin
In-Reply-To: <0bd00cda-65d0-eeba-d8b9-a839e76d8e88@virtuell-zuhause.de>
From: "Thomas Braun" Friday, January 20, 2017 11:35 PM
> Am 20.01.2017 um 23:28 schrieb Philip Oakley:
>> A recent question on stackoverflow
>> http://stackoverflow.com/questions/41753252/drop-commits-by-commit-message-in-git-rebase
>> sought to remove automatically commits that could be identified by
>> relevant words in the commit message.
>>
>> I had thought that the ubiquitous `git filter-branch` should be able to
>> do this sort of thing. I was wrong. (It was pointed out to me that...)
>> The man page notes that removing a commit via filter-branch does not
>> remove the changes from following commits and directs readers to using
>> `git rebase(1)`.
>>
>> However the rebase command does not have any filter option to allow the
>> automatic population of its TODO list with the appropriate
>> pick/edit/drop/etc. values.
>
> Well you can use an arbitrary shell command as editor, so something like
>
> $ GIT_SEQUENCE_EDITOR="sed -i -re 's/^pick /edit /'" git rebase -i master
>
> will change pick to edit of all commits.
>
> Maybe that can be mentioned in the man page of rebase?
>
I had been more thinking of a process that passed single sha1's to the
filter on each pass through the rebase list, so that the coding was simpler,
plus the --interactive could be used, if required, for final refinement
(gitk being handy for that).
However, a mention in the man pages would be zero code cost, and could help.
--
Philip
^ permalink raw reply
* [PATCH 6/7] Documentation: move dblatex arguments into variable
From: brian m. carlson @ 2017-01-21 21:59 UTC (permalink / raw)
To: git; +Cc: Johannes Schindelin, Jeff King
In-Reply-To: <20170121215912.246691-1-sandals@crustytoothpaste.net>
Our dblatex invocation uses several style components from the AsciiDoc
distribution, but those components are not available when building with
Asciidoctor. Move the command line arguments into a variable so it can
be overridden by the user or makefile configuration options.
Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
---
Documentation/Makefile | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)
diff --git a/Documentation/Makefile b/Documentation/Makefile
index 76be7017c..0f4db48eb 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -120,6 +120,7 @@ INSTALL_INFO = install-info
DOCBOOK2X_TEXI = docbook2x-texi
DBLATEX = dblatex
ASCIIDOC_DBLATEX_DIR = /etc/asciidoc/dblatex
+DBLATEX_COMMON = -p $(ASCIIDOC_DBLATEX_DIR)/asciidoc-dblatex.xsl -s $(ASCIIDOC_DBLATEX_DIR)/asciidoc-dblatex.sty
ifndef PERL_PATH
PERL_PATH = /usr/bin/perl
endif
@@ -368,7 +369,7 @@ user-manual.texi: user-manual.xml
user-manual.pdf: user-manual.xml
$(QUIET_DBLATEX)$(RM) $@+ $@ && \
- $(DBLATEX) -o $@+ -p $(ASCIIDOC_DBLATEX_DIR)/asciidoc-dblatex.xsl -s $(ASCIIDOC_DBLATEX_DIR)/asciidoc-dblatex.sty $< && \
+ $(DBLATEX) $-o $@+ (DBLATEX_COMMON) $< && \
mv $@+ $@
gitman.texi: $(MAN_XML) cat-texi.perl texi.xsl
^ permalink raw reply related
* [PATCH 5/7] Documentation: add XSLT to fix DocBook for Texinfo
From: brian m. carlson @ 2017-01-21 21:59 UTC (permalink / raw)
To: git; +Cc: Johannes Schindelin, Jeff King
In-Reply-To: <20170121215912.246691-1-sandals@crustytoothpaste.net>
There are two ways to create a section in a reference document (i.e.,
manpage) in DocBook 4: refsection elements and refsect, refsect2, and
refsect3 elements. Either form is acceptable as of DocBook 4.2, but
they cannot be mixed. Prior to DocBook 4.2, only the numbered forms
were acceptable.
docbook2texi only accepts the numbered forms, and this has not generally
been a problem, since AsciiDoc produces the numbered forms.
Asciidoctor, on the other hand, uses a shared backend for DocBook 4 and
5, and uses the unnumbered refsection elements instead.
If we don't convert the unnumbered form to the numbered form,
docbook2texi omits section headings, which is undesirable. Add an XSLT
stylesheet to transform the unnumbered forms to the numbered forms
automatically, and preprocess the DocBook XML as part of the
transformation to Texinfo format.
Note that this transformation is only necessary for Texinfo, since
docbook2texi provides its own stylesheets. The DocBook stylesheets,
which we use for other formats, provide the full range of DocBook 4 and
5 compatibility, and don't have this issue.
Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
---
Documentation/Makefile | 7 ++++---
Documentation/texi.xsl | 26 ++++++++++++++++++++++++++
2 files changed, 30 insertions(+), 3 deletions(-)
create mode 100644 Documentation/texi.xsl
diff --git a/Documentation/Makefile b/Documentation/Makefile
index 6e6c82409..76be7017c 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -371,10 +371,11 @@ user-manual.pdf: user-manual.xml
$(DBLATEX) -o $@+ -p $(ASCIIDOC_DBLATEX_DIR)/asciidoc-dblatex.xsl -s $(ASCIIDOC_DBLATEX_DIR)/asciidoc-dblatex.sty $< && \
mv $@+ $@
-gitman.texi: $(MAN_XML) cat-texi.perl
+gitman.texi: $(MAN_XML) cat-texi.perl texi.xsl
$(QUIET_DB2TEXI)$(RM) $@+ $@ && \
- ($(foreach xml,$(sort $(MAN_XML)),$(DOCBOOK2X_TEXI) --encoding=UTF-8 \
- --to-stdout $(xml) &&) true) > $@++ && \
+ ($(foreach xml,$(sort $(MAN_XML)),xsltproc -o $(xml)+ texi.xsl $(xml) && \
+ $(DOCBOOK2X_TEXI) --encoding=UTF-8 --to-stdout $(xml)+ && \
+ rm $(xml)+ &&) true) > $@++ && \
$(PERL_PATH) cat-texi.perl $@ <$@++ >$@+ && \
rm $@++ && \
mv $@+ $@
diff --git a/Documentation/texi.xsl b/Documentation/texi.xsl
new file mode 100644
index 000000000..0f8ff07ec
--- /dev/null
+++ b/Documentation/texi.xsl
@@ -0,0 +1,26 @@
+<!-- texi.xsl:
+ convert refsection elements into refsect elements that docbook2texi can
+ understand -->
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+ version="1.0">
+
+<xsl:output method="xml"
+ encoding="UTF-8"
+ doctype-public="-//OASIS//DTD DocBook XML V4.5//EN"
+ doctype-system="http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" />
+
+<xsl:template match="//refsection">
+ <xsl:variable name="element">refsect<xsl:value-of select="count(ancestor-or-self::refsection)" /></xsl:variable>
+ <xsl:element name="{$element}">
+ <xsl:apply-templates select="@*|node()" />
+ </xsl:element>
+</xsl:template>
+
+<!-- Copy all other nodes through. -->
+<xsl:template match="node()|@*">
+ <xsl:copy>
+ <xsl:apply-templates select="@*|node()" />
+ </xsl:copy>
+</xsl:template>
+
+</xsl:stylesheet>
^ permalink raw reply related
* [PATCH 7/7] Makefile: add a knob to enable the use of Asciidoctor
From: brian m. carlson @ 2017-01-21 21:59 UTC (permalink / raw)
To: git; +Cc: Johannes Schindelin, Jeff King
In-Reply-To: <20170121215912.246691-1-sandals@crustytoothpaste.net>
While Git has traditionally built its documentation using AsciiDoc, some
people wish to use Asciidoctor for speed or other reasons. Add a
Makefile knob, USE_ASCIIDOCTOR, that sets various options in order to
produce acceptable output. For HTML output, XHTML5 was chosen, since
the AsciiDoc options also produce XHTML, albeit XHTML 1.1.
Asciidoctor does not have built-in support for the linkgit macro, but it
is available using the Asciidoctor Extensions Lab. Add a macro to
enable the use of this extension if it is available. Without it, the
linkgit macros are emitted into the output.
Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
---
Documentation/Makefile | 12 ++++++++++++
Makefile | 6 ++++++
2 files changed, 18 insertions(+)
diff --git a/Documentation/Makefile b/Documentation/Makefile
index 0f4db48eb..5cbecfa99 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -174,6 +174,18 @@ ifdef GNU_ROFF
XMLTO_EXTRA += -m manpage-quote-apos.xsl
endif
+ifdef USE_ASCIIDOCTOR
+ASCIIDOC = asciidoctor
+ASCIIDOC_CONF =
+ASCIIDOC_HTML = xhtml5
+ASCIIDOC_DOCBOOK = docbook45
+ifdef ASCIIDOCTOR_EXTENSIONS_LAB
+ASCIIDOC_EXTRA = -I$(ASCIIDOCTOR_EXTENSIONS_LAB) -rasciidoctor/extensions -rman-inline-macro
+endif
+ASCIIDOC_EXTRA += -alitdd='&\#x2d;&\#x2d;'
+DBLATEX_COMMON =
+endif
+
SHELL_PATH ?= $(SHELL)
# Shell quote;
SHELL_PATH_SQ = $(subst ','\'',$(SHELL_PATH))
diff --git a/Makefile b/Makefile
index 27afd0f37..7ed9d4d4b 100644
--- a/Makefile
+++ b/Makefile
@@ -250,6 +250,12 @@ all::
# 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.
+#
+# Define ASCIIDOCTOR_EXTENSIONS_LAB to point to the location of the Asciidoctor
+# Extensions Lab if you have it available.
+#
# Define PERL_PATH to the path of your Perl binary (usually /usr/bin/perl).
#
# Define NO_PERL_MAKEMAKER if you cannot use Makefiles generated by perl's
^ permalink raw reply related
* [PATCH 4/7] Documentation: sort sources for gitman.texi
From: brian m. carlson @ 2017-01-21 21:59 UTC (permalink / raw)
To: git; +Cc: Johannes Schindelin, Jeff King
In-Reply-To: <20170121215912.246691-1-sandals@crustytoothpaste.net>
Sorting the sources makes it easier to compare the output using diff.
In addition, it aids groups creating reproducible builds, as the order
of the files is no longer dependent on the file system or other
irrelevant factors.
Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
---
Documentation/Makefile | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/Documentation/Makefile b/Documentation/Makefile
index a9fb497b8..6e6c82409 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -373,7 +373,7 @@ user-manual.pdf: user-manual.xml
gitman.texi: $(MAN_XML) cat-texi.perl
$(QUIET_DB2TEXI)$(RM) $@+ $@ && \
- ($(foreach xml,$(MAN_XML),$(DOCBOOK2X_TEXI) --encoding=UTF-8 \
+ ($(foreach xml,$(sort $(MAN_XML)),$(DOCBOOK2X_TEXI) --encoding=UTF-8 \
--to-stdout $(xml) &&) true) > $@++ && \
$(PERL_PATH) cat-texi.perl $@ <$@++ >$@+ && \
rm $@++ && \
^ permalink raw reply related
* [PATCH 1/7] Documentation: fix warning in cat-texi.perl
From: brian m. carlson @ 2017-01-21 21:59 UTC (permalink / raw)
To: git; +Cc: Johannes Schindelin, Jeff King
In-Reply-To: <20170121215912.246691-1-sandals@crustytoothpaste.net>
Newer versions of Perl produce the warning "Unescaped left brace in
regex is deprecated, passed through in regex" when an unescaped left
brace occurs in a regex. Escape the brace to avoid this warning.
Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
---
Documentation/cat-texi.perl | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/Documentation/cat-texi.perl b/Documentation/cat-texi.perl
index 87437f8a9..b1fe52e8b 100755
--- a/Documentation/cat-texi.perl
+++ b/Documentation/cat-texi.perl
@@ -11,7 +11,7 @@ while (<STDIN>) {
if (s/^\@top (.*)/\@node $1,,,Top/) {
push @menu, $1;
}
- s/\(\@pxref{\[(URLS|REMOTES)\]}\)//;
+ s/\(\@pxref\{\[(URLS|REMOTES)\]}\)//;
s/\@anchor\{[^{}]*\}//g;
print TMP;
}
^ permalink raw reply related
* [PATCH 2/7] Documentation: modernize cat-texi.perl
From: brian m. carlson @ 2017-01-21 21:59 UTC (permalink / raw)
To: git; +Cc: Johannes Schindelin, Jeff King
In-Reply-To: <20170121215912.246691-1-sandals@crustytoothpaste.net>
Good style for Perl includes using the strict and warnings pragmas, and
preferring lexical file handles over bareword file handles. Using
lexical file handles necessitates being explicit when $_ is printed, so
that Perl does not get confused and instead print the glob ref.
The benefit of this modernization is that a formerly obscured bug is now
visible, which will be fixed in a followup patch.
Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
---
Documentation/cat-texi.perl | 15 +++++++++------
1 file changed, 9 insertions(+), 6 deletions(-)
diff --git a/Documentation/cat-texi.perl b/Documentation/cat-texi.perl
index b1fe52e8b..1bc84d3c7 100755
--- a/Documentation/cat-texi.perl
+++ b/Documentation/cat-texi.perl
@@ -1,9 +1,12 @@
#!/usr/bin/perl -w
+use strict;
+use warnings;
+
my @menu = ();
my $output = $ARGV[0];
-open TMP, '>', "$output.tmp";
+open my $tmp, '>', "$output.tmp";
while (<STDIN>) {
next if (/^\\input texinfo/../\@node Top/);
@@ -13,9 +16,9 @@ while (<STDIN>) {
}
s/\(\@pxref\{\[(URLS|REMOTES)\]}\)//;
s/\@anchor\{[^{}]*\}//g;
- print TMP;
+ print $tmp $_;
}
-close TMP;
+close $tmp;
printf '\input texinfo
@setfilename gitman.info
@@ -34,10 +37,10 @@ for (@menu) {
print "* ${_}::\n";
}
print "\@end menu\n";
-open TMP, '<', "$output.tmp";
-while (<TMP>) {
+open $tmp, '<', "$output.tmp";
+while (<$tmp>) {
print;
}
-close TMP;
+close $tmp;
print "\@bye\n";
unlink "$output.tmp";
^ permalink raw reply related
* [PATCH 3/7] Documentation: remove unneeded argument in cat-texi.perl
From: brian m. carlson @ 2017-01-21 21:59 UTC (permalink / raw)
To: git; +Cc: Johannes Schindelin, Jeff King
In-Reply-To: <20170121215912.246691-1-sandals@crustytoothpaste.net>
The newly-added use of the warnings pragma exposes that the $menu[0]
argument to printf has long been silently ignored, since there is no
format specifier for it. It doesn't appear that the argument is
actually needed, either: there is no reason to insert the name of one
particular documentation page anywhere in the header that's being
generated.
Remove the unused argument, and since the format specification
functionality is no longer needed, convert the printf to a simple print.
Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
---
Documentation/cat-texi.perl | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/Documentation/cat-texi.perl b/Documentation/cat-texi.perl
index 1bc84d3c7..14d2f8341 100755
--- a/Documentation/cat-texi.perl
+++ b/Documentation/cat-texi.perl
@@ -20,7 +20,7 @@ while (<STDIN>) {
}
close $tmp;
-printf '\input texinfo
+print '\input texinfo
@setfilename gitman.info
@documentencoding UTF-8
@dircategory Development
@@ -31,7 +31,7 @@ printf '\input texinfo
@top Git Manual Pages
@documentlanguage en
@menu
-', $menu[0];
+';
for (@menu) {
print "* ${_}::\n";
^ permalink raw reply related
page: next (older) | prev (newer) | latest
- recent:[subjects (threaded)|topics (new)|topics (active)]
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox