develooper Front page | perl.perl5.porters | Postings from February 2000

[DOC PATCH pod/perlapi.pod 5.5.64] Change 'See C<Foo>' to 'See L<"Foo">'

Thread Next
From:
Michael G Schwern
Date:
February 7, 2000 18:25
Subject:
[DOC PATCH pod/perlapi.pod 5.5.64] Change 'See C<Foo>' to 'See L<"Foo">'
Message ID:
20000205175236.A1969@blackrider.aocn.com
perlapi.pod has lots of "See also C<Move>" and "See C<warn>" which
would probably be better written as "See also L<"Move">" and "See
L<"warn">" as they're all =item's.

However, this touches on the same issue as the whole L<"qr//">
discussion.  L<"foo"> is supposed to indicate that "foo" is a section
in the current man page, not an item.  As far as I can see, there's no
way to indicate a link to an item in the current man page, only in
other man pages.  Is this a problem, or do POD parsers just kinda
fudge the whole distinction between items and sections?


--- pod/perlapi.pod	2000/02/04 18:56:05
+++ pod/perlapi.pod	2000/02/05 22:28:34
@@ -150,8 +150,8 @@
 
 =item CLASS
 
-Variable which is setup by C<xsubpp> to indicate the 
-class name for a C++ XS constructor.  This is always a C<char*>.  See C<THIS>.
+Variable which is setup by C<xsubpp> to indicate the class name for a
+C++ XS constructor.  This is always a C<char*>.  See L<"THIS">.
 
 	char*	CLASS
 
@@ -159,7 +159,7 @@
 
 The XSUB-writer's interface to the C C<memcpy> function.  The C<src> is the
 source, C<dest> is the destination, C<nitems> is the number of items, and C<type> is
-the type.  May fail on overlapping copies.  See also C<Move>.
+the type.  May fail on overlapping copies.  See also L<"Move">.
 
 	void	Copy(void* src, void* dest, int nitems, type)
 
@@ -167,7 +167,7 @@
 
 This is the XSUB-writer's interface to Perl's C<die> function.  Use this
 function the same way you use the C C<printf> function.  See
-C<warn>.
+L<"warn">.
 
 	void	croak(const char* pat, ...)
 
@@ -179,21 +179,21 @@
 
 =item dMARK
 
-Declare a stack marker variable, C<mark>, for the XSUB.  See C<MARK> and
-C<dORIGMARK>.
+Declare a stack marker variable, C<mark>, for the XSUB.  See L<"MARK"> and
+L<"dORIGMARK">.
 
 		dMARK;
 
 =item dORIGMARK
 
-Saves the original stack mark for the XSUB.  See C<ORIGMARK>.
+Saves the original stack mark for the XSUB.  See L<"ORIGMARK">.
 
 		dORIGMARK;
 
 =item dSP
 
 Declares a local copy of perl's stack pointer for the XSUB, available via
-the C<SP> macro.  See C<SP>.
+the C<SP> macro.  See L<"SP">.
 
 		dSP;
 
@@ -214,7 +214,7 @@
 
 =item ENTER
 
-Opening bracket on a callback.  See C<LEAVE> and L<perlcall>.
+Opening bracket on a callback.  See L<"LEAVE"> and L<perlcall>.
 
 		ENTER;
 
@@ -260,7 +260,7 @@
 
 =item FREETMPS
 
-Closing bracket for temporaries on a callback.  See C<SAVETMPS> and
+Closing bracket for temporaries on a callback.  See L<"SAVETMPS"> and
 L<perlcall>.
 
 		FREETMPS;
@@ -349,7 +349,7 @@
 
 =item gv_fetchmethod
 
-See L<gv_fetchmethod_autoload.
+See L<"gv_fetchmethod_autoload">.
 
 	GV*	gv_fetchmethod(HV* stash, const char* name)
 
@@ -391,13 +391,13 @@
 =item gv_stashsv
 
 Returns a pointer to the stash for a specified package.  See
-C<gv_stashpv>.
+L<"gv_stashpv">.
 
 	HV*	gv_stashsv(SV* sv, I32 create)
 
 =item G_ARRAY
 
-Used to indicate array context.  See C<GIMME_V>, C<GIMME> and
+Used to indicate array context.  See L<"GIMME_V">, L<"GIMME"> and
 L<perlcall>.
 
 =item G_DISCARD
