freshlybakedca.ke / git
Git fork
fork atom

doc: check well-formedness of delimited sections

Having an empty line before each delimited sections is not required by
asciidoc, but it is a safety measure that prevents generating malformed
asciidoc when generating translated documentation.

When a delimited section appears just after a paragraph, the asciidoc
processor checks that the length of the delimited section header is
different from the length of the paragraph. If it is not, the asciidoc
processor will generate a title. In the original English documentation, this
is not a problem because the authors always check the output of the asciidoc
processor and fix the length of the delimited section header if it turns out
to be the same as the paragraph length. However, this is not the case for
translations, where the authors have no way to check the length of the
delimited section header or the output of the asciidoc processor. This can
lead to a section title that is not intended.

Indeed, this test also checks that titles are correctly formed, that is,
the length of the underline is equal to the length of the title (otherwise
it would not be a title but a section header).

Finally, this test checks that the delimited section are terminated within
the same file.

Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

authored by

Jean-Noël Avila and committed by
Junio C Hamano 63d33eb7 f81a574f

+80 -4
unified split
+10 -1
Documentation/Makefile
··· 497 497 $(call mkdir_p_parent_template) 498 498 $(QUIET_GEN)$(PERL_PATH) lint-fsck-msgids.perl \ 499 499 ../fsck.h fsck-msgids.adoc $@ 500 + lint-docs-fsck-msgids: $(LINT_DOCS_FSCK_MSGIDS) 500 501 501 - lint-docs-fsck-msgids: $(LINT_DOCS_FSCK_MSGIDS) 502 + ## Lint: delimited sections 503 + LINT_DOCS_DELIMITED_SECTIONS = $(patsubst %.adoc,.build/lint-docs/delimited-sections/%.ok,$(MAN_TXT)) 504 + $(LINT_DOCS_DELIMITED_SECTIONS): lint-delimited-sections.perl 505 + $(LINT_DOCS_DELIMITED_SECTIONS): .build/lint-docs/delimited-sections/%.ok: %.adoc 506 + $(call mkdir_p_parent_template) 507 + $(QUIET_LINT_DELIMSEC)$(PERL_PATH) lint-delimited-sections.perl $< >$@ 508 + .PHONY: lint-docs-delimited-sections 509 + lint-docs-delimited-sections: $(LINT_DOCS_DELIMITED_SECTIONS) 502 510 503 511 lint-docs-manpages: 504 512 $(QUIET_GEN)./lint-manpages.sh ··· 528 536 lint-docs: lint-docs-gitlink 529 537 lint-docs: lint-docs-man-end-blurb 530 538 lint-docs: lint-docs-man-section-order 539 + lint-docs: lint-docs-delimited-sections 531 540 lint-docs: lint-docs-manpages 532 541 lint-docs: lint-docs-meson 533 542
+1
Documentation/RelNotes/1.6.2.4.adoc
··· 37 37 echo O=$(git describe maint) 38 38 O=v1.6.2.3-38-g318b847 39 39 git shortlog --no-merges $O..maint 40 + ---
+1
Documentation/diff-format.adoc
··· 103 103 followed by the name of the path in the merge commit. 104 104 105 105 Examples for `-c` and `--cc` without `--combined-all-paths`: 106 + 106 107 ------------------------------------------------ 107 108 ::100644 100644 100644 fabadb8 cc95eb0 4866510 MM desc.c 108 109 ::100755 100755 100755 52b7a2d 6d1ac04 d2ac7d7 RM bar.sh
+1
Documentation/git-commit.adoc
··· 281 281 + 282 282 -- 283 283 It is a rough equivalent for: 284 + 284 285 ------ 285 286 $ git reset --soft HEAD^ 286 287 $ ... do something else to come up with the right tree ...
+2
Documentation/git-fast-import.adoc
··· 605 605 606 606 The special case of restarting an incremental import from the 607 607 current branch value should be written as: 608 + 608 609 ---- 609 610 from refs/heads/branch^0 610 611 ---- 612 + 611 613 The `^0` suffix is necessary as fast-import does not permit a branch to 612 614 start from itself, and the branch is created in memory before the 613 615 `from` command is even read from the input. Adding `^0` will force
+1
Documentation/git-p4.adoc
··· 66 66 ~~~~~ 67 67 Generally, 'git p4 clone' is used to create a new Git directory 68 68 from an existing p4 repository: 69 + 69 70 ------------ 70 71 $ git p4 clone //depot/path/project 71 72 ------------
+1 -1
Documentation/git-rebase.adoc
··· 687 687 * --fork-point and --root 688 688 689 689 BEHAVIORAL DIFFERENCES 690 - ----------------------- 690 + ---------------------- 691 691 692 692 `git rebase` has two primary backends: 'apply' and 'merge'. (The 'apply' 693 693 backend used to be known as the 'am' backend, but the name led to
+2
Documentation/git-svn.adoc
··· 1012 1012 1013 1013 If you do merge, note the following rule: 'git svn dcommit' will 1014 1014 attempt to commit on top of the SVN commit named in 1015 + 1015 1016 ------------------------------------------------------------------------ 1016 1017 git log --grep=^git-svn-id: --first-parent -1 1017 1018 ------------------------------------------------------------------------ 1019 + 1018 1020 You 'must' therefore ensure that the most recent commit of the branch 1019 1021 you want to dcommit to is the 'first' parent of the merge. Chaos will 1020 1022 ensue otherwise, especially if the first parent is an older commit on
+1 -1
Documentation/gitprotocol-http.adoc
··· 318 318 319 319 320 320 Smart Service git-upload-pack 321 - ------------------------------ 321 + ----------------------------- 322 322 This service reads from the repository pointed to by `$GIT_URL`. 323 323 324 324 Clients MUST first perform ref discovery with
+2 -1
Documentation/gitsubmodules.adoc
··· 8 8 SYNOPSIS 9 9 -------- 10 10 .gitmodules, $GIT_DIR/config 11 + 11 12 ------------------ 12 13 git submodule 13 14 git <command> --recurse-submodules ··· 240 241 241 242 242 243 Workflow for an artificially split repo 243 - -------------------------------------- 244 + --------------------------------------- 244 245 245 246 # Enable recursion for relevant commands, such that 246 247 # regular commands recurse into submodules by default
+48
Documentation/lint-delimited-sections.perl
··· 1 + #!/usr/bin/perl 2 + 3 + use strict; 4 + use warnings; 5 + 6 + my $exit_code = 0; 7 + sub report { 8 + my ($msg) = @_; 9 + print STDERR "$ARGV:$.: $msg\n"; 10 + $exit_code = 1; 11 + } 12 + 13 + my $line_length = 0; 14 + my $in_section = 0; 15 + my $section_header = ""; 16 + 17 + 18 + while (my $line = <>) { 19 + if (($line =~ /^\+?$/) || 20 + ($line =~ /^\[.*\]$/) || 21 + ($line =~ /^ifdef::/)) { 22 + $line_length = 0; 23 + } elsif ($line =~ /^[^-.]/) { 24 + $line_length = length($line); 25 + } elsif (($line =~ /^-{3,}$/) || ($line =~ /^\.{3,}$/)) { 26 + if ($in_section) { 27 + if ($line eq $section_header) { 28 + $in_section = 0; 29 + } 30 + next; 31 + } 32 + if ($line_length == 0) { 33 + $in_section = 1; 34 + $section_header = $line; 35 + next; 36 + } 37 + if (($line_length != 0) && (length($line) != $line_length)) { 38 + report("section delimiter not preceded by an empty line"); 39 + } 40 + $line_length = 0; 41 + } 42 + } 43 + 44 + if ($in_section) { 45 + report("section not finished"); 46 + } 47 + 48 + exit $exit_code;
+8
Documentation/mergetools/vimdiff.adoc
··· 3 3 4 4 When specifying `--tool=vimdiff` in `git mergetool` Git will open Vim with a 4 5 5 windows layout distributed in the following way: 6 + 6 7 .... 7 8 ------------------------------------------ 8 9 | | | | ··· 56 57 + 57 58 -- 58 59 If, for some reason, we are not interested in the `BASE` buffer. 60 + 59 61 .... 60 62 ------------------------------------------ 61 63 | | | | ··· 72 74 Only the `MERGED` buffer will be shown. Note, however, that all the other 73 75 ones are still loaded in vim, and you can access them with the "buffers" 74 76 command. 77 + 75 78 .... 76 79 ------------------------------------------ 77 80 | | ··· 88 91 When `MERGED` is not present in the layout, you must "mark" one of the 89 92 buffers with an arobase (`@`). That will become the buffer you need to edit and 90 93 save after resolving the conflicts. 94 + 91 95 .... 92 96 ------------------------------------------ 93 97 | | | ··· 106 110 Three tabs will open: the first one is a copy of the default layout, while 107 111 the other two only show the differences between (`BASE` and `LOCAL`) and 108 112 (`BASE` and `REMOTE`) respectively. 113 + 109 114 .... 110 115 ------------------------------------------ 111 116 | <TAB #1> | TAB #2 | TAB #3 | | ··· 119 124 | | 120 125 ------------------------------------------ 121 126 .... 127 + 122 128 .... 123 129 ------------------------------------------ 124 130 | TAB #1 | <TAB #2> | TAB #3 | | ··· 132 138 | | | 133 139 ------------------------------------------ 134 140 .... 141 + 135 142 .... 136 143 ------------------------------------------ 137 144 | TAB #1 | TAB #2 | <TAB #3> | | ··· 151 158 -- 152 159 Same as the previous example, but adds a fourth tab with the same 153 160 information as the first tab, with a different layout. 161 + 154 162 .... 155 163 --------------------------------------------- 156 164 | TAB #1 | TAB #2 | TAB #3 | <TAB #4> |
+1
Documentation/technical/long-running-process-protocol.adoc
··· 24 24 it supports and a flush packet. Git expects to read a list of desired 25 25 capabilities, which must be a subset of the supported capabilities list, 26 26 and a flush packet as response: 27 + 27 28 ------------------------ 28 29 packet: git> git-filter-client 29 30 packet: git> version=2
+1
shared.mak
··· 88 88 89 89 QUIET_LINT_GITLINK = @echo ' ' LINT GITLINK $<; 90 90 QUIET_LINT_MANSEC = @echo ' ' LINT MAN SEC $<; 91 + QUIET_LINT_DELIMSEC = @echo ' ' LINT DEL SEC $<; 91 92 QUIET_LINT_MANEND = @echo ' ' LINT MAN END $<; 92 93 93 94 export V