On Wed, 09 Aug 2000, Hildo Biersma wrote:
> > =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.
>
> I have a strong feeling this is a bad idea, because:
> - Not everyone is interested in the changes
Some of us have to add them anyway. :-)
The real question is whether the distributed Perl docs will include
change bars.
> - Human authors are fallible, and it's easy to forget changebars
Yep. (Although human authors are fallible, and it's easy to ^_foo,
or whatever the current currying syntax is now.)
> - We don't want the pods to grow indefinitely
Yep. (I think we keep the last five versions, so we simply filter out
/^\|{6,}/.
>
> Instead, it should be pretty trivial to write a tool that compares the
> pods for the current and (any) previous version, generate the
> changebars, then writes that out as a separate document - for those who
> want it. It may be desirable to include that with the default module
> distribution, or we may want to make this a web-based CPAN resource, but
> boy this should not clutter up every module out there.
We tried this, too. It worked, but was a little too awkward for our
use. (And failed the requirements in the end anyway.)
FFT.
--
Bryan C. Warnock
([EMAIL PROTECTED])
