Separating out the implementation of the handshake when starting a
long-running subprocess (for example, as is done for a clean/smudge
filter) was done in commit fa64a2fdbe ("sub-process: refactor
handshake to common function", 2017-07-26), but its documentation still
resides in gitattributes. Split out the documentation as well.
Signed-off-by: Jonathan Tan <jonathantanmy@google.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
We allow the builders, who want to install the preformatted manpages
and html documents, to specify where in their filesystem these two
repositories are stored. Let them also specify which ref (or even a
revision) to grab the preformatted material from.
Signed-off-by: Randall S. Becker <rsbecker@nexbridge.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The SubmittingPatches document is often cited by outside parties as an
example of good practices to follow, including logical, independent
commits; patch sign-offs; and sending patches to a mailing list.
Currently, people who want to cite a particular section tend to either
refer to it by name and let the interested party search through the
document to find it, or link to a given line number on GitHub and hope
the file doesn't change.
Instead, convert the document to AsciiDoc. Build it as part of the
technical documentation, since it is likely of interest to the same
group of people. Provide stable links to the sections which outside
parties are likely to want to link to. Make some minor structural
changes to organize it so that it can be formatted sanely.
Since the makefile needs a .txt extension in order to build with the
rest of the documentation, simply copy the file. Ignore the temporary
file so it doesn't get checked in accidentally, and remove it as part of
the clean process. Do this instead of renaming the file so that people
who have already linked to the documentation (who we're trying to help)
don't find their links broken. Avoid symlinking since Windows will not
like that.
This allows us to render the document as part of the website for the
benefit of others who wish to link to it as well as providing a more
nicely formatted display for our community and potential contributors.
Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Asciidoctor 1.5.0 and later have a compatibility mode that makes it more
compatible with some Asciidoc syntax, notably the single and double
quote handling. While this doesn't affect any of our current
documentation, it would be beneficial to enable this mode to reduce the
differences between AsciiDoc and Asciidoctor if we make use of those
features in the future.
Since this mode is specified as an attribute, if a version of
Asciidoctor doesn't understand it, it will simply be ignored.
Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This document describes what a transition to a new hash function for
Git would look like. Add it to Documentation/technical/ as the plan
of record so that future changes can be recorded as patches.
Also-by: Brandon Williams <bmwill@google.com>
Also-by: Jonathan Tan <jonathantanmy@google.com>
Also-by: Stefan Beller <sbeller@google.com>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This patch aims to detangle (a) the usage of `git-submodule`
from (b) the concept of submodules and (c) how the actual
implementation looks like, such as where they are configured
and (d) what the best practices are.
To do so, move the conceptual parts of the 'git-submodule'
man page to a new man page gitsubmodules(7). This new page
is just like gitmodules(5), gitattributes(5), gitcredentials(7),
gitnamespaces(7), gittutorial(7), which introduce a concept
rather than explaining a specific command.
Signed-off-by: Stefan Beller <sbeller@google.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Asciidoctor, an alternative reimplementation of AsciiDoc, still
needs some changes to work with documents meant to be formatted
with AsciiDoc. "make USE_ASCIIDOCTOR=YesPlease" to use it out of
the box to document our pages is getting closer to reality.
* bc/use-asciidoctor-opt:
Documentation: implement linkgit macro for Asciidoctor
Makefile: add a knob to enable the use of Asciidoctor
Documentation: move dblatex arguments into variable
Documentation: add XSLT to fix DocBook for Texinfo
Documentation: sort sources for gitman.texi
Documentation: remove unneeded argument in cat-texi.perl
Documentation: modernize cat-texi.perl
Documentation: fix warning in cat-texi.perl
AsciiDoc uses a configuration file to implement macros like linkgit,
while Asciidoctor uses Ruby extensions. Implement a Ruby extension that
implements the linkgit macro for Asciidoctor in the same way that
asciidoc.conf does for AsciiDoc. Adjust the Makefile to use it by
default.
Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
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>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
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>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
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>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
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>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The `user-manual.txt` is designed as a `book` but the `Makefile` wants
to build it as an `article`. This seems to be a problem when building
the documentation with `asciidoctor`. Furthermore the parts *Git
Glossary* and *Appendix B* had no subsections which is not allowed when
building with `asciidoctor`. So lets add a *dummy* section.
Signed-off-by: 마누엘 <nalla@hamal.uberspace.de>
Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
We use different types of signature formats in different places.
Set up the infrastructure and overview to describe them systematically
in our technical documentation.
Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Backticks are emphasized through monospaced styling in the HTML
version of Git documentation. But they were left unstyled in the
manual pages.
To make the man pages more comfortably read, `MAN_BOLD_LITERAL` was
added by 5121a6d (Documentation: option to render literal text as
bold for manpages, 2009-03-27). It allowed the user to build the
manpages with literals in bold style.
For precaution it was not set by default back then.
Since 79c461d (docs: default to more modern toolset, 2010-11-19), it
is assumed ASCIIDOC 8 and at least docbook-xsl 1.73 are used, so the
need for compatibility concern is much lessor now.
Remove `MAN_BOLD_LITERAL`, and typeset literals as bold by default .
Add `NO_MAN_BOLD_LITERAL`, a new Makefile option, disabling this
feature when defined.
Signed-off-by: Erwan MATHONIERE <erwan.mathoniere@grenoble-inp.org>
Signed-off-by: Samuel GROOT <samuel.groot@grenoble-inp.org>
Signed-off-by: Tom RUSSELLO <tom.russello@grenoble-inp.org>
Signed-off-by: Matthieu MOY <matthieu.moy@grenoble-inp.fr>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
It is easy to add incorrect "linkgit:<page>[<section>]" references
to our documentation suite. Catch these common classes of errors:
* Referring to Documentation/<page>.txt that does not exist.
* Referring to a <page> outside the Git suite. In general, <page>
must begin with "git".
* Listing the manual <section> incorrectly. The first line of the
Documentation/<page>.txt must end with "(<section>)".
with a new script "ci/lint-gitlink", and drive it from "make check-docs".
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Version numbers in asciidoc-generated content (such as man pages)
went missing as of da8a366 (Documentation: refactor common operations
into variables). Fix by putting the underscore back in the variable
name.
Signed-off-by: Sven van Haastregt <svenvh@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Add machinery to alternatively use AsciiDoctor to format our
documentation.
* bc/asciidoctor:
Documentation: remove Asciidoctor linkgit macro
Documentation: refactor common operations into variables
Documentation: implement linkgit macro for Asciidoctor
Documentation: move some AsciiDoc parameters into variables
The Makefile performs several very similar tasks to convert AsciiDoc
files into either HTML or DocBook. Move these items into variables to
reduce the duplication.
Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Asciidoctor takes slightly different arguments from AsciiDoc in some
cases. It has a different name for the HTML backend and the "docbook"
backend produces DocBook 5, not DocBook 4.5. Also, Asciidoctor does not
accept the -f option. Move these values into variables so that they can
be overridden by users wishing to use Asciidoctor instead of Asciidoc.
Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The "Everyday GIT With 20 Commands Or So" is not accessible via the
Git help system. Move everyday.txt to giteveryday.txt so that "git
help everyday" works, and create a new placeholder file everyday.html
to refer people who follow existing URLs to the updated location.
giteveryday.txt now formats well with AsciiDoc as a man page and
refreshed content to a more command modern style.
Add 'everyday' to the help --guides list and update git(1) and 5
other links to giteveryday.
Signed-off-by: Philip Oakley <philipoakley@iee.org>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
During the mail thread about "Pull is mostly evil" a user asked how
the first parent could become reversed.
This howto explains how the first parent can get reversed when viewed
by the project and then explains a method to keep the history correct.
Signed-off-by: Stephen P. Smith <ischis2@cox.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Instead of starting an enumeration of documents with a DOC = doc1
followed by DOC += doc2, DOC += doc3, ..., empty it with "DOC =" at
the beginning and consistently add them with "DOC += ...".
Signed-off-by: Junio C Hamano <gitster@pobox.com>
./Documentation/technical/http-protocol.txt was missing from TECH_DOCS in Makefile.
Add it and also improve HTML formatting while still retaining good readability of the ASCII text:
- Use monospace font instead of italicized or roman font for machine output and source text
- Use roman font for things which should be body text
- Use double quotes consistently for "want" and "have" commands
- Use uppercase "C" / "S" consistently for "client" / "server";
also use "C:" / "S:" instead of "(C)" / "(S)" for consistency and
to avoid having formatted "(C)" as copyright symbol in HTML
- Use only spaces and not a combination of tabs and spaces for whitespace
Signed-off-by: Thomas Ackermann <th.acker@arcor.de>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Use asciidoc style 'article' instead of 'book' and change asciidoc
title level. This removes blank first page and superfluous "Part I"
page (there is no "Part II") in pdf output. Also pdf size is
decreased by this from 77 to 67 pages. In html output this removes
unnecessary sub-tocs and chapter numbering.
Signed-off-by: Thomas Ackermann <th.acker@arcor.de>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This is an asciidoc-ified version of a corruption post-mortem sent to
the git list. It complements the existing howto article, since it covers
a case where the object couldn't be easily recreated or copied from
elsewhere.
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
On my system this is in /usr/share/asciidoc/dblatex not
/etc/asciidoc/dblatex. Extract this portion of the path to a variable
so that is can be set in config.mak.
Signed-off-by: John Keeping <john@keeping.me.uk>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
Build on top of the clean-up done by jk/mergetool and automatically
generate the list of mergetool and difftool backends the build
supports to be included in the documentation.
* da/mergetool-docs:
doc: generate a list of valid merge tools
mergetool--lib: list user configured tools in '--tool-help'
mergetool--lib: add functions for finding available tools
mergetool--lib: improve the help text in guess_merge_tool()
mergetool--lib: simplify command expressions
"git help remote-helpers" did not work; 'remote-helpers' is not
a subcommand name but a concept, so its documentation should have
been in gitremote-helpers, not git-remote-helpers.
* jk/remote-helpers-doc:
Rename {git- => git}remote-helpers.txt
Use the show_tool_names() function to build lists of all
the built-in tools supported by difftool and mergetool.
This frees us from needing to update the documentation
whenever a new tool is added.
Signed-off-by: David Aguilar <davvid@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
When looking up a topic via "git help <topic>", git-help prepends "git-"
to topics that are the names of commands (either builtin or found on the
path) and "git" (no hyphen) to any other topic name.
"git-remote-helpers" is not the name of a command, so "git help
remote-helpers" looks for "gitremote-helpers" and does not find it.
Fix this by renaming "git-remote-helpers.txt" to
"gitremote-helpers.txt".
Signed-off-by: John Keeping <john@keeping.me.uk>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
We keep a list of the various files that end up as man1,
man5, etc. Let's break these single-line lists into sorted
multi-line lists, which makes diffs that touch them much
easier to read.
Reviewed-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
When building manual pages, the source text is transformed to XML with
AsciiDoc before the man pages are generated from the XML with xmlto.
Fix the dependencies in the Makefile so that the XML files are rebuilt
when asciidoc.conf changes and not just the manual pages from
unchanged XML, and move the dependencies from a recipeless rule to the
rules with commands that use asciidoc.conf to make the dependencies
easier to understand and maintain.
Reported-by: John Keeping <john@keeping.me.uk>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
Tested-by: John Keeping <john@keeping.me.uk>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
* ta/doc-cleanup:
Documentation: build html for all files in technical and howto
Documentation/howto: convert plain text files to asciidoc
Documentation/technical: convert plain text files to asciidoc
Change headline of technical/send-pack-pipeline.txt to not confuse its content with content from git-send-pack.txt
Shorten two over-long lines in git-bisect-lk2009.txt by abbreviating some sha1
Split over-long synopsis in git-fetch-pack.txt into several lines
Howto documents in howto-index.txt were listed in a rather
random order. So better sort them.
Signed-off-by: Thomas Ackermann <th.acker@arcor.de>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The contents of this document does not describe any particular API, but
is more about the way to add a new command, which belongs to the "How To"
section of the documentation suite.
Signed-off-by: Thomas Ackermann <th.acker@arcor.de>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
These files were recently revised to be valid asciidoc, so
there is no reason not to build html versions.
Signed-off-by: Thomas Ackermann <th.acker66@arcor.de>
Signed-off-by: Jeff King <peff@peff.net>
The current code tries to get a list of documented commands
by doing "ls Documentation/git*txt" and culling a bunch of
special cases from the result. Looking for "git-*.txt" would
be more accurate, but would miss a few commands like
"gitweb" and "gitk".
Fortunately, Documentation/Makefile already knows what this
list is, so we can just ask it. Annoyingly, we still have to
post-process its output a little, since make will print
extra cruft like "GIT-VERSION-FILE is up to date" to stdout.
Now that our list is accurate, we can remove all of the ugly
special-cases.
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
We no longer use AsciiDoc7 syntax in our documentation and favor a
more modern style.
* jk/no-more-asciidoc7:
docs: drop antique comment from Makefile
docs: drop asciidoc7compatible flag
Most of our documentation is in a single directory, so using
linkgit:git-config[1] just generates a relative link in the
same directory. However, this is not the case with the API
documentation in technical/*, which need to refer to
git-config from the parent directory.
We can fix this by passing a special prefix attribute when building
in a subdirectory, and respecting that prefix in our linkgit
definitions.
We only have to modify the html linkgit definition. For
manpages, we can ignore this for two reasons:
1. we do not generate actual links to the file in
manpages, but instead just give the name and section of
the linked manpage
2. we do not currently build manpages for subdirectories,
only html
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This comment warns about a bug in asciidoc 6, and points to
a patch from 2005. Since we don't even support versions of
asciidoc that old, we can safely get rid of the warning.
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
When we made the switch to supporting asciidoc 8 in 4c7100a
(Documentation: adjust to AsciiDoc 8, 2007-06-14), we were
able to leave most of the documentation intact by defining
asciidoc7compatible.
Since commit 6cf378f (docs: stop using asciidoc no-inline-literal,
2012-04-26), we don't support versions of asciidoc older
than 8.4.1, which is when inline literals were introduced.
Therefore there is not much point in keeping our
documentation compatible with asciidoc 7.
So we are now free to drop the asciidoc7compatible flag and
update the documentation itself to assume asciidoc8.
Fortunately, doing the latter is very easy; we weren't using
any of the constructs impacted by asciidoc7compatible, so
there are no changes to make.
The reason is somewhat subtle. The asciidoc7compatible
affects only super/sub-scripts ("^" and "~") and index
terms. We don't use the latter at all. Nor we do we use the
former, but we did have to protect them from accidental
expansion in constructs like "rev^1". However, all of our
uses of "~" and "^" are either in code blocks (which are
rendered literally), or inside backticks. Prior to 6cf378f,
backticks were not inline literals, and needed proper
quoting. But post-6cf378f, we don't have to worry whether we
are using the old or new rules, as those characters are not
interpreted at all in either case.
I verified that the result of "make install-html
install-man" is identical before and after this patch on
asciidoc 8.6.7.
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Our documentation was written for an ancient version of AsciiDoc,
making the source not very readable.
By Jeff King
* jk/doc-asciidoc-inline-literal:
docs: stop using asciidoc no-inline-literal
In asciidoc 7, backticks like `foo` produced a typographic
effect, but did not otherwise affect the syntax. In asciidoc
8, backticks introduce an "inline literal" inside which markup
is not interpreted. To keep compatibility with existing
documents, asciidoc 8 has a "no-inline-literal" attribute to
keep the old behavior. We enabled this so that the
documentation could be built on either version.
It has been several years now, and asciidoc 7 is no longer
in wide use. We can now decide whether or not we want
inline literals on their own merits, which are:
1. The source is much easier to read when the literal
contains punctuation. You can use `master~1` instead
of `master{tilde}1`.
2. They are less error-prone. Because of point (1), we
tend to make mistakes and forget the extra layer of
quoting.
This patch removes the no-inline-literal attribute from the
Makefile and converts every use of backticks in the
documentation to an inline literal (they must be cleaned up,
or the example above would literally show "{tilde}" in the
output).
Problematic sites were found by grepping for '`.*[{\\]' and
examined and fixed manually. The results were then verified
by comparing the output of "html2text" on the set of
generated html pages. Doing so revealed that in addition to
making the source more readable, this patch fixes several
formatting bugs:
- HTML rendering used the ellipsis character instead of
literal "..." in code examples (like "git log A...B")
- some code examples used the right-arrow character
instead of '->' because they failed to quote
- api-config.txt did not quote tilde, and the resulting
HTML contained a bogus snippet like:
<tt><sub></tt> foo <tt></sub>bar</tt>
which caused some parsers to choke and omit whole
sections of the page.
- git-commit.txt confused ``foo`` (backticks inside a
literal) with ``foo'' (matched double-quotes)
- mentions of `A U Thor <author@example.com>` used to
erroneously auto-generate a mailto footnote for
author@example.com
- the description of --word-diff=plain incorrectly showed
the output as "[-removed-] and {added}", not "{+added+}".
- using "prime" notation like:
commit `C` and its replacement `C'`
confused asciidoc into thinking that everything between
the first backtick and the final apostrophe were meant
to be inside matched quotes
- asciidoc got confused by the escaping of some of our
asterisks. In particular,
`credential.\*` and `credential.<url>.\*`
properly escaped the asterisk in the first case, but
literally passed through the backslash in the second
case.
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Document the default pager and editor chosen at compile time in the
git-var(1) manpage so users curious about what command _this_ copy of
git will fall back to when EDITOR, VISUAL, and PAGER are unset can
find the answer quickly.
In builds leaving those settings uncustomized, this patch makes the
manpage continue to say "usually vi" and "usually less" so the
formatted documentation is usable for a wide audience including users
of custom builds that change those settings. If you would like your
copy of the docs to be less noncommittal, you will need to set
DEFAULT_PAGER=less and DEFAULT_EDITOR=vi explicitly.
Suggested-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The credential API and helper format is already defined in
technical/api-credentials.txt. This presents the end-user
view.
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The preformatted documentation pages live in their own repositories
these days. Adjust the installation procedure to the updated layout.
Tested-by: Stefan Naewe <stefan.naewe@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Most of what is in gitweb.txt it has been pulled directly from the
README and INSTALL files of gitweb.
Current version is somewhat based on structure of SVN::Web manpage
(one of web interfaces for Subversion).
gitweb.conf(5) i.e. gitweb configuration manpage now refers to
appropriate sections in gitweb(1). gitweb/README now refers to
gitweb/INSTALL and gitweb(1) manpage. gitweb/INSTALL now refers to
gitweb.conf(5) and gitweb(1).
Inspired-by: Drew Northup <drew.northup@maine.edu>
Signed-off-by: Jakub Narebski <jnareb@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Much of what is in gitweb.conf.txt has been pulled directly from the
README file of gitweb. The manpage was supplemented with description
of missing gitweb config variables, and with description of gitweb's
%features.
There remains a bit of redundancy, which should be reduced if
possible... but I think some of duplication of information is
inevitable.
[jn: Improved, extended, removed duplicate info from README]
Signed-off-by: Drew Northup <drew.northup@maine.edu>
Signed-off-by: Jakub Narebski <jnareb@gmail.com>
Helped-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
user-manual.pdf is not removed by `make clean'; fix it.
Signed-off-by: Emilio G. Cota <cota@braap.org>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Document the namespace mechanism in a new gitnamespaces(7) page.
Reference it from receive-pack and upload-pack.
Document the new --namespace option and GIT_NAMESPACE environment
variable in git(1), and reference gitnamespaces(7).
Add a sample Apache configuration to http-backend(1) to support
namespaced repositories, and reference gitnamespaces(7).
Signed-off-by: Josh Triplett <josh@joshtriplett.org>
Signed-off-by: Jamey Sharp <jamey@minilop.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
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>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
We use our custom xsl file to build the user manual, so make
sure we depend on it. We don't use it anywhere else, so we
can stick it straight in the rule.
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Create a new man page gitrevisions(7) which contains the revsions and
ranges documentation but not more. This uses (per include) the same bits
as the pertaining section of git-rev-parse(1).
Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Unlike gcc, asciidoc does not atomically write its output file or
delete it when interrupted. If it is interrupted in the middle of
writing an XML file, the result will be truncated input for xsltproc.
XSLTPROC user-manual.html
user-manual.xml:998: parser error : Premature end of data in t
Take care of this case by writing to a temporary and renaming it when
finished.
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Providing multiple targets to force a rebuild is unnecessary
complication.
Avoid using a name that could conflict with future special
targets in GNU make (a leading period followed by uppercase
letters).
The corresponding change to the git-gui Makefile is left for
another patch.
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The --stringparam option is not available on older xmlto versions.
Instead, set man.base.url.for.relative.links via a .xsl file. Older
docbook versions will ignore this without causing grief to users of
older xmlto versions.
Signed-off-by: Todd Zullinger <tmz@pobox.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Newer DocBook stylesheets want man.base.url.for.relative.links
parameter set when formatting manpages with external references
to turn them into full URLs, and leave a helpful "you should
set this parameter" message in the output. Earlier we added
the MAN_BASE_URL make variable to specify the value for it.
When MAN_BASE_URL is not given, it ought to be safe to set the
parameter to empty; it would result in an empty leading path for
older stylesheets that ignore the parameter, and newer ones
would produce the same "relative URL" without the message.
Unfortunately, older xmlto (at least version 0.0.18 released in
early 2004 that comes with RHEL/CentOS 5) does not understand
the --stringparam command line option, so we cannot add the
parameter definition unconditionally to the command line. Work
it around by passing the parameter only when set.
If you do not have a suitable URL prefix, you can pass a quoted empty
string to it, like so:
$ make MAN_BASE_URL='""'
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Even setting it to empty is better than leaving it unset as it
prevents the warning cruft from appearing in the output.
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This patch adds an asciidoc version of the "Fighting regressions with
git bisect" article that the author wrote for the Linux-Kongress
2009 (http://www.linux-kongress.org/2009).
This paper might be interesting to people who want to learn as much as
possible about "git bisect" from a single document.
The slides of the related presentation are available at:
http://www.linux-kongress.org/2009/slides/fighting_regressions_with_git_bisect_christian_couder.pdf
But the Linux Kongress people will not publish this paper online because
they print the papers on their UpTimes magazine
(http://www.lob.de/isbn/978-3-86541-358-1). But they don't take away the
rights of the author (which is very nice), so I have the right to publish
it.
Signed-off-by: Christian Couder <chriscool@tuxfamily.org>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The docbook/xmlto toolchain insists on quoting ' as \'. This does
achieve the quoting goal, but modern 'man' implementations turn the
apostrophe into a unicode "proper" apostrophe (given the right
circumstances), breaking code examples in many of our manpages.
Quote them as \(aq instead, which is an "apostrophe quote" as per the
groff_char manpage.
Unfortunately, as Anders Kaseorg kindly pointed out, this is not
portable beyond groff, so we add an extra Makefile variable GNU_ROFF
which you need to enable to get the new quoting.
Thanks also to Miklos Vajna for documentation.
Signed-off-by: Thomas Rast <trast@student.ethz.ch>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
asciidoc 8.4.1 changed the semantics of inline backtick quoting so
that they disable parsing of inline constructs, i.e.,
Input: `{plus}`
Pre 8.4.1: +
Post 8.4.1: {plus}
Fix this by defining the asciidoc attribute 'no-inline-literal'
(which, per the 8.4.1 changelog, is the toggle to return to the old
behaviour) when under ASCIIDOC8.
Signed-off-by: Thomas Rast <trast@student.ethz.ch>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
For all uses of $(ASCIIDOC) in Documentation/Makefile, supply the same
options via $(ASCIIDOC_EXTRA).
Signed-off-by: Eric Blake <ebb9@byu.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Ensure that the Makefile that generates and installs the Documentation is
aware of any SHELL_PATH setting. Use this value if found or the current
setting for SHELL if not. This is an accommodation for systems where sh
is not POSIX enough.
Signed-off-by: Ben Walton <bwalton@artsci.utoronto.ca>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
With this change, the "spurious .sp" suppression XSLT code is
disabled by default. It can be enabled by defining
DOCBOOK_SUPPRESS_SP.
The "spurious .sp" XSLT fragment was used to work around a bug
first released in docbook-xsl 1.69.1. Modern versions of
docbook-xsl are negatively affected by the code (some empty lines
are omitted from manpage output; see
<http://article.gmane.org/gmane.comp.version-control.git/115302>).
The key revisions in the docbook SVN repo seem to be 5144 (before
docbook-xsl 1.69.1) and 6359 (before docbook-xsl 1.71.1).
Testing done with asciidoc 8.3.1 and docbook-xsl 1.74.0.
Signed-off-by: Chris Johnsen <chris_johnsen@pobox.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This allows manpages viewed on a tty to render inline literal
text in a manner that is distinct from the surrounding text.
The initial implementation (pre-mailing-list) of this patch
included a conditional variant of the XSLT code in
manpage-base.xsl and use xmlto's --stringparam option to
optionally enable the functionality. It turns out that
--stringparam is broken in all versions of xmlto except for the
pre-release, SVN version. Since xmlto is a shell script the patch
to fix it is simple enough, but I instead opted to use xmlto's
"module" functionality.
Testing done with asciidoc 8.3.1 and docbook-xsl 1.74.0.
Signed-off-by: Chris Johnsen <chris_johnsen@pobox.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
It seems that the ability to use raw roff codes in asciidoc.conf
was eliminated by docbook-xsl 1.72.0 _and later_. Unlike the
1.72.0-specific XSLT problem, this behavior was not reverted in
later releases.
This patch aims to make it clear that the affected asciidoc
attribute (flag) can be reasonably used with docbook-xsl versions
other than 1.72.0.
Also, document which make variables should be set for various
versions of asciidoc and docbook-xsl.
Testing done with asciidoc 8.3.1 and docbook-xsl 1.74.0.
Signed-off-by: Chris Johnsen <chris_johnsen@pobox.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Each of manpage-base.xsl and manpage-normal.xsl gets a copy of
the contents of callouts.xsl and the original is removed. The
Makefile is adjusted to refer to manpage-normal.xsl instead of
callouts.xsl. manpage-base.xsl will be later made into a common
base for -normal and -1.72.
Testing done with asciidoc 8.3.1 and docbook-xsl 1.74.0.
Signed-off-by: Chris Johnsen <chris_johnsen@pobox.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Most shells define the exit value of a pipeline as the exit value
of the last process. For each texi rule, run the DOCBOOK2X_TEXI
tool and the "fixup" script in their own non-pipeline commands so
that make will notice an error exit code.
Signed-off-by: Chris Johnsen <chris_johnsen@pobox.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This adapts the "quiet make" implementation from the main
Makefile.
Signed-off-by: Chris Johnsen <chris_johnsen@pobox.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
"makeinfo" failed to generate gitman.info from gitman.texi input file
because the combined manual page file contains several nodes with the
same name (DESCRIPTION, OPTIONS, SEE ALSO etc.). An Info document should
contain unique node names.
This patch creates a simple (read: ugly) work-around by suppressing the
validation of the final Info file. Jumping to nodes in the Info document
still works but they are not very useful. Common man-page headings like
DESCRIPTION and OPTIONS appear in the Info node list and they point to
the man page where they appear first (that is git-add currently).
Also, this patch adds directory-entry information for Info document to
make the document appear in the top-level Info directory.
Signed-off-by: Teemu Likonen <tlikonen@iki.fi>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Previously "docbook2x-texi" failed to generate user-manual.texi and
gitman.texi files from .xml input files because "iconv" stopped at
"illegal input sequence" error. This was due to some UTF-8 octets in the
input .xml files. This patch adds option --encoding=UTF-8 for
"docbook2x-texi" to allow the building of .texi files complete.
Signed-off-by: Teemu Likonen <tlikonen@iki.fi>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Use dblatex in order to create a pdf version of the git user manual. No
existing Makefile targets (including "all") are touched, so you need to
explicitly say
make pdf
sudo make install-pdf
to get user-manual.pdf created and installed.
Signed-off-by: Miklos Vajna <vmiklos@frugalware.org>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This attempts to make a manpage about workflows that is both handy to
point people at it and as a beginner's introduction.
Signed-off-by: Thomas Rast <trast@student.ethz.ch>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This patch introduces a make target "quick-install-html" which installs
the html documentation from the branch origin/html, without the need for
asciidoc/xmlto. This is analogous to the existing "quick-install-doc"
target for the man pages.
We advertise these targets in the INSTALL file now.
Signed-off-by: Michael J Gruber <michaeljgruber+gmane@fastmail.fm>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
