This and other RFCs are available on the web at
http://dev.perl.org/rfc/
=head1 TITLE
Add change bar functionality to pod
=head1 VERSION
Maintainer: Dan Sugalski <[EMAIL PROTECTED]>
Date: August 08, 2000
Version: 1
Mailing List: [EMAIL PROTECTED]
Number: 65
=head1 ABSTRACT
Documents change, and change bars are a nice way to indicate what's
changed. This RFC suggests a way to indicate the changed parts of a
document that POD2whatever translators can mark appropriately. The
change bars should also be distinct to the reader of the raw POD.
=head1 DESCRIPTION
Making what's changed in documentation stand out's quite useful,
something I'm coming to appreciate more and more as the RFCs are
flying back and forth. The standard way to do this is to mark the
changed sections with one or more vertical bars on the left margin.
Since changes can themselves be changed, multiple levels of change bar
can occur. This mirrors the common practice in printed documentation.
=head1 IMPLEMENTATION
The pod parser modules look for the sequence /^|+\s/ at the beginning
of a line and, if it's there, that line is considered as changed. The
number of bars in front of a line indicates the number of bars in
front of the text in the formatted output.
If, when outputtiing a line, there is any changed text in it, then the
entire line is marked as changed. So, for example, if the POD looked
like:
this
is
| a
line
the output would be:
| this is a line
since at least one character on the formatted version was changed.
=head1 REFERENCES
Every piece of good documentation for version 1.1 or higher of something.
