comment on

One of the interesting problems that real typesetting brings to documentation is the representation of source code. Mostly this is because we want a book to look like a “book” and source code to look like “source code”! Even in the world of HTML we insist on these things. This paragraph should look like it does, but the source to this paragraph should look like:

<body>
One of the interesting problems that real typesetting brings to 
documentation is the representation of source code. Mostly this 
is because we want a book to look like a &ldquo;book&rdquo; and 
source code to look like &ldquo;source code&rdquo;! Even in the 
world of HTML we insist on these things. This paragraph should 
look like it does, but the source to this paragraph should 
look like:
</body>
[download]

And that is without any useful decoration (line numbers, line wrapping and the like)! If, for instance, we wanted it to look more like this:

₁ <body>

₂ One of the interesting problems that real typesetting brings to

₃ documentation is the representation of source code. Mostly this

₄ is because we want a book to look like a “book” and

₅ source code to look like “source code”! Even in the

then we have to do a great deal more work. Perl to the rescue! Beyond the <READMORE> tag is the source to a script that does the trick in LaTeX, my current hammer of choice when doing all things documented. By running your text through this filter you wind up with a verbatim version with line numbers (every fifth in red) and the left margin indicated by a vertical rule. Line wraps are indicated by a fancy symbol (also in red) and an un-numbered line. As my tech support says “Works for me---enjoy!”.

#!/perl/bin/perl
#
# trim.pl -- trim input file to wrap at the column specified...
use strict;
use warnings;
use diagnostics;

my @text;
my $length = ( $ARGV[1] or 59 );
my $lineno = 1;
my @delimiters =
  ( '~', '!', '@', '#', '$', '%', '^', '&', '*', '_', '+', '-', '=', '
+`' );

foreach (<>) {
    chomp;
    s/\t/  /g;
    if ( length($_) > $length ) {
        push ( @text, cleanline( substr( $_, 0, $length ) ) );
        $_ = substr( $_, $length );
        while ( length($_) > $length ) {
            push ( @text, wrapline( substr( $_, 0, $length ) ) );
            $_ = substr( $_, $length );
            $_ = '' unless (/[^_]+/);
        }
        push ( @text, wrapline($_) ) if (/[^_]+/);
    }
    else {
        push ( @text, cleanline($_) );
    }
}
print
  "\\vskip .125in {\\offinterlineskip\\setlength{\\parindent}{0pt}\\sm
+all\n";
print join ( '', @text );
print "}\\vskip .125in\n";

sub clean {
    my $s = shift;
    my $d = '|';

    if ( $s =~ /\|/ ) {
        my %list;
        @list{ split ( '', $s ) } = ();

        foreach (@delimiters) {
            unless ( exists( $list{$_} ) ) {
                $d = $_;
                last;
            }
        }
    }
    return "\\verb$d$s$d";
}

sub wrapline {
    return "\\vr{}", clean(shift), "\\par\\wrapmark\n";
}

sub cleanline {
    if ( $lineno % 5 ) {
        return "\\vr{", $lineno++, "}", clean(shift), "\\par\n";
    }
    else {
        return "\\vr{\\textcolor{red}{", $lineno++, "}}", clean(shift)
+, "\\par\n";
    }
}
[download]

The only thing close to clever here is the clean sub that essentially determines what to use as a delimiter for the quoting mechanism. The default is the vertical bar, '|' but of course the very nature of verbatim quoting is that any character may occur. The good news is that the \verb macro in LaTeX will use any character you hand it to indicate start and stop. The clean sub reads the line proposed and modifys the delimiter accordingly.

The code you need in your LaTeX document looks like this:

\documentclass{article}%
\usepackage{marvosym}
\usepackage{color}
\reversemarginpar %
\newcommand{\wrapmark}{%
  \marginpar[\hfill\textcolor{red}{\Lefttorque}]{\textcolor{red}{\Left
+torque}}%
}
\newcommand{\vr}[1]{%
  \makebox[2em][r]{%
    \tiny#1\hskip .5em%
  }%
  \vrule height 10pt\hskip .5em%
}%
\begin{document}%
\input{your_document_here}
\end{document}%
[download]

--hsm

"Never try to teach a pig to sing...it wastes your time and it annoys the pig."

In reply to Perl, LaTeX and verbatim text by hsmyers

Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!

Titles consisting of a single word are discouraged, and in most cases are disallowed outright.

Read Where should I post X? if you're not absolutely sure you're posting in the right place.

Please read these before you post! —

Posts may use any of the Perl Monks Approved HTML tags:

a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr

You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)

	For:		Use:
	&		`&`
	<		`<`
	>		`>`
	[		`[`
	]		`]`

Link using PerlMonks shortcuts! What shortcuts can I use for linking?

See Writeup Formatting Tips and other pages linked from there for more info.

₁	`<body>`
₂	`One of the interesting problems that real typesetting brings to`
₃	`documentation is the representation of source code. Mostly this`
₄	`is because we want a book to look like a “book” and`
₅	`source code to look like “source code”! Even in the`