add support for copying head3 sections

Author: book

Porting/merge-deltas.pl

@@ -62,6 +62,49 @@ ( $tree, $directive, $pos = 0 )
           0, $delta->@[ $from .. $to ];
     },
 
+    # copy =head3 sections from known =head2 ones
+    head3 => sub ( $master, $title, $delta ) {
+
+        # find the section in the delta and master
+        my ( $master_pos, $delta_pos ) =
+          map header_pos( $_, 1, $title ),
+          $master, $delta;
+
+        # loop over the =head2 in the section
+        while ( $delta_pos = next_header_pos( $delta, 2, $delta_pos ) ) {
+
+            my $section_title = $delta->[$delta_pos][2];
+            $master_pos =    # find the same =head2 in the master
+              header_pos( $master, 2, $section_title, $master_pos );
+
+            # find the first =head3
+            if ( my $from = next_header_pos( $delta, 3, $delta_pos ) ) {
+
+                # until the next =head2 or =head1
+                my $to = next_header_pos( $delta, 2, $from )
+                  // next_header_pos( $delta, 1, $from );
+
+                # inject at the end of the =head2 section in the master
+                my $end_pos = next_header_pos( $master, 2, $master_pos )
+                  // next_header_pos( $master, 1, $master_pos );
+                splice @$master, $end_pos, 0, $delta->@[ $from .. $to - 1 ];
+            }
+            else {    # copy the whole section over
+
+                # until the next =head2 or =head1
+                my $to = next_header_pos( $delta, 2, $delta_pos )
+                  // next_header_pos( $delta, 1, $delta_pos );
+
+                # inject at the end of the =head2 section in the master
+                my $end_pos = next_header_pos( $master, 2, $master_pos )
+                  // next_header_pos( $master, 1, $master_pos );
+                splice @$master, $end_pos, 0,
+                  $delta->@[ $delta_pos + 1 .. $to - 1 ];
+            }
+        }
+        continue { ++$delta_pos }    # avoid an infinite loop
+    },
+
     # [ List each improvement as an =item entry ]
     item => sub ( $master, $title, $delta ) {
 
@@ -149,7 +192,7 @@ ( $tree, $directive, $pos = 0 )
     'Deprecations'                  => 'deprecations',
     'Performance Enhancements'      => 'item',
     'Modules and Pragmata'          => 'skip',
-    'Documentation'                 => 'skip',
+    'Documentation'                 => 'head3',
     'Diagnostics'                   => 'skip',
     'Utility Changes'               => 'head2',
     'Configuration and Compilation' => 'item',