@@ -417,12 +417,12 @@
 
 =item G_SCALAR
 
-Used to indicate scalar context.  See C<GIMME_V>, C<GIMME>, and
+Used to indicate scalar context.  See L<"GIMME_V">, L<"GIMME">, and
 L<perlcall>.
 
 =item G_VOID
 
-Used to indicate void context.  See C<GIMME_V> and L<perlcall>.
+Used to indicate void context.  See L<"GIMME_V"> and L<perlcall>.
 
 =item HEf_SVKEY
 
@@ -498,7 +498,7 @@
 
 =item HvNAME
 
-Returns the package name of a stash.  See C<SvSTASH>, C<CvSTASH>.
+Returns the package name of a stash.  See L<"SvSTASH">, L<"CvSTASH">.
 
 	char*	HvNAME(HV* stash)
 
@@ -583,7 +583,7 @@
 =item hv_iterkey
 
 Returns the key from the current position of the hash iterator.  See
-C<hv_iterinit>.
+L<"hv_iterinit">.
 
 	char*	hv_iterkey(HE* entry, I32* retlen)
 
@@ -597,7 +597,7 @@
 
 =item hv_iternext
 
-Returns entries from a hash iterator.  See C<hv_iterinit>.
+Returns entries from a hash iterator.  See L<"hv_iterinit">.
 
 	HE*	hv_iternext(HV* tb)
 
@@ -611,13 +611,13 @@
 =item hv_iterval
 
 Returns the value from the current position of the hash iterator.  See
-C<hv_iterkey>.
+L<"hv_iterkey">.
 
 	SV*	hv_iterval(HV* tb, HE* entry)
 
 =item hv_magic
 
-Adds magic to a hash.  See C<sv_magic>.
+Adds magic to a hash.  See L<"sv_magic">.
 
 	void	hv_magic(HV* hv, GV* gv, int how)
 
@@ -717,7 +717,7 @@
 
 =item LEAVE
 
-Closing bracket on a callback.  See C<ENTER> and L<perlcall>.
+Closing bracket on a callback.  See L<"ENTER"> and L<perlcall>.
 
 		LEAVE;
 
@@ -730,61 +730,62 @@
 
 =item MARK
 
-Stack marker variable for the XSUB.  See C<dMARK>.
+Stack marker variable for the XSUB.  See L<"dMARK">.
 
 =item mg_clear
 
-Clear something magical that the SV represents.  See C<sv_magic>.
+Clear something magical that the SV represents.  See L<"sv_magic">.
 
 	int	mg_clear(SV* sv)
 
 =item mg_copy
 
-Copies the magic from one SV to another.  See C<sv_magic>.
+Copies the magic from one SV to another.  See L<"sv_magic">.
 
 	int	mg_copy(SV* sv, SV* nsv, const char* key, I32 klen)
 
 =item mg_find
 
-Finds the magic pointer for type matching the SV.  See C<sv_magic>.
+Finds the magic pointer for type matching the SV.  See L<"sv_magic">.
 
 	MAGIC*	mg_find(SV* sv, int type)
 
 =item mg_free
 
-Free any magic storage used by the SV.  See C<sv_magic>.
+Free any magic storage used by the SV.  See L<"sv_magic">.
 
 	int	mg_free(SV* sv)
 
 =item mg_get
 
-Do magic after a value is retrieved from the SV.  See C<sv_magic>.
+Do magic after a value is retrieved from the SV.  See L<"sv_magic">.
 
 	int	mg_get(SV* sv)
 
 =item mg_length
 
-Report on the SV's length.  See C<sv_magic>.
+Report on the SV's length.  See L<"sv_magic">.
 
 	U32	mg_length(SV* sv)
 
 =item mg_magical
 
-Turns on the magical status of an SV.  See C<sv_magic>.
+Turns on the magical status of an SV.  See L<"sv_magic">.
 
 	void	mg_magical(SV* sv)
 
 =item mg_set
 
-Do magic after a value is assigned to the SV.  See C<sv_magic>.
+Do magic after a value is assigned to the SV.  See L<"sv_magic">.
 
 	int	mg_set(SV* sv)
 
 =item Move
 
