Re: .devhelp generator for --html mode in makeinfo

[Patrice Dumas]

On Tue, Mar 17, 2015 at 12:27:36PM +0000, Gavin Smith wrote:
> On 16 March 2015 at 22:09, Dimitri John Ledkov <address@hidden> wrote:
> > I've assembled things from devhelp git tree & debian python docs
> > packaging into one place here with comments:
> >
> > https://people.debian.org/~xnox/devhelp/
> >
> > It has the twenty line dtd description of the xml .devhelp format,
> > sample output for python3.4 docs in python3.4.devhelp, script which
> > processes python's html docs to generate .devhelp, and the broken
> > texi2html based script to process html into .devhelp.
> >
> > This should be all that's needed to understand the format - it really
> > is a flat TOC & flat Index with links to html pages / anchors.
> >
> 
> Here's what I've been able to do so far. It needs more work and
> polish, of course, but it should point in the right direction.

>From a very rapid look, it looks good.  Maybe it could be in a separate
file in tp/init/devhelp.pm, those files are "customization" files that are
supposed to be maintained.  The chm.pm file does broadly similar output
files, in fact (in chm_init).  Maybe the phase to use in handler
registration shoud be different, maybe init is to soon, maybe it should
be 'finish' in order to have index entry labels already formatted.

> Index: HTML.pm
> ===================================================================
> --- HTML.pm   (revision 6156)
> +++ HTML.pm   (working copy)
> @@ -7125,8 +7125,82 @@
>        }
>      }
>    }
> +
> +  # TODO: Get this from the command-line
> +  my $output_devhelp = 1;
> +  if ($output_devhelp) {
> +    # TODO: What is the name/location of the devhelp file?
> +    # For split v. non-split output
> +    output_devhelp_file ($self, $self->{'output_file'} . '.devhelp', $root);
> +  }
>  }
>  
> +# Output a .devhelp file usable by GNOME Devhelp.  $FILENAME is the name
> +# the file to write to and $ROOT the root of the parse tree.
> +sub output_devhelp_file ($$$)
> +{
> +  my $self = shift;
> +  my $filename = shift;
> +  my $root = shift;
> +
> +  print "WRITING DEVHELP $filename\n";
> +  my $fh = $self->Texinfo::Common::open_out($filename);
> +  if (!$fh) {
> +    $self->document_error(sprintf($self->__(
> +                           "could not open %s for writing: %s"),
> +                           $filename, $!));
> +    return;
> +  }
> +
> +  # Contents of .devhelp file.
> +  my $a = '';
> +
> +  # TODO: encoding attribute?
> +  $a .= '<?xml version="1.0"?>' . "\n";
> +
> +  $a .= '<book>' . "\n";
> +
> +  $a .= '<chapters>' . "\n";
> +  foreach my $element (@{$root->{'contents'}}) {
> +    if ($element->{'cmdname'} and $element->{'cmdname'} eq 'chapter') {
> +      my $href = $self->command_href($element);
> +      my $chapter_name = $self->command_text($element);
> +      if ($href and $chapter_name) {
> +        $a .= "  <sub link=\"$href\" name=\"$chapter_name\">\n  </sub>\n";
> +      }
> +    }
> +  }
> +  $a .= '</chapters>' . "\n";
> +
> +  my ($index_names, $merged_indices)
> +     = $self->{'parser'}->indices_information();
> +  if ($index_names and $index_names->{'fn'}) {
> +
> +    $a .= '<functions>' . "\n";
> +
> +    foreach my $entry (@{$index_names->{'fn'}->{'index_entries'}}) {
> +      my $command = $entry->{'command'};
> +      my $href = $self->command_href($command);
> +      my $label = $self->command_text($command);
> +      $a .= "<function link=\"$href\" name=\"$label\"/>\n";
> +    }
> +
> +    $a .= '</functions>' . "\n";
> +
> +  }
> +
> +  $a .= '</book>' . "\n";
> +
> +  print $fh $a;
> +  $self->register_close_file($filename);
> +  if (!close ($fh)) {
> +    $self->document_error(sprintf($self->__(
> +                  "error on closing file %s: %s"),
> +                         $filename, $!));
> +    return undef;
> +  }
> +}
> +
>  sub _parse_node_and_warn_external($$$$$)
>  {
>    my $self = shift;