The 'clean' target is noticeably slow on cygwin, even for a 'do-nothing'
invocation of 'make clean'. For example, the second 'make clean' below:
$ make clean >/dev/null 2>&1
$ make clean
GIT_VERSION = 2.29.0
...
make[1]: Entering directory '/home/ramsay/git/Documentation'
GEN mergetools-list.made
GEN cmd-list.made
GEN doc.dep
...
$
has been timed at 23.339s, using git v2.29.0, on my laptop (an old core
i5-4200M @ 2.50GHz, 8GB RAM, 1TB HDD).
Notice that, since the 'doc.dep' file does not exist, make takes the
time (about 8s) to generate several files in order to create the doc.dep
include file. (If an 'include' file is missing, but a target for the
said file is present in the Makefile, make will execute that target
and, if that file now exists, throw away all its internal data and
re-read and re-parse the Makefile). Having spent the time to include
the 'doc.dep' file, the 'clean' target immediately deletes those files.
The document dependencies specified in the 'doc.dep' include file,
expressed as make targets and prerequisites, do not affect what the
'clean' target removes. Therefore, the time spent in generating the
dependencies is completely wasted effort.
In order to eliminate such wasted effort, use the value of the internal
$(MAKECMDGOALS) variable to only '-include doc.dep' when the target is
not 'clean'. (This drops the time down to 12.364s, on my laptop, giving
an improvement of 47.02%).
Signed-off-by: Ramsay Jones <ramsay@ramsayjones.plus.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Not all man5/man7 guides are mentioned in the 'git(1)' documentation,
which makes the missing ones somewhat hard to find.
Add a list of the guides to git(1) by leveraging the existing
`Documentation/cmd-list.perl` script to generate a file `cmds-guide.txt`
which gets included in git.txt.
Also, do not hard-code the manual section '1'. Instead, use a regex so
that the manual section is discovered from the first line of each
`git*.txt` file.
This addition was hinted at in 1b81d8cb19 (help: use command-list.txt
for the source of guides, 2018-05-20).
Helped-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Instead of hard-coding the list of command categories in both
`Documentation/Makefile` and `Documentation/cmd-list.perl`, make the
Makefile the authoritative source and tweak `cmd-list.perl` so that it
receives the list of command categories as argument.
Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The guides 'gitcredentials' and 'gitremote-helpers' do not currently
appear in command-list.txt.
'gitcredentials' was forgotten back when guides were added to
command-list.txt in 1b81d8cb19 (help: use command-list.txt for the
source of guides, 2018-05-20).
'gitremote-helpers' was moved to section 7 in 439cc74632 (docs: move
gitremote-helpers into section 7, 2019-03-25), but command-list.txt was
not updated at the time.
Add these two guides to the list of guides in 'command-list.txt', so
that they appear in the output of 'git help --guides', and capitalize
the first word of the description of 'gitcredentials', as was done in
1b81d8c (help: use command-list.txt for the source of guides,
2018-05-20) for the other guides.
While at it, add a comment in Documentation/Makefile to remind developers
to update command-list.txt if they add a new guide.
Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Shawn Pearce explains:
Some repositories contain a lot of references (e.g. android at 866k,
rails at 31k). The reftable format provides:
- Near constant time lookup for any single reference, even when the
repository is cold and not in process or kernel cache.
- Near constant time verification if a SHA-1 is referred to by at least
one reference (for allow-tip-sha1-in-want).
- Efficient lookup of an entire namespace, such as `refs/tags/`.
- Support atomic push `O(size_of_update)` operations.
- Combine reflog storage with ref storage.
This file format spec was originally written in July, 2017 by Shawn
Pearce. Some refinements since then were made by Shawn and by Han-Wen
Nienhuys based on experiences implementing and experimenting with the
format. (All of this was in the context of our work at Google and
Google is happy to contribute the result to the Git project.)
Imported from JGit[1]'s current version (c217d33ff,
"Documentation/technical/reftable: improve repo layout", 2020-02-04)
of Documentation/technical/reftable.md and converted to asciidoc by
running
pandoc -t asciidoc -f markdown reftable.md >reftable.txt
using pandoc 2.2.1. The result required the following additional
minor changes:
- removed the [TOC] directive to add a table of contents, since
asciidoc does not support it
- replaced git-scm.com/docs links with linkgit: directives that link
to other pages within Git's documentation
[1] https://eclipse.googlesource.com/jgit/jgit
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Raise the minimum required version of docbook-xsl package to 1.74,
as 1.74.0 was from late 2008, which is more than 10 years old, and
drop compatibility cruft from our documentation suite.
* ma/doc-discard-docbook-xsl-1.73:
user-manual.conf: don't specify [listingblock]
INSTALL: drop support for docbook-xsl before 1.74
manpage-normal.xsl: fold in manpage-base.xsl
manpage-bold-literal.xsl: stop using git.docbook.backslash
Doc: drop support for docbook-xsl before 1.73.0
Doc: drop support for docbook-xsl before 1.72.0
Doc: drop support for docbook-xsl before 1.71.1
Git is an enormously flexible and powerful piece of software. However,
it can be intimidating for many users and there are a set of common
questions that users often ask. While we already have some new user
documentation, it's worth adding a FAQ to address common questions that
users often have. Even though some of this is addressed elsewhere in
the documentation, experience has shown that it is difficult for users
to find, so a centralized location is helpful.
Add such a FAQ and fill it with some common questions and answers.
While there are few entries now, we can expand it in the future to cover
more things as we find new questions that users have. Let's also add
section markers so that people answering questions can directly link
users to the proper answer.
The FAQ also addresses common configuration questions that apply not
only to Git as an independent piece of software but also the ecosystem
of CI tools and hosting providers that people use, since these are the
source of common questions. An attempt has been made to avoid
mentioning any particular provider or tool, but to nevertheless cover
common configurations that apply to a wide variety of such tools.
Note that the long lines for certain questions are required, since
Asciidoctor does not permit broken lines there.
Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Drop the DOCBOOK_XSL_172 config knob, which was needed with docbook-xsl
1.72 (but neither 1.71 nor 1.73). Version 1.73.0 is more than twelve
years old.
Together with the last few commits, we are now at a point where we don't
have any Makefile knobs to cater to old/broken versions of docbook-xsl.
Signed-off-by: Martin Ågren <martin.agren@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
docbook-xsl 1.72.0 is thirteen years old. Drop the ASCIIDOC_ROFF knob
which was needed to support 1.68.1 - 1.71.1. The next commit will
increase the required/assumed version further.
Signed-off-by: Martin Ågren <martin.agren@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Drop the DOCBOOK_SUPPRESS_SP mechanism, which needs to be used with
docbook-xsl versions 1.69.1 through 1.71.0.
We probably broke this for Asciidoctor builds in f6461b82b9
("Documentation: fix build with Asciidoctor 2", 2019-09-15). That is, we
should/could fix this similar to 55aca515eb ("manpage-bold-literal.xsl:
match for namespaced "d:literal" in template", 2019-10-31). But rather
than digging out such an old version of docbook-xsl to test that, let's
just use this as an excuse for dropping this decade-old workaround.
DOCBOOK_SUPPRESS_SP was not needed with docbook-xsl 1.69.0 and older.
Maybe such old versions still work fine on our docs, or maybe not. Let's
just refer to everything before 1.71.1 as "not supported". The next
commit will increase the required/assumed version further.
Signed-off-by: Martin Ågren <martin.agren@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Existing documentation on object walks seems to be primarily intended
as a reference for those already familiar with the procedure. This
tutorial attempts to give an entry-level guide to a couple of bare-bones
object walks so that new Git contributors can learn the concepts
without having to wade through options parsing or special casing.
The target audience is a Git contributor who is just getting started
with the concept of object walking. The goal is to prepare this
contributor to be able to understand and modify existing commands which
perform revision walks more easily, although it will also prepare
contributors to create new commands which perform walks.
The tutorial covers a basic overview of the structs involved during
object walk, setting up a basic commit walk, setting up a basic
all-object walk, and adding some configuration changes to both walk
types. It intentionally does not cover how to create new commands or
search for options from the command line or gitconfigs.
There is an associated patchset at
https://github.com/nasamuffin/git/tree/revwalk that contains a reference
implementation of the code generated by this tutorial.
Signed-off-by: Emily Shaffer <emilyshaffer@google.com>
Helped-by: Eric Sunshine <sunshine@sunshineco.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Start using DocBook 5 (instead of DocBook 4.5) as Asciidoctor 2.0
no longer works with the older one.
* bc/doc-use-docbook-5:
Documentation: fix build with Asciidoctor 2
Update support for Asciidoctor documentation toolchain.
* ma/asciidoctor-refmiscinfo:
doc-diff: replace --cut-header-footer with --cut-footer
asciidoctor-extensions: provide `<refmiscinfo/>`
Doc/Makefile: give mansource/-version/-manual attributes
Rather than hardcoding "Git Manual" and "Git" as the manual and source
in asciidoc.conf, provide them as attributes `manmanual` and
`mansource`. Rename the `git_version` attribute to `manversion`.
These new attribute names are not arbitrary, see, e.g., [1].
For AsciiDoc (8.6.10) and Asciidoctor <1.5.7, this is a no-op. Starting
with Asciidoctor 1.5.7, `manmanual` and `mansource` actually end up in
the xml-files and eventually in the rendered manpages. In particular,
the manpage headers now render just as with AsciiDoc.
No versions of Asciidoctor pick up the `manversion` [2], and older
versions don't pick up any of these attributes. -- We'll fix that with a
bit of a hack in the next commit.
[1] https://asciidoctor.org/docs/user-manual/#man-pages
[2] Note how [1] says "Not used by Asciidoctor".
Signed-off-by: Martin Ågren <martin.agren@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Our documentation toolchain has traditionally been built around DocBook
4.5. This version of DocBook is the last DTD-based version of DocBook.
In 2009, DocBook 5 was introduced using namespaces and its syntax is
expressed in RELAX NG, which is more expressive and allows a wider
variety of syntax forms.
Asciidoctor, one of the alternatives for building our documentation,
moved support for DocBook 4.5 out of core in its recent 2.0 release and
now only supports DocBook 5 in the main release. The DocBoook 4.5
converter is still available as a separate component, but this is not
available in most distro packages. This would not be a problem but for
the fact that we use xmlto, which is still stuck in the DocBook 4.5 era.
xmlto performs DTD validation as part of the build process. This is not
problematic for DocBook 4.5, which has a valid DTD, but it clearly
cannot work for DocBook 5, since no DTD can adequately express its full
syntax. In addition, even if xmlto did support RELAX NG validation,
that wouldn't be sufficient because it uses the libxml2-based xmllint to
do so, which has known problems with validating interleaves in RELAX NG.
Fortunately, there's an easy way forward: ask Asciidoctor to use its
DocBook 5 backend and tell xmlto to skip validation. Asciidoctor has
supported DocBook 5 since v0.1.4 in 2013 and xmlto has supported
skipping validation for probably longer than that.
We also need to teach xmlto how to use the namespaced DocBook XSLT
stylesheets instead of the non-namespaced ones it usually uses.
Normally these stylesheets are interchangeable, but the non-namespaced
ones have a bug that causes them not to strip whitespace automatically
from certain elements when namespaces are in use. This results in
additional whitespace at the beginning of list elements, which is
jarring and unsightly.
We can do this by passing a custom stylesheet with the -x option that
simply imports the namespaced stylesheets via a URL. Any system with
support for XML catalogs will automatically look this URL up and
reference a local copy instead without us having to know where this
local copy is located. We know that anyone using xmlto will already
have catalogs set up properly since the DocBook 4.5 DTD used during
validation is also looked up via catalogs. All major Linux
distributions distribute the necessary stylesheets and have built-in
catalog support, and Homebrew does as well, albeit with a requirement to
set an environment variable to enable catalog support.
On the off chance that someone lacks support for catalogs, it is
possible for xmlto (via xmllint) to download the stylesheets from the
URLs in question, although this will likely perform poorly enough to
attract attention. People still have the option of using the prebuilt
documentation that we ship, so happily this should not be an impediment.
Finally, we need to filter out some messages from other stylesheets that
occur when invoking dblatex in the CI job. This tool strips namespaces
much like the unnamespaced DocBook stylesheets and prints similar
messages. If we permit these messages to be printed to standard error,
our documentation CI job will fail because we check standard error for
unexpected output. Due to dblatex's reliance on Python 2, we may need
to revisit its use in the future, in which case this problem may go
away, but this can be delayed until a future patch.
The final message we filter is due to libxslt on modern Debian and
Ubuntu. The patch which they use to implement reproducible ID
generation also prints messages about the ID generation. While this
doesn't affect our current CI images since they use Ubuntu 16.04 which
lacks this patch, if we upgrade to Ubuntu 18.04 or a modern Debian,
these messages will appear and, like the above messages, cause a CI
failure.
Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
A new tutorial targetting specifically aspiring git-core
developers.
* es/first-contrib-tutorial:
doc: add some nit fixes to MyFirstContribution
documentation: add anchors to MyFirstContribution
documentation: add tutorial for first contribution
This tutorial covers how to add a new command to Git and, in the
process, everything from cloning git/git to getting reviewed on the
mailing list. It's meant for new contributors to go through
interactively, learning the techniques generally used by the git/git
development community.
Reviewed-by: Johannes Schindelin <johannes.schindelin@gmx.de>
Reviewed-by: Jonathan Tan <jonathantanmy@google.com>
Signed-off-by: Emily Shaffer <emilyshaffer@google.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
"make check-docs", "git help -a", etc. did not account for cases
where a particular build may deliberately omit some subcommands,
which has been corrected.
* js/misc-doc-fixes:
Turn `git serve` into a test helper
test-tool: handle the `-C <directory>` option just like `git`
check-docs: do not bother checking for legacy scripts' documentation
docs: exclude documentation for commands that have been excluded
check-docs: allow command-list.txt to contain excluded commands
help -a: do not list commands that are excluded from the build
Makefile: drop the NO_INSTALL variable
remote-testgit: move it into the support directory for t5801
Dev support update.
* js/check-docs-exe:
check-docs: fix for setups where executables have an extension
check-docs: do not expect guide pages to correspond to commands
check-docs: really look at the documented commands again
docs: do not document the `git remote-testgit` command
docs: move gitremote-helpers into section 7
When building with certain build options, some commands are excluded
from the build. For example, `git-credential-cache` is skipped when
building with `NO_UNIX_SOCKETS`.
Let's not build or package documentation for those excluded commands.
This issue was pointed out rightfully when running `make check-docs` on
Windows, where we do not yet have Unix sockets, and therefore the
`credential-cache` command is excluded (yet its documentation was built
and shipped).
Note: building the documentation via `make -C Documentation` leaves the
build system with no way to determine which commands have been
excluded. If called thusly, we gracefully fail to exclude their
documentation. Only when building the documentation via the top-level
Makefile will it get excluded properly, or after building
`Documentation/GIT-EXCLUDED-PROGRAMS` manually.
Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Dev support update to make it easier to compare two formatted
results from our documentation.
* ma/doc-diff-doc-vs-doctor-comparison:
doc-diff: add `--cut-header-footer`
doc-diff: support diffing from/to AsciiDoc(tor)
doc-diff: let `render_tree()` take an explicit directory name
Doc: auto-detect changed build flags
Build fix around use of asciidoctor instead of asciidoc
* ma/asciidoctor-fixes:
asciidoctor-extensions: fix spurious space after linkgit
Documentation/Makefile: add missing dependency on asciidoctor-extensions
Documentation/Makefile: add missing xsl dependencies for manpages
It is currently in section 1, but that section is intended for
"Executable programs or shell commands".
A more appropriate place is section 7: "Miscellaneous (including macro
packages and conventions), e.g. man(7), groff(7)".
This issue should have been detected earlier by `make check-docs`, but
was missed due to a bug in that Makefile target (that we are about to
fix).
Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
If you build the documentation switching between different options,
e.g., to build with both Asciidoc and Asciidoctor, you'll probably find
yourself running `make -C Documentation clean` either too often (wasting
time) or too rarely (getting mixed builds).
Track the flags we're using in the documentation build, similar to how
the main Makefile tracks CFLAGS and prefix flags. Track ASCIIDOC_COMMON
directly rather than its individual components -- that should make it
harder to forget to update the tracking if/when we modify the build
commands.
Signed-off-by: Martin Ågren <martin.agren@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
asciidoctor-extensions.rb has never changed, but when it does -- such as
in the next commit --, it helps if the xml-files depend on it. We're
casting the net a bit too wide here, since we'll be rebuilding even with
AsciiDoc, which won't look at this file. But since this file changes so
rarely, that should be ok. It's better than missing a dependency.
Similarly, most of the html-files are produced directly from ".txt';
make the html-files too depend on asciidoctor-extensions.rb, both
the HTMLified manual pages as well as the user-manual that does use
.xml intermediary.
Signed-off-by: Martin Ågren <martin.agren@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
These stylesheets very rarely change, but when they do, it really helps
if the manpages depend on them. We're casting the net a bit too wide
here, since we'll only ever use a subset of the stylesheets, but since
these files change so rarely, that should be ok. It's better than
missing a dependency.
Observe that manpage-base-url.xsl is a generated file, so we need to
list it explicitly, besides the `wildcard` expression we're adding here.
Signed-off-by: Martin Ågren <martin.agren@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The standard doc lists can be filtered to allow using the
compilation rules with translated manpages where all the pages of
the original version may not be present.
The install variable are reused in the secondary repo so that the
configured paths can be used for translated manpages too.
Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The git-multi-pack-index doc links to technical/multi-pack-index.html.
Ensure it is built to prevent a broken link.
Signed-off-by: Todd Zullinger <tmz@pobox.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
config.txt is going to be broken down in smaller pieces and put under
Documentation/config directory. Update build rules to take these files
into account.
A dummy file is added to make sure wildcard expansion is predictable
(depending on shell setting it could expand to nothing or becomes a
path if config directory is empty). The file will be deleted once the
move is over.
Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The exact sed command to generate manpage-base-url.xsl appears in
the output, unlike the rules for other files that by default only
show summary.
Make the output for this rule similiar to all the other rules by
printing a short status message instead of the whole command.
Signed-off-by: Tim Schumacher <timschumi@gmx.de>
Reviewed-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Rendered documentation can be easier to read than raw text because
headings and emphasized phrases stand out. Add the missing markup and
Makefile rule required to render this design document using asciidoc.
Tested by running
make -C Documentation technical/partial-clone.html
and viewing the output in a browser.
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Asciidoctor gives a reasonable imitation for AsciiDoc, but does not
render illustration in a literal block correctly when indented with
HT by default. The problem is fixed by forcing 8-space tabs.
* bc/asciidoctor-tab-width:
Documentation: render revisions correctly under Asciidoctor
Documentation: use 8-space tabs with Asciidoctor
The beginning of the next-gen transfer protocol.
* bw/protocol-v2: (35 commits)
remote-curl: don't request v2 when pushing
remote-curl: implement stateless-connect command
http: eliminate "# service" line when using protocol v2
http: don't always add Git-Protocol header
http: allow providing extra headers for http requests
remote-curl: store the protocol version the server responded with
remote-curl: create copy of the service name
pkt-line: add packet_buf_write_len function
transport-helper: introduce stateless-connect
transport-helper: refactor process_connect_service
transport-helper: remove name parameter
connect: don't request v2 when pushing
connect: refactor git_connect to only get the protocol version once
fetch-pack: support shallow requests
fetch-pack: perform a fetch using v2
upload-pack: introduce fetch server command
push: pass ref prefixes when pushing
fetch: pass ref prefixes when fetching
ls-remote: pass ref prefixes when requesting a remote's refs
transport: convert transport_get_remote_refs to take a list of ref prefixes
...
Asciidoctor expands tabs at the beginning of a line. However, it does
not expand them into 8 spaces by default. Since we use 8-space tabs,
tell Asciidoctor that we want 8 spaces by setting the tabsize attribute.
This ensures that our ASCII art renders properly.
Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Introduce git-serve, the base server for protocol version 2.
Protocol version 2 is intended to be a replacement for Git's current
wire protocol. The intention is that it will be a simpler, less
wasteful protocol which can evolve over time.
Protocol version 2 improves upon version 1 by eliminating the initial
ref advertisement. In its place a server will export a list of
capabilities and commands which it supports in a capability
advertisement. A client can then request that a particular command be
executed by providing a number of capabilities and command specific
parameters. At the completion of a command, a client can request that
another command be executed or can terminate the connection by sending a
flush packet.
Signed-off-by: Brandon Williams <bmwill@google.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
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>