-The XSUB-writer's interface to the C C<memmove> function.  The C<src> is the
-source, C<dest> is the destination, C<nitems> is the number of items, and C<type> is
-the type.  Can do overlapping moves.  See also C<Copy>.
+The XSUB-writer's interface to the C C<memmove> function.  The C<src>
+is the source, C<dest> is the destination, C<nitems> is the number of
+items, and C<type> is the type.  Can do overlapping moves.  See also
+L<"Copy">.
 
 	void	Move(void* src, void* dest, int nitems, type)
 
@@ -935,7 +936,7 @@
 
 =item ORIGMARK
 
-The original stack mark for the XSUB.  See C<dORIGMARK>.
+The original stack mark for the XSUB.  See L<"dORIGMARK">.
 
 =item perl_alloc
 
@@ -979,7 +980,7 @@
 boolean which indicates whether subs are being single-stepped. 
 Single-stepping is automatically turned on after every step.  This is the C
 variable which corresponds to Perl's $DB::single variable.  See
-C<PL_DBsub>.
+L<"PL_DBsub">.
 
 	SV *	PL_DBsingle
 
@@ -988,7 +989,7 @@
 When Perl is run in debugging mode, with the B<-d> switch, this GV contains
 the SV which holds the name of the sub being debugged.  This is the C
 variable which corresponds to Perl's $DB::sub variable.  See
-C<PL_DBsingle>.
+L<"PL_DBsingle">.
 
 	GV *	PL_DBsub
 
@@ -996,7 +997,7 @@
 
 Trace variable used when Perl is run in debugging mode, with the B<-d>
 switch.  This is the C variable which corresponds to Perl's $DB::trace
-variable.  See C<PL_DBsingle>.
+variable.  See L<"PL_DBsingle">.
 
 	SV *	PL_DBtrace
 
@@ -1027,7 +1028,7 @@
 
 =item PL_sv_no
 
-This is the C<false> SV.  See C<PL_sv_yes>.  Always refer to this as
+This is the C<false> SV.  See L<"PL_sv_yes">.  Always refer to this as
 C<&PL_sv_no>.
 
 	SV	PL_sv_no
@@ -1040,7 +1041,7 @@
 
 =item PL_sv_yes
 
-This is the C<true> SV.  See C<PL_sv_no>.  Always refer to this as
+This is the C<true> SV.  See L<"PL_sv_no">.  Always refer to this as
 C<&PL_sv_yes>.
 
 	SV	PL_sv_yes
@@ -1078,13 +1079,13 @@
 =item PUSHi
 
 Push an integer onto the stack.  The stack must have room for this element.
-Handles 'set' magic.  See C<XPUSHi>.
+Handles 'set' magic.  See L<"XPUSHi">.
 
 	void	PUSHi(IV iv)
 
 =item PUSHMARK
 
-Opening bracket for arguments on a callback.  See C<PUTBACK> and
+Opening bracket for arguments on a callback.  See L<"PUTBACK"> and
 L<perlcall>.
 
 		PUSHMARK;
@@ -1092,7 +1093,7 @@
 =item PUSHn
 
 Push a double onto the stack.  The stack must have room for this element.
-Handles 'set' magic.  See C<XPUSHn>.
+Handles 'set' magic.  See L<"XPUSHn">.
 
 	void	PUSHn(NV nv)
 
@@ -1100,28 +1101,28 @@
 
 Push a string onto the stack.  The stack must have room for this element.
 The C<len> indicates the length of the string.  Handles 'set' magic.  See
-C<XPUSHp>.
+L<"XPUSHp">.
 
 	void	PUSHp(char* str, STRLEN len)
 
 =item PUSHs
 
 Push an SV onto the stack.  The stack must have room for this element. 
-Does not handle 'set' magic.  See C<XPUSHs>.
+Does not handle 'set' magic.  See L<"XPUSHs">.
 
 	void	PUSHs(SV* sv)
 
 =item PUSHu
 
 Push an unsigned integer onto the stack.  The stack must have room for this
-element.  See C<XPUSHu>.
+element.  See L<"XPUSHu">.
 
 	void	PUSHu(UV uv)
 
 =item PUTBACK
 
 Closing bracket for XSUB arguments.  This is usually handled by C<xsubpp>.
