summaryrefslogtreecommitdiff
path: root/Documentation/doc-diff
AgeCommit message (Collapse)AuthorFilesLines
2020-02-18doc-diff: use single-colon rule in rendering MakefileLibravatar Jeff King1-1/+1
When rendering the troff manpages to text via "man", we create an ad-hoc Makefile and feed it to "make". The purpose here is two-fold: - reuse results from a prior interrupted render of the same tree - use make's -j option to build in parallel But the second part doesn't seem to work (at least with my version of GNU make, 4.2.1). It just runs one render at a time. We use a double-colon "all" rule for each file, like: all:: foo foo: ...actual render recipe... all:: bar bar: ...actual render recipe... ...and so on... And it's this double-colon that seems to inhibit the parallelism. We can just switch to a regular single-colon rule. Even though we do have multiple rules for "all" here, we don't have any recipe to execute for "all" (we only care about triggering its dependencies), so the distinction is irrelevant. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-09-16doc-diff: replace --cut-header-footer with --cut-footerLibravatar Martin Ågren1-9/+8
After the previous commit, AsciiDoc and Asciidoctor render the manpage headers identically, so we no longer need the "cut the header" part of our `--cut-header-footer` option. We do still need the "cut the footer" part, though. The previous commits improved the rendering of the footer in Asciidoctor by quite a bit, but the two programs still disagree on how to format the date in the footer: 01/01/1970 vs 1970-01-01. We could keep using `--cut-header-footer`, but it would be nice if we had a slightly smaller hammer `--cut-footer` that would be less likely to hide regressions. Rather than simply adding such an option, let's also drop `--cut-header-footer`, i.e., rework it to lose the "header" part of its name and functionality. `--cut-header-footer` is just a developer tool and it probably has no more than a handful of users, so we can afford to be aggressive. Signed-off-by: Martin Ågren <martin.agren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-03-18doc-diff: add `--cut-header-footer`Libravatar Martin Ågren1-2/+17
AsciiDoc and Asciidoctor do not agree on what to write in the header and footer of each man-page, i.e., the very first and the very last line of *.[157]. Those differences can certainly be interesting in their own right, but they clutter the output of `./doc-diff --from-asciidoc --to-asciidoctor HEAD HEAD` quite a bit since the diff contains some 10-15 lines of noise per file diffed. Teach doc-diff to cut away the first two and last two lines, i.e., the header/footer and the empty line immediately following/preceding it. Because Asciidoctor uses an extra empty line compared to AsciiDoc, remove one more line at each end of the file, but only if it's empty. An alternative approach might be to pass down `--no-header-footer`, which both AsciiDoc and Asciidoctor understand, but it has some drawbacks. First of all, the result doesn't build -- `xmlto` stumbles on the resulting xml since it has multiple root elements. Second, it cuts too much -- dropping the header loses the synopsis, which would be interesting to diff. Like in the previous commit, encode this option into the directory name of the "installed" and "rendered" files. Otherwise, we wouldn't be able to trust that what we use out of that cache actually corresponds to the options given for this run. (We could optimize this caching a little since this flag doesn't affect the contents of "installed" at all, but let's punt on that.) Signed-off-by: Martin Ågren <martin.agren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-03-18doc-diff: support diffing from/to AsciiDoc(tor)Libravatar Martin Ågren1-8/+45
Provide `--from-asciidoctor` and `--to-asciidoctor` to select that the "from" resp. "to" commit should be built with Asciidoctor, and provide an `--asciidoctor` shortcut for giving both. Similarly, provide --{from-,to-,}asciidoc for explicitly selecting AsciiDoc. Implement this using the USE_ASCIIDOCTOR flag. Let's not enforce a default here, but instead just let the Makefile fall back on whatever is in config.mak, so that `./doc-diff foo bar` without any of of these new options behaves exactly like it did before this commit. Encode the choice into the directory names of our "installed" and "rendered" files, so that we can run `./doc-diff --from-asciidoc --to-asciidoctor HEAD HEAD` without our two runs stomping on each other. Signed-off-by: Martin Ågren <martin.agren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-03-18doc-diff: let `render_tree()` take an explicit directory nameLibravatar Martin Ågren1-11/+17
In `render_tree()`, `$1` is documented to be the commit-ish/oid and we use it as that with `git checkout`, but we mostly use it to form the name of various directories. To separate these concerns, and because we are about to construct the directory names a bit differently, take two distinct arguments instead. Signed-off-by: Martin Ågren <martin.agren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-02-06Merge branch 'ma/doc-diff-usage-fix'Libravatar Junio C Hamano1-3/+2
Running "Documentation/doc-diff x" from anywhere other than the top-level of the working tree did not show the usage string correctly, which has been fixed. * ma/doc-diff-usage-fix: doc-diff: don't `cd_to_toplevel`
2019-02-04doc-diff: don't `cd_to_toplevel`Libravatar Martin Ågren1-3/+2
`usage` tries to call $0, which might very well be "./doc-diff", so if we `cd_to_toplevel` before calling `usage`, we'll end with an error to the effect of "./doc-diff: not found" rather than a friendly `doc-diff -h` output. This regressed in ad51743007 ("doc-diff: add --clean mode to remove temporary working gunk", 2018-08-31) where we moved the call to `cd_to_toplevel` to much earlier. A general fix might be to teach git-sh-setup to save away the absolute path for $0 and then use that, instead. I'm not aware of any portable way of doing that, see, e.g., d2addc3b96 ("t7800: readlink may not be available", 2016-05-31). An early version of this patch moved `cd_to_toplevel` back to where it was before ad51743007 and taught the "--clean" code to cd on its own. But let's try instead to get rid of the cd-ing entirely. We don't really need it and we can work with absolute paths instead. There's just one use of $PWD that we need to adjust by simply dropping it. Suggested-by: Jeff King <peff@peff.net> Signed-off-by: Martin Ågren <martin.agren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-09-17Merge branch 'es/worktree-forced-ops-fix'Libravatar Junio C Hamano1-1/+1
Fix a bug in which the same path could be registered under multiple worktree entries if the path was missing (for instance, was removed manually). Also, as a convenience, expand the number of cases in which --force is applicable. * es/worktree-forced-ops-fix: doc-diff: force worktree add worktree: delete .git/worktrees if empty after 'remove' worktree: teach 'remove' to override lock when --force given twice worktree: teach 'move' to override lock when --force given twice worktree: teach 'add' to respect --force for registered but missing path worktree: disallow adding same path multiple times worktree: prepare for more checks of whether path can become worktree worktree: generalize delete_git_dir() to reduce code duplication worktree: move delete_git_dir() earlier in file for upcoming new callers worktree: don't die() in library function find_worktree()
2018-09-05doc-diff: force worktree addLibravatar Jeff King1-1/+1
We avoid re-creating our temporary worktree if it's already there. But we may run into a situation where the worktree has been deleted, but an entry still exists in $GIT_DIR/worktrees. Older versions of git-worktree would annoyingly create a series of duplicate entries. Recent versions now detect and prevent this, allowing you to override with "-f". Since we know that the worktree in question was just our temporary workspace, it's safe for us to always pass "-f". Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-08-31doc-diff: add --clean mode to remove temporary working gunkLibravatar Eric Sunshine1-3/+16
As part of its operation, doc-diff creates a bunch of temporary working files and holds onto them in order to speed up subsequent invocations. These files are never deleted. Moreover, it creates a temporary working tree (via git-wortkree) which likewise never gets removed. Without knowing the implementation details of the tool, a user may not know how to clean up manually afterward. Worse, the user may find it surprising and alarming to discover a working tree which s/he did not create explicitly. To address these issues, add a --clean mode which removes the temporary working tree and deletes all generated files. Signed-off-by: Eric Sunshine <sunshine@sunshineco.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-08-31doc-diff: fix non-portable 'man' invocationLibravatar Eric Sunshine1-1/+1
doc-diff invokes 'man' with the -l option to force "local" mode, however, neither MacOS nor FreeBSD recognize this option. On those platforms, if the argument to 'man' contains a slash, it is automatically interpreted as a file specification, so a "local"-like mode is not needed. And, it turns out, 'man' which does support -l falls back to enabling -l automatically if it can't otherwise find a manual entry corresponding to the argument. Since doc-diff always passes an absolute path of the nroff source file to 'man', the -l option kicks in anyhow, despite not being specified explicitly. Therefore, make the invocation portable to the various platforms by simply dropping -l. Signed-off-by: Eric Sunshine <sunshine@sunshineco.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-08-30doc-diff: always use oids inside worktreeLibravatar Jeff King1-4/+4
The doc-diff script immediately resolves its two endpoints to actual object ids, so that we can reuse cached results even if they appear under a different name. But we still use the original name the user fed us when running "git checkout" in our temporary worktree. This can lead to confusing results: - the namespace inside the worktree is different than the one outside. In particular, "./doc-diff origin HEAD" will resolve HEAD inside the worktree, whose detached HEAD will be pointing at origin! As a result, such a diff would always be empty. - worse, we will store this result under the oid we got by resolving HEAD in the main worktree, thus polluting our cache - we didn't pass --detach, which meant that using a branch name would cause us to actually check out that branch, making it unavailable to other worktrees. We can solve this by feeding the already-resolved object id to git-checkout. That naturally forces a detached HEAD, but just to make clear our expectation, let's explicitly pass --detach. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-08-21SubmittingPatches: mention doc-diffLibravatar Jeff King1-0/+8
We already advise people to make sure their documentation formats correctly. Let's point them at the doc-diff script, which can help with that. Let's also put a brief note in the script about its purpose, since that otherwise can only be found in the original commit message. Along with the existing -h/usage text, that's hopefully enough for developers to make use of it. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-08-06add a script to diff rendered documentationLibravatar Jeff King1-0/+109
After making a change to the documentation, it's easy to forget to check the rendered version to make sure it was formatted as you intended. And simply doing a diff between the two built versions is less trivial than you might hope: - diffing the roff or html output isn't particularly readable; what we really care about is what the end user will see - you have to tweak a few build variables to avoid spurious differences (e.g., version numbers, build times) Let's provide a script that builds and installs the manpages for two commits, renders the results using "man", and diffs the result. Since this is time-consuming, we'll also do our best to avoid repeated work, keeping intermediate results between runs. Some of this could probably be made a little less ugly if we built support into Documentation/Makefile. But by relying only on "make install-man" working, this script should work for generating a diff between any two versions, whether they include this script or not. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>