844739ba27
Create a new "File formats, protocols and other developer interfaces" section in the main "git help git" manual page and start moving the documentation that now lives in "Documentation/technical/*.git" over to it. This complements the newly added and adjacent "Repository, command and file interfaces" section. This makes the technical documentation more accessible and discoverable. Before this we wouldn't install it by default, and had no ability to build man page versions of them. The links to them from our existing documentation link to the generated HTML version of these docs. So let's start moving those over, starting with just the "bundle-format.txt" documentation added in 7378ec90e1c (doc: describe Git bundle format, 2020-02-07). We'll now have a new gitformat-bundle(5) man page. Subsequent commits will move more git internal format documentation over. Unfortunately the syntax of the current Documentation/technical/*.txt is not the same (when it comes to section headings etc.) as our Documentation/*.txt documentation, so change the relevant bits of syntax as we're moving this over. Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
109 lines
2.1 KiB
Perl
Executable File
109 lines
2.1 KiB
Perl
Executable File
#!/usr/bin/perl
|
|
|
|
use strict;
|
|
use warnings;
|
|
|
|
my %SECTIONS;
|
|
{
|
|
my $order = 0;
|
|
%SECTIONS = (
|
|
'NAME' => {
|
|
required => 1,
|
|
order => $order++,
|
|
},
|
|
'SYNOPSIS' => {
|
|
required => 1,
|
|
order => $order++,
|
|
},
|
|
'DESCRIPTION' => {
|
|
required => 1,
|
|
order => $order++,
|
|
},
|
|
'OPTIONS' => {
|
|
order => $order++,
|
|
required => 0,
|
|
},
|
|
'CONFIGURATION' => {
|
|
order => $order++,
|
|
},
|
|
'BUGS' => {
|
|
order => $order++,
|
|
},
|
|
'SEE ALSO' => {
|
|
order => $order++,
|
|
},
|
|
'FILE FORMAT' => {
|
|
order => $order++,
|
|
},
|
|
'GIT' => {
|
|
required => 1,
|
|
order => $order++,
|
|
},
|
|
);
|
|
}
|
|
my $SECTION_RX = do {
|
|
my ($names) = join "|", keys %SECTIONS;
|
|
qr/^($names)$/s;
|
|
};
|
|
|
|
my $exit_code = 0;
|
|
sub report {
|
|
my ($msg) = @_;
|
|
print STDERR "$ARGV:$.: $msg\n";
|
|
$exit_code = 1;
|
|
}
|
|
|
|
my $last_was_section;
|
|
my @actual_order;
|
|
while (my $line = <>) {
|
|
chomp $line;
|
|
if ($line =~ $SECTION_RX) {
|
|
push @actual_order => $line;
|
|
$last_was_section = 1;
|
|
# Have no "last" section yet, processing NAME
|
|
next if @actual_order == 1;
|
|
|
|
my @expected_order = sort {
|
|
$SECTIONS{$a}->{order} <=> $SECTIONS{$b}->{order}
|
|
} @actual_order;
|
|
|
|
my $expected_last = $expected_order[-2];
|
|
my $actual_last = $actual_order[-2];
|
|
if ($actual_last ne $expected_last) {
|
|
report("section '$line' incorrectly ordered, comes after '$actual_last'");
|
|
}
|
|
next;
|
|
}
|
|
if ($last_was_section) {
|
|
my $last_section = $actual_order[-1];
|
|
if (length $last_section ne length $line) {
|
|
report("dashes under '$last_section' should match its length!");
|
|
}
|
|
if ($line !~ /^-+$/) {
|
|
report("dashes under '$last_section' should be '-' dashes!");
|
|
}
|
|
$last_was_section = 0;
|
|
}
|
|
|
|
if (eof) {
|
|
# We have both a hash and an array to consider, for
|
|
# convenience
|
|
my %actual_sections;
|
|
@actual_sections{@actual_order} = ();
|
|
|
|
for my $section (sort keys %SECTIONS) {
|
|
next if !$SECTIONS{$section}->{required} or exists $actual_sections{$section};
|
|
report("has no required '$section' section!");
|
|
}
|
|
|
|
# Reset per-file state
|
|
{
|
|
@actual_order = ();
|
|
# this resets our $. for each file
|
|
close ARGV;
|
|
}
|
|
}
|
|
}
|
|
|
|
exit $exit_code;
|