-See C<PUSHMARK> and L<perlcall> for other uses.
+See L<"PUSHMARK"> and L<perlcall> for other uses.
 
 		PUTBACK;
 
@@ -1659,7 +1660,7 @@
 =item sv_bless
 
 Blesses an SV into a specified package.  The SV must be an RV.  The package
-must be designated by its stash (see C<gv_stashpv()>).  The reference count
+must be designated by its stash (see L<"gv_stashpv">).  The reference count
 of the SV is unaffected.
 
 	SV*	sv_bless(SV* sv, HV* stash)
@@ -1667,7 +1668,7 @@
 =item sv_catpv
 
 Concatenates the string onto the end of the string which is in the SV.
-Handles 'get' magic, but not 'set' magic.  See C<sv_catpv_mg>.
+Handles 'get' magic, but not 'set' magic.  See L<"sv_catpv_mg">.
 
 	void	sv_catpv(SV* sv, const char* ptr)
 
@@ -1689,7 +1690,7 @@
 
 Concatenates the string onto the end of the string which is in the SV.  The
 C<len> indicates number of bytes to copy.  Handles 'get' magic, but not
-'set' magic.  See C<sv_catpvn_mg>.
+'set' magic.  See L<"sv_catpvn_mg">.
 
 	void	sv_catpvn(SV* sv, const char* ptr, STRLEN len)
 
@@ -1708,7 +1709,7 @@
 =item sv_catsv
 
 Concatenates the string from SV C<ssv> onto the end of the string in SV
-C<dsv>.  Handles 'get' magic, but not 'set' magic.  See C<sv_catsv_mg>.
+C<dsv>.  Handles 'get' magic, but not 'set' magic.  See L<"sv_catsv_mg">.
 
 	void	sv_catsv(SV* dsv, SV* ssv)
 
@@ -1795,7 +1796,7 @@
 
 =item sv_len
 
-Returns the length of the string in the SV.  See also C<SvCUR>.
+Returns the length of the string in the SV.  See also L<"SvCUR">.
 
 	STRLEN	sv_len(SV* sv)
 
@@ -1821,7 +1822,7 @@
 =item sv_setiv
 
 Copies an integer into the given SV.  Does not handle 'set' magic.  See
-C<sv_setiv_mg>.
+L<"sv_setiv_mg">.
 
 	void	sv_setiv(SV* sv, IV num)
 
@@ -1834,7 +1835,7 @@
 =item sv_setnv
 
 Copies a double into the given SV.  Does not handle 'set' magic.  See
-C<sv_setnv_mg>.
+L<"sv_setnv_mg">.
 
 	void	sv_setnv(SV* sv, NV num)
 
@@ -1847,14 +1848,14 @@
 =item sv_setpv
 
 Copies a string into an SV.  The string must be null-terminated.  Does not
-handle 'set' magic.  See C<sv_setpv_mg>.
+handle 'set' magic.  See L<"sv_setpv_mg">.
 
 	void	sv_setpv(SV* sv, const char* ptr)
 
 =item sv_setpvf
 
 Processes its arguments like C<sprintf> and sets an SV to the formatted
-output.  Does not handle 'set' magic.  See C<sv_setpvf_mg>.
+output.  Does not handle 'set' magic.  See L<"sv_setpvf_mg">.
 
 	void	sv_setpvf(SV* sv, const char* pat, ...)
 
@@ -1867,7 +1868,7 @@
 =item sv_setpviv
 
 Copies an integer into the given SV, also updating its string value.
-Does not handle 'set' magic.  See C<sv_setpviv_mg>.
+Does not handle 'set' magic.  See L<"sv_setpviv_mg">.
 
 	void	sv_setpviv(SV* sv, IV num)
 
@@ -1880,7 +1881,7 @@
 =item sv_setpvn
 
 Copies a string into an SV.  The C<len> parameter indicates the number of
-bytes to be copied.  Does not handle 'set' magic.  See C<sv_setpvn_mg>.
+bytes to be copied.  Does not handle 'set' magic.  See L<"sv_setpvn_mg">.
 
 	void	sv_setpvn(SV* sv, const char* ptr, STRLEN len)
 
