kernel/git - git - PowerEL Git System

Commit Graph

Author	SHA1	Message	Date
Jeff King	2607d39da3	doc-diff: use single-colon rule in rendering Makefile 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>	5 years ago
Martin Ågren	83b0b8953e	doc-diff: replace --cut-header-footer with --cut-footer 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>	5 years ago
Martin Ågren	e605077260	doc-diff: add `--cut-header-footer` 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>	6 years ago
Martin Ågren	2be39bb43d	doc-diff: support diffing from/to AsciiDoc(tor) 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>	6 years ago
Martin Ågren	bc71dc3fa1	doc-diff: let `render_tree()` take an explicit directory name 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>	6 years ago
Martin Ågren	2afe9278a2	doc-diff: don't `cd_to_toplevel` `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>	6 years ago
Jeff King	684e742249	doc-diff: force worktree add 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>	6 years ago
Eric Sunshine	ad51743007	doc-diff: add --clean mode to remove temporary working gunk 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>	7 years ago
Eric Sunshine	83d4b5ff29	doc-diff: fix non-portable 'man' invocation 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>	7 years ago
Jeff King	27064fb7fb	doc-diff: always use oids inside worktree 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>	7 years ago
Jeff King	7a76f5c611	SubmittingPatches: mention doc-diff 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>	7 years ago
Jeff King	beb188e22a	add a script to diff rendered documentation 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>	7 years ago

14 Commits (0fabafd0b948bfc1c07db73494863d581c7f5d04)