summaryrefslogtreecommitdiff
path: root/Documentation/Makefile
AgeCommit message (Collapse)AuthorFilesLines
2017-12-12install-doc-quick: allow specifying what ref to installLibravatar Randall S. Becker1-2/+3
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>
2017-11-13Documentation: convert SubmittingPatches to AsciiDocLibravatar brian m. carlson1-0/+5
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>
2017-10-30Documentation: enable compat-mode for AsciidoctorLibravatar brian m. carlson1-0/+1
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>
2017-09-28technical doc: add a design doc for hash function transitionLibravatar Jonathan Nieder1-0/+1
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>
2017-06-22submodules: overhaul documentationLibravatar Stefan Beller1-0/+1
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>
2017-02-02Merge branch 'bc/use-asciidoctor-opt'Libravatar Junio C Hamano1-4/+16
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
2017-01-31Documentation: implement linkgit macro for AsciidoctorLibravatar brian m. carlson1-3/+1
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>
2017-01-23Makefile: add a knob to enable the use of AsciidoctorLibravatar brian m. carlson1-0/+12
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>
2017-01-23Documentation: move dblatex arguments into variableLibravatar brian m. carlson1-1/+2
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>
2017-01-23Documentation: add XSLT to fix DocBook for TexinfoLibravatar brian m. carlson1-3/+4
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>
2017-01-23Documentation: sort sources for gitman.texiLibravatar brian m. carlson1-1/+1
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>
2017-01-13asciidoctor: fix user-manual to be built by `asciidoctor`Libravatar 마누엘1-1/+1
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>
2016-06-17Documentation/technical: describe signature formatsLibravatar Michael J Gruber1-0/+1
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>
2016-05-31Documentation: bold literals in manLibravatar Erwan Mathoniere1-1/+1
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>
2016-05-10ci: validate "linkgit:" in documentationLibravatar Junio C Hamano1-0/+4
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>
2015-01-22Documentation: fix version numberingLibravatar Sven van Haastregt1-1/+1
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>
2014-10-29Merge branch 'bc/asciidoctor'Libravatar Junio C Hamano1-11/+15
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
2014-10-27Documentation: refactor common operations into variablesLibravatar brian m. carlson1-11/+11
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>
2014-10-15Documentation: move some AsciiDoc parameters into variablesLibravatar brian m. carlson1-7/+11
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>
2014-10-10doc: add 'everyday' to 'git help'Libravatar Philip Oakley1-1/+2
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>
2014-10-10doc: Makefile regularise OBSOLETE_HTML list buildingLibravatar Philip Oakley1-1/+2
Helped-by: Junio C Hamano <gitster@pobox.com> Signed-off-by: Philip Oakley <philipoakley@iee.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2014-05-28How to keep a project's canonical history correct.Libravatar Stephen P. Smith1-0/+1
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>
2014-01-27Documentation: make it easier to maintain enumerated documentsLibravatar Junio C Hamano1-3/+6
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>
2014-01-27create HTML for http-protocol.txtLibravatar Thomas Ackermann1-1/+2
./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>
2014-01-06user-manual: improve html and pdf formattingLibravatar Thomas Ackermann1-1/+1
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>
2013-10-25howto: add article on recovering a corrupted objectLibravatar Jeff King1-0/+1
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>
2013-10-03Documentation/Makefile: make AsciiDoc dblatex dir configurableLibravatar John Keeping1-1/+2
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>
2013-06-17Documentation/Makefile: move infodir to be with other '*dir'sLibravatar John Keeping1-1/+1
Signed-off-by: John Keeping <john@keeping.me.uk> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-06-17Documentation/Makefile: fix spaces around assignmentsLibravatar John Keeping1-21/+21
A simple style fix; no functional change. Signed-off-by: John Keeping <john@keeping.me.uk> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-07Merge branch 'da/mergetool-docs'Libravatar Junio C Hamano1-2/+20
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
2013-02-07Merge branch 'jk/doc-makefile-cleanup'Libravatar Junio C Hamano1-9/+30
* jk/doc-makefile-cleanup: Documentation/Makefile: clean up MAN*_TXT lists
2013-02-07Merge branch 'jk/remote-helpers-doc'Libravatar Junio C Hamano1-2/+9
"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
2013-02-02doc: generate a list of valid merge toolsLibravatar David Aguilar1-2/+20
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>
2013-02-01Rename {git- => git}remote-helpers.txtLibravatar John Keeping1-2/+9
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>
2013-02-01Documentation: the name of the system is 'Git', not 'git'Libravatar Thomas Ackermann1-2/+2
Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-01Documentation/Makefile: clean up MAN*_TXT listsLibravatar Jeff King1-9/+29
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>
2013-01-14Merge branch 'jn/xml-depends-on-asciidoc-conf' into maintLibravatar Junio C Hamano1-5/+3
* jn/xml-depends-on-asciidoc-conf: docs: manpage XML depends on asciidoc.conf
2013-01-11Merge branch 'jn/xml-depends-on-asciidoc-conf'Libravatar Junio C Hamano1-5/+3
* jn/xml-depends-on-asciidoc-conf: docs: manpage XML depends on asciidoc.conf
2013-01-06docs: manpage XML depends on asciidoc.confLibravatar Jonathan Nieder1-5/+3
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>
2012-12-22Merge branch 'maint'Libravatar Junio C Hamano1-1/+1
2012-12-22Merge branch 'ta/doc-cleanup' into maintLibravatar Junio C Hamano1-2/+24
* 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
2012-12-22Sort howto documents in howto-index.txtLibravatar Thomas Ackermann1-1/+1
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>
2012-12-21Merge branch 'ta/new-command-howto'Libravatar Junio C Hamano1-0/+1
* ta/new-command-howto: Move ./technical/api-command.txt to ./howto/new-command.txt
2012-12-21Move ./technical/api-command.txt to ./howto/new-command.txtLibravatar Thomas Ackermann1-0/+1
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>
2012-12-19Remove duplicate entry in ./Documentation/MakefileLibravatar Thomas Ackermann1-1/+0
Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-10-25Documentation: build html for all files in technical and howtoLibravatar Thomas Ackermann1-2/+24
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>
2012-09-19Documentation/Makefile: Allow custom XMLTO binaryLibravatar Dave Borowitz1-2/+3
Signed-off-by: Dave Borowitz <dborowitz@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-08-08check-docs: get documented command list from MakefileLibravatar Jeff King1-0/+3
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>
2012-06-25Merge branch 'jk/no-more-asciidoc7'Libravatar Junio C Hamano1-18/+0
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
2012-06-08Merge branch 'mm/api-credentials-doc'Libravatar Junio C Hamano1-0/+2
Finishing touches... * mm/api-credentials-doc: docs: fix cross-directory linkgit references