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

[Junio C Hamano <gitster@pobox.com>]

"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Julia Evans <julia@jvns.ca>
>
> Remove the SYNOPSIS section from the section 7 man pages where
> appropriate, to avoid having a section that contains no information.
> It's not the norm in section 7 to always require a SYNOPSIS.

Very true.

> diff --git a/Documentation/gitcli.adoc b/Documentation/gitcli.adoc
> index 6815d6bfb7..9c4598e29c 100644
> --- a/Documentation/gitcli.adoc
> +++ b/Documentation/gitcli.adoc
> @@ -5,11 +5,6 @@ NAME
>  ----
>  gitcli - Git command-line interface and conventions
>  
> -SYNOPSIS
> ---------
> -gitcli
> -
> -
>  DESCRIPTION
>  -----------
>  

Yup.  Thanks for starting this move.  These "we add meaningless
filler only because we need to" were always eyesore.

> diff --git a/Documentation/lint-man-section-order.perl b/Documentation/lint-man-section-order.perl
> index 02408a0062..e032f6ae53 100755
> --- a/Documentation/lint-man-section-order.perl
> +++ b/Documentation/lint-man-section-order.perl
> @@ -53,6 +53,11 @@ sub report {
>  	$exit_code = 1;
>  }
>  
> +# assume the first line is formatted like 'gitglossary(7)'
> +my $firstline = <>;
> +$firstline =~ m/\((\d)\)/;
> +my $man_section_number = $1;

This means that the main loop that has already read all the lines of
the file no longer sees the first line.  I do not think it would
immediately break anything (in other words, the current
implementation of the loop only checks the section header and
nothing else), but it may be an unhealthy thing to assume that this
will not change.

It would be very simple to move it inside the loop.

Would it work better to do it this way, I wonder?  The idea is to
notice what manual sections we are in, and tweak the %SECTIONS
contents there, to allow us customize behaviour for other sections
later, and keep such customizations out of the actual code.


 Documentation/lint-man-section-order.perl | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git c/Documentation/lint-man-section-order.perl w/Documentation/lint-man-section-order.perl
index 02408a0062..ce60c34809 100755
--- c/Documentation/lint-man-section-order.perl
+++ w/Documentation/lint-man-section-order.perl
@@ -55,8 +55,23 @@ sub report {
 
 my $last_was_section;
 my @actual_order;
+my $section_tweak_done;
 while (my $line = <>) {
 	chomp $line;
+
+	if (!$section_tweak_done) {
+		# assume the first line is formatted like 'gitglossary(7)'
+		my $firstline = <>;
+		$firstline =~ m/\((\d)\)/;
+		my $man_section_number = $1;
+
+		if ($man_section_number == "7") {
+			# section 7 usually do not have SYNOPSIS
+			$SECTIONS{SYNOPSIS}{required} = 0;
+		}
+		$section_tweak_done = 1;
+	}
+
 	if ($line =~ $SECTION_RX) {
 		push @actual_order => $line;
 		$last_was_section = 1;