development/git
development/git
1
0
Fork 0
mirror of https://github.com/git/git synced 2024-11-05 18:59:29 +00:00
Code Issues Projects Releases Packages Wiki Activity
git/Documentation/Makefile

492 lines
14 KiB
Makefile
Raw Normal View History

Documentation/Makefile: clean up MAN*_TXT lists 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-02-01 19:41:14 +00:00
# Guard against environment variables
MAN1_TXT =
MAN5_TXT =
MAN7_TXT =
Documentation: make it easier to maintain enumerated documents 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-27 17:04:32 +00:00
TECH_DOCS =
ARTICLES =
SP_ARTICLES =
doc: Makefile regularise OBSOLETE_HTML list building 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-10-10 21:25:36 +00:00
OBSOLETE_HTML =
Documentation/Makefile: clean up MAN*_TXT lists 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-02-01 19:41:14 +00:00
docs: exclude documentation for commands that have been excluded 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>
2019-04-18 13:16:44 +00:00
-include GIT-EXCLUDED-PROGRAMS
Documentation/Makefile: clean up MAN*_TXT lists 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-02-01 19:41:14 +00:00
MAN1_TXT += $(filter-out \
docs: exclude documentation for commands that have been excluded 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>
2019-04-18 13:16:44 +00:00
$(patsubst %,%.txt,$(EXCLUDED_PROGRAMS)) \
Documentation/Makefile: clean up MAN*_TXT lists 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-02-01 19:41:14 +00:00
$(addsuffix .txt, $(ARTICLES) $(SP_ARTICLES)), \
$(wildcard git-*.txt))
MAN1_TXT += git.txt
MAN1_TXT += gitk.txt
MAN1_TXT += gitweb.txt
MAN5_TXT += gitattributes.txt
MAN5_TXT += githooks.txt
MAN5_TXT += gitignore.txt
MAN5_TXT += gitmodules.txt
MAN5_TXT += gitrepository-layout.txt
MAN5_TXT += gitweb.conf.txt
MAN7_TXT += gitcli.txt
MAN7_TXT += gitcore-tutorial.txt
docs: end-user documentation for the credential subsystem 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-12-10 10:31:38 +00:00
MAN7_TXT += gitcredentials.txt
Documentation/Makefile: clean up MAN*_TXT lists 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-02-01 19:41:14 +00:00
MAN7_TXT += gitcvs-migration.txt
MAN7_TXT += gitdiffcore.txt
doc: add 'everyday' to 'git help' 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-10 21:25:37 +00:00
MAN7_TXT += giteveryday.txt
Documentation/Makefile: clean up MAN*_TXT lists 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-02-01 19:41:14 +00:00
MAN7_TXT += gitglossary.txt
MAN7_TXT += gitnamespaces.txt
docs: move gitremote-helpers into section 7 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>
2019-03-25 21:41:36 +00:00
MAN7_TXT += gitremote-helpers.txt
Documentation/Makefile: clean up MAN*_TXT lists 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-02-01 19:41:14 +00:00
MAN7_TXT += gitrevisions.txt
submodules: overhaul documentation 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-06-22 21:01:49 +00:00
MAN7_TXT += gitsubmodules.txt
Documentation/Makefile: clean up MAN*_TXT lists 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-02-01 19:41:14 +00:00
MAN7_TXT += gittutorial-2.txt
MAN7_TXT += gittutorial.txt
MAN7_TXT += gitworkflows.txt
[PATCH 4/4] split core-git.txt and update Makefile for html and man Signed-off-by: David Greaves <david@dgreaves.com>
2005-05-10 21:32:39 +00:00
Documentation/Makefile add optional targets for l10n 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>
2019-01-07 19:21:12 +00:00
ifdef MAN_FILTER
MAN_TXT = $(filter $(MAN_FILTER),$(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT))
else
Documentation: add gitman.info target Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-10 09:15:57 +00:00
MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT)
Documentation/Makefile add optional targets for l10n 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>
2019-01-07 19:21:12 +00:00
MAN_FILTER = $(MAN_TXT)
endif
Documentation/Makefile: fix spaces around assignments 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-06-16 17:13:00 +00:00
MAN_XML = $(patsubst %.txt,%.xml,$(MAN_TXT))
MAN_HTML = $(patsubst %.txt,%.html,$(MAN_TXT))
install-doc-quick: allow specifying what ref to install 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-12-09 22:07:57 +00:00
GIT_MAN_REF = master
Documentation: add gitman.info target Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-10 09:15:57 +00:00
doc: add 'everyday' to 'git help' 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-10 21:25:37 +00:00
OBSOLETE_HTML += everyday.html
doc: Makefile regularise OBSOLETE_HTML list building 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-10-10 21:25:36 +00:00
OBSOLETE_HTML += git-remote-helpers.html
Documentaion updates. Mostly making the formatted html prettier. Signed-off-by: Junio C Hamano <junkio@cox.net> (cherry picked from 7adf1f15ebe074d4767df941817a6cf86d8e2533 commit)
2005-08-30 20:51:01 +00:00
Documentation: make it easier to maintain enumerated documents 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-27 17:04:32 +00:00
ARTICLES += howto-index
Documentation/Makefile: Some `git-*.txt' files aren't manpages. In particular, git-tools.txt isn't a manpage, and my Asciidoc gets upset by it. The simplest fix is to Remove articles from the list of manpages the Makefile. Signed-off-by: Mark Wooding <mdw@distorted.org.uk> Signed-off-by: Junio C Hamano <junkio@cox.net>
2006-03-05 09:36:33 +00:00
ARTICLES += git-tools
Documentation: add "Fighting regressions with git bisect" article This patch adds an asciidoc version of the "Fighting regressions with git bisect" article that the author wrote for the Linux-Kongress 2009 (http://www.linux-kongress.org/2009). This paper might be interesting to people who want to learn as much as possible about "git bisect" from a single document. The slides of the related presentation are available at: http://www.linux-kongress.org/2009/slides/fighting_regressions_with_git_bisect_christian_couder.pdf But the Linux Kongress people will not publish this paper online because they print the papers on their UpTimes magazine (http://www.lob.de/isbn/978-3-86541-358-1). But they don't take away the rights of the author (which is very nice), so I have the right to publish it. Signed-off-by: Christian Couder <chriscool@tuxfamily.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-11-08 15:09:47 +00:00
ARTICLES += git-bisect-lk2009
Documentaion updates. Mostly making the formatted html prettier. Signed-off-by: Junio C Hamano <junkio@cox.net> (cherry picked from 7adf1f15ebe074d4767df941817a6cf86d8e2533 commit)
2005-08-30 20:51:01 +00:00
# with their own formatting rules.
Documentation: make it easier to maintain enumerated documents 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-27 17:04:32 +00:00
SP_ARTICLES += user-manual
Move ./technical/api-command.txt to ./howto/new-command.txt 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-21 18:05:28 +00:00
SP_ARTICLES += howto/new-command
pulling signed tag: add howto document Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-01-17 22:52:24 +00:00
SP_ARTICLES += howto/revert-branch-rebase
SP_ARTICLES += howto/using-merge-subtree
SP_ARTICLES += howto/using-signed-tag-in-pull-request
Documentation: build html for all files in technical and howto 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-10-23 17:58:04 +00:00
SP_ARTICLES += howto/use-git-daemon
SP_ARTICLES += howto/update-hook-example
SP_ARTICLES += howto/setup-git-server-over-http
SP_ARTICLES += howto/separating-topic-branches
SP_ARTICLES += howto/revert-a-faulty-merge
SP_ARTICLES += howto/recover-corrupted-blob-object
howto: add article on recovering a corrupted object 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-25 07:55:02 +00:00
SP_ARTICLES += howto/recover-corrupted-object-harder
Documentation: build html for all files in technical and howto 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-10-23 17:58:04 +00:00
SP_ARTICLES += howto/rebuild-from-update-hook
SP_ARTICLES += howto/rebase-from-internal-branch
How to keep a project's canonical history correct. 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-05-09 06:08:41 +00:00
SP_ARTICLES += howto/keep-canonical-history-correct
Documentation: build html for all files in technical and howto 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-10-23 17:58:04 +00:00
SP_ARTICLES += howto/maintain-git
Start preparing the API documents. Most of them are still stubs, but the procedure to build the HTML documentation, maintaining the index and installing the end product are there. I placed names of people who are likely to know the most about the topic in the stub files, so that volunteers will know whom to ask questions as needed. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-11-25 07:48:04 +00:00
API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technical/api-index.txt, $(wildcard technical/api-*.txt)))
SP_ARTICLES += $(API_DOCS)
Documentation: build html for all files in technical and howto 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-10-23 17:58:04 +00:00
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>
2019-05-17 19:07:02 +00:00
TECH_DOCS += MyFirstContribution
documentation: add tutorial for object walking 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>
2019-10-11 23:55:54 +00:00
TECH_DOCS += MyFirstObjectWalk
Documentation: convert SubmittingPatches to AsciiDoc 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-11-12 22:07:18 +00:00
TECH_DOCS += SubmittingPatches
technical doc: add a design doc for hash function transition 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-09-28 04:43:21 +00:00
TECH_DOCS += technical/hash-function-transition
Documentation: make it easier to maintain enumerated documents 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-27 17:04:32 +00:00
TECH_DOCS += technical/http-protocol
create HTML for http-protocol.txt ./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-26 12:57:19 +00:00
TECH_DOCS += technical/index-format
Docs: split out long-running subprocess handshake 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 fa64a2fdbeed ("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>
2018-01-25 18:53:24 +00:00
TECH_DOCS += technical/long-running-process-protocol
Documentation: build technical/multi-pack-index 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>
2018-11-20 18:04:54 +00:00
TECH_DOCS += technical/multi-pack-index
Documentation: build html for all files in technical and howto 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-10-23 17:58:04 +00:00
TECH_DOCS += technical/pack-format
TECH_DOCS += technical/pack-heuristics
TECH_DOCS += technical/pack-protocol
partial-clone: render design doc using asciidoc 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>
2018-08-14 22:28:46 +00:00
TECH_DOCS += technical/partial-clone
Documentation: build html for all files in technical and howto 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-10-23 17:58:04 +00:00
TECH_DOCS += technical/protocol-capabilities
TECH_DOCS += technical/protocol-common
serve: introduce git-serve 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>
2018-03-15 17:31:19 +00:00
TECH_DOCS += technical/protocol-v2
Documentation: build html for all files in technical and howto 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-10-23 17:58:04 +00:00
TECH_DOCS += technical/racy-git
TECH_DOCS += technical/send-pack-pipeline
TECH_DOCS += technical/shallow
Documentation/technical: describe signature formats 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-06-17 07:46:08 +00:00
TECH_DOCS += technical/signature-format
Documentation: build html for all files in technical and howto 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-10-23 17:58:04 +00:00
TECH_DOCS += technical/trivial-merge
SP_ARTICLES += $(TECH_DOCS)
Start preparing the API documents. Most of them are still stubs, but the procedure to build the HTML documentation, maintaining the index and installing the end product are there. I placed names of people who are likely to know the most about the topic in the stub files, so that volunteers will know whom to ask questions as needed. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-11-25 07:48:04 +00:00
SP_ARTICLES += technical/api-index
Documentaion updates. Mostly making the formatted html prettier. Signed-off-by: Junio C Hamano <junkio@cox.net> (cherry picked from 7adf1f15ebe074d4767df941817a6cf86d8e2533 commit)
2005-08-30 20:51:01 +00:00
Documentation/Makefile add optional targets for l10n 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>
2019-01-07 19:21:12 +00:00
ARTICLES_HTML += $(patsubst %,%.html,$(ARTICLES) $(SP_ARTICLES))
HTML_FILTER ?= $(ARTICLES_HTML) $(OBSOLETE_HTML)
DOC_HTML = $(MAN_HTML) $(filter $(HTML_FILTER),$(ARTICLES_HTML) $(OBSOLETE_HTML))
Make sure howto/*.html is built as well. Signed-off-by: Junio C Hamano <junkio@cox.net>
2005-08-30 06:09:22 +00:00
Documentation/Makefile add optional targets for l10n 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>
2019-01-07 19:21:12 +00:00
DOC_MAN1 = $(patsubst %.txt,%.1,$(filter $(MAN_FILTER),$(MAN1_TXT)))
DOC_MAN5 = $(patsubst %.txt,%.5,$(filter $(MAN_FILTER),$(MAN5_TXT)))
DOC_MAN7 = $(patsubst %.txt,%.7,$(filter $(MAN_FILTER),$(MAN7_TXT)))
[PATCH] Docs - Makefile update A Makefile that works just fine when the 6 character patch is applied to asciidoc Signed-off-by: David Greaves <david@dgreaves.com> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
2005-05-22 17:44:15 +00:00
Documentation/Makefile: fix spaces around assignments 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-06-16 17:13:00 +00:00
prefix ?= $(HOME)
bindir ?= $(prefix)/bin
htmldir ?= $(prefix)/share/doc/git-doc
Documentation/Makefile: move infodir to be with other '*dir's Signed-off-by: John Keeping <john@keeping.me.uk> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-06-16 17:13:01 +00:00
infodir ?= $(prefix)/share/info
Documentation/Makefile: fix spaces around assignments 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-06-16 17:13:00 +00:00
pdfdir ?= $(prefix)/share/doc/git-doc
mandir ?= $(prefix)/share/man
man1dir = $(mandir)/man1
man5dir = $(mandir)/man5
man7dir = $(mandir)/man7
# DESTDIR =
[PATCH] Add doc and install-doc targets to the Makefile This makes it straightforward for people wanting to build and install the git man pages and the rest of the documentation to do so. Signed-off-by: Eric W. Biederman <ebiederm@xmission.com> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
2005-07-15 01:21:57 +00:00
Documentation/Makefile: Allow custom XMLTO binary Signed-off-by: Dave Borowitz <dborowitz@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-09-19 17:06:37 +00:00
ASCIIDOC = asciidoc
Add release notes to the distribution. This also adds a hook in the Makefile I can use to automatically include pointers to documentation for older releases when updating the pages at http://kernel.org/pub/software/scm/git/docs/. Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-02-13 23:15:05 +00:00
ASCIIDOC_EXTRA =
Documentation: move some AsciiDoc parameters into variables 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-11 23:37:35 +00:00
ASCIIDOC_HTML = xhtml11
ASCIIDOC_DOCBOOK = docbook
ASCIIDOC_CONF = -f asciidoc.conf
Documentation: refactor common operations 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>
2014-10-27 00:13:42 +00:00
ASCIIDOC_COMMON = $(ASCIIDOC) $(ASCIIDOC_EXTRA) $(ASCIIDOC_CONF) \
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>
2019-09-16 19:00:26 +00:00
-amanversion=$(GIT_VERSION) \
-amanmanual='Git Manual' -amansource='Git'
Documentation: refactor common operations 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>
2014-10-27 00:13:42 +00:00
TXT_TO_HTML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_HTML)
TXT_TO_XML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_DOCBOOK)
Documentation: move callouts.xsl to manpage-{base,normal}.xsl Each of manpage-base.xsl and manpage-normal.xsl gets a copy of the contents of callouts.xsl and the original is removed. The Makefile is adjusted to refer to manpage-normal.xsl instead of callouts.xsl. manpage-base.xsl will be later made into a common base for -normal and -1.72. Testing done with asciidoc 8.3.1 and docbook-xsl 1.74.0. Signed-off-by: Chris Johnsen <chris_johnsen@pobox.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-03-27 06:43:58 +00:00
MANPAGE_XSL = manpage-normal.xsl
Documentation/Makefile: Allow custom XMLTO binary Signed-off-by: Dave Borowitz <dborowitz@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-09-19 17:06:37 +00:00
XMLTO = xmlto
Documentation: option to render literal text as bold for manpages This allows manpages viewed on a tty to render inline literal text in a manner that is distinct from the surrounding text. The initial implementation (pre-mailing-list) of this patch included a conditional variant of the XSLT code in manpage-base.xsl and use xmlto's --stringparam option to optionally enable the functionality. It turns out that --stringparam is broken in all versions of xmlto except for the pre-release, SVN version. Since xmlto is a shell script the patch to fix it is simple enough, but I instead opted to use xmlto's "module" functionality. Testing done with asciidoc 8.3.1 and docbook-xsl 1.74.0. Signed-off-by: Chris Johnsen <chris_johnsen@pobox.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-03-27 06:44:05 +00:00
XMLTO_EXTRA =
Documentation/Makefile: fix spaces around assignments 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-06-16 17:13:00 +00:00
INSTALL ?= install
Use $(RM) in Makefiles instead of 'rm -f' Signed-off-by: Emil Medve <Emilian.Medve@Freescale.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-07-14 17:51:44 +00:00
RM ?= rm -f
docs: Update install-doc-quick 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-11-08 18:17:40 +00:00
MAN_REPO = ../../git-manpages
HTML_REPO = ../../git-htmldocs
[PATCH] Add doc and install-doc targets to the Makefile This makes it straightforward for people wanting to build and install the git man pages and the rest of the documentation to do so. Signed-off-by: Eric W. Biederman <ebiederm@xmission.com> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
2005-07-15 01:21:57 +00:00
Documentation/Makefile: fix spaces around assignments 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-06-16 17:13:00 +00:00
MAKEINFO = makeinfo
INSTALL_INFO = install-info
DOCBOOK2X_TEXI = docbook2x-texi
DBLATEX = dblatex
Documentation/Makefile: make AsciiDoc dblatex dir configurable 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-10-03 19:17:32 +00:00
ASCIIDOC_DBLATEX_DIR = /etc/asciidoc/dblatex
Documentation: move dblatex arguments into variable 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-22 02:41:55 +00:00
DBLATEX_COMMON = -p $(ASCIIDOC_DBLATEX_DIR)/asciidoc-dblatex.xsl -s $(ASCIIDOC_DBLATEX_DIR)/asciidoc-dblatex.sty
Run the specified perl in Documentation/ Makefile uses $(PERL_PATH) but Documentation/Makefile uses "perl"; that means the two Makefiles can use two different Perl installations. Teach Documentation/Makefile to use PERL_PATH that is exported from the toplevel Makefile, and give a sane fallback for people who run "make" from Documentation directory. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-01 02:36:34 +00:00
ifndef PERL_PATH
PERL_PATH = /usr/bin/perl
endif
Add support for an info version of the user manual These patches use docbook2x in order to create an info version of the git user manual. No existing Makefile targets (including "all") are touched, so you need to explicitly say make info sudo make install-info to get git.info created and installed. If the info target directory does not already contain a "dir" file, no directory entry is created. This facilitates $(DESTDIR)-based installations. The same could be achieved with sudo make INSTALL_INFO=: install-info explicitly. perl is used for patching up sub-par file and directory information in the Texinfo file. It would be cleaner to place the respective info straight into user-manual.txt or the conversion configurations, but I find myself unable to find out how to do this with Asciidoc/Texinfo. Signed-off-by: David Kastrup <dak@gnu.org>
2007-08-06 10:22:57 +00:00
Include config.mak.autogen in the doc Makefile ... to install documentation relative to the path set with configure's --prefix option. Signed-off-by: Jonas Fonseca <fonseca@diku.dk> Signed-off-by: Junio C Hamano <junkio@cox.net>
2006-08-31 22:31:08 +00:00
-include ../config.mak.autogen
Include config.mak in doc/Makefile config.mak.autogen is already there. Without this change it is not possible to override mandir in config.mak. Signed-off-by: Uwe Kleine-König <ukleinek@informatik.uni-freiburg.de> Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-02-28 20:57:42 +00:00
-include ../config.mak
Include config.mak.autogen in the doc Makefile ... to install documentation relative to the path set with configure's --prefix option. Signed-off-by: Jonas Fonseca <fonseca@diku.dk> Signed-off-by: Junio C Hamano <junkio@cox.net>
2006-08-31 22:31:08 +00:00
Documentation: rename docbook-xsl-172 attribute to git-asciidoc-no-roff It seems that the ability to use raw roff codes in asciidoc.conf was eliminated by docbook-xsl 1.72.0 _and later_. Unlike the 1.72.0-specific XSLT problem, this behavior was not reverted in later releases. This patch aims to make it clear that the affected asciidoc attribute (flag) can be reasonably used with docbook-xsl versions other than 1.72.0. Also, document which make variables should be set for various versions of asciidoc and docbook-xsl. Testing done with asciidoc 8.3.1 and docbook-xsl 1.74.0. Signed-off-by: Chris Johnsen <chris_johnsen@pobox.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-03-27 06:44:00 +00:00
#
# For docbook-xsl ...
docs: default to more modern toolset When the ASCIIDOC8 and ASCIIDOC_NO_ROFF knobs were built, many people were still on asciidoc 7 and using older versions of docbook-xsl. These days, even the almost 2-year-old Debian stable needs these knobs turned. So let's turn them by default. The new knobs ASCIIDOC7 and ASCIIDOC_ROFF can be used to get the old behavior if people are on older systems. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-11-19 17:54:24 +00:00
# -1.68.1, no extra settings are needed?
# 1.69.0, set ASCIIDOC_ROFF?
Documentation: use "spurious .sp" XSLT if DOCBOOK_SUPPRESS_SP is set With this change, the "spurious .sp" suppression XSLT code is disabled by default. It can be enabled by defining DOCBOOK_SUPPRESS_SP. The "spurious .sp" XSLT fragment was used to work around a bug first released in docbook-xsl 1.69.1. Modern versions of docbook-xsl are negatively affected by the code (some empty lines are omitted from manpage output; see <http://article.gmane.org/gmane.comp.version-control.git/115302>). The key revisions in the docbook SVN repo seem to be 5144 (before docbook-xsl 1.69.1) and 6359 (before docbook-xsl 1.71.1). Testing done with asciidoc 8.3.1 and docbook-xsl 1.74.0. Signed-off-by: Chris Johnsen <chris_johnsen@pobox.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-01 08:50:34 +00:00
# 1.69.1-1.71.0, set DOCBOOK_SUPPRESS_SP?
docs: default to more modern toolset When the ASCIIDOC8 and ASCIIDOC_NO_ROFF knobs were built, many people were still on asciidoc 7 and using older versions of docbook-xsl. These days, even the almost 2-year-old Debian stable needs these knobs turned. So let's turn them by default. The new knobs ASCIIDOC7 and ASCIIDOC_ROFF can be used to get the old behavior if people are on older systems. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-11-19 17:54:24 +00:00
# 1.71.1, set ASCIIDOC_ROFF?
Documentation: rename docbook-xsl-172 attribute to git-asciidoc-no-roff It seems that the ability to use raw roff codes in asciidoc.conf was eliminated by docbook-xsl 1.72.0 _and later_. Unlike the 1.72.0-specific XSLT problem, this behavior was not reverted in later releases. This patch aims to make it clear that the affected asciidoc attribute (flag) can be reasonably used with docbook-xsl versions other than 1.72.0. Also, document which make variables should be set for various versions of asciidoc and docbook-xsl. Testing done with asciidoc 8.3.1 and docbook-xsl 1.74.0. Signed-off-by: Chris Johnsen <chris_johnsen@pobox.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-03-27 06:44:00 +00:00
# 1.72.0, set DOCBOOK_XSL_172.
docs: default to more modern toolset When the ASCIIDOC8 and ASCIIDOC_NO_ROFF knobs were built, many people were still on asciidoc 7 and using older versions of docbook-xsl. These days, even the almost 2-year-old Debian stable needs these knobs turned. So let's turn them by default. The new knobs ASCIIDOC7 and ASCIIDOC_ROFF can be used to get the old behavior if people are on older systems. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-11-19 17:54:24 +00:00
# 1.73.0-, no extra settings are needed
Documentation: rename docbook-xsl-172 attribute to git-asciidoc-no-roff It seems that the ability to use raw roff codes in asciidoc.conf was eliminated by docbook-xsl 1.72.0 _and later_. Unlike the 1.72.0-specific XSLT problem, this behavior was not reverted in later releases. This patch aims to make it clear that the affected asciidoc attribute (flag) can be reasonably used with docbook-xsl versions other than 1.72.0. Also, document which make variables should be set for various versions of asciidoc and docbook-xsl. Testing done with asciidoc 8.3.1 and docbook-xsl 1.74.0. Signed-off-by: Chris Johnsen <chris_johnsen@pobox.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-03-27 06:44:00 +00:00
#
Documentation: Fix man page breakage with DocBook XSL v1.72 From version 1.72 it will replace all dots in roff requests with U+2302 ("house" character), and add escaping in output for all instances of dot that are not in roff requests. This caused the ".ft" hack forcing monospace font in listingblocks to end up as "\&.ft" and being visible in the resulting man page. The fix adds a DOCBOOK_XSL_172 build variable that will disable the hack. To allow this variable to be defined in config.mak it also moves build variable handling below the inclusion of config.mak. Signed-off-by: Jonas Fonseca <fonseca@diku.dk> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-11-14 09:38:46 +00:00
ifdef DOCBOOK_XSL_172
Documentation: rename docbook-xsl-172 attribute to git-asciidoc-no-roff It seems that the ability to use raw roff codes in asciidoc.conf was eliminated by docbook-xsl 1.72.0 _and later_. Unlike the 1.72.0-specific XSLT problem, this behavior was not reverted in later releases. This patch aims to make it clear that the affected asciidoc attribute (flag) can be reasonably used with docbook-xsl versions other than 1.72.0. Also, document which make variables should be set for various versions of asciidoc and docbook-xsl. Testing done with asciidoc 8.3.1 and docbook-xsl 1.74.0. Signed-off-by: Chris Johnsen <chris_johnsen@pobox.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-03-27 06:44:00 +00:00
ASCIIDOC_EXTRA += -a git-asciidoc-no-roff
man pages are littered with .ft C and others Jakub Narebski <jnareb@gmail.com> wrote Sun, Feb 03, 2008: > Junio C Hamano wrote: > > Jakub Narebski <jnareb@gmail.com> writes: > > > > [From] http://thread.gmane.org/gmane.comp.version-control.git/53457/focus=53458 > Julian Phillips: > > Are you using docbook xsl 1.72? There are known problems building the > > manpages with that version. 1.71 works, and 1.73 should work when it get > > released. I was able to solve this problem with this patch, which adds a XSL file used specifically for DOCBOOK_XSL_172=YesPlease and where dots and backslashes are escaped properly so they won't be substituted to the wrong thing further down the "DocBook XSL pipeline". Doing the escaping in the existing callout.xsl breaks v1.70.1. Hopefully v1.73 will end this part of the manpage nightmare. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-02-04 22:01:20 +00:00
MANPAGE_XSL = manpage-1.72.xsl
Documentation: rename docbook-xsl-172 attribute to git-asciidoc-no-roff It seems that the ability to use raw roff codes in asciidoc.conf was eliminated by docbook-xsl 1.72.0 _and later_. Unlike the 1.72.0-specific XSLT problem, this behavior was not reverted in later releases. This patch aims to make it clear that the affected asciidoc attribute (flag) can be reasonably used with docbook-xsl versions other than 1.72.0. Also, document which make variables should be set for various versions of asciidoc and docbook-xsl. Testing done with asciidoc 8.3.1 and docbook-xsl 1.74.0. Signed-off-by: Chris Johnsen <chris_johnsen@pobox.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-03-27 06:44:00 +00:00
else
docs: default to more modern toolset When the ASCIIDOC8 and ASCIIDOC_NO_ROFF knobs were built, many people were still on asciidoc 7 and using older versions of docbook-xsl. These days, even the almost 2-year-old Debian stable needs these knobs turned. So let's turn them by default. The new knobs ASCIIDOC7 and ASCIIDOC_ROFF can be used to get the old behavior if people are on older systems. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-11-19 17:54:24 +00:00
ifndef ASCIIDOC_ROFF
Documentation: rename docbook-xsl-172 attribute to git-asciidoc-no-roff It seems that the ability to use raw roff codes in asciidoc.conf was eliminated by docbook-xsl 1.72.0 _and later_. Unlike the 1.72.0-specific XSLT problem, this behavior was not reverted in later releases. This patch aims to make it clear that the affected asciidoc attribute (flag) can be reasonably used with docbook-xsl versions other than 1.72.0. Also, document which make variables should be set for various versions of asciidoc and docbook-xsl. Testing done with asciidoc 8.3.1 and docbook-xsl 1.74.0. Signed-off-by: Chris Johnsen <chris_johnsen@pobox.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-03-27 06:44:00 +00:00
# docbook-xsl after 1.72 needs the regular XSL, but will not
# pass-thru raw roff codes from asciidoc.conf, so turn them off.
ASCIIDOC_EXTRA += -a git-asciidoc-no-roff
endif
Documentation: Fix man page breakage with DocBook XSL v1.72 From version 1.72 it will replace all dots in roff requests with U+2302 ("house" character), and add escaping in output for all instances of dot that are not in roff requests. This caused the ".ft" hack forcing monospace font in listingblocks to end up as "\&.ft" and being visible in the resulting man page. The fix adds a DOCBOOK_XSL_172 build variable that will disable the hack. To allow this variable to be defined in config.mak it also moves build variable handling below the inclusion of config.mak. Signed-off-by: Jonas Fonseca <fonseca@diku.dk> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-11-14 09:38:46 +00:00
endif
Documentation: bold literals in man 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-31 16:20:33 +00:00
ifndef NO_MAN_BOLD_LITERAL
Documentation: option to render literal text as bold for manpages This allows manpages viewed on a tty to render inline literal text in a manner that is distinct from the surrounding text. The initial implementation (pre-mailing-list) of this patch included a conditional variant of the XSLT code in manpage-base.xsl and use xmlto's --stringparam option to optionally enable the functionality. It turns out that --stringparam is broken in all versions of xmlto except for the pre-release, SVN version. Since xmlto is a shell script the patch to fix it is simple enough, but I instead opted to use xmlto's "module" functionality. Testing done with asciidoc 8.3.1 and docbook-xsl 1.74.0. Signed-off-by: Chris Johnsen <chris_johnsen@pobox.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-03-27 06:44:05 +00:00
XMLTO_EXTRA += -m manpage-bold-literal.xsl
endif
Documentation: use "spurious .sp" XSLT if DOCBOOK_SUPPRESS_SP is set With this change, the "spurious .sp" suppression XSLT code is disabled by default. It can be enabled by defining DOCBOOK_SUPPRESS_SP. The "spurious .sp" XSLT fragment was used to work around a bug first released in docbook-xsl 1.69.1. Modern versions of docbook-xsl are negatively affected by the code (some empty lines are omitted from manpage output; see <http://article.gmane.org/gmane.comp.version-control.git/115302>). The key revisions in the docbook SVN repo seem to be 5144 (before docbook-xsl 1.69.1) and 6359 (before docbook-xsl 1.71.1). Testing done with asciidoc 8.3.1 and docbook-xsl 1.74.0. Signed-off-by: Chris Johnsen <chris_johnsen@pobox.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-01 08:50:34 +00:00
ifdef DOCBOOK_SUPPRESS_SP
XMLTO_EXTRA += -m manpage-suppress-sp.xsl
endif
Documentation: Fix man page breakage with DocBook XSL v1.72 From version 1.72 it will replace all dots in roff requests with U+2302 ("house" character), and add escaping in output for all instances of dot that are not in roff requests. This caused the ".ft" hack forcing monospace font in listingblocks to end up as "\&.ft" and being visible in the resulting man page. The fix adds a DOCBOOK_XSL_172 build variable that will disable the hack. To allow this variable to be defined in config.mak it also moves build variable handling below the inclusion of config.mak. Signed-off-by: Jonas Fonseca <fonseca@diku.dk> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-11-14 09:38:46 +00:00
Unconditionally set man.base.url.for.relative.links Even setting it to empty is better than leaving it unset as it prevents the warning cruft from appearing in the output. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-12-03 08:06:52 +00:00
# Newer DocBook stylesheet emits warning cruft in the output when
Documentation: Avoid use of xmlto --stringparam The --stringparam option is not available on older xmlto versions. Instead, set man.base.url.for.relative.links via a .xsl file. Older docbook versions will ignore this without causing grief to users of older xmlto versions. Signed-off-by: Todd Zullinger <tmz@pobox.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-12-04 17:53:21 +00:00
# this is not set, and if set it shows an absolute link. Older
# stylesheets simply ignore this parameter.
Documentation: xmlto 0.0.18 does not know --stringparam Newer DocBook stylesheets want man.base.url.for.relative.links parameter set when formatting manpages with external references to turn them into full URLs, and leave a helpful "you should set this parameter" message in the output. Earlier we added the MAN_BASE_URL make variable to specify the value for it. When MAN_BASE_URL is not given, it ought to be safe to set the parameter to empty; it would result in an empty leading path for older stylesheets that ignore the parameter, and newer ones would produce the same "relative URL" without the message. Unfortunately, older xmlto (at least version 0.0.18 released in early 2004 that comes with RHEL/CentOS 5) does not understand the --stringparam command line option, so we cannot add the parameter definition unconditionally to the command line. Work it around by passing the parameter only when set. If you do not have a suitable URL prefix, you can pass a quoted empty string to it, like so: $ make MAN_BASE_URL='""' Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-12-03 19:12:32 +00:00
#
Documentation: Avoid use of xmlto --stringparam The --stringparam option is not available on older xmlto versions. Instead, set man.base.url.for.relative.links via a .xsl file. Older docbook versions will ignore this without causing grief to users of older xmlto versions. Signed-off-by: Todd Zullinger <tmz@pobox.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-12-04 17:53:21 +00:00
# Distros may want to use MAN_BASE_URL=file:///path/to/git/docs/
# or similar.
ifndef MAN_BASE_URL
MAN_BASE_URL = file://$(htmldir)/
Documentation: xmlto 0.0.18 does not know --stringparam Newer DocBook stylesheets want man.base.url.for.relative.links parameter set when formatting manpages with external references to turn them into full URLs, and leave a helpful "you should set this parameter" message in the output. Earlier we added the MAN_BASE_URL make variable to specify the value for it. When MAN_BASE_URL is not given, it ought to be safe to set the parameter to empty; it would result in an empty leading path for older stylesheets that ignore the parameter, and newer ones would produce the same "relative URL" without the message. Unfortunately, older xmlto (at least version 0.0.18 released in early 2004 that comes with RHEL/CentOS 5) does not understand the --stringparam command line option, so we cannot add the parameter definition unconditionally to the command line. Work it around by passing the parameter only when set. If you do not have a suitable URL prefix, you can pass a quoted empty string to it, like so: $ make MAN_BASE_URL='""' Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-12-03 19:12:32 +00:00
endif
Documentation: Avoid use of xmlto --stringparam The --stringparam option is not available on older xmlto versions. Instead, set man.base.url.for.relative.links via a .xsl file. Older docbook versions will ignore this without causing grief to users of older xmlto versions. Signed-off-by: Todd Zullinger <tmz@pobox.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-12-04 17:53:21 +00:00
XMLTO_EXTRA += -m manpage-base-url.xsl
Documentation/Makefile: allow man.base.url.for.relative.link to be set from Make Signed-off-by: Junio C Hamano <junio@kernel.org>
2009-12-03 02:45:09 +00:00
Quote ' as \(aq in manpages The docbook/xmlto toolchain insists on quoting ' as \'. This does achieve the quoting goal, but modern 'man' implementations turn the apostrophe into a unicode "proper" apostrophe (given the right circumstances), breaking code examples in many of our manpages. Quote them as \(aq instead, which is an "apostrophe quote" as per the groff_char manpage. Unfortunately, as Anders Kaseorg kindly pointed out, this is not portable beyond groff, so we add an extra Makefile variable GNU_ROFF which you need to enable to get the new quoting. Thanks also to Miklos Vajna for documentation. Signed-off-by: Thomas Rast <trast@student.ethz.ch> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-10-22 08:19:06 +00:00
# If your target system uses GNU groff, it may try to render
# apostrophes as a "pretty" apostrophe using unicode. This breaks
# cut&paste, so you should set GNU_ROFF to force them to be ASCII
# apostrophes. Unfortunately does not work with non-GNU roff.
ifdef GNU_ROFF
XMLTO_EXTRA += -m manpage-quote-apos.xsl
endif
Makefile: add a knob to enable the use of Asciidoctor 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-22 02:41:56 +00:00
ifdef USE_ASCIIDOCTOR
ASCIIDOC = asciidoctor
ASCIIDOC_CONF =
ASCIIDOC_HTML = xhtml5
Documentation: fix build with Asciidoctor 2 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>
2019-09-15 22:43:32 +00:00
ASCIIDOC_DOCBOOK = docbook5
Documentation: use 8-space tabs with Asciidoctor 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>
2018-05-06 20:42:25 +00:00
ASCIIDOC_EXTRA += -acompat-mode -atabsize=8
Documentation: implement linkgit macro for Asciidoctor 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-26 00:13:44 +00:00
ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions
Makefile: add a knob to enable the use of Asciidoctor 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-22 02:41:56 +00:00
ASCIIDOC_EXTRA += -alitdd='&\#x2d;&\#x2d;'
DBLATEX_COMMON =
Documentation: fix build with Asciidoctor 2 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>
2019-09-15 22:43:32 +00:00
XMLTO_EXTRA += --skip-validation
XMLTO_EXTRA += -x manpage.xsl
Makefile: add a knob to enable the use of Asciidoctor 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-22 02:41:56 +00:00
endif
documentation: Makefile accounts for SHELL_PATH setting Ensure that the Makefile that generates and installs the Documentation is aware of any SHELL_PATH setting. Use this value if found or the current setting for SHELL if not. This is an accommodation for systems where sh is not POSIX enough. Signed-off-by: Ben Walton <bwalton@artsci.utoronto.ca> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-03-22 13:20:44 +00:00
SHELL_PATH ?= $(SHELL)
# Shell quote;
SHELL_PATH_SQ = $(subst ','\'',$(SHELL_PATH))
var doc: advertise current DEFAULT_PAGER and DEFAULT_EDITOR settings 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-03-31 08:44:53 +00:00
ifdef DEFAULT_PAGER
DEFAULT_PAGER_SQ = $(subst ','\'',$(DEFAULT_PAGER))
ASCIIDOC_EXTRA += -a 'git-default-pager=$(DEFAULT_PAGER_SQ)'
endif
ifdef DEFAULT_EDITOR
DEFAULT_EDITOR_SQ = $(subst ','\'',$(DEFAULT_EDITOR))
ASCIIDOC_EXTRA += -a 'git-default-editor=$(DEFAULT_EDITOR_SQ)'
endif
Documentation/Makefile: make most operations "quiet" This adapts the "quiet make" implementation from the main Makefile. Signed-off-by: Chris Johnsen <chris_johnsen@pobox.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-03-27 06:49:38 +00:00
QUIET_SUBDIR0 = +$(MAKE) -C # space to separate -C and subdir
QUIET_SUBDIR1 =
ifneq ($(findstring $(MAKEFLAGS),w),w)
PRINT_DIR = --no-print-directory
else # "make -w"
NO_SUBDIR = :
endif
ifneq ($(findstring $(MAKEFLAGS),s),s)
ifndef V
QUIET_ASCIIDOC = @echo ' ' ASCIIDOC $@;
QUIET_XMLTO = @echo ' ' XMLTO $@;
QUIET_DB2TEXI = @echo ' ' DB2TEXI $@;
QUIET_MAKEINFO = @echo ' ' MAKEINFO $@;
QUIET_DBLATEX = @echo ' ' DBLATEX $@;
QUIET_XSLTPROC = @echo ' ' XSLTPROC $@;
QUIET_GEN = @echo ' ' GEN $@;
ci: validate "linkgit:" in documentation 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>
2016-05-04 21:34:23 +00:00
QUIET_LINT = @echo ' ' LINT $@;
Documentation/Makefile: make most operations "quiet" This adapts the "quiet make" implementation from the main Makefile. Signed-off-by: Chris Johnsen <chris_johnsen@pobox.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-03-27 06:49:38 +00:00
QUIET_STDERR = 2> /dev/null
QUIET_SUBDIR0 = +@subdir=
QUIET_SUBDIR1 = ;$(NO_SUBDIR) echo ' ' SUBDIR $$subdir; \
$(MAKE) $(PRINT_DIR) -C $$subdir
export V
endif
endif
[PATCH] Docs - Makefile update A Makefile that works just fine when the 6 character patch is applied to asciidoc Signed-off-by: David Greaves <david@dgreaves.com> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
2005-05-22 17:44:15 +00:00
all: html man
[PATCH 4/4] split core-git.txt and update Makefile for html and man Signed-off-by: David Greaves <david@dgreaves.com>
2005-05-10 21:32:39 +00:00
html: $(DOC_HTML)
Documentation: support manual section (5) - file formats. Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-04-20 03:47:04 +00:00
man: man1 man5 man7
[PATCH] Docs - Makefile update A Makefile that works just fine when the 6 character patch is applied to asciidoc Signed-off-by: David Greaves <david@dgreaves.com> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
2005-05-22 17:44:15 +00:00
man1: $(DOC_MAN1)
Documentation: support manual section (5) - file formats. Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-04-20 03:47:04 +00:00
man5: $(DOC_MAN5)
[PATCH] Docs - Makefile update A Makefile that works just fine when the 6 character patch is applied to asciidoc Signed-off-by: David Greaves <david@dgreaves.com> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
2005-05-22 17:44:15 +00:00
man7: $(DOC_MAN7)
[PATCH 4/4] split core-git.txt and update Makefile for html and man Signed-off-by: David Greaves <david@dgreaves.com>
2005-05-10 21:32:39 +00:00
Documentation: add gitman.info target Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-10 09:15:57 +00:00
info: git.info gitman.info
Add support for an info version of the user manual These patches use docbook2x in order to create an info version of the git user manual. No existing Makefile targets (including "all") are touched, so you need to explicitly say make info sudo make install-info to get git.info created and installed. If the info target directory does not already contain a "dir" file, no directory entry is created. This facilitates $(DESTDIR)-based installations. The same could be achieved with sudo make INSTALL_INFO=: install-info explicitly. perl is used for patching up sub-par file and directory information in the Texinfo file. It would be cleaner to place the respective info straight into user-manual.txt or the conversion configurations, but I find myself unable to find out how to do this with Asciidoc/Texinfo. Signed-off-by: David Kastrup <dak@gnu.org>
2007-08-06 10:22:57 +00:00
Add support for a pdf version of the user manual Use dblatex in order to create a pdf version of the git user manual. No existing Makefile targets (including "all") are touched, so you need to explicitly say make pdf sudo make install-pdf to get user-manual.pdf created and installed. Signed-off-by: Miklos Vajna <vmiklos@frugalware.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-12-10 22:44:50 +00:00
pdf: user-manual.pdf
Makefile: add install-man rules (quick and normal) Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-11-02 17:53:03 +00:00
install: install-man
install-man: man
install-sh from automake does not like -m without delimiting space The install-sh script as shipped with automake requires a space between the -m switch and its argument. Since this is also the regular way of doing it with other install implementations this change inserts the missing space in all makefiles. Signed-off-by: Robert Schiele <rschiele@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-01 17:05:40 +00:00
$(INSTALL) -d -m 755 $(DESTDIR)$(man1dir)
$(INSTALL) -d -m 755 $(DESTDIR)$(man5dir)
$(INSTALL) -d -m 755 $(DESTDIR)$(man7dir)
$(INSTALL) -m 644 $(DOC_MAN1) $(DESTDIR)$(man1dir)
$(INSTALL) -m 644 $(DOC_MAN5) $(DESTDIR)$(man5dir)
$(INSTALL) -m 644 $(DOC_MAN7) $(DESTDIR)$(man7dir)
[PATCH] Add doc and install-doc targets to the Makefile This makes it straightforward for people wanting to build and install the git man pages and the rest of the documentation to do so. Signed-off-by: Eric W. Biederman <ebiederm@xmission.com> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
2005-07-15 01:21:57 +00:00
Add support for an info version of the user manual These patches use docbook2x in order to create an info version of the git user manual. No existing Makefile targets (including "all") are touched, so you need to explicitly say make info sudo make install-info to get git.info created and installed. If the info target directory does not already contain a "dir" file, no directory entry is created. This facilitates $(DESTDIR)-based installations. The same could be achieved with sudo make INSTALL_INFO=: install-info explicitly. perl is used for patching up sub-par file and directory information in the Texinfo file. It would be cleaner to place the respective info straight into user-manual.txt or the conversion configurations, but I find myself unable to find out how to do this with Asciidoc/Texinfo. Signed-off-by: David Kastrup <dak@gnu.org>
2007-08-06 10:22:57 +00:00
install-info: info
install-sh from automake does not like -m without delimiting space The install-sh script as shipped with automake requires a space between the -m switch and its argument. Since this is also the regular way of doing it with other install implementations this change inserts the missing space in all makefiles. Signed-off-by: Robert Schiele <rschiele@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-01 17:05:40 +00:00
$(INSTALL) -d -m 755 $(DESTDIR)$(infodir)
Documentation: add gitman.info target Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-10 09:15:57 +00:00
$(INSTALL) -m 644 git.info gitman.info $(DESTDIR)$(infodir)
Add support for an info version of the user manual These patches use docbook2x in order to create an info version of the git user manual. No existing Makefile targets (including "all") are touched, so you need to explicitly say make info sudo make install-info to get git.info created and installed. If the info target directory does not already contain a "dir" file, no directory entry is created. This facilitates $(DESTDIR)-based installations. The same could be achieved with sudo make INSTALL_INFO=: install-info explicitly. perl is used for patching up sub-par file and directory information in the Texinfo file. It would be cleaner to place the respective info straight into user-manual.txt or the conversion configurations, but I find myself unable to find out how to do this with Asciidoc/Texinfo. Signed-off-by: David Kastrup <dak@gnu.org>
2007-08-06 10:22:57 +00:00
if test -r $(DESTDIR)$(infodir)/dir; then \
$(INSTALL_INFO) --info-dir=$(DESTDIR)$(infodir) git.info ;\
Documentation: add gitman.info target Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-10 09:15:57 +00:00
$(INSTALL_INFO) --info-dir=$(DESTDIR)$(infodir) gitman.info ;\
Add support for an info version of the user manual These patches use docbook2x in order to create an info version of the git user manual. No existing Makefile targets (including "all") are touched, so you need to explicitly say make info sudo make install-info to get git.info created and installed. If the info target directory does not already contain a "dir" file, no directory entry is created. This facilitates $(DESTDIR)-based installations. The same could be achieved with sudo make INSTALL_INFO=: install-info explicitly. perl is used for patching up sub-par file and directory information in the Texinfo file. It would be cleaner to place the respective info straight into user-manual.txt or the conversion configurations, but I find myself unable to find out how to do this with Asciidoc/Texinfo. Signed-off-by: David Kastrup <dak@gnu.org>
2007-08-06 10:22:57 +00:00
else \
echo "No directory found in $(DESTDIR)$(infodir)" >&2 ; \
fi
Documentation: -merge and -pull: describe merge strategies. ... and give a couple of examples of running 'git pull' against local repository. Signed-off-by: Junio C Hamano <junkio@cox.net>
2005-11-04 08:06:20 +00:00
Add support for a pdf version of the user manual Use dblatex in order to create a pdf version of the git user manual. No existing Makefile targets (including "all") are touched, so you need to explicitly say make pdf sudo make install-pdf to get user-manual.pdf created and installed. Signed-off-by: Miklos Vajna <vmiklos@frugalware.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-12-10 22:44:50 +00:00
install-pdf: pdf
$(INSTALL) -d -m 755 $(DESTDIR)$(pdfdir)
$(INSTALL) -m 644 user-manual.pdf $(DESTDIR)$(pdfdir)
git-help: add -w|--web option to display html man page in a browser. Now when using "git help -w cmd", we will try to show the HTML man page "git-cmd.html" in your prefered web browser. To do that "help.c" code will call a new shell script "git-browse-help". This currently works only if the HTML versions of the man page have been installed in $(htmldir) (typically "/usr/share/doc/git-doc"), so new target to do that is added to "Documentation/Makefile". The browser to use can be configured using the "web.browser" config variable. We try to open a new tab in an existing web browser, if possible. The code in "git-browse-help" is heavily stolen from "git-mergetool" by Theodore Y. Ts'o. Thanks. Signed-off-by: Christian Couder <chriscool@tuxfamily.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-02 05:07:55 +00:00
install-html: html
documentation: Makefile accounts for SHELL_PATH setting Ensure that the Makefile that generates and installs the Documentation is aware of any SHELL_PATH setting. Use this value if found or the current setting for SHELL if not. This is an accommodation for systems where sh is not POSIX enough. Signed-off-by: Ben Walton <bwalton@artsci.utoronto.ca> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-03-22 13:20:44 +00:00
'$(SHELL_PATH_SQ)' ./install-webdoc.sh $(DESTDIR)$(htmldir)
git-help: add -w|--web option to display html man page in a browser. Now when using "git help -w cmd", we will try to show the HTML man page "git-cmd.html" in your prefered web browser. To do that "help.c" code will call a new shell script "git-browse-help". This currently works only if the HTML versions of the man page have been installed in $(htmldir) (typically "/usr/share/doc/git-doc"), so new target to do that is added to "Documentation/Makefile". The browser to use can be configured using the "web.browser" config variable. We try to open a new tab in an existing web browser, if possible. The code in "git-browse-help" is heavily stolen from "git-mergetool" by Theodore Y. Ts'o. Thanks. Signed-off-by: Christian Couder <chriscool@tuxfamily.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-02 05:07:55 +00:00
Makefile: consolidate .FORCE-* targets Providing multiple targets to force a rebuild is unnecessary complication. Avoid using a name that could conflict with future special targets in GNU make (a leading period followed by uppercase letters). The corresponding change to the git-gui Makefile is left for another patch. Signed-off-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-01-06 08:06:58 +00:00
../GIT-VERSION-FILE: FORCE
Documentation/Makefile: make most operations "quiet" This adapts the "quiet make" implementation from the main Makefile. Signed-off-by: Chris Johnsen <chris_johnsen@pobox.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-03-27 06:49:38 +00:00
$(QUIET_SUBDIR0)../ $(QUIET_SUBDIR1) GIT-VERSION-FILE
Documentation: Replace @@GIT_VERSION@@ in documentation Include GIT-VERSION-FILE and replace @@GIT_VERSION@@ in the HTML and XML asciidoc output. The documentation doesn't depend on GIT-VERSION-FILE so it will not be automatically rebuild if nothing else changed. [jc: fixing the case for interrupted build] Signed-off-by: Frank Lichtenheld <frank@lichtenheld.de> Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-03-25 11:56:49 +00:00
-include ../GIT-VERSION-FILE
Refactored merge options into separate merge-options.txt. Refactored fetch options into separate fetch-options.txt. Made git-merge use merge-options. Made git-fetch use fetch-options. Made git-pull use merge-options and fetch-options. Added --help option to git-pull and git-format-patch scripts. Rewrote Documentation/Makefile to dynamically determine include dependencies. Signed-off-by: Jon Loeliger <jdl@freescale.com> Signed-off-by: Junio C Hamano <junkio@cox.net>
2005-11-07 05:30:56 +00:00
#
# Determine "include::" file references in asciidoc files.
#
doc: generate a list of valid merge tools 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-01-28 00:52:26 +00:00
docdep_prereqs = \
mergetools-list.made $(mergetools_txt) \
cmd-list.made $(cmds_txt)
Update makefile in preparation for Documentation/config/*.txt 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>
2018-10-27 06:22:34 +00:00
doc.dep : $(docdep_prereqs) $(wildcard *.txt) $(wildcard config/*.txt) build-docdep.perl
Documentation/Makefile: make most operations "quiet" This adapts the "quiet make" implementation from the main Makefile. Signed-off-by: Chris Johnsen <chris_johnsen@pobox.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-03-27 06:49:38 +00:00
$(QUIET_GEN)$(RM) $@+ $@ && \
$(PERL_PATH) ./build-docdep.perl >$@+ $(QUIET_STDERR) && \
Fix documentation dependency generation. Documentation/Makefile spent a lot of time to generate include dependencies, which was quite noticeable especially during "make clean". Rewrite it to generate just a single dependency file. Signed-off-by: Junio C Hamano <junkio@cox.net>
2005-11-08 02:21:51 +00:00
mv $@+ $@
Refactored merge options into separate merge-options.txt. Refactored fetch options into separate fetch-options.txt. Made git-merge use merge-options. Made git-fetch use fetch-options. Made git-pull use merge-options and fetch-options. Added --help option to git-pull and git-format-patch scripts. Rewrote Documentation/Makefile to dynamically determine include dependencies. Signed-off-by: Jon Loeliger <jdl@freescale.com> Signed-off-by: Junio C Hamano <junkio@cox.net>
2005-11-07 05:30:56 +00:00
Fix documentation dependency generation. Documentation/Makefile spent a lot of time to generate include dependencies, which was quite noticeable especially during "make clean". Rewrite it to generate just a single dependency file. Signed-off-by: Junio C Hamano <junkio@cox.net>
2005-11-08 02:21:51 +00:00
-include doc.dep
Documentation: -merge and -pull: describe merge strategies. ... and give a couple of examples of running 'git pull' against local repository. Signed-off-by: Junio C Hamano <junkio@cox.net>
2005-11-04 08:06:20 +00:00
Documentation: Generate command lists. This moves the source of the list of commands and categorization to the end of Documentation/cmd-list.perl, so that re-categorization and re-ordering would become easier to manage. Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-01-19 00:02:13 +00:00
cmds_txt = cmds-ancillaryinterrogators.txt \
cmds-ancillarymanipulators.txt \
cmds-mainporcelain.txt \
cmds-plumbinginterrogators.txt \
cmds-plumbingmanipulators.txt \
Documentation/git.txt: command re-classification This adds two new classes (pure-helpers and "Interacting with Others") to the command list in the main manual page. The latter class is primarily about foreign SCM interface and is placed before low-level (plumbing) commands. Also it promotes a handful commands to mainporcelain category while demoting some others. Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-01-19 06:32:38 +00:00
cmds-synchingrepositories.txt \
cmds-synchelpers.txt \
cmds-purehelpers.txt \
cmds-foreignscminterface.txt
Documentation: Generate command lists. This moves the source of the list of commands and categorization to the end of Documentation/cmd-list.perl, so that re-categorization and re-ordering would become easier to manage. Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-01-19 00:02:13 +00:00
Documentation: tighten dependency for git.{html,txt} Every time _any_ documentation page changed, cmds-*.txt files were regenerated, which caused git.{html,txt} to be remade. Try not to update cmds-*.txt files if their new contents match the old ones. Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-04-06 05:17:20 +00:00
$(cmds_txt): cmd-list.made
Consolidate command list to one. The categorized list of commands in git(7) and the list of common commands in "git help" output were maintained separately, which was insane. This consolidates them to a single command-list.txt file. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-02 07:39:19 +00:00
cmd-list.made: cmd-list.perl ../command-list.txt $(MAN1_TXT)
Documentation/Makefile: make most operations "quiet" This adapts the "quiet make" implementation from the main Makefile. Signed-off-by: Chris Johnsen <chris_johnsen@pobox.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-03-27 06:49:38 +00:00
$(QUIET_GEN)$(RM) $@ && \
$(PERL_PATH) ./cmd-list.perl ../command-list.txt $(QUIET_STDERR) && \
Documentation: tighten dependency for git.{html,txt} Every time _any_ documentation page changed, cmds-*.txt files were regenerated, which caused git.{html,txt} to be remade. Try not to update cmds-*.txt files if their new contents match the old ones. Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-04-06 05:17:20 +00:00
date >$@
[PATCH 4/4] split core-git.txt and update Makefile for html and man Signed-off-by: David Greaves <david@dgreaves.com>
2005-05-10 21:32:39 +00:00
doc: generate a list of valid merge tools 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-01-28 00:52:26 +00:00
mergetools_txt = mergetools-diff.txt mergetools-merge.txt
$(mergetools_txt): mergetools-list.made
mergetools-list.made: ../git-mergetool--lib.sh $(wildcard ../mergetools/*)
$(QUIET_GEN)$(RM) $@ && \
$(SHELL_PATH) -c 'MERGE_TOOLS_DIR=../mergetools && \
. ../git-mergetool--lib.sh && \
show_tool_names can_diff "* " || :' >mergetools-diff.txt && \
$(SHELL_PATH) -c 'MERGE_TOOLS_DIR=../mergetools && \
. ../git-mergetool--lib.sh && \
show_tool_names can_merge "* " || :' >mergetools-merge.txt && \
date >$@
Doc: auto-detect changed build flags 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>
2019-03-17 18:36:00 +00:00
TRACK_ASCIIDOCFLAGS = $(subst ','\'',$(ASCIIDOC_COMMON):$(ASCIIDOC_HTML):$(ASCIIDOC_DOCBOOK))
GIT-ASCIIDOCFLAGS: FORCE
@FLAGS='$(TRACK_ASCIIDOCFLAGS)'; \
if test x"$$FLAGS" != x"`cat GIT-ASCIIDOCFLAGS 2>/dev/null`" ; then \
echo >&2 " * new asciidoc flags"; \
echo "$$FLAGS" >GIT-ASCIIDOCFLAGS; \
fi
[PATCH 4/4] split core-git.txt and update Makefile for html and man Signed-off-by: David Greaves <david@dgreaves.com>
2005-05-10 21:32:39 +00:00
clean:
Documentation: remove gitman.info with "make clean" Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-01-06 03:09:09 +00:00
$(RM) *.xml *.xml+ *.html *.html+ *.1 *.5 *.7
Documentation/Makefile: break up texi pipeline Most shells define the exit value of a pipeline as the exit value of the last process. For each texi rule, run the DOCBOOK2X_TEXI tool and the "fixup" script in their own non-pipeline commands so that make will notice an error exit code. Signed-off-by: Chris Johnsen <chris_johnsen@pobox.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-03-27 06:49:39 +00:00
$(RM) *.texi *.texi+ *.texi++ git.info gitman.info
Documentation/Makefile: add *.pdf to `clean' target user-manual.pdf is not removed by `make clean'; fix it. Signed-off-by: Emilio G. Cota <cota@braap.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-08-08 08:33:05 +00:00
$(RM) *.pdf
Start preparing the API documents. Most of them are still stubs, but the procedure to build the HTML documentation, maintaining the index and installing the end product are there. I placed names of people who are likely to know the most about the topic in the stub files, so that volunteers will know whom to ask questions as needed. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-11-25 07:48:04 +00:00
$(RM) howto-index.txt howto/*.html doc.dep
Documentation: build html for all files in technical and howto 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-10-23 17:58:04 +00:00
$(RM) technical/*.html technical/api-index.txt
Documentation: convert SubmittingPatches to AsciiDoc 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-11-12 22:07:18 +00:00
$(RM) SubmittingPatches.txt
doc: generate a list of valid merge tools 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-01-28 00:52:26 +00:00
$(RM) $(cmds_txt) $(mergetools_txt) *.made
Documentation: Avoid use of xmlto --stringparam The --stringparam option is not available on older xmlto versions. Instead, set man.base.url.for.relative.links via a .xsl file. Older docbook versions will ignore this without causing grief to users of older xmlto versions. Signed-off-by: Todd Zullinger <tmz@pobox.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-12-04 17:53:21 +00:00
$(RM) manpage-base-url.xsl
Doc: auto-detect changed build flags 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>
2019-03-17 18:36:00 +00:00
$(RM) GIT-ASCIIDOCFLAGS
[PATCH 4/4] split core-git.txt and update Makefile for html and man Signed-off-by: David Greaves <david@dgreaves.com>
2005-05-10 21:32:39 +00:00
Merge branch 'ma/doc-diff-doc-vs-doctor-comparison' 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
2019-04-16 10:28:09 +00:00
$(MAN_HTML): %.html : %.txt asciidoc.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS
Documentation/Makefile: make most operations "quiet" This adapts the "quiet make" implementation from the main Makefile. Signed-off-by: Chris Johnsen <chris_johnsen@pobox.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-03-27 06:49:38 +00:00
$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
Documentation: refactor common operations 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>
2014-10-27 00:13:42 +00:00
$(TXT_TO_HTML) -d manpage -o $@+ $< && \
Documentation: Replace @@GIT_VERSION@@ in documentation Include GIT-VERSION-FILE and replace @@GIT_VERSION@@ in the HTML and XML asciidoc output. The documentation doesn't depend on GIT-VERSION-FILE so it will not be automatically rebuild if nothing else changed. [jc: fixing the case for interrupted build] Signed-off-by: Frank Lichtenheld <frank@lichtenheld.de> Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-03-25 11:56:49 +00:00
mv $@+ $@
[PATCH 4/4] split core-git.txt and update Makefile for html and man Signed-off-by: David Greaves <david@dgreaves.com>
2005-05-10 21:32:39 +00:00
Merge branch 'ma/doc-diff-doc-vs-doctor-comparison' 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
2019-04-16 10:28:09 +00:00
$(OBSOLETE_HTML): %.html : %.txto asciidoc.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS
Rename {git- => git}remote-helpers.txt 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-01-31 21:59:50 +00:00
$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
Documentation: refactor common operations 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>
2014-10-27 00:13:42 +00:00
$(TXT_TO_HTML) -o $@+ $< && \
Rename {git- => git}remote-helpers.txt 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-01-31 21:59:50 +00:00
mv $@+ $@
Documentation: Avoid use of xmlto --stringparam The --stringparam option is not available on older xmlto versions. Instead, set man.base.url.for.relative.links via a .xsl file. Older docbook versions will ignore this without causing grief to users of older xmlto versions. Signed-off-by: Todd Zullinger <tmz@pobox.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-12-04 17:53:21 +00:00
manpage-base-url.xsl: manpage-base-url.xsl.in
Documentation/Makefile: make manpage-base-url.xsl generation quieter 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>
2018-08-29 15:47:20 +00:00
$(QUIET_GEN)sed "s|@@MAN_BASE_URL@@|$(MAN_BASE_URL)|" $< > $@
Documentation: Avoid use of xmlto --stringparam The --stringparam option is not available on older xmlto versions. Instead, set man.base.url.for.relative.links via a .xsl file. Older docbook versions will ignore this without causing grief to users of older xmlto versions. Signed-off-by: Todd Zullinger <tmz@pobox.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-12-04 17:53:21 +00:00
Documentation/Makefile: add missing xsl dependencies for manpages 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>
2019-02-27 18:17:52 +00:00
%.1 %.5 %.7 : %.xml manpage-base-url.xsl $(wildcard manpage*.xsl)
Documentation/Makefile: make most operations "quiet" This adapts the "quiet make" implementation from the main Makefile. Signed-off-by: Chris Johnsen <chris_johnsen@pobox.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-03-27 06:49:38 +00:00
$(QUIET_XMLTO)$(RM) $@ && \
Documentation/Makefile: Allow custom XMLTO binary Signed-off-by: Dave Borowitz <dborowitz@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-09-19 17:06:37 +00:00
$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<
[PATCH 4/4] split core-git.txt and update Makefile for html and man Signed-off-by: David Greaves <david@dgreaves.com>
2005-05-10 21:32:39 +00:00
Merge branch 'ma/doc-diff-doc-vs-doctor-comparison' 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
2019-04-16 10:28:09 +00:00
%.xml : %.txt asciidoc.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS
Documentation/Makefile: make most operations "quiet" This adapts the "quiet make" implementation from the main Makefile. Signed-off-by: Chris Johnsen <chris_johnsen@pobox.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-03-27 06:49:38 +00:00
$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
Documentation: refactor common operations 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>
2014-10-27 00:13:42 +00:00
$(TXT_TO_XML) -d manpage -o $@+ $< && \
Documentation: Replace @@GIT_VERSION@@ in documentation Include GIT-VERSION-FILE and replace @@GIT_VERSION@@ in the HTML and XML asciidoc output. The documentation doesn't depend on GIT-VERSION-FILE so it will not be automatically rebuild if nothing else changed. [jc: fixing the case for interrupted build] Signed-off-by: Frank Lichtenheld <frank@lichtenheld.de> Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-03-25 11:56:49 +00:00
mv $@+ $@
Documentation updates. Linus brought up that documentation for many commands have incorrect attribution. I started counting lines again, but ended up adding a handful of missing manual pages. Signed-off-by: Junio C Hamano <junkio@cox.net>
2005-08-15 00:24:36 +00:00
Merge branch 'ma/doc-diff-doc-vs-doctor-comparison' 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
2019-04-16 10:28:09 +00:00
user-manual.xml: user-manual.txt user-manual.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS
Documentation/Makefile: fix interrupted builds of user-manual.xml Unlike gcc, asciidoc does not atomically write its output file or delete it when interrupted. If it is interrupted in the middle of writing an XML file, the result will be truncated input for xsltproc. XSLTPROC user-manual.html user-manual.xml:998: parser error : Premature end of data in t Take care of this case by writing to a temporary and renaming it when finished. Signed-off-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-04-22 01:18:21 +00:00
$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
asciidoctor: fix user-manual to be built by `asciidoctor` 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>
2017-01-02 16:03:57 +00:00
$(TXT_TO_XML) -d book -o $@+ $< && \
Documentation/Makefile: fix interrupted builds of user-manual.xml Unlike gcc, asciidoc does not atomically write its output file or delete it when interrupted. If it is interrupted in the middle of writing an XML file, the result will be truncated input for xsltproc. XSLTPROC user-manual.html user-manual.xml:998: parser error : Premature end of data in t Take care of this case by writing to a temporary and renaming it when finished. Signed-off-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-04-22 01:18:21 +00:00
mv $@+ $@
Documentation: add git user's manual The goals are: - Readable from beginning to end in order without having read any other git documentation beforehand. - Helpful section names and cross-references, so it's not too hard to skip around some if you need to. - Organized to allow it to grow much larger (unlike the tutorials) It's more liesurely than tutorial.txt, but tries to stay focused on practical how-to stuff. It adds a discussion of how to resolve merge conflicts, and partial instructions on setting up and dealing with a public repository. I've lifted a little bit from "branching and merging" (e.g., some of the discussion of history diagrams), and could probably steal more if that's OK. (Similarly anyone should of course feel free to reuse bits of this if any parts seem more useful than the whole.) There's a lot of detail on managing branches and using git-fetch, just because those are essential even to people needing read-only access (e.g., kernel testers). I think those sections will be much shorter once the new "git remote" command and the disconnected checkouts are taken into account. I do feel bad about adding yet another piece of documentation, but I we need something that goes through all the basics in a logical order, and I wasn't seeing how to grow the tutorials into that. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-01-08 00:23:49 +00:00
Start preparing the API documents. Most of them are still stubs, but the procedure to build the HTML documentation, maintaining the index and installing the end product are there. I placed names of people who are likely to know the most about the topic in the stub files, so that volunteers will know whom to ask questions as needed. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-11-25 07:48:04 +00:00
technical/api-index.txt: technical/api-index-skel.txt \
technical/api-index.sh $(patsubst %,%.txt,$(API_DOCS))
documentation: Makefile accounts for SHELL_PATH setting Ensure that the Makefile that generates and installs the Documentation is aware of any SHELL_PATH setting. Use this value if found or the current setting for SHELL if not. This is an accommodation for systems where sh is not POSIX enough. Signed-off-by: Ben Walton <bwalton@artsci.utoronto.ca> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-03-22 13:20:44 +00:00
$(QUIET_GEN)cd technical && '$(SHELL_PATH_SQ)' ./api-index.sh
Start preparing the API documents. Most of them are still stubs, but the procedure to build the HTML documentation, maintaining the index and installing the end product are there. I placed names of people who are likely to know the most about the topic in the stub files, so that volunteers will know whom to ask questions as needed. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-11-25 07:48:04 +00:00
docs: fix cross-directory linkgit references 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-06-07 21:03:23 +00:00
technical/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../
Doc: auto-detect changed build flags 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>
2019-03-17 18:36:00 +00:00
$(patsubst %,%.html,$(API_DOCS) technical/api-index $(TECH_DOCS)): %.html : %.txt \
asciidoc.conf GIT-ASCIIDOCFLAGS
Documentation: refactor common operations 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>
2014-10-27 00:13:42 +00:00
$(QUIET_ASCIIDOC)$(TXT_TO_HTML) $*.txt
Start preparing the API documents. Most of them are still stubs, but the procedure to build the HTML documentation, maintaining the index and installing the end product are there. I placed names of people who are likely to know the most about the topic in the stub files, so that volunteers will know whom to ask questions as needed. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-11-25 07:48:04 +00:00
Documentation: convert SubmittingPatches to AsciiDoc 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-11-12 22:07:18 +00:00
SubmittingPatches.txt: SubmittingPatches
$(QUIET_GEN) cp $< $@
Mark user-manual as UTF-8 There have been several complaints against k.org's user-manual page. The document is generated in ISO-8859-1 by the xsltproc toolchain (I suspect this is because released docbook.xsl we use has xsl:output element that says the output is ISO-8859-1) but server delivers it with "charset=UTF-8", and all h*ll breaks loose. This attempts to force UTF-8 on the generating end. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-07-24 07:46:35 +00:00
XSLT = docbook.xsl
user-manual: run xsltproc without --nonet option The --nonet option prevents xsltproc from going to the network to find anything. But it always tries to find them locally first, so for a user with the necessary docbook stylesheets installed the build will work just fine without xsltproc attempting to use the network; all --nonet does is make it fail rather than falling back on that. That doesn't seem particularly helpful. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-03-16 15:45:29 +00:00
XSLTOPTS = --xinclude --stringparam html.stylesheet docbook-xsl.css
user-manual: ensure generated manual references stylesheet The generated user manual is rather hard to read thanks to the lack of the css that's supposed to be included from docbook-xsl.css. I'm totally ignorant of the toolchain; grubbing through xmlto and related scripts, the easiest way I could find to ensure that the generated html links to the stylesheet is by calling xsltproc directly. Maybe there's some better way. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu> Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-03-03 18:33:48 +00:00
docs: fix Makefile dependency for user manual We use our custom xsl file to build the user manual, so make sure we depend on it. We don't use it anywhere else, so we can stick it straight in the rule. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-08-21 06:21:22 +00:00
user-manual.html: user-manual.xml $(XSLT)
Documentation/Makefile: fix interrupted builds of user-manual.xml Unlike gcc, asciidoc does not atomically write its output file or delete it when interrupted. If it is interrupted in the middle of writing an XML file, the result will be truncated input for xsltproc. XSLTPROC user-manual.html user-manual.xml:998: parser error : Premature end of data in t Take care of this case by writing to a temporary and renaming it when finished. Signed-off-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-04-22 01:18:21 +00:00
$(QUIET_XSLTPROC)$(RM) $@+ $@ && \
xsltproc $(XSLTOPTS) -o $@+ $(XSLT) $< && \
mv $@+ $@
Documentation: add git user's manual The goals are: - Readable from beginning to end in order without having read any other git documentation beforehand. - Helpful section names and cross-references, so it's not too hard to skip around some if you need to. - Organized to allow it to grow much larger (unlike the tutorials) It's more liesurely than tutorial.txt, but tries to stay focused on practical how-to stuff. It adds a discussion of how to resolve merge conflicts, and partial instructions on setting up and dealing with a public repository. I've lifted a little bit from "branching and merging" (e.g., some of the discussion of history diagrams), and could probably steal more if that's OK. (Similarly anyone should of course feel free to reuse bits of this if any parts seem more useful than the whole.) There's a lot of detail on managing branches and using git-fetch, just because those are essential even to people needing read-only access (e.g., kernel testers). I think those sections will be much shorter once the new "git remote" command and the disconnected checkouts are taken into account. I do feel bad about adding yet another piece of documentation, but I we need something that goes through all the basics in a logical order, and I wasn't seeing how to grow the tutorials into that. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-01-08 00:23:49 +00:00
Documentation: rename git.texi to user-manual.texi Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-12 21:31:02 +00:00
git.info: user-manual.texi
Documentation/Makefile: make most operations "quiet" This adapts the "quiet make" implementation from the main Makefile. Signed-off-by: Chris Johnsen <chris_johnsen@pobox.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-03-27 06:49:38 +00:00
$(QUIET_MAKEINFO)$(MAKEINFO) --no-split -o $@ user-manual.texi
Documentation: add gitman.info target Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-10 09:15:57 +00:00
Documentation: rename git.texi to user-manual.texi Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-12 21:31:02 +00:00
user-manual.texi: user-manual.xml
Documentation/Makefile: make most operations "quiet" This adapts the "quiet make" implementation from the main Makefile. Signed-off-by: Chris Johnsen <chris_johnsen@pobox.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-03-27 06:49:38 +00:00
$(QUIET_DB2TEXI)$(RM) $@+ $@ && \
Documentation/Makefile: break up texi pipeline Most shells define the exit value of a pipeline as the exit value of the last process. For each texi rule, run the DOCBOOK2X_TEXI tool and the "fixup" script in their own non-pipeline commands so that make will notice an error exit code. Signed-off-by: Chris Johnsen <chris_johnsen@pobox.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-03-27 06:49:39 +00:00
$(DOCBOOK2X_TEXI) user-manual.xml --encoding=UTF-8 --to-stdout >$@++ && \
$(PERL_PATH) fix-texi.perl <$@++ >$@+ && \
rm $@++ && \
Documentation: add gitman.info target Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-10 09:15:57 +00:00
mv $@+ $@
Add support for a pdf version of the user manual Use dblatex in order to create a pdf version of the git user manual. No existing Makefile targets (including "all") are touched, so you need to explicitly say make pdf sudo make install-pdf to get user-manual.pdf created and installed. Signed-off-by: Miklos Vajna <vmiklos@frugalware.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-12-10 22:44:50 +00:00
user-manual.pdf: user-manual.xml
Documentation/Makefile: make most operations "quiet" This adapts the "quiet make" implementation from the main Makefile. Signed-off-by: Chris Johnsen <chris_johnsen@pobox.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-03-27 06:49:38 +00:00
$(QUIET_DBLATEX)$(RM) $@+ $@ && \
Documentation: move dblatex arguments into variable 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-22 02:41:55 +00:00
$(DBLATEX) -o $@+ $(DBLATEX_COMMON) $< && \
Add support for a pdf version of the user manual Use dblatex in order to create a pdf version of the git user manual. No existing Makefile targets (including "all") are touched, so you need to explicitly say make pdf sudo make install-pdf to get user-manual.pdf created and installed. Signed-off-by: Miklos Vajna <vmiklos@frugalware.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-12-10 22:44:50 +00:00
mv $@+ $@
Documentation: add XSLT to fix DocBook for Texinfo 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-22 02:41:54 +00:00
gitman.texi: $(MAN_XML) cat-texi.perl texi.xsl
Documentation/Makefile: make most operations "quiet" This adapts the "quiet make" implementation from the main Makefile. Signed-off-by: Chris Johnsen <chris_johnsen@pobox.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-03-27 06:49:38 +00:00
$(QUIET_DB2TEXI)$(RM) $@+ $@ && \
Documentation: add XSLT to fix DocBook for Texinfo 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-22 02:41:54 +00:00
($(foreach xml,$(sort $(MAN_XML)),xsltproc -o $(xml)+ texi.xsl $(xml) && \
$(DOCBOOK2X_TEXI) --encoding=UTF-8 --to-stdout $(xml)+ && \
rm $(xml)+ &&) true) > $@++ && \
Documentation/Makefile: break up texi pipeline Most shells define the exit value of a pipeline as the exit value of the last process. For each texi rule, run the DOCBOOK2X_TEXI tool and the "fixup" script in their own non-pipeline commands so that make will notice an error exit code. Signed-off-by: Chris Johnsen <chris_johnsen@pobox.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-03-27 06:49:39 +00:00
$(PERL_PATH) cat-texi.perl $@ <$@++ >$@+ && \
rm $@++ && \
Documentation: add gitman.info target Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-10 09:15:57 +00:00
mv $@+ $@
gitman.info: gitman.texi
Documentation/Makefile: make most operations "quiet" This adapts the "quiet make" implementation from the main Makefile. Signed-off-by: Chris Johnsen <chris_johnsen@pobox.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-03-27 06:49:38 +00:00
$(QUIET_MAKEINFO)$(MAKEINFO) --no-split --no-validate $*.texi
Documentation: add gitman.info target Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-10 09:15:57 +00:00
$(patsubst %.txt,%.texi,$(MAN_TXT)): %.texi : %.xml
Documentation/Makefile: make most operations "quiet" This adapts the "quiet make" implementation from the main Makefile. Signed-off-by: Chris Johnsen <chris_johnsen@pobox.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-03-27 06:49:38 +00:00
$(QUIET_DB2TEXI)$(RM) $@+ $@ && \
$(DOCBOOK2X_TEXI) --to-stdout $*.xml >$@+ && \
Documentation: add gitman.info target Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-10 09:15:57 +00:00
mv $@+ $@
Add support for an info version of the user manual These patches use docbook2x in order to create an info version of the git user manual. No existing Makefile targets (including "all") are touched, so you need to explicitly say make info sudo make install-info to get git.info created and installed. If the info target directory does not already contain a "dir" file, no directory entry is created. This facilitates $(DESTDIR)-based installations. The same could be achieved with sudo make INSTALL_INFO=: install-info explicitly. perl is used for patching up sub-par file and directory information in the Texinfo file. It would be cleaner to place the respective info straight into user-manual.txt or the conversion configurations, but I find myself unable to find out how to do this with Asciidoc/Texinfo. Signed-off-by: David Kastrup <dak@gnu.org>
2007-08-06 10:22:57 +00:00
Link howto documents from the main git.txt documentation. Signed-off-by: Junio C Hamano <junkio@cox.net>
2005-08-25 07:28:18 +00:00
howto-index.txt: howto-index.sh $(wildcard howto/*.txt)
Documentation/Makefile: make most operations "quiet" This adapts the "quiet make" implementation from the main Makefile. Signed-off-by: Chris Johnsen <chris_johnsen@pobox.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-03-27 06:49:38 +00:00
$(QUIET_GEN)$(RM) $@+ $@ && \
Sort howto documents in howto-index.txt 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-22 18:34:27 +00:00
'$(SHELL_PATH_SQ)' ./howto-index.sh $(sort $(wildcard howto/*.txt)) >$@+ && \
Link howto documents from the main git.txt documentation. Signed-off-by: Junio C Hamano <junkio@cox.net>
2005-08-25 07:28:18 +00:00
mv $@+ $@
Documentaion updates. Mostly making the formatted html prettier. Signed-off-by: Junio C Hamano <junkio@cox.net> (cherry picked from 7adf1f15ebe074d4767df941817a6cf86d8e2533 commit)
2005-08-30 20:51:01 +00:00
$(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt
Documentation: refactor common operations 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>
2014-10-27 00:13:42 +00:00
$(QUIET_ASCIIDOC)$(TXT_TO_HTML) $*.txt
Link howto documents from the main git.txt documentation. Signed-off-by: Junio C Hamano <junkio@cox.net>
2005-08-25 07:28:18 +00:00
WEBDOC_DEST = /pub/software/scm/git/docs
docs: fix cross-directory linkgit references 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-06-07 21:03:23 +00:00
howto/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../
Doc: auto-detect changed build flags 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>
2019-03-17 18:36:00 +00:00
$(patsubst %.txt,%.html,$(wildcard howto/*.txt)): %.html : %.txt GIT-ASCIIDOCFLAGS
Documentation/Makefile: make most operations "quiet" This adapts the "quiet make" implementation from the main Makefile. Signed-off-by: Chris Johnsen <chris_johnsen@pobox.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-03-27 06:49:38 +00:00
$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
Documentation: move some AsciiDoc parameters into variables 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-11 23:37:35 +00:00
sed -e '1,/^$$/d' $< | \
Documentation: refactor common operations 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>
2014-10-27 00:13:42 +00:00
$(TXT_TO_HTML) - >$@+ && \
Allow asciidoc formatted documentation in howto/ Signed-off-by: Junio C Hamano <junkio@cox.net>
2005-08-30 05:38:12 +00:00
mv $@+ $@
Link howto documents from the main git.txt documentation. Signed-off-by: Junio C Hamano <junkio@cox.net>
2005-08-25 07:28:18 +00:00
install-webdoc : html
documentation: Makefile accounts for SHELL_PATH setting Ensure that the Makefile that generates and installs the Documentation is aware of any SHELL_PATH setting. Use this value if found or the current setting for SHELL if not. This is an accommodation for systems where sh is not POSIX enough. Signed-off-by: Ben Walton <bwalton@artsci.utoronto.ca> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-03-22 13:20:44 +00:00
'$(SHELL_PATH_SQ)' ./install-webdoc.sh $(WEBDOC_DEST)
Makefile: add quick-install-doc for installing pre-built manpages This adds and uses the install-doc-quick.sh file to Documentation/, which is usable for people who track either the 'html' or 'man' heads in Junio's repository (prefixed with 'origin/' if cloned locally). You may override this by specifying DOC_REF in the make environment or in config.mak. GZ may also be set in the environment (or config.mak) if you wish to gzip the documentation after installing it. Signed-off-by: Eric Wong <normalperson@yhbt.net> Signed-off-by: Junio C Hamano <junkio@cox.net>
2006-12-23 16:26:09 +00:00
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 19:17:53 +00:00
# You must have a clone of 'git-htmldocs' and 'git-manpages' repositories
# next to the 'git' repository itself for the following to work.
docs: Update install-doc-quick 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-11-08 18:17:40 +00:00
Makefile: add install-man rules (quick and normal) Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-11-02 17:53:03 +00:00
quick-install: quick-install-man
docs: Update install-doc-quick 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-11-08 18:17:40 +00:00
require-manrepo::
@if test ! -d $(MAN_REPO); \
then echo "git-manpages repository must exist at $(MAN_REPO)"; exit 1; fi
quick-install-man: require-manrepo
install-doc-quick: allow specifying what ref to install 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-12-09 22:07:57 +00:00
'$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(MAN_REPO) $(DESTDIR)$(mandir) $(GIT_MAN_REF)
docs: Update install-doc-quick 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-11-08 18:17:40 +00:00
require-htmlrepo::
@if test ! -d $(HTML_REPO); \
then echo "git-htmldocs repository must exist at $(HTML_REPO)"; exit 1; fi
Documentation: Replace @@GIT_VERSION@@ in documentation Include GIT-VERSION-FILE and replace @@GIT_VERSION@@ in the HTML and XML asciidoc output. The documentation doesn't depend on GIT-VERSION-FILE so it will not be automatically rebuild if nothing else changed. [jc: fixing the case for interrupted build] Signed-off-by: Frank Lichtenheld <frank@lichtenheld.de> Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-03-25 11:56:49 +00:00
docs: Update install-doc-quick 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-11-08 18:17:40 +00:00
quick-install-html: require-htmlrepo
install-doc-quick: allow specifying what ref to install 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-12-09 22:07:57 +00:00
'$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(HTML_REPO) $(DESTDIR)$(htmldir) $(GIT_MAN_REF)
allow installation of man and html doc from the man and html branches This patch introduces a make target "quick-install-html" which installs the html documentation from the branch origin/html, without the need for asciidoc/xmlto. This is analogous to the existing "quick-install-doc" target for the man pages. We advertise these targets in the INSTALL file now. Signed-off-by: Michael J Gruber <michaeljgruber+gmane@fastmail.fm> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-09-09 20:44:17 +00:00
check-docs: get documented command list from Makefile 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-08-08 20:57:52 +00:00
print-man1:
@for i in $(MAN1_TXT); do echo $$i; done
ci: validate "linkgit:" in documentation 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>
2016-05-04 21:34:23 +00:00
lint-docs::
$(QUIET_LINT)$(PERL_PATH) lint-gitlink.perl
Documentation/Makefile add optional targets for l10n 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>
2019-01-07 19:21:12 +00:00
ifeq ($(wildcard po/Makefile),po/Makefile)
doc-l10n install-l10n::
$(MAKE) -C po $@
endif
Makefile: consolidate .FORCE-* targets Providing multiple targets to force a rebuild is unnecessary complication. Avoid using a name that could conflict with future special targets in GNU make (a leading period followed by uppercase letters). The corresponding change to the git-gui Makefile is left for another patch. Signed-off-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-01-06 08:06:58 +00:00
.PHONY: FORCE
Reference in a new issue Copy permalink