nginx-xml2pod: ensured <link> tags contents are parsed.

In recent nginx 1.15.8 documentation, the following XML document:

    <module name="Module ngx_stream_proxy_module"
            link="/en/docs/stream/ngx_stream_proxy_module.html">

    <para>
    Enables terminating all sessions to a proxied server
    after it was removed from the group or marked as permanently unavailable.
    This can occur because of
    <link doc="ngx_stream_core_module.xml" id="resolver">re-resolve</link>
    or with the API
    <link doc="../http/ngx_http_api_module.xml" id="deleteStreamUpstreamServer"><literal>DELETE</literal></link>
    command.
    </para>

    </module>

Would produce this output:

    Enables terminating all sessions to a proxied server
    after it was removed from the group or marked as permanently unavailable.
    This can occur because of
    L<re-resolve|ngx_stream_core_module>
    or with the API
    L<E<ltE<gt>literalE<gt>DELETEE<ltE<gt>E<sol>literalE<gt>|ngx_http_api_module>
    command.

Thanks to this patch, the output is now:

    Enables terminating all sessions to a proxied server
    after it was removed from the group or marked as permanently unavailable.
    This can occur because of
    L<re-resolve|ngx_stream_core_module>
    or with the API
    L<C<DELETE>|ngx_http_api_module>
    command.

Note that now, links can contain nested markup as well.

---

We also modified the parsing of `\&\w+;` subjects (i.e. `&ldquo;`) to
void a regression in the parsing of `welcome_nginx_facebook.pod`.

The input:

    <link url="http://www.dcwg.org/fix/">
    How to clean up or fix malicious software (&ldquo;malware&rdquo;)
    associated with DNS Changer
    </link>

The (invalid) output without this change would be:

    L<How to clean up or fix malicious software (E<ldquo>malwareE<rdquo>) ... >

Since we removed the `encode_pod()` call on the link's contents.

The correct output is instead:

    L<How to clean up or fix malicious software (E<amp>ldquo;malwareE<amp>rdquo;) ...>

So we forced the `encode_pod()` call when this subject is parsed
_inside_ of a link's contents.

Author: thibaultcha

bin/nginx-xml2pod

@@ -41,6 +41,7 @@ sub process_xml_file {
     my $directive;
     my @lists;
     my $syntax_block;
+    my $link_attrs;
 
     while (1) {
         #warn "scanner: ", pos_str($_);
@@ -98,36 +99,37 @@ sub process_xml_file {
             next;
         }
 
-        if (m{ \G < \s* link ( (?: \s+ \w+ \s* = \s* " [^"]* " )* ) >
-              (.*?)
-                 < \s* / \s* link \s* > }gcxs)
-         {
-            my ($attrs, $label) = ($1, $2);
+        if (m{ \G < \s* link ( (?: \s+ \w+ \s* = \s* " [^"]* " )* ) > }gcxs) {
+            $link_attrs = parse_attrs($1);
 
-            $label = encode_pod(decode_xml($label));
-            $label =~ s/^\s+|\s+$//gs;
+            if (defined $link_attrs->{doc} || defined $link_attrs->{url}) {
+                $pod .= "L<";
+            }
+        }
 
-            $attrs = parse_attrs($attrs);
+        if (m{ \G < \s* / \s* link \s* > }gcxs) {
+            if (!defined $link_attrs) {
+                die "No attributes for link: $&";
+            }
 
-            my $doc = $attrs->{doc};
-            my $url = $attrs->{url};
-            my $id = $attrs->{id};
+            my $doc = $link_attrs->{doc};
+            my $url = $link_attrs->{url};
+            my $id = $link_attrs->{id};
 
             if ($doc) {
                 $doc =~ s{.*/}{};
                 $doc =~ s/\.xml$//;
-                $pod .= "L<$label|$doc>";
+                $pod .= "|$doc>";
 
             } elsif ($url) {
-                $pod .= "L<$label|$url>";
-
-            } elsif ($id) {
-                $pod .= "$label";
+                $pod .= "|$url>";
 
-            } else {
+            } elsif (!defined $id) {
                 die "Bad link: $&";
             }
 
+            undef $link_attrs;
+
             next;
         }
 
@@ -496,9 +498,15 @@ _EOC_
             next;
         }
 
-        if (m{ \G \&(\w+); }gcxs) {
-            my $entity = $1;
-            $pod .= "E<$entity>";
+        if (m{ \G (\&(\w+);) }gcxs) {
+            if (!defined $link_attrs) {
+                my $entity = $2;
+                $pod .= "E<$entity>";
+
+            } else {
+                $pod .= encode_pod(decode_xml($1));
+            }
+
             next;
         }
 
@@ -509,7 +517,13 @@ _EOC_
         }
 
         if (m{ \G ([^<&]+) }gcxs) {
-            $pod .= encode_pod(decode_xml($1));
+            my $txt = $1;
+
+            if ($link_attrs) {
+                $txt =~ s/^\s+|\s+$//gs;
+            }
+
+            $pod .= encode_pod(decode_xml($txt));
             next;
         }