]> git.ipfire.org Git - thirdparty/git.git/commitdiff
doc: check well-formedness of delimited sections
authorJean-Noël Avila <jn.avila@free.fr>
Mon, 11 Aug 2025 20:53:16 +0000 (20:53 +0000)
committerJunio C Hamano <gitster@pobox.com>
Mon, 11 Aug 2025 21:16:03 +0000 (14:16 -0700)
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>
14 files changed:
Documentation/Makefile
Documentation/RelNotes/1.6.2.4.adoc
Documentation/diff-format.adoc
Documentation/git-commit.adoc
Documentation/git-fast-import.adoc
Documentation/git-p4.adoc
Documentation/git-rebase.adoc
Documentation/git-svn.adoc
Documentation/gitprotocol-http.adoc
Documentation/gitsubmodules.adoc
Documentation/lint-delimited-sections.perl [new file with mode: 0755]
Documentation/mergetools/vimdiff.adoc
Documentation/technical/long-running-process-protocol.adoc
shared.mak

index df2ce187eb84cf6ca43fa1229789058155931347..76a9e1d02b2643930aa4fef3975178b495e55404 100644 (file)
@@ -497,9 +497,17 @@ $(LINT_DOCS_FSCK_MSGIDS): ../fsck.h fsck-msgids.adoc
        $(call mkdir_p_parent_template)
        $(QUIET_GEN)$(PERL_PATH) lint-fsck-msgids.perl \
                ../fsck.h fsck-msgids.adoc $@
-
 lint-docs-fsck-msgids: $(LINT_DOCS_FSCK_MSGIDS)
 
+## Lint: delimited sections
+LINT_DOCS_DELIMITED_SECTIONS = $(patsubst %.adoc,.build/lint-docs/delimited-sections/%.ok,$(MAN_TXT))
+$(LINT_DOCS_DELIMITED_SECTIONS): lint-delimited-sections.perl
+$(LINT_DOCS_DELIMITED_SECTIONS): .build/lint-docs/delimited-sections/%.ok: %.adoc
+       $(call mkdir_p_parent_template)
+       $(QUIET_LINT_DELIMSEC)$(PERL_PATH) lint-delimited-sections.perl $< >$@
+.PHONY: lint-docs-delimited-sections
+lint-docs-delimited-sections: $(LINT_DOCS_DELIMITED_SECTIONS)
+
 lint-docs-manpages:
        $(QUIET_GEN)./lint-manpages.sh
 
@@ -528,6 +536,7 @@ lint-docs: lint-docs-fsck-msgids
 lint-docs: lint-docs-gitlink
 lint-docs: lint-docs-man-end-blurb
 lint-docs: lint-docs-man-section-order
+lint-docs: lint-docs-delimited-sections
 lint-docs: lint-docs-manpages
 lint-docs: lint-docs-meson
 
index f4bf1d09863c71cddec95a75d7a26bb09879712a..053dbb604de6c4403213dbcb1d0ff3cf6b02d1c2 100644 (file)
@@ -37,3 +37,4 @@ exec >/var/tmp/1
 echo O=$(git describe maint)
 O=v1.6.2.3-38-g318b847
 git shortlog --no-merges $O..maint
+---
index 80e36e153dac880e788d720b4219f9171094a4d3..9f7e98824183494575d32248215c71af71a2d3f1 100644 (file)
@@ -103,6 +103,7 @@ if the file was renamed on any side of history.  With
 followed by the name of the path in the merge commit.
 
 Examples for `-c` and `--cc` without `--combined-all-paths`:
+
 ------------------------------------------------
 ::100644 100644 100644 fabadb8 cc95eb0 4866510 MM      desc.c
 ::100755 100755 100755 52b7a2d 6d1ac04 d2ac7d7 RM      bar.sh
index ae988a883b5b86f79a0c3b5e125f6d392bb96e2b..d4d576ce665f1967782aefa41dd39b7c35e65179 100644 (file)
@@ -281,6 +281,7 @@ variable (see linkgit:git-config[1]).
 +
 --
 It is a rough equivalent for:
+
 ------
        $ git reset --soft HEAD^
        $ ... do something else to come up with the right tree ...
