.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Alt 3pm"
.TH Alt 3pm "2022-11-27" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Alt \- Alternate Module Implementations
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& PERL_ALT_INSTALL=OVERWRITE cpanm Alt::IO::All::Redux
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`Alt::\*(C'\fR is the namespace for alternate implementations of \s-1CPAN\s0 modules.
.PP
The purpose of the Alt module is to provide documentation explaining the
Alt concept, how it works, and guidelines for using it well.
.SH "THE PROBLEM"
.IX Header "THE PROBLEM"
For a given piece of software, \s-1CPAN\s0 only allows for one implementation of a
given module/distribution name.
.PP
GitHub on the other hand, is not limited this way. Any author can make a fork,
since GitHub repos are namespaced by author id.
.PP
On \s-1CPAN,\s0 even the author(s) of the module in question is limited by this, as
they cannot release newer or older forks of their code, without introducing
a new name.
.SH "THE SOLUTION"
.IX Header "THE SOLUTION"
A module \f(CW\*(C`Foo::Bar\*(C'\fR is distributed on \s-1CPAN\s0 as \f(CW\*(C`Foo\-Bar\*(C'\fR. It may have
submodules like \f(CW\*(C`Foo::Bar::Baz\*(C'\fR.
.PP
To make an alternate \s-1CPAN\s0 version, leave everything exactly the same, except
distribute the new version as \f(CW\*(C`Alt\-Foo\-Bar\-AltIdentifier\*(C'\fR.
.PP
When a user installs your module like so:
.PP
.Vb 1
\& PERL_ALT_INSTALL=OVERWRITE cpanm Alt::Foo::Bar::better
.Ve
.PP
they will get your version of the Foo::Bar framework (Foo::Bar,
Foo::Bar::Baz).
.PP
Obviously, this completely overlays the old Foo::Bar install, but that's the
whole idea. The user isn't surprised by this because they just asked for an
\&\fBAlt\fRernate implementation. If they don't like it, they can simply reinstall
the original Foo-Bar, or try some other alternate.
.SH "ALT BEST PRACTICES"
.IX Header "ALT BEST PRACTICES"
This idea is new, and the details should be sorted out through proper
discussions. Pull requests welcome.
.PP
Here are the basic guidelines for best using the Alt namespace:
.IP "Name Creation" 4
.IX Item "Name Creation"
Names for alternate modules should be minted like this:
.Sp
.Vb 1
\& "Alt\-$Original_Dist_Name\-$phrase"
.Ve
.Sp
For instance, if \s-1MSTROUT\s0 wants to make an alternate IO-All distribution to
have it be Moo-based, he might call it:
.Sp
.Vb 1
\& Alt\-IO\-All\-Moo
.Ve
.Sp
He might also just call it:
.Sp
.Vb 1
\& Alt\-IO\-All\-MSTROUT
.Ve
.Sp
By having 'Alt' at the start, it guarantees that it does not mess with future
IO::All development. The \*(L"phrase\*(R" at the end can be anything unique to \s-1CPAN,\s0
but should describe the spirit of the alternate. If the alternate is meant to
be short-lived, it can just be the author's \s-1CPAN\s0 id.
.IP "Makefile.PL Changes" 4
.IX Item "Makefile.PL Changes"
Due to experience with problems, it is important to
make your Alt module \fBnot\fR install without explicit direction. You can
accomplish this easily in a Makefile.PL, with something like this:
.Sp
.Vb 3
\& my $alt = $ENV{PERL_ALT_INSTALL} || \*(Aq\*(Aq;
\& $WriteMakefileArgs{DESTDIR} =
\& $alt ? $alt eq \*(AqOVERWRITE\*(Aq ? \*(Aq\*(Aq : $alt : \*(Aqno\-install\-alt\*(Aq;
.Ve
.Sp
Similar techniques should be available for other module release frameworks.
.IP "Module for \s-1CPAN\s0 Indexing" 4
.IX Item "Module for CPAN Indexing"
You will need to provide a module like \f(CW\*(C`Alt::IO::All::MSTROUT\*(C'\fR so that
\&\s-1CPAN\s0 will index something that can cause your distribution to get installed
by people:
.Sp
.Vb 1
\& PERL_ALT_INSTALL=OVERWRITE cpanm Alt::IO::All::MSTROUT
.Ve
.Sp
Since you are adding this module, you should add some doc to it explaining
your alternate version's improvements.
.Sp
The Alt:: module can be as simple as this:
.Sp
.Vb 2
\& package Alt::IO::All::MSTROUT;
\& our $VERSION = \*(Aq0.01\*(Aq;
.Ve
.IP "no_index" 4
.IX Item "no_index"
It is important to use the \f(CW\*(C`no_index\*(C'\fR directive on the modules you are
providing an alternates for. This is especially important if you are the
author of the original, as \s-1PAUSE\s0 will reindex \s-1CPAN\s0 to your Alt\- version which
defeats the purpose. Even if you are not the same author, it will make your
index reports not show failures.
.IP "Versioning" 4
.IX Item "Versioning"
It is important to not declare a \f(CW$VERSION\fR in any of the modules that you
are providing alternates for. This will help ensure that your alternate
module does not satisfy the version requirements for something that wants the
real module.
.Sp
If you want to depend on the alternate versions, then set the dependency on
the \f(CW\*(C`Alt::\*(C'\fR module.
.Sp
\&\s-1NOTE:\s0 If you provide an alternate Foo::Bar (with no \s-1VERSION\s0) it \fBwill\fR
satisfy the version requirements for someone who requires \f(CW\*(C`Foo::Bar => 0\*(C'\fR. In a sense, depending on version 0 means that
alternates are \s-1OK.\s0
.ie n .IP """use"" the Alt" 4
.el .IP "\f(CWuse\fR the Alt" 4
.IX Item "use the Alt"
You should add this line to your alternate modules:
.Sp
.Vb 1
\& use Alt::IO::All::MSTROUT;
.Ve
.Sp
That way the Alt:: module gets loaded any time you \f(CW\*(C`use IO::All\*(C'\fR (with the
alternate version installed). This gives debugging clues since the Alt::
module is now in \f(CW%INC\fR.
.IP "Other Concerns" 4
.IX Item "Other Concerns"
If you have em, I(ngy) would like to know them. Discuss on #toolchain on
irc.perl.org for now.
.SH "WHENCE ALT?"
.IX Header "WHENCE ALT?"
The Alt\- concept was thought up by Ingy as he tried to figure out how to
revamp the somewhat popular IO::All and \s-1YAML\s0.pm modules. Alternates can now be
released and alpha/beta tested, while the originals remain stable.
.PP
When Alt-IO-All-new is \*(L"community approved\*(R" it can replace IO-All. If people
want the old code, they can can install Alt-IO-All-old.
.SH "AUTHOR"
.IX Header "AUTHOR"
Ingy döt Net
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2012\-2014. Ingy döt Net.
.PP
See