Re: [PATCH] doc: don't require a SYNOPSIS in section 7

[Tuomas Ahola <taahol@utu.fi>]

Junio C Hamano <gitster@pobox.com> wrote:

> "Julia Evans" <julia@jvns.ca> writes:
> 
> >> +# assume the first line is formatted like 'gitglossary(7)'
> >> +my $firstline = <>;
> >> +$firstline =~ m/\((\d)\)/;
> >> +my $man_section_number = $1;
> >> +
> >>  my $last_was_section;
> >>  my @actual_order;
> >>  while (my $line = <>) {
> >> @@ -93,6 +98,8 @@ while (my $line = <>) {
> >> 
> >>  		for my $section (sort keys %SECTIONS) {
> >>  			next if !$SECTIONS{$section}->{required} or exists 
> >> $actual_sections{$section};
> >> +			# Synopsis is not required in section 7
> >> +			next if ($section eq "SYNOPSIS" && $man_section_number eq "7");
> >>  			report("has no required '$section' section!");
> >>  		}
> >
> >
> > I just realized that this script is actually supposed to be able to process multiple
> > files as command line arguments, and that this patch won't work for that.
> 
> Yeah, your version would then notice only the first line of the
> first file, and my update would also do the same.
> 
> You can work from what I gave you and inside the "eof" part of the
> loop reset the %SECTIONS back to the original (which means you'd
> need to keep a separate copy of the original) and also reset the
> "did I tweak the %SECTIONS thing already?  have I handled the first
> line of the current file?" variable.
> 

Something slightly more declarative I managed to hack up:

diff --git a/Documentation/lint-man-section-order.perl b/Documentation/lint-man-section-order.perl
index 02408a0062..160c65e1be 100755
--- a/Documentation/lint-man-section-order.perl
+++ b/Documentation/lint-man-section-order.perl
@@ -13,6 +13,9 @@
 		},
 		'SYNOPSIS' => {
 			required => 1,
+			optional_in_man_sections => {
+				'7' => 1,
+			},
 			order => $order++,
 		},
 		'DESCRIPTION' => {
@@ -53,10 +56,18 @@ sub report {
 	$exit_code = 1;
 }
 
+my $man_section_number;
 my $last_was_section;
 my @actual_order;
 while (my $line = <>) {
 	chomp $line;
+
+	if ($. == 1) {
+		# assume the first line is formatted like 'gitglossary(7)'
+		$line =~ m/\((\d)\)/;
+		$man_section_number = $1;
+	}
+
 	if ($line =~ $SECTION_RX) {
 		push @actual_order => $line;
 		$last_was_section = 1;
@@ -92,7 +103,9 @@ sub report {
 		@actual_sections{@actual_order} = ();
 
 		for my $section (sort keys %SECTIONS) {
-			next if !$SECTIONS{$section}->{required} or exists $actual_sections{$section};
+			next if !$SECTIONS{$section}->{required} or
+				$SECTIONS{$section}->{optional_in_man_sections}->{$man_section_number} or
+				exists $actual_sections{$section};
 			report("has no required '$section' section!");
 		}