index 6f9763c11b3cfd6956059372b4f642f41b0d4c6c..6490d67fab56e19019f932b36a32939dc904ed2a 100644 (file)
@@ -605,9 +605,11 @@ Marks must be declared (via `mark`) before they can be used.
 
 The special case of restarting an incremental import from the
 current branch value should be written as:
+
 ----
        from refs/heads/branch^0
 ----
+
 The `^0` suffix is necessary as fast-import does not permit a branch to
 start from itself, and the branch is created in memory before the
 `from` command is even read from the input.  Adding `^0` will force
index f97b786bf98a214206815f647e62314569146492..59edd241341e0db8f0d6541dbcc0411b0361d533 100644 (file)
@@ -66,6 +66,7 @@ Clone
 ~~~~~
 Generally, 'git p4 clone' is used to create a new Git directory
 from an existing p4 repository:
+
 ------------
 $ git p4 clone //depot/path/project
 ------------
index 956d3048f5a6189f254ada226f47e9ccba3609fc..727160c6db77fcaf68a0532cbecd6cd9f2919d11 100644 (file)
@@ -687,7 +687,7 @@ In addition, the following pairs of options are incompatible:
  * --fork-point and --root
 
 BEHAVIORAL DIFFERENCES
------------------------
+----------------------
 
 `git rebase` has two primary backends: 'apply' and 'merge'.  (The 'apply'
 backend used to be known as the 'am' backend, but the name led to
index bcf7d84a87d1cc17358f3662c07b0e7adec0057f..c26c12bab37abfd01a29395ed39b2df3a46cb2d7 100644 (file)
@@ -1012,9 +1012,11 @@ branch.
 
 If you do merge, note the following rule: 'git svn dcommit' will
 attempt to commit on top of the SVN commit named in
+
 ------------------------------------------------------------------------
 git log --grep=^git-svn-id: --first-parent -1
 ------------------------------------------------------------------------
+
 You 'must' therefore ensure that the most recent commit of the branch
 you want to dcommit to is the 'first' parent of the merge.  Chaos will
 ensue otherwise, especially if the first parent is an older commit on
index ec40a550ccab88b35f826e9133635e15c0f6c5ff..d024010414aa6dbc18c6f7bab59a44eb2d33afe0 100644 (file)
@@ -318,7 +318,7 @@ Extra Parameter.
 
 
 Smart Service git-upload-pack
-------------------------------
+-----------------------------
 This service reads from the repository pointed to by `$GIT_URL`.
 
 Clients MUST first perform ref discovery with
index f7b5a25a0caa91c7eec2612d56300af08718c2a6..20822961999aa86402f7224d9cee7e26c68cff35 100644 (file)
@@ -8,6 +8,7 @@ gitsubmodules - Mounting one repository inside another
 SYNOPSIS
 --------
  .gitmodules, $GIT_DIR/config
+
 ------------------
 git submodule
 git <command> --recurse-submodules
@@ -240,7 +241,7 @@ Workflow for a third party library
 
 
 Workflow for an artificially split repo
---------------------------------------
+---------------------------------------
 
   # Enable recursion for relevant commands, such that
   # regular commands recurse into submodules by default
diff --git a/Documentation/lint-delimited-sections.perl b/Documentation/lint-delimited-sections.perl
new file mode 100755 (executable)
index 0000000..140b852
--- /dev/null
@@ -0,0 +1,48 @@
+#!/usr/bin/perl
+
+use strict;
+use warnings;
+
+my $exit_code = 0;
+sub report {
+       my ($msg) = @_;
+       print STDERR "$ARGV:$.: $msg\n";
+       $exit_code = 1;
+}
+
+my $line_length = 0;
+my $in_section = 0;
+my $section_header = "";
+
+
+while (my $line = <>) {
+       if (($line =~ /^\+?$/) ||
+           ($line =~ /^\[.*\]$/) ||
+           ($line =~ /^ifdef::/)) {
+               $line_length = 0;
+       } elsif ($line =~ /^[^-.]/) {
+               $line_length = length($line);
+       } elsif (($line =~ /^-{3,}$/) || ($line =~ /^\.{3,}$/)) {
+               if ($in_section) {
+                       if ($line eq $section_header) {
+                               $in_section = 0;
+                       }
+               next;
+               }
+               if ($line_length == 0) {
+                       $in_section = 1;
+                       $section_header = $line;
+                       next;
+               }
+               if (($line_length != 0) && (length($line) != $line_length)) {
+                       report("section delimiter not preceded by an empty line");
+               }
+               $line_length = 0;
+       }
+}
+
+if ($in_section) {
+       report("section not finished");
+}
+
+exit $exit_code;
index abfd426f74a07940a29156b61213078e4e5936ba..b4ab83a510e0b02eb20311c3cb04b784738c7590 100644 (file)
@@ -3,6 +3,7 @@ Description
 
 When specifying `--tool=vimdiff` in `git mergetool` Git will open Vim with a 4
 windows layout distributed in the following way:
+
 ....
 ------------------------------------------
 |             |           |              |
@@ -56,6 +57,7 @@ needed in this case. The next layout definition is equivalent:
 +
 --
 If, for some reason, we are not interested in the `BASE` buffer.
+
 ....
 ------------------------------------------
 |             |           |              |
@@ -72,6 +74,7 @@ If, for some reason, we are not interested in the `BASE` buffer.
 Only the `MERGED` buffer will be shown. Note, however, that all the other
 ones are still loaded in vim, and you can access them with the "buffers"
 command.
+
 ....
 ------------------------------------------
 |                                        |
@@ -88,6 +91,7 @@ command.
 When `MERGED` is not present in the layout, you must "mark" one of the
 buffers with an arobase (`@`). That will become the buffer you need to edit and
 save after resolving the conflicts.
+
 ....
 ------------------------------------------
 |                   |                    |
@@ -106,6 +110,7 @@ save after resolving the conflicts.
 Three tabs will open: the first one is a copy of the default layout, while
 the other two only show the differences between (`BASE` and `LOCAL`) and
 (`BASE` and `REMOTE`) respectively.
+
 ....
 ------------------------------------------
 | <TAB #1> |  TAB #2  |  TAB #3  |       |
@@ -119,6 +124,7 @@ the other two only show the differences between (`BASE` and `LOCAL`) and
 |                                        |
 ------------------------------------------
 ....
+
 ....
 ------------------------------------------
 |  TAB #1  | <TAB #2> |  TAB #3  |       |
@@ -132,6 +138,7 @@ the other two only show the differences between (`BASE` and `LOCAL`) and
 |                   |                    |
 ------------------------------------------
 ....
+
 ....
 ------------------------------------------
 |  TAB #1  |  TAB #2  | <TAB #3> |       |
@@ -151,6 +158,7 @@ the other two only show the differences between (`BASE` and `LOCAL`) and
 --
 Same as the previous example, but adds a fourth tab with the same
 information as the first tab, with a different layout.
+
 ....
 ---------------------------------------------
 |  TAB #1  |  TAB #2  |  TAB #3  | <TAB #4> |
index 6f33654b4288d4effafed8a78162da9da2bf7f9a..39bd89d467d6b93e6bf0f36ed5571bf094f742f1 100644 (file)
@@ -24,6 +24,7 @@ After the version negotiation Git sends a list of all capabilities that
 it supports and a flush packet. Git expects to read a list of desired
 capabilities, which must be a subset of the supported capabilities list,
 and a flush packet as response:
+
 ------------------------
 packet:          git> git-filter-client
 packet:          git> version=2
index 1a99848a95174c5e386c59321655937e7b7d8a28..57095d6cf96c1271a79efadea9c4013f6d66d58b 100644 (file)
@@ -88,6 +88,7 @@ ifndef V
 
        QUIET_LINT_GITLINK      = @echo '   ' LINT GITLINK $<;
        QUIET_LINT_MANSEC       = @echo '   ' LINT MAN SEC $<;
+       QUIET_LINT_DELIMSEC     = @echo '   ' LINT DEL SEC $<;
        QUIET_LINT_MANEND       = @echo '   ' LINT MAN END $<;
 
        export V