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

[Dimitri John Ledkov]

Now, attempting to load this in devhelp.

Some notes:

Imagine software foo, that is documented with foo.texi, when
generating a folder "foo/" with html documentation it should contain
e.g. "foo/foo.devhelp" & "foo/index.html" files.

Inside the foo.devhelp, the book element should declare the book
title, name, version and link to index.html attributes.

e.g. <book title="Autoconf" name="Autoconf" version="1.69" link="index.html">

On 18 March 2015 at 07:38, Patrice Dumas <address@hidden> wrote:
> 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:
>> 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);

So at the moment this ends up generating (split):
./foo.html.devhelp
./foo/index.html

Instead it should be (split)
./foo/foo.devhelp
./foo/index.html

Split / non-split output doesn't matter as long as link="" attributes
point to correctly named files/things.

For non-split the right output is:
./foo.devhelp
./foo.html

Finally to "integrate" into devhelp a symlink will be needed.

E.g. if $foo html documentation is installed in
/usr/share/doc/foo/html/index.html

A symlink /usr/share/devhelp/books/foo -> /usr/share/doc/foo/html will
make devhelp search for /usr/share/devhelp/books/foo/foo.devhelp (note
the directory name under books should match the .devhelp file name)
and things will work.

I believe this means non-split outputs will work as well -> e.g:
/usr/share/devhelp/books/foo -> /usr/share/doc/html/
/usr/share/devhelp/books/bar -> /usr/share/doc/html/

Will load up: /usr/share/doc/html/foo.devhelp|.html
/usr/share/doc/html/bar.devhelp|.html just fine.


>> +  }
>>  }
>>
>> +# 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";

This element is not valid.
name
title
version
link

are mandatory attributes.

>> +
>> +  $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";

This works correctly, and e.g. search within devhelp works correctly.
However when operating against e.g. autoconf/automake with access to
misc_content contained in an else clause all of the name="" attributes
remained empty =( thus no search. I send separate email about it.

>> +    }
>> +
>> +    $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;
>
>
>

Otherwise this looks very promising and very nice =) If you have time
to improve this as per above comment, I'll be very grateful. Otherwise
I will try to dig into perfecting this support further.

Also it looks like there is ".devhelp2" format as well. I'm not sure
if that's new or old/legacy suffix with devhelp upstream. Also devhelp
loads things from /usr/share/gtk-doc/html path, I'll check if that
path is preferred over the /usr/share/devhelp/books/ or not for the
non-gtk-doc based books.

-- 
Regards,

Dimitri.