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 7378ec90e1 (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;
|