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>
