[% setvar title Add change bar functionality to pod %]

This file is part of the Perl 6 Archive

Note: these documents may be out of date. Do not use as reference!

To see what is currently happening visit http://www.perl6.org/


Add change bar functionality to pod


  Maintainer: Dan Sugalski <dan@sidhe.org>
  Date: 8 Aug 2000
  Mailing List: perl6-language@perl.org
  Number: 65
  Version: 1
  Status: Developing


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.


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.


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:

   | a

the output would be:

  | this is a line

since at least one character on the formatted version was changed.


Every piece of good documentation for version 1.1 or higher of something.