[t2t] How to write Perl documentation in format txt2tags (instead of Pod)

[rch]

I'd like to use txt2tags to document my Perl scripts.

I couldnt find anything relevant using Google, so I asked a
correspondent, off list -

Q. «How to write Perl documentation in txt2tags format?»
A. «Try podselect»

So I just made testfile.pl with documentation enclosed between «=pod»
and «=cut», as usual,
but written in format t2t, instead of format pod.

Then a tiny script ran
(1) podselect, to extract the t2t lines, and
(2) txt2tags, to transform the t2t to html.

Result at STDOUT:-
«txt2tags wrote testfile.html
«THAT TOOK 0.200652 SECONDS

Magic!

Many thanks to my correspondent. Posted here in the hopes that others
may benefit.


------------------------------------------------------------------------------

[Florent Gallaire]

Thanks for your feedback !
Have satisfied users is a real motivation for the txt2tags team.

Regards

Florent

Post by rch
I'd like to use txt2tags to document my Perl scripts.
I couldnt find anything relevant using Google, so I asked a
correspondent, off list -
Q. «How to write Perl documentation in txt2tags format?»
A. «Try podselect»
So I just made testfile.pl with documentation enclosed between «=pod»
and «=cut», as usual,
but written in format t2t, instead of format pod.
Then a tiny script ran
(1) podselect, to extract the t2t lines, and
(2) txt2tags, to transform the t2t to html.
Result at STDOUT:-
«txt2tags wrote testfile.html
«THAT TOOK 0.200652 SECONDS
Magic!
Many thanks to my correspondent. Posted here in the hopes that others
may benefit.
------------------------------------------------------------------------------
_______________________________________________
txt2tags-list mailing list
https://lists.sourceforge.net/lists/listinfo/txt2tags-list

[rch]

Post by Florent Gallaire
Have satisfied users is a real motivation for the txt2tags team.

I think a lot of other Perl users would also be very happy
to use txt2tags instead of pod.

Then instead of having to write e.g.:
=over
=item I<this>
=item B<that>
=item U<the other>
=item etc
=back

they can just write:
- //this//
- **that**
- __the other__
- etc


So heres a challenge for someone who knows more about Perl than I do:
+ Rewrite my quick and dirty pod-as-txt2tags script (below)
as a Perl module.
+ Then put that module on CPAN.
+ Then blog/tweet/rave about it.

rch
----------------------------------------------------------------------
#!/usr/bin/perl
# This script reads a Perl file
# which has been documented (=pod … =cut) using txt2tags markup
# and writes out the documentation format html
# It assumes that executables «podselect» and «txt2tags»
# are already installed

use strict;
use Carp;
use Cwd (qw(abs_path));

# Please fill in values for the following
my $pfil = '';# name of the Perl script with t2t documentation
my $wrkgdir = '';# path to that Perl script
my $heading = '';# title of the html outfile
my $subheading = '';# second line of the html outfile
my $my_css_file= '';# path and name of the css file

# Dont touch anything below here
my $plfile = $wrkgdir . $pfil;
unless( -d $wrkgdir){croak "Cannot find \$wrkgdir $wrkgdir\n\tCroaked";}
unless( -f $plfile ){croak "Cannot find \$plfile $plfile\n\tCroaked";}

my $header = "$heading\n$subheading\n";

(my $t2tfile = $plfile ) =~ s/\.pl/.t2t/;
(my $tempfile = $plfile ) =~ s/\.pl/.temp/;
(my $htmlfile = $plfile ) =~ s/\.pl/.html/;

# Precautionary principle ...
croak if( ( $t2tfile eq $plfile ) );
croak if( ( $tempfile eq $plfile )or( $tempfile eq $t2tfile ) );
croak if( ( $htmlfile eq $plfile )or( $htmlfile eq $tempfile )or(
$htmlfile eq $t2tfile ) );

# Run podselect on the .pl file
my $command1 = "podselect $plfile > $tempfile";
system $command1;
croak unless( -f $tempfile );

# Prepare to read temp file and write t2t file
open TEMPFILE, "<", $tempfile or croak;
open T2TFILE, ">", $t2tfile or croak;

# Write header into the t2t file
print T2TFILE $header;
print T2TFILE <<"EOF";
\%\%mtime(\%Y-\%m-\%d \%H:\%M:\%S)

\%!target : html
\%!encoding : UTF-8
\%!options : --css-sugar --css-inside
\%!style(html) : $my_css_file

EOF

# Write the temp file into the t2t file
while(<TEMPFILE>){
print T2TFILE unless( ( /^=pod/ )or( /^=begin txt2tags/ )or( /^=end
txt2tags/ )or( /^=cut/ ));
}
close TEMPFILE or croak;

# Close the t2t file with a coda
printf T2TFILE "\n\n\n===CODA===\n\n\n- This file was made from [%s
%s]\n- By [%s %s]\n\n\n",
$pfil,$plfile,$0, abs_path($0),;
close T2TFILE or croak;

# Run txt2tags on the t2t file
my $command2 = "txt2tags --target html $t2tfile";
print STDOUT "\n\n";
system $command2;
print STDOUT "\n\n";

# Remove the file *.temp and the file *.t2t
foreach my $file ( $t2tfile, $tempfile ) {
unlink $file or warn "Could not unlink $file: $!\n";
}

# All done! Say goodbye
if(-f $htmlfile){print STDOUT "DONE THAT!\n\n";}
else{print STDOUT "\n\n\tOHHH! NO SIGN OF $htmlfile\n\n";}

__END__

=pod

==NAME==

t.b.c.

==SYNOPSIS==

t.b.c.

==DESCRIPTION==

t.b.c.

==EXAMPLES==

t.b.c.

==REQUIREMENTS==

+ Requires //podselect//; standard part of Perl installation, usually
found (Linux) at /usr/bin/podselect. See [CPAN
http://search.cpan.org/~jhi/perl-5.8.1/pod/podselect.PL]
+ And //txt2tags//. See [download page http://txt2tags.org/download.html]

==CAVEATS==

t.b.c.

==NOTES==

t.b.c.

==AUTHOR==

t.b.c.

==COPYRIGHT AND LICENSE==

This program is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.

=cut




------------------------------------------------------------------------------