[PATCH] 79ce185 Restore perlrepository.pod in stub form

[p5pRT]

Migrated from rt.perl.org#119571 (status was 'resolved')

Searchable as RT119571$

[p5pRT]

From @Smylers

This is a bug report for perl from smylers@​stripey.com,
generated with the help of perlbug 1.39 running under perl 5.19.4.

From 79ce1858a00ed46c50bbaf3012a2d4440fd95db1 Mon Sep 17 00​:00​:00 2001
From​: Smylers <Smylers@​stripey.com>
Date​: Tue, 3 Sep 2013 14​:52​:12 +0100
Subject​: [PATCH] Restore perlrepository.pod in stub form
MIME-Version​: 1.0
Content-Type​: multipart/mixed; boundary="------------1.8.1.2"

This is a multi-part message in MIME format.
--------------1.8.1.2
Content-Type​: text/plain; charset=UTF-8; format=fixed
Content-Transfer-Encoding​: 8bit

Give Perl doc sites a sane ‘latest’ version to display, directing readers
to current information, rather than showing the Perl 5.12 version in
perpetuity.

And help anybody typing man perlrepository find where the docs have moved
to.

Suggested by Father Chrysostomos in​:
http​://www.nntp.perl.org/group/perl.perl5.porters/2013/09/msg207079.html

---

MANIFEST | 1 +
pod/perl.pod | 1 +
pod/perlrepository.pod | 18 ++++++++++++++++++
win32/pod.mak | 4 ++++
4 files changed, 24 insertions(+)
create mode 100644 pod/perlrepository.pod

--------------1.8.1.2
Content-Type​: text/x-patch; name="0001-Restore-perlrepository.pod-in-stub-form.patch"
Content-Transfer-Encoding​: 8bit
Content-Disposition​: attachment; filename="0001-Restore-perlrepository.pod-in-stub-form.patch"

Inline Patch

diff --git a/MANIFEST b/MANIFEST
index 8b4fd50..72d44bb 100644
--- a/MANIFEST
+++ b/MANIFEST
@@ -4703,6 +4703,7 @@ pod/perlref.pod			Perl references, the rest of the story
 pod/perlreftut.pod		Perl references short introduction
 pod/perlreguts.pod		Perl regular expression engine internals
 pod/perlre.pod			Perl regular expressions, the rest of the story
+pod/perlrepository.pod		
 pod/perlrequick.pod		Perl regular expressions quick start
 pod/perlreref.pod		Perl regular expressions quick reference
 pod/perlretut.pod		Perl regular expressions tutorial
diff --git a/pod/perl.pod b/pod/perl.pod
index 20b6ad3..7ff91e4 100644
--- a/pod/perl.pod
+++ b/pod/perl.pod
@@ -271,6 +271,7 @@ aux a2p c2ph h2ph h2xs perlbug pl2pm pod2html pod2man s2p splain xsubpp
     perltodo
     perltooc		
     perltoot		
+    perlrepository
 
 =for buildtoc __END__
 
diff --git a/pod/perlrepository.pod b/pod/perlrepository.pod
new file mode 100644
index 0000000..5c4ab00
--- /dev/null
+++ b/pod/perlrepository.pod
@@ -0,0 +1,18 @@
+=encoding utf8
+
+=head1 NAME
+
+perlrepository - Links to current information on the Perl source repository
+
+=head1 DESCRIPTION
+
+Perl's source code is stored in a Git repository.
+
+See L<perlhack> for an explanation of Perl development, including the
+L<Super Quick Patch Guide|perlhack/SUPER QUICK PATCH GUIDE> for making and
+submitting a small patch.
+
+See L<perlgit> for detailed information about Perl's Git repository.
+
+(The above documents supersede the information that was formerly here in
+perlrepository.)
diff --git a/win32/pod.mak b/win32/pod.mak
index 44e6cea..65589ee 100644
--- a/win32/pod.mak
+++ b/win32/pod.mak
@@ -118,6 +118,7 @@ POD = perl.pod	\
 	perlref.pod	\
 	perlreftut.pod	\
 	perlreguts.pod	\
+	perlrepository.pod	\
 	perlrequick.pod	\
 	perlreref.pod	\
 	perlretut.pod	\
@@ -249,6 +250,7 @@ MAN = perl.man	\
 	perlref.man	\
 	perlreftut.man	\
 	perlreguts.man	\
+	perlrepository.man	\
 	perlrequick.man	\
 	perlreref.man	\
 	perlretut.man	\
@@ -380,6 +382,7 @@ HTML = perl.html	\
 	perlref.html	\
 	perlreftut.html	\
 	perlreguts.html	\
+	perlrepository.html	\
 	perlrequick.html	\
 	perlreref.html	\
 	perlretut.html	\
@@ -511,6 +514,7 @@ TEX = perl.tex	\
 	perlref.tex	\
 	perlreftut.tex	\
 	perlreguts.tex	\
+	perlrepository.tex	\
 	perlrequick.tex	\
 	perlreref.tex	\
 	perlretut.tex	\

--------------1.8.1.2--


---

Flags:   category=docs   severity=low

---

Site configuration information for perl 5.19.4​:

Configured by smylers at Tue Sep 3 10​:58​:31 BST 2013.