@@ -1949,8 +1950,8 @@
 
 Copies the contents of the source SV C<ssv> into the destination SV C<dsv>.
 The source SV may be destroyed if it is mortal.  Does not handle 'set'
-magic.  See the macro forms C<SvSetSV>, C<SvSetSV_nosteal> and
-C<sv_setsv_mg>.
+magic.  See the macro forms L<"SvSetSV">, L<"SvSetSV_nosteal"> and
+L<"sv_setsv_mg">.
 
 	void	sv_setsv(SV* dsv, SV* ssv)
 
@@ -1963,7 +1964,7 @@
 =item sv_setuv
 
 Copies an unsigned integer into the given SV.  Does not handle 'set' magic.
-See C<sv_setuv_mg>.
+See L<"sv_setuv_mg">.
 
 	void	sv_setuv(SV* sv, UV num)
 
@@ -1977,14 +1978,14 @@
 
 Unsets the RV status of the SV, and decrements the reference count of
 whatever was being referenced by the RV.  This can almost be thought of
-as a reversal of C<newSVrv>.  See C<SvROK_off>.
+as a reversal of C<newSVrv>.  See L<"SvROK_off">.
 
 	void	sv_unref(SV* sv)
 
 =item sv_upgrade
 
 Upgrade an SV to a more complex form.  Use C<SvUPGRADE>.  See
-C<svtype>.
+L<"svtype">.
 
 	bool	sv_upgrade(SV* sv, U32 mt)
 
@@ -1996,7 +1997,7 @@
 string length, C<len>, must be supplied.  This function will realloc the
 memory pointed to by C<ptr>, so that pointer should not be freed or used by
 the programmer after giving it to sv_usepvn.  Does not handle 'set' magic.
-See C<sv_usepvn_mg>.
+See L<"sv_usepvn_mg">.
 
 	void	sv_usepvn(SV* sv, char* ptr, STRLEN len)
 
@@ -2026,7 +2027,7 @@
 =item THIS
 
 Variable which is setup by C<xsubpp> to designate the object in a C++ 
-XSUB.  This is always the proper type for the C++ object.  See C<CLASS> and 
+XSUB.  This is always the proper type for the C++ object.  See L<"CLASS"> and 
 L<perlxs/"Using XS With C++">.
 
 	(whatever)	THIS
@@ -2047,21 +2048,21 @@
 
 This is the XSUB-writer's interface to Perl's C<warn> function.  Use this
 function the same way you use the C C<printf> function.  See
-C<croak>.
+L<"croak">.
 
 	void	warn(const char* pat, ...)
 
 =item XPUSHi
 
 Push an integer onto the stack, extending the stack if necessary.  Handles
-'set' magic. See C<PUSHi>.
+'set' magic. See L<"PUSHi">.
 
 	void	XPUSHi(IV iv)
 
 =item XPUSHn
 
 Push a double onto the stack, extending the stack if necessary.  Handles
-'set' magic.  See C<PUSHn>.
+'set' magic.  See L<"PUSHn">.
 
 	void	XPUSHn(NV nv)
 
@@ -2069,21 +2070,21 @@
 
 Push a string onto the stack, extending the stack if necessary.  The C<len>
 indicates the length of the string.  Handles 'set' magic.  See
-C<PUSHp>.
+L<"PUSHp">.
 
 	void	XPUSHp(char* str, STRLEN len)
 
 =item XPUSHs
 
 Push an SV onto the stack, extending the stack if necessary.  Does not
-handle 'set' magic.  See C<PUSHs>.
+handle 'set' magic.  See L<"PUSHs">.
 
 	void	XPUSHs(SV* sv)
 
 =item XPUSHu
 
 Push an unsigned integer onto the stack, extending the stack if necessary. 
-See C<PUSHu>.
+See L<"PUSHu">.
 
 	void	XPUSHu(UV uv)
 
@@ -2185,8 +2186,9 @@
 
 =item XS_VERSION
 
-The version identifier for an XS module.  This is usually
-handled automatically by C<ExtUtils::MakeMaker>.  See C<XS_VERSION_BOOTCHECK>.
+The version identifier for an XS module.  This is usually handled
+automatically by C<ExtUtils::MakeMaker>.  See
+L<"XS_VERSION_BOOTCHECK">.
 
 =item XS_VERSION_BOOTCHECK
 

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