develooper Front page | perl.perl5.porters | Postings from April 2003

Re: Standard HISTORY section?

Thread Next
From:
Slaven Rezic
Date:
April 27, 2003 04:05
Subject:
Re: Standard HISTORY section?
Message ID:
873ck45i27.fsf@vran.herceg.de
Tels <perl_dummy@bloodgate.com> writes:

> Moin,
> 
> | (for Storable)
> | HISTORY
> |      Storable is part of the standard perl distribution since 5.7.3.
> | 
> | Later some *important* module API changes (not every little bugfix)
> | could be manually added to the HISTORY section.
> 
> While the idea in principle is fine, there are some ugly cornercases. Like
> BigInt *cough* . The (condensed) history is already 30 K, even if you take
> out the bugfixes, internals, the dates etc, you would probably end up with
> a couple of K of text. Is this really necc. to put it into the doc?
>
> Another idea I was pondering was just including the full changelog of each
> module (maybe convert it to pod beforehand). Although it would bloat
> the core distribution, the changelogs are probably kept uptodate by the
> authors, where the new-fangled HISTORY section would get outdated fast (who
> is to keep them uptodate? the author? the maintainer? the integrator? ouch.)
> 

I would say, keep the HISTORY section as short as possible, like the
previous examples from the FreeBSD manpages. If there's more to say,
then a link to a ChangeLog file or another Pod document named
This::Module-ChangeLog could be introduced. After all, Math::BigInt is
one of the bigger modules. The description for most other modules may
fit into a small HISTORY section.

Regards,
	Slaven

-- 
Slaven Rezic - slaven@rezic.de

Tk-AppMaster: a perl/Tk module launcher designed for handhelds
	http://tk-appmaster.sf.net

Thread Next


nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About