summaryrefslogtreecommitdiff
path: root/Documentation/Makefile
AgeCommit message (Collapse)AuthorFilesLines
2021-05-24doc: avoid using rm directlyLibravatar Felipe Contreras1-3/+3
That's what we have $(RM) for. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2021-05-24doc: simplify Makefile using .DELETE_ON_ERRORLibravatar Felipe Contreras1-28/+19
Currently GNU make already removes files when catching an interruption signal, however, in order to deal with other kinds of errors a workaround is in place to store target output to a temporary file, and only move it to its right place on success. By enabling the built-in .DELETE_ON_ERROR we let make do this task, so we don't have to. This way the rules can be simplified a lot. Suggested-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2021-05-24doc: remove unnecessary rm instancesLibravatar Felipe Contreras1-27/+15
Commits 50cff52f1a (When generating manpages, delete outdated targets first., 2007-08-02) and f9286765b2 (Documentation/Makefile: remove cmd-list.made before redirecting to it., 2007-08-06) created these rm instances for a very rare corner-case: building as root by mistake. It's odd to have workarounds here, but nowhere else in the Makefile-- which already fails in this stuation, starting from Documentation/technical/. We gain nothing but complexity, so let's remove them. Comments-by: Jeff King <peff@peff.net> Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2021-05-24doc: improve asciidoc dependenciesLibravatar Felipe Contreras1-1/+2
asciidoc needs asciidoc.conf, asciidoctor asciidoctor-extensions.rb. Neither needs the other. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2021-05-24doc: refactor common asciidoc dependenciesLibravatar Felipe Contreras1-3/+4
Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2021-05-07Merge branch 'ab/doc-lint'Libravatar Junio C Hamano1-5/+18
Dev support. * ab/doc-lint: docs: fix linting issues due to incorrect relative section order doc lint: lint relative section order doc lint: lint and fix missing "GIT" end sections doc lint: fix bugs in, simplify and improve lint script doc lint: Perl "strict" and "warnings" in lint-gitlink.perl Documentation/Makefile: make doc.dep dependencies a variable again Documentation/Makefile: make $(wildcard howto/*.txt) a var
2021-04-19parallel-checkout: add design documentationLibravatar Matheus Tavares1-0/+1
Co-authored-by: Jeff Hostetler <jeffhost@microsoft.com> Signed-off-by: Matheus Tavares <matheus.bernardino@usp.br> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2021-04-10doc lint: lint relative section orderLibravatar Ævar Arnfjörð Bjarmason1-1/+2
Add a linting script to check the relative order of the sections in the documentation. We should have NAME, then SYNOPSIS, DESCRIPTION, OPTIONS etc. in that order. That holds true throughout our documentation, except for a few exceptions which are hardcoded in the linting script. Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2021-04-10doc lint: lint and fix missing "GIT" end sectionsLibravatar Ævar Arnfjörð Bjarmason1-1/+2
Lint for and fix the three manual pages that were missing the standard "Part of the linkgit:git[1] suite" end section. We only do this for the man[157] section documents (we don't have anything outside those sections), not files to be included, howto *.txt files etc. We could also add this to the existing (and then renamed) lint-gitlink.perl, but I'm not doing that here. Obviously all of that fits in one script, but I think for something like this that's a one-off script with global variables it's much harder to follow when a large part of your script is some if/else or keeping/resetting of state simply to work around the script doing two things instead of one. Especially because in this case this script wants to process the file as one big string, but lint-gitlink.perl wants to look at it one line at a time. We could also consolidate this whole thing and t/check-non-portable-shell.pl, but that one likes to join lines as part of its shell parsing. So let's just add another script, whole scaffolding is basically: use strict; use warnings; sub report { ... } my $code = 0; while (<>) { ... } exit $code; We'd spend more lines effort trying to consolidate them than just copying that around. Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2021-04-10doc lint: fix bugs in, simplify and improve lint scriptLibravatar Ævar Arnfjörð Bjarmason1-1/+5
The lint-gitlink.perl script added in ab81411ced (ci: validate "linkgit:" in documentation, 2016-05-04) was more complex than it needed to be. It: - Was using File::Find to recursively find *.txt files in Documentation/, let's instead use the Makefile as a source of truth for *.txt files, and pass it down to the script. - We now don't lint linkgit:* in RelNotes/* or technical/*, which we shouldn't have been doing in the first place anyway. - When the doc-diff script was added in beb188e22a (add a script to diff rendered documentation, 2018-08-06) we started sometimes having a "git worktree" under Documentation/. This tree contains a full checkout of git.git, as a result the "lint" script would recurse into that, and lint any *.txt file found in that entire repository. In practice the only in-tree "linkgit" outside of the Documentation/ tree is contrib/contacts/git-contacts.txt and contrib/subtree/git-subtree.txt, so this wouldn't emit any errors Now we instead simply trust the Makefile to give us *.txt files. Since the Makefile also knows what sections each page should be in we don't have to open the files ourselves and try to parse that out. As a bonus this will also catch bugs with the section line in the files themselves being incorrect. The structure of the new script is mostly based on t/check-non-portable-shell.pl. As an added bonus it will also use pos() to print where the problems it finds are, e.g. given an issue like: diff --git a/Documentation/git-cherry.txt b/Documentation/git-cherry.txt [...] and line numbers. git-cherry therefore detects when commits have been -"copied" by means of linkgit:git-cherry-pick[1], linkgit:git-am[1] or -linkgit:git-rebase[1]. +"copied" by means of linkgit:git-cherry-pick[2], linkgit:git-am[3] or +linkgit:git-rebase[4]. We'll now emit: git-cherry.txt:20: error: git-cherry-pick[2]: wrong section (should be 1), shown with 'HERE' below: git-cherry.txt:20: '"copied" by means of linkgit:git-cherry-pick[2]' <-- HERE git-cherry.txt:20: error: git-am[3]: wrong section (should be 1), shown with 'HERE' below: git-cherry.txt:20: '"copied" by means of linkgit:git-cherry-pick[2], linkgit:git-am[3]' <-- HERE git-cherry.txt:21: error: git-rebase[4]: wrong section (should be 1), shown with 'HERE' below: git-cherry.txt:21: 'linkgit:git-rebase[4]' <-- HERE Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2021-04-10Documentation/Makefile: make doc.dep dependencies a variable againLibravatar Ævar Arnfjörð Bjarmason1-1/+5
Re-introduce a variable to declare what *.txt files need to be considered for the purposes of scouring files to generate a dependency graph of includes. When doc.dep was introduced in a5ae8e64cf (Fix documentation dependency generation., 2005-11-07) we had such a variable called TEXTFILES, but it was refactored away just a few commits after that in fb612d54c1 (Documentation: fix dependency generation., 2005-11-07). I'm planning to add more wildcards here, so let's bring it back. I'm not calling it TEXTFILES because we e.g. don't consider Documentation/technical/*.txt when generating the graph (they don't use includes). Let's instead call it DOC_DEP_TXT. Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2021-04-10Documentation/Makefile: make $(wildcard howto/*.txt) a varLibravatar Ævar Arnfjörð Bjarmason1-3/+6
Refactor occurrences of $(wildcard howto/*.txt) into a single HOWTO_TXT variable for readability and consistency. Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2021-03-27Document how we do embargoed releasesLibravatar Johannes Schindelin1-0/+1
Whenever we fix critical vulnerabilities, we follow some sort of protocol (e.g. setting a coordinated release date, keeping the fix under embargo until that time, coordinating with packagers and/or hosting sites, etc). Similar in spirit to `Documentation/howto/maintain-git.txt`, let's formalize the details in a document. Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2021-01-12mailmap doc: create a new "gitmailmap(5)" man pageLibravatar Ævar Arnfjörð Bjarmason1-0/+1
Create a gitmailmap(5) page similar to how .gitmodules and .gitignore have their own pages at gitmodules(5) and gitignore(5). Now instead of "check-mailmap", "blame" and "shortlog" documentation including the description of the format we link to one canonical place. This makes things easier for readers, since in our manpage or web-based[1] output it's not clear that the "MAPPING AUTHORS" sections aren't subtly different, as opposed to just included. 1. https://git-scm.com/docs/git-check-mailmap Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-12-17Merge branch 'rj/make-clean'Libravatar Junio C Hamano1-0/+4
Build optimization. * rj/make-clean: Makefile: don't use a versioned temp distribution directory Makefile: don't try to clean old debian build product gitweb/Makefile: conditionally include ../GIT-VERSION-FILE Documentation/Makefile: conditionally include ../GIT-VERSION-FILE Documentation/Makefile: conditionally include doc.dep
2020-12-08Documentation/Makefile: conditionally include ../GIT-VERSION-FILELibravatar Ramsay Jones1-0/+2
The 'clean' target is still noticeably slow on cygwin, despite the substantial improvement made by the previous patch. For example, the second invocation of 'make clean' below: $ make clean >/dev/null 2>&1 $ make clean ... make[1]: Entering directory '/home/ramsay/git/Documentation' make[2]: Entering directory '/home/ramsay/git' make[2]: 'GIT-VERSION-FILE' is up to date. make[2]: Leaving directory '/home/ramsay/git' ... $ has been timed at 12.364s on my laptop (an old core i5-4200M @ 2.50GHz, 8GB RAM, 1TB HDD). Notice that the 'clean' target is making a nested call to the parent Makefile to ensure that the GIT-VERSION-FILE is up-to-date (prior to the previous patch, there would have been _two_ such invocations). This is to ensure that the $(GIT_VERSION) make variable is set, once that file had been included. However, the 'clean' target does not use the $(GIT_VERSION) variable, directly or indirectly, so it does not have any affect on what the target removes. Therefore, the time spent on ensuring an up to date GIT-VERSION-FILE is wasted effort. In order to eliminate such wasted effort, use the value of the internal $(MAKECMDGOALS) variable to only '-include ../GIT-VERSION-FILE' when the target is not 'clean'. (This drops the time down to 10.361s, on my laptop, giving an improvement of 16.20%). Signed-off-by: Ramsay Jones <ramsay@ramsayjones.plus.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-12-08Documentation/Makefile: conditionally include doc.depLibravatar Ramsay Jones1-0/+2
The 'clean' target is noticeably slow on cygwin, even for a 'do-nothing' invocation of 'make clean'. For example, the second 'make clean' below: $ make clean >/dev/null 2>&1 $ make clean GIT_VERSION = 2.29.0 ... make[1]: Entering directory '/home/ramsay/git/Documentation' GEN mergetools-list.made GEN cmd-list.made GEN doc.dep ... $ has been timed at 23.339s, using git v2.29.0, on my laptop (an old core i5-4200M @ 2.50GHz, 8GB RAM, 1TB HDD). Notice that, since the 'doc.dep' file does not exist, make takes the time (about 8s) to generate several files in order to create the doc.dep include file. (If an 'include' file is missing, but a target for the said file is present in the Makefile, make will execute that target and, if that file now exists, throw away all its internal data and re-read and re-parse the Makefile). Having spent the time to include the 'doc.dep' file, the 'clean' target immediately deletes those files. The document dependencies specified in the 'doc.dep' include file, expressed as make targets and prerequisites, do not affect what the 'clean' target removes. Therefore, the time spent in generating the dependencies is completely wasted effort. In order to eliminate such wasted effort, use the value of the internal $(MAKECMDGOALS) variable to only '-include doc.dep' when the target is not 'clean'. (This drops the time down to 12.364s, on my laptop, giving an improvement of 47.02%). Signed-off-by: Ramsay Jones <ramsay@ramsayjones.plus.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-12-02doc: make HTML manual reproducibleLibravatar Arnout Engelen1-1/+4
Versions of docbook-xsl newer than 1.79.1 allows xsltproc to assign IDs to nodes in the generated HTML consistently, to make the output resulting from the same source stable and reproducible. Pass the generate.consistent.ids parameter from the command line to ask for this feature. Older versions of the tool simply ignores the parameter and produces their output the same way as before this change, so there is no need to check for toolchain version. Signed-off-by: Arnout Engelen <arnout@bzzt.net> Helped-by: brian m. carlson <sandals@crustytoothpaste.net> Helped-by: Todd Zullinger <tmz@pobox.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-08-04git.txt: add list of guidesLibravatar Philippe Blain1-0/+1
Not all man5/man7 guides are mentioned in the 'git(1)' documentation, which makes the missing ones somewhat hard to find. Add a list of the guides to git(1) by leveraging the existing `Documentation/cmd-list.perl` script to generate a file `cmds-guide.txt` which gets included in git.txt. Also, do not hard-code the manual section '1'. Instead, use a regex so that the manual section is discovered from the first line of each `git*.txt` file. This addition was hinted at in 1b81d8cb19 (help: use command-list.txt for the source of guides, 2018-05-20). Helped-by: Junio C Hamano <gitster@pobox.com> Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-08-04Documentation: don't hardcode command categories twiceLibravatar Junio C Hamano1-1/+1
Instead of hard-coding the list of command categories in both `Documentation/Makefile` and `Documentation/cmd-list.perl`, make the Makefile the authoritative source and tweak `cmd-list.perl` so that it receives the list of command categories as argument. Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-08-04command-list.txt: add missing 'gitcredentials' and 'gitremote-helpers'Libravatar Philippe Blain1-0/+1
The guides 'gitcredentials' and 'gitremote-helpers' do not currently appear in command-list.txt. 'gitcredentials' was forgotten back when guides were added to command-list.txt in 1b81d8cb19 (help: use command-list.txt for the source of guides, 2018-05-20). 'gitremote-helpers' was moved to section 7 in 439cc74632 (docs: move gitremote-helpers into section 7, 2019-03-25), but command-list.txt was not updated at the time. Add these two guides to the list of guides in 'command-list.txt', so that they appear in the output of 'git help --guides', and capitalize the first word of the description of 'gitcredentials', as was done in 1b81d8c (help: use command-list.txt for the source of guides, 2018-05-20) for the other guides. While at it, add a comment in Documentation/Makefile to remind developers to update command-list.txt if they add a new guide. Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-06-09reftable: file format documentationLibravatar Jonathan Nieder1-0/+1
Shawn Pearce explains: Some repositories contain a lot of references (e.g. android at 866k, rails at 31k). The reftable format provides: - Near constant time lookup for any single reference, even when the repository is cold and not in process or kernel cache. - Near constant time verification if a SHA-1 is referred to by at least one reference (for allow-tip-sha1-in-want). - Efficient lookup of an entire namespace, such as `refs/tags/`. - Support atomic push `O(size_of_update)` operations. - Combine reflog storage with ref storage. This file format spec was originally written in July, 2017 by Shawn Pearce. Some refinements since then were made by Shawn and by Han-Wen Nienhuys based on experiences implementing and experimenting with the format. (All of this was in the context of our work at Google and Google is happy to contribute the result to the Git project.) Imported from JGit[1]'s current version (c217d33ff, "Documentation/technical/reftable: improve repo layout", 2020-02-04) of Documentation/technical/reftable.md and converted to asciidoc by running pandoc -t asciidoc -f markdown reftable.md >reftable.txt using pandoc 2.2.1. The result required the following additional minor changes: - removed the [TOC] directive to add a table of contents, since asciidoc does not support it - replaced git-scm.com/docs links with linkgit: directives that link to other pages within Git's documentation [1] https://eclipse.googlesource.com/jgit/jgit Signed-off-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-04-28Merge branch 'ma/doc-discard-docbook-xsl-1.73'Libravatar Junio C Hamano1-23/+0
Raise the minimum required version of docbook-xsl package to 1.74, as 1.74.0 was from late 2008, which is more than 10 years old, and drop compatibility cruft from our documentation suite. * ma/doc-discard-docbook-xsl-1.73: user-manual.conf: don't specify [listingblock] INSTALL: drop support for docbook-xsl before 1.74 manpage-normal.xsl: fold in manpage-base.xsl manpage-bold-literal.xsl: stop using git.docbook.backslash Doc: drop support for docbook-xsl before 1.73.0 Doc: drop support for docbook-xsl before 1.72.0 Doc: drop support for docbook-xsl before 1.71.1
2020-03-30docs: add a FAQLibravatar brian m. carlson1-0/+1
Git is an enormously flexible and powerful piece of software. However, it can be intimidating for many users and there are a set of common questions that users often ask. While we already have some new user documentation, it's worth adding a FAQ to address common questions that users often have. Even though some of this is addressed elsewhere in the documentation, experience has shown that it is difficult for users to find, so a centralized location is helpful. Add such a FAQ and fill it with some common questions and answers. While there are few entries now, we can expand it in the future to cover more things as we find new questions that users have. Let's also add section markers so that people answering questions can directly link users to the proper answer. The FAQ also addresses common configuration questions that apply not only to Git as an independent piece of software but also the ecosystem of CI tools and hosting providers that people use, since these are the source of common questions. An attempt has been made to avoid mentioning any particular provider or tool, but to nevertheless cover common configurations that apply to a wide variety of such tools. Note that the long lines for certain questions are required, since Asciidoctor does not permit broken lines there. Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-03-29Doc: drop support for docbook-xsl before 1.73.0Libravatar Martin Ågren1-10/+0
Drop the DOCBOOK_XSL_172 config knob, which was needed with docbook-xsl 1.72 (but neither 1.71 nor 1.73). Version 1.73.0 is more than twelve years old. Together with the last few commits, we are now at a point where we don't have any Makefile knobs to cater to old/broken versions of docbook-xsl. Signed-off-by: Martin Ågren <martin.agren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-03-29Doc: drop support for docbook-xsl before 1.72.0Libravatar Martin Ågren1-9/+1
docbook-xsl 1.72.0 is thirteen years old. Drop the ASCIIDOC_ROFF knob which was needed to support 1.68.1 - 1.71.1. The next commit will increase the required/assumed version further. Signed-off-by: Martin Ågren <martin.agren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-03-29Doc: drop support for docbook-xsl before 1.71.1Libravatar Martin Ågren1-6/+1
Drop the DOCBOOK_SUPPRESS_SP mechanism, which needs to be used with docbook-xsl versions 1.69.1 through 1.71.0. We probably broke this for Asciidoctor builds in f6461b82b9 ("Documentation: fix build with Asciidoctor 2", 2019-09-15). That is, we should/could fix this similar to 55aca515eb ("manpage-bold-literal.xsl: match for namespaced "d:literal" in template", 2019-10-31). But rather than digging out such an old version of docbook-xsl to test that, let's just use this as an excuse for dropping this decade-old workaround. DOCBOOK_SUPPRESS_SP was not needed with docbook-xsl 1.69.0 and older. Maybe such old versions still work fine on our docs, or maybe not. Let's just refer to everything before 1.71.1 as "not supported". The next commit will increase the required/assumed version further. Signed-off-by: Martin Ågren <martin.agren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-11-10Merge branch 'es/walken-tutorial'Libravatar Junio C Hamano1-0/+1
A tutorial on object enumeration. * es/walken-tutorial: documentation: add tutorial for object walking
2019-10-12documentation: add tutorial for object walkingLibravatar Emily Shaffer1-0/+1
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-06Merge branch 'bc/doc-use-docbook-5'Libravatar Junio C Hamano1-1/+3
Start using DocBook 5 (instead of DocBook 4.5) as Asciidoctor 2.0 no longer works with the older one. * bc/doc-use-docbook-5: Documentation: fix build with Asciidoctor 2
2019-10-06Merge branch 'ma/asciidoctor-refmiscinfo'Libravatar Junio C Hamano1-1/+2
Update support for Asciidoctor documentation toolchain. * ma/asciidoctor-refmiscinfo: doc-diff: replace --cut-header-footer with --cut-footer asciidoctor-extensions: provide `<refmiscinfo/>` Doc/Makefile: give mansource/-version/-manual attributes
2019-09-16Doc/Makefile: give mansource/-version/-manual attributesLibravatar Martin Ågren1-1/+2
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-16Documentation: fix build with Asciidoctor 2Libravatar brian m. carlson1-1/+3
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-06-17Merge branch 'es/first-contrib-tutorial'Libravatar Junio C Hamano1-0/+1
A new tutorial targetting specifically aspiring git-core developers. * es/first-contrib-tutorial: doc: add some nit fixes to MyFirstContribution documentation: add anchors to MyFirstContribution documentation: add tutorial for first contribution
2019-05-19documentation: add tutorial for first contributionLibravatar Emily Shaffer1-0/+1
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-09Merge branch 'js/misc-doc-fixes'Libravatar Junio C Hamano1-0/+3
"make check-docs", "git help -a", etc. did not account for cases where a particular build may deliberately omit some subcommands, which has been corrected. * js/misc-doc-fixes: Turn `git serve` into a test helper test-tool: handle the `-C <directory>` option just like `git` check-docs: do not bother checking for legacy scripts' documentation docs: exclude documentation for commands that have been excluded check-docs: allow command-list.txt to contain excluded commands help -a: do not list commands that are excluded from the build Makefile: drop the NO_INSTALL variable remote-testgit: move it into the support directory for t5801
2019-04-22Merge branch 'js/check-docs-exe'Libravatar Junio C Hamano1-1/+1
Dev support update. * js/check-docs-exe: check-docs: fix for setups where executables have an extension check-docs: do not expect guide pages to correspond to commands check-docs: really look at the documented commands again docs: do not document the `git remote-testgit` command docs: move gitremote-helpers into section 7
2019-04-19docs: exclude documentation for commands that have been excludedLibravatar Johannes Schindelin1-0/+3
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-16Merge branch 'ma/doc-diff-doc-vs-doctor-comparison'Libravatar Junio C Hamano1-6/+17
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-16Merge branch 'ma/asciidoctor-fixes'Libravatar Junio C Hamano1-5/+5
Build fix around use of asciidoctor instead of asciidoc * ma/asciidoctor-fixes: asciidoctor-extensions: fix spurious space after linkgit Documentation/Makefile: add missing dependency on asciidoctor-extensions Documentation/Makefile: add missing xsl dependencies for manpages
2019-04-01docs: move gitremote-helpers into section 7Libravatar Johannes Schindelin1-1/+1
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-18Doc: auto-detect changed build flagsLibravatar Martin Ågren1-6/+17
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-11Documentation/Makefile: add missing dependency on asciidoctor-extensionsLibravatar Martin Ågren1-4/+4
asciidoctor-extensions.rb has never changed, but when it does -- such as in the next commit --, it helps if the xml-files depend on it. We're casting the net a bit too wide here, since we'll be rebuilding even with AsciiDoc, which won't look at this file. But since this file changes so rarely, that should be ok. It's better than missing a dependency. Similarly, most of the html-files are produced directly from ".txt'; make the html-files too depend on asciidoctor-extensions.rb, both the HTMLified manual pages as well as the user-manual that does use .xml intermediary. Signed-off-by: Martin Ågren <martin.agren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-03-11Documentation/Makefile: add missing xsl dependencies for manpagesLibravatar Martin Ågren1-1/+1
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-01-07Documentation/Makefile add optional targets for l10nLibravatar Jean-Noel Avila1-5/+17
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>
2018-11-21Documentation: build technical/multi-pack-indexLibravatar Todd Zullinger1-0/+1
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-10-29Update makefile in preparation for Documentation/config/*.txtLibravatar Nguyễn Thái Ngọc Duy1-1/+1
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-09-17Merge branch 'ts/doc-build-manpage-xsl-quietly'Libravatar Junio C Hamano1-1/+1
Build tweak. * ts/doc-build-manpage-xsl-quietly: Documentation/Makefile: make manpage-base-url.xsl generation quieter
2018-08-29Documentation/Makefile: make manpage-base-url.xsl generation quieterLibravatar Tim Schumacher1-1/+1
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-20Merge branch 'jh/partial-clone-doc'Libravatar Junio C Hamano1-0/+1
Doc updates. * jh/partial-clone-doc: partial-clone: render design doc using asciidoc