summaryrefslogtreecommitdiff
path: root/Documentation/Makefile
AgeCommit message (Collapse)AuthorFilesLines
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
2012-06-08docs: fix cross-directory linkgit referencesLibravatar Jeff King1-0/+2
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>
2012-05-30docs: drop antique comment from MakefileLibravatar Jeff King1-9/+0
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>
2012-05-30docs: drop asciidoc7compatible flagLibravatar Jeff King1-9/+0
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>
2012-05-02Merge branch 'jk/doc-asciidoc-inline-literal'Libravatar Junio C Hamano1-1/+1
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
2012-04-26docs: stop using asciidoc no-inline-literalLibravatar Jeff King1-1/+1
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>
2012-04-10var doc: advertise current DEFAULT_PAGER and DEFAULT_EDITOR settingsLibravatar Jonathan Nieder1-0/+10
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>
2012-01-18pulling signed tag: add howto documentLibravatar Junio C Hamano1-1/+4
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-12-11docs: end-user documentation for the credential subsystemLibravatar Jeff King1-0/+1
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>
2011-11-08Sync with 1.7.7.3Libravatar Junio C Hamano1-6/+17
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-11-08docs: Update install-doc-quickLibravatar Junio C Hamano1-6/+17
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>
2011-10-16gitweb: Add gitweb(1) manpage for gitweb itselfLibravatar Jakub Narebski1-1/+1
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>
2011-10-16gitweb: Add gitweb.conf(5) manpage for gitweb configuration filesLibravatar Drew Northup1-1/+1
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>