Here are some patches which
1) Modify Pod::PseudoPod::LaTeX to (when requested) emit LaTeX code which
requires that certain environments be defined (rather than enforcing style in
Pod::PseudoPod::LaTeX itself). In particular, the "sidebar" environment. Tests
included.
2) Add a "sidebar" environment to bin/book-to-latex and request that
Pod::PseudoPod::LaTeX emits sidebars in this environment.
I think this reasonably makes the output of Pod::PseudoPod::LaTeX customizable
without unnecessarily requiring a lot of work on the user.
As for styling of the sidebar, here are some suggested alternate definitions
for the sidebar environment. Once the attached patches are in place, making
these changes is just a matter of replacing the sidebar definition in
bin/book-to-latex.
% Honest sidebar (marginpar)
%%% probably too narrow given the rather verbose "sidebars" which currently
exist
\newsavebox{\sidebarcontent}
\newenvironment{sidebar}[1][]{\begin{lrbox}{\sidebarcontent}\begin{minipage}{1in}\sloppy\small
\ifx\relax#1\else\centerline{\normalsize\bfseries #1}\par\fi}
{\end{minipage}\end{lrbox}\marginpar{\shadowbox{\usebox{\sidebarcontent}}}}
% shadowbox
%%% my favorite
\newsavebox{\sidebarcontent}
\newenvironment{sidebar}[1][]{\begin{lrbox}{\sidebarcontent}\begin{minipage}{3.5in}\sloppy
\ifx\relax#1\else\centerline{\large\bfseries #1}\par\fi}
{\end{minipage}\end{lrbox}\begin{center}\shadowbox{\usebox{\sidebarcontent}}\end{center}}
% doublebox
%%% just another of the boxes available in fancybox
\newsavebox{\sidebarcontent}
\newenvironment{sidebar}[1][]{\begin{lrbox}{\sidebarcontent}\begin{minipage}{3.5in}\sloppy
\ifx\relax#1\else\centerline{\large\bfseries #1}\par\fi}
{\end{minipage}\end{lrbox}\begin{center}\doublebox{\usebox{\sidebarcontent}}\end{center}}
% Floating figures (sidebar but not in margins)
%%% Probably _not_ recommended since floatingfigures are rather fragile
\usepackage[rflt]{floatflt}
\newenvironment{sidebar}[1][]{\begin{floatingfigure}{2.5in}
\ifx\relax#1\else\centerline{\large\bfseries #1}\par\fi}
{\end{floatingfigure}}
Good Day,
Dean Serenevy
diff --git a/lib/Pod/PseudoPod/LaTeX.pm b/lib/Pod/PseudoPod/LaTeX.pm
index d7a4819..d5bb519 100644
--- a/lib/Pod/PseudoPod/LaTeX.pm
+++ b/lib/Pod/PseudoPod/LaTeX.pm
@@ -24,6 +24,15 @@ sub new
return $self;
}
+sub emit_environments
+{
+ my ( $self, %env ) = @_;
+ for ( keys %env )
+ {
+ $self->{emit_environment}->{$_} = $env{$_};
+ }
+}
+
sub end_Document
{
my $self = shift;
@@ -505,30 +514,48 @@ sub start_item_text
sub start_sidebar
{
my ( $self, $flags ) = @_;
- $self->{scratch} .= "\\begin{figure}[!h]\n"
- . "\\begin{center}\n"
- . "\\framebox{\n"
- . "\\begin{minipage}{3.5in}\n"
- . "\\vspace{3pt}\n\n";
+ my $title;
+ $title = $self->encode_text( $flags->{title} ) if $flags->{title};
- if ( $flags->{title} )
+ if ( $self->{emit_environment}->{sidebar} )
{
- my $title = $self->encode_text( $flags->{title} );
- $self->{scratch} .= "\\begin{center}\n"
- . "\\large{\\bfseries{" . $title . "}}\n"
- . "\\end{center}\n\n";
+ $self->{scratch} .= "\\begin{" . $self->{emit_environment}->{sidebar} . "}";
+ $self->{scratch} .= "[$title]" if $title;
+ $self->{scratch} .= "\n";
+ }
+ else
+ {
+ $self->{scratch} .= "\\begin{figure}[!h]\n"
+ . "\\begin{center}\n"
+ . "\\framebox{\n"
+ . "\\begin{minipage}{3.5in}\n"
+ . "\\vspace{3pt}\n\n";
+
+ if ( $title )
+ {
+ $self->{scratch} .= "\\begin{center}\n"
+ . "\\large{\\bfseries{" . $title . "}}\n"
+ . "\\end{center}\n\n";
+ }
}
}
sub end_sidebar
{
my $self = shift;
- $self->{scratch} .= "\\vspace{3pt}\n"
- . "\\end{minipage}\n"
- # end framebox
- . "}\n"
- . "\\end{center}\n"
- . "\\end{figure}\n";
+ if ( $self->{emit_environment}->{sidebar} )
+ {
+ $self->{scratch} .= "\\end{" . $self->{emit_environment}->{sidebar} . "}\n\n";
+ }
+ else
+ {
+ $self->{scratch} .= "\\vspace{3pt}\n"
+ . "\\end{minipage}\n"
+ # end framebox
+ . "}\n"
+ . "\\end{center}\n"
+ . "\\end{figure}\n";
+ }
}
BEGIN
@@ -593,13 +620,12 @@ Perhaps a little code snippet.
use Pod::PseudoPod::LaTeX;
my $parser = Pod::PseudoPod::LaTeX->new();
+ $parser->emit_environments( sidebar => 'sidebar' );
$parser->output_fh( $some_fh );
$parser->parse_file( 'some_document.pod' );
...
-There aren't really any user-servicable parts inside.
-
=head1 LATEX PRELUDE
The generated LaTeX code needs some packages to be loaded to work correctly.
@@ -614,6 +640,14 @@ variants of its monospace font, an alternative is
\usepackage{textcomp}
\usepackage[scaled]{beramono}
+=head1 STYLES / EMITTING ENVIRONMENTS
+
+The C<emit_environments> method accepts a hashref whose keys are POD environments
+and values are latex environments. Use this method if you would like
+C<Pod::PseudoPod::LaTeX> to emit a simple C<\begin{foo}...\end{foo}> environment
+rather than emit specific formatting codes. You must define any environemtns you
+use in this way in your latex prelude.
+
=head1 AUTHOR
chromatic, C<< <chromatic at wgz.org> >>
diff --git a/t/emit_environments.t b/t/emit_environments.t
new file mode 100644
index 0000000..9412d08
--- /dev/null
+++ b/t/emit_environments.t
@@ -0,0 +1,37 @@
+#! perl
+
+use strict;
+use warnings;
+
+use IO::String;
+use File::Spec::Functions;
+
+use Test::More tests => 4;
+
+use_ok( 'Pod::PseudoPod::LaTeX' ) or exit;
+
+my $fh = IO::String->new();
+my $parser = Pod::PseudoPod::LaTeX->new();
+$parser->output_fh( $fh );
+$parser->parse_file( catfile( qw( t test_file.pod ) ) );
+
+$fh->setpos(0);
+my $text = join( '', <$fh> );
+
+like( $text, qr/\\vspace{3pt}\s*Hello, this is a sidebar/,
+ 'Emit formatting code when emit_environment option not set' );
+
+unlike( $text, qr/\\(?:begin|end){A?sidebar}/,
+ 'No sidebar environemnt whatsoever when emit_environment option not set' );
+
+$fh = IO::String->new();
+$parser = Pod::PseudoPod::LaTeX->new();
+$parser->emit_environments( sidebar => 'Asidebar' );
+$parser->output_fh( $fh );
+$parser->parse_file( catfile( qw( t test_file.pod ) ) );
+
+$fh->setpos(0);
+$text = join( '', <$fh> );
+
+like( $text, qr/\\begin{Asidebar}\s*Hello, this is a sidebar\s*\\end{Asidebar}/,
+ 'Emit abstract \begin{foo} when emit_environment option is set' );
diff --git a/t/test_file.pod b/t/test_file.pod
index 6935ef7..a1f6a51 100644
--- a/t/test_file.pod
+++ b/t/test_file.pod
@@ -47,6 +47,12 @@ Diacritics are more difficult E<aacute> la the naE<iuml>ve attachE<egrave> and
the E<copy> caper, E<plusmn> some constant. FranE<ccedilla>aise has some fun
ones.
+=for sidebar
+
+Hello, this is a sidebar
+
+=end
+
X<Special formatting> is B<very> important, especially in C<code-like text>,
for special F<emphasis>, and I<semantic-only emphasis>N<but beware of
footnotes!>.
diff --git a/bin/book-to-latex b/bin/book-to-latex
index a909a46..b13d83c 100644
--- a/bin/book-to-latex
+++ b/bin/book-to-latex
@@ -12,6 +12,13 @@ print <<'HEADER';
\usepackage[utf8]{inputenc}
\usepackage{makeidx}
\usepackage[colorlinks=true,pagebackref]{hyperref}
+\usepackage{fancybox}
+
+% shadowbox
+\newsavebox{\sidebarcontent}
+\newenvironment{sidebar}[1][]{\begin{lrbox}{\sidebarcontent}\begin{minipage}{3.5in}\sloppy
+\ifx\relax#1\else\centerline{\large\bfseries #1}\par\fi}
+{\end{minipage}\end{lrbox}\begin{center}\shadowbox{\usebox{\sidebarcontent}}\end{center}}
\makeindex
@@ -27,6 +34,7 @@ HEADER
for (@ARGV) {
my $parser = Pod::PseudoPod::LaTeX->new();
+ $parser->emit_environments( sidebar => "sidebar" );
$parser->codes_in_verbatim(1);
$parser->output_fh( *STDOUT );
$parser->parse_file( $_ );
