perl documentation to texinfo

[Patrice Dumas]

Hello,

Here is a report on the translation to texinfo of perl pod files.  I have
only investigated the warning and error messages obtained when converting
the manuals as standalone manuals to info.  There may also be some bugs
somewhere in Pod::Simple::Texinfo that do not lead to warning/errors
when converting to Info.

The first issue is sort of solved.  I still describe it anyway.
In Pod, refs may be done to any =head* and =item (equivalent with @table
@item).  So I added an anchor for each =item (and =head*).  The problem
is that it is acceptable to have a ref there in Pod (or at least nothing
prevents it and it is used a lot in the perl documentation).

So something like

  =item L<perlhaiku>

should have become

  @item @ref{Top,,, perlhaiku}
  @address@hidden,,, perlhaiku}}

which is incorrect Texinfo.  I have handled that by 'fixing' the anchor,
but then some anchors may not be what they should.  The result is now, for
tht case:

  @item @ref{Top,,, perlhaiku}



There are 4 remaining issues.  first correspond to

  Upping the section level of @subsection which is too low

Indeed, it does not seems to be an error to have that kind of construct in Pod,
like

  =head1 top level

  =head3 gap in sectioning

I don't know exactly what to do on that one.  Maybe detect it when converting
to texinfo and upping the section at that time?  Maybe providing a more
general texinfo tree manipulation function that fills the gaps in
sectioning levels?


The next 2 issues should certainly be handled by the node protection stuff
we have been talking a bit about (although we did not talk about
those possibilities):

  warning: @strong{Note...} produces a spurious cross-reference in Info; reword 
to avoid that

And
  Syntax for an external node used for `(Win32)The -C Switch Has Been 
Repurposed'

For example from
  =head2 (Win32) The -C Switch Has Been Repurposed



And last there are commas, and other punctuation characters that do not
fit in node names/menus/anchors, protection should help there.

-- 
Pat