Summary of my perl5 (revision 5 version 19 subversion 4) configuration​:
  Commit id​: 5565c73
  Platform​:
  osname=linux, osvers=3.8.0-30-generic, archname=x86_64-linux
  uname='linux fozzie 3.8.0-30-generic #44-ubuntu smp thu aug 22 20​:52​:24 utc 2013 x86_64 x86_64 x86_64 gnulinux '
  config_args='-des -Dusedevel'
  hint=recommended, useposix=true, d_sigaction=define
  useithreads=undef, usemultiplicity=undef
  useperlio=define, d_sfio=undef, uselargefiles=define, usesocks=undef
  use64bitint=define, use64bitall=define, uselongdouble=undef
  usemymalloc=n, bincompat5005=undef
  Compiler​:
  cc='cc', ccflags ='-fno-strict-aliasing -pipe -fstack-protector -I/usr/local/include -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64',
  optimize='-O2',
  cppflags='-fno-strict-aliasing -pipe -fstack-protector -I/usr/local/include'
  ccversion='', gccversion='4.7.3', gccosandvers=''
  intsize=4, longsize=8, ptrsize=8, doublesize=8, byteorder=12345678
  d_longlong=define, longlongsize=8, d_longdbl=define, longdblsize=16
  ivtype='long', ivsize=8, nvtype='double', nvsize=8, Off_t='off_t', lseeksize=8
  alignbytes=8, prototype=define
  Linker and Libraries​:
  ld='cc', ldflags =' -fstack-protector -L/usr/local/lib'
  libpth=/usr/local/lib /lib/x86_64-linux-gnu /lib/../lib /usr/lib/x86_64-linux-gnu /usr/lib/../lib /lib /usr/lib
  libs=-lnsl -ldl -lm -lcrypt -lutil -lc
  perllibs=-lnsl -ldl -lm -lcrypt -lutil -lc
  libc=, so=so, useshrplib=false, libperl=libperl.a
  gnulibc_version='2.17'
  Dynamic Linking​:
  dlsrc=dl_dlopen.xs, dlext=so, d_dlsymun=undef, ccdlflags='-Wl,-E'
  cccdlflags='-fPIC', lddlflags='-shared -O2 -L/usr/local/lib -fstack-protector'

---

@​INC for perl 5.19.4​:
  lib
  /home/smylers/lib/perl5/site_perl
  /home/smylers/lib/perl5
  /usr/local/lib/perl5/site_perl/5.19.4/x86_64-linux
  /usr/local/lib/perl5/site_perl/5.19.4
  /usr/local/lib/perl5/5.19.4/x86_64-linux
  /usr/local/lib/perl5/5.19.4
  .

---

Environment for perl 5.19.4​:
  HOME=/home/smylers
  LANG=en_GB.utf8
  LANGUAGE=en_GB​:en
  LC_COLLATE=C
  LD_LIBRARY_PATH (unset)
  LOGDIR (unset)
  PATH=/home/smylers/bin​:/usr/local/sbin​:/usr/local/bin​:/sbin​:/bin​:/usr/sbin​:/usr/bin​:/usr/X11R6/bin​:/usr/games
  PERL5LIB=/home/smylers/lib/perl5/site_perl​:/home/smylers/lib/perl5
  PERL_BADLANG (unset)
  PERL_CPANM_OPT=--sudo --prompt
  SHELL=/bin/bash

[p5pRT]

From @Smylers

I wrote​:

Give Perl doc sites a sane ‘latest’ version to display, directing
readers to current information, rather than showing the Perl 5.12
version in perpetuity.

And help anybody typing man perlrepository find where the docs have
moved to.

Note I've set the NAME section to​:

  perlrepository - Links to current information on the Perl source repository

I see that other stubs of former documentation have NAMEs like this​:

  perltoot - This document has been deleted

That strikes me as suboptimal, because it means that commands like
whatis give output like this​:

  $ whatis perltoot
  perltoot (1) - This document has been deleted

That doesn't give any hint that it's nonetheless still worthwhile
somebody encountering that document looking at it, to discover where to
read the latest and shiniest information.

Please let me know which form is preferred.

If it's the “has been deleted” one then I'll tweak my patch
accordingly.

If it's how I've written it, then I'll create patches to change perltoot
and friends.

Cheers

Smylers
--
Stop drug companies hiding negative research results.
Sign the AllTrials petition to get all clinical research results published.
Read more​: http​://www.alltrials.net/blog/the-alltrials-campaign/

[p5pRT]

From @cpansprout

On Tue Sep 03 07​:52​:32 2013, smylers@​stripey.com wrote​:

I wrote​:

Give Perl doc sites a sane ‘latest’ version to display, directing
readers to current information, rather than showing the Perl 5.12
version in perpetuity.

And help anybody typing man perlrepository find where the docs have
moved to.

Note I've set the NAME section to​:

perlrepository - Links to current information on the Perl source
repository

I see that other stubs of former documentation have NAMEs like this​:

perltoot - This document has been deleted

That strikes me as suboptimal, because it means that commands like
whatis give output like this​:

$ whatis perltoot
perltoot (1) - This document has been deleted

That doesn't give any hint that it's nonetheless still worthwhile
somebody encountering that document looking at it, to discover where
to
read the latest and shiniest information.

Please let me know which form is preferred.

If it's the “has been deleted” one then I'll tweak my patch
accordingly.

If it's how I've written it, then I'll create patches to change
perltoot
and friends.

I think you are right, and that ‘has been deleted’ is not so helpful. I
have applied your patch as 5edbc4f. Thank you.

--

Father Chrysostomos

[p5pRT]

The RT System itself - Status changed from 'new' to 'open'

[p5pRT]

@cpansprout - Status changed from 'open' to 'resolved'