Nicer rendering for see-also in index

[exim-website.git] / script / gen

diff --git a/script/gen b/script/gen
index 559619989388664e9a587890bd9a369d41a245a9..dc2926adeb7d9407f00a07367cfbdf53b6570641 100755 (executable)
--- a/script/gen
+++ b/script/gen
@@ -131,11 +131,21 @@ sub do_doc {
     my ( $type, $xml_path ) = @_;
 
     ## Read and validate the XML file
-    my $xml = XML::LibXML->new()->parse_file($xml_path) or die $!;
+    my $xml = XML::LibXML->new(expand_entities => 1)->parse_file($xml_path) or die $!;
 
     ## Get the version number
-    my $version = $xml->findvalue('/book/bookinfo/revhistory/revision/revnumber');
-    die "Unable to get version number\n" unless defined $version && $version =~ /^\d+(\.\d+)*$/;
+    my $version = do {
+       my $version = $xml->findvalue('/book/bookinfo/revhistory/revision/revnumber');
+       die "Unable to get version number\n"
+           unless defined $version and $version =~ /^
+               (?<version>
+                   \d+                     # major
+                   (?:\.\d+(?:\.\d+)?)?    # (minor(.patch))
+                   (?:\.\d+(?:\.\d+(?:\.\d+)?)?)?    # (minor(.patch.(fixes)))
+               )
+               (?:-RC\d+)?$/x;             # -RCX
+       $+{version};
+    };
 
     ## Prepend chapter filenames?
     my $prepend_chapter = $type eq 'filter' ? 'filter_' : '';
@@ -318,6 +328,7 @@ sub build_indexes {
     my ( $xml, $prepend_chapter, $xref ) = @_;
 
     my $index_hash = {};
+    my $seealso_hash = {};
     my $current_id;
     foreach my $node ( $xml->findnodes('//section | //chapter | //indexterm') ) {
         if ( $node->nodeName eq 'indexterm' ) {
@@ -325,9 +336,27 @@ sub build_indexes {
             my $primary   = $node->findvalue('child::primary');
             my $first     = ( $primary =~ /^[A-Za-z]/ ) ? uc( substr( $primary, 0, 1 ) ) : '';  # first letter or marker
             my $secondary = $node->findvalue('child::secondary') || '';
+           my $see       = $node->findvalue('child::see');
+           my $see_also  = $node->findvalue('child::seealso');
+
             next unless ( $primary || $secondary );    # skip blank entries for now...
+
             $index_hash->{$role}{$first}{$primary}{$secondary} ||= [];
-            push @{ $index_hash->{$role}{$first}{$primary}{$secondary} }, $current_id;
+           if ( $see || $see_also ) {
+             # The scalar value being written here assumes only one seealso on an indeed term
+             # It would be nice to have the $see displayed in bold rather than in quotes
+             $seealso_hash->{$role}{$first}{$primary}{$secondary} = 'see "' . $see .'"' if ($see);
+             $seealso_hash->{$role}{$first}{$primary}{$secondary} = 'see also "' . $see_also .'"' if ($see_also);
+           }
+
+           else {
+# JGH 2022/07/01
+# The $current_id being pushed here is presumably the section, given where the
+# hyperlink end up pointing to.  For bug 2889 we'd like to have something more
+# precise; tha presumably requires an anchor at the indexed point?
+
+               push @{ $index_hash->{$role}{$first}{$primary}{$secondary} }, $current_id;
+           }
         }
         else {
             $current_id = $node->getAttribute('id');
@@ -373,6 +402,10 @@ sub build_indexes {
                         $slist->appendChild($sentry)->appendTextChild( 'term', $secondary );
                         $sentry->appendChild($sitem)->appendChild($para);
                     }
+
+                   my $seealso = $seealso_hash->{$role}{$first}{$primary}{$secondary};
+                   $para->appendText($seealso) if ($seealso);
+
                     my $count = 0;
                     foreach my $ref ( @{ $index_hash->{$role}{$first}{$primary}{$secondary} } ) {
                         $para->appendText(', ')
@@ -409,7 +442,7 @@ sub transform {
     $xml->documentElement()->appendTextChild( 'old_versions', $_ ) foreach old_docs_versions();
 
     ## Parse the ".xsl" file as XML
-    my $xsl = XML::LibXML->new()->parse_file($xsl_path) or die $!;
+    my $xsl = XML::LibXML->new(expand_entities => 1)->parse_file($xsl_path) or die $!;
 
     ## Generate a stylesheet from the ".xsl" XML.
     my $stylesheet = XML::LibXSLT->new()->parse_stylesheet($xsl);
@@ -507,11 +540,11 @@ __END__
 
 =head1 NAME
 
-gen.pl - Generate exim html documentation and website
+gen - Generate exim html documentation and website
 
 =head1 SYNOPSIS
 
-gen.pl [options]
+gen [options]
 
  Options:
    --help              display this help and exits
@@ -591,7 +624,7 @@ Generates the exim website and HTML documentation.
 
 =head1 EXAMPLE
 
-    script/gen.pl \
+    script/gen \
       --web \
       --spec docbook/*/spec.xml \
       --filter  docbook/*/filter.xml \