Converts Javadoc comments in a Java file to pod comments.
After running this filter, copy each pod section into the appropriate spot
in your Perl file. You should need only minor cleanup.
Notes:
Inside a doccomment, the leading spaces, asterisk,
then *one* space-or-tab are stripped. So to achieve pre-formatted text,
make sure there are at least *two* spaces or tabs after the comment asterisk.
After reformatting and adding some blank lines, the entire text is
scanned again to cleanup blank lines. Only a single blank line will be
retained between paragraphs, except before a '=head1' tag, where two blank
lines will be used.
Tables will be converted to tab-delimited columns; unfortunately, that
means columns wll generally *not* line up when just viewed as text with no
formatting.
By convention, a head1 tag is generated with
<B>some text here</B><BR><BR>
and a head2 tag is generated with
<B>some text here</B><BR>
Tables in HTML, could of course be used for pages generated
with pod2html. But the corresponding perldoc page
needs non-HTML code. So this translator converts the HTML table into text,
surrounds it with a =begin text...=end block, and creates
a marker block for HTML where you can copy the HTML table back in.
Watch out for nested inline tags (e.g. C<func(I<paramName>)> ).
Neither perldoc nor pod2html will handle these properly.
Bug: "this" surrounded by CODE tags come out as just "C" !
Convert javadoc text to pod text.
A series of regular expression substitutions is performed on the input
to do the conversion. This involves simply feeding a list of
regular expressions to an REConverter object.
The only special handling required is for tables.
We actually want two copies of each table in the output,
one in a =begin text ... =end bracket and
one in a =begin html ... =end bracket.
This is achieved by copying all tables, doing the javadoc to pod
conversion (which creates the text version of the tables),
restoring the html tables where we've left markers,
and doing any final conversions of the entire text.
com.cleancode.format.SimpleJavadocToPod
