Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

expand P<>, ADMIN<>, and DEVEL<> pod shortcuts for good

  • Loading branch information...
commit 6de479ae5b1894a42a4355b2db8fd0e32ff30878 1 parent 0dcd410
@jonswar authored
View
4 lib/HTML/Mason.pm
@@ -135,7 +135,7 @@ running mod_perl.
The <Location> section routes all requests to the Mason handler, which
is a simple way to try out Mason. A more refined setup is discussed
-in ADMIN<Controlling Access via Filename Extension>.
+in L<Controlling Access via Filename Extension|HTML::Mason::Admin/Controlling Access via Filename Extension>.
Once you have added the configuration directives, restart the
server. First, go to a standard URL on your site to make sure you
@@ -173,7 +173,7 @@ mod_perl, since that is the most common configuration. If you would
like to run Mason via a CGI script, refer to the
L<HTML::Mason::CGIHandler|HTML::Mason::CGIHandler> documentation.
If you are using Mason from a standalone program, refer to
-ADMIN<Using Mason from a Standalone Script>.
+L<Using Mason from a Standalone Script|HTML::Mason::Admin/Using Mason from a Standalone Script>.
There is also a book about Mason, I<Embedding Perl in HTML with
Mason>, by Dave Rolsky and Ken Williams, published by O'Reilly and
View
52 lib/HTML/Mason/Admin.pod
@@ -202,7 +202,7 @@ of parameters, and their associated types.
=head2 Component Root
-The component root (P<comp_root>) marks the top of your component
+The component root (L<comp_root|HTML::Mason::Params/comp_root>) marks the top of your component
hierarchy. When running Mason with the ApacheHandler or CGIHandler
modules, this defaults to your document root.
@@ -235,7 +235,7 @@ component roots, and they appear in the C<title()> of a component.
=head2 Data Directory
-The data directory (P<data_dir>) is a writable directory that Mason
+The data directory (L<data_dir|HTML::Mason::Params/data_dir>) is a writable directory that Mason
uses for various features and optimizations. By default, it is a
directory called "mason" under your Apache server root. Because Mason
will not use a I<default> data directory under a top-level directory,
@@ -313,7 +313,7 @@ directory: F</foo/bar/dhandler> does not get a chance to
handle a request for F</foo/bar/>.
If you would like Mason to handle directory requests, set
-P<decline_dirs> to 0. The dhandler that catches a directory request
+L<decline_dirs|HTML::Mason::Params/decline_dirs> to 0. The dhandler that catches a directory request
is responsible for setting a reasonable content type via
C<< $r->content_type() >>.
@@ -678,7 +678,7 @@ user session information, the server root for forming absolute URLs.
Because Mason by default parses components in C<strict> mode, you'll
need to declare a global if you don't want to access it with an
explicit package name. The easiest way to declare a global is with
-the P<allow_globals> parameter.
+the L<allow_globals|HTML::Mason::Params/allow_globals> parameter.
Since all components run in the same package, you'll be able to set
the global in one component and access it in all the others.
@@ -711,7 +711,7 @@ although this may be overridden by the developer. C<Cache::FileCache>
creates a separate subdirectory for every component that uses caching,
and one file some number of levels underneath that subdirectory for
each cached item. The root of the cache tree is
-P<data_dir>/C<cache>. The name of the cache subdirectory for a component
+L<data_dir|HTML::Mason::Params/data_dir>/C<cache>. The name of the cache subdirectory for a component
is determined by the function C<HTML::Mason::Utils::data_cache_namespace>.
=item Default constructor options
@@ -721,7 +721,7 @@ constructor the C<namespace>, and C<cache_root> options, along with
any other options given in the C<< $m->cache >> method.
You may specify other default constructor options with the
-P<data_cache_defaults> parameter. For example,
+L<data_cache_defaults|HTML::Mason::Params/data_cache_defaults> parameter. For example,
PerlSetVar MasonDataCacheDefaults "cache_class => SizeAwareFileCache"
PerlAddVar MasonDataCacheDefaults "cache_depth => 2"
@@ -742,14 +742,14 @@ implements the cache API but never stores data.
This section explains Mason's various performance enhancements and how
to administer them. One of the best ways to maximize performance on
-your production server is run in P<static_source> mode; see the third
+your production server is run in L<static_source|HTML::Mason::Params/static_source> mode; see the third
subsection below.
=head2 Code Cache
When Mason loads a component, it places it in a memory cache. By
default, the cache has no limit, but you can specify a maximum number
-of components to cache with the P<code_cache_max_size> parameter. In
+of components to cache with the L<code_cache_max_size|HTML::Mason::Params/code_cache_max_size> parameter. In
this case, Mason will free up space as needed by discarding
components. The discard algorithm is least frequently used (LFU), with
a periodic decay to gradually eliminate old frequency information. In
@@ -762,7 +762,7 @@ for cache policy. The max size is now specified purely in number of
components.
Mason can use certain optimizations with an unlimited cache,
-especially in conjunction with P<static_source>, so don't limit the
+especially in conjunction with L<static_source|HTML::Mason::Params/static_source>, so don't limit the
cache unless experience shows that your servers are growing too
large. Many dynamic sites can be served comfortably with all
components in memory.
@@ -775,7 +775,7 @@ and can be discarded like any others.
Naturally, a cache entry is invalidated if the corresponding component
source file changes.
-To turn off code caching completely, set P<code_cache_max_size> to 0.
+To turn off code caching completely, set L<code_cache_max_size|HTML::Mason::Params/code_cache_max_size> to 0.
=head2 Object Files
@@ -785,7 +785,7 @@ are conceivable in the future, but even those will not survive between
web server restarts.
As a secondary, longer-term cache mechanism, Mason stores a compiled
-form of each component in an object file under P<data_dir>/obj. Any
+form of each component in an object file under L<data_dir|HTML::Mason::Params/data_dir>/obj. Any
server process can eval the object file and save time on parsing the
component source file. The object file is recreated whenever the
source file changes.
@@ -800,7 +800,7 @@ object file, such as after an upgrade
=item * the component path
-=item * P<object_file_extension>, by default ".obj"
+=item * L<object_file_extension|HTML::Mason::Params/object_file_extension>, by default ".obj"
=back
@@ -812,20 +812,20 @@ for pre-1.10 Mason, in which error line numbers were based on the
object file rather than the source file.
If for some reason you don't want Mason to create object files, set
-P<use_object_files> to 0.
+L<use_object_files|HTML::Mason::Params/use_object_files> to 0.
=head2 Static Source Mode
-In P<static_source> mode, Mason assumes that the component hierarchy
+In L<static_source|HTML::Mason::Params/static_source> mode, Mason assumes that the component hierarchy
is unchanging and thus does not check source timestamps when using an
in-memory cached component or object file. This significantly reduces
filesystem stats and other overhead. We've seen speedups by a factor
of two or three as a result of this mode, though of course YMMV.
-When in P<static_source> mode, you must remove object files and call
+When in L<static_source|HTML::Mason::Params/static_source> mode, you must remove object files and call
$interp->flush_code_cache in order for the server to recognize
component changes. The easiest way to arrange this is to point
-P<static_source_touch_file> to a file that can be touched whenever
+L<static_source_touch_file|HTML::Mason::Params/static_source_touch_file> to a file that can be touched whenever
components change.
We highly recommend running in this mode in production if you can
@@ -835,12 +835,12 @@ this off so that components are reloaded automatically.
=head2 Disabling Autoflush
-To support the dynamic P<autoflush> feature, Mason has to check for
+To support the dynamic L<autoflush|HTML::Mason::Params/autoflush> feature, Mason has to check for
autoflush mode after printing every piece of text. If you can commit
-to not using autoflush, setting P<enable_autoflush> to 0 will allow
+to not using autoflush, setting L<enable_autoflush|HTML::Mason::Params/enable_autoflush> to 0 will allow
Mason to compile components more efficiently. Consider whether a few
well-placed C<< $m->flush_buffer >> calls would be just as good as
-P<autoflush>.
+L<autoflush|HTML::Mason::Params/autoflush>.
=head2 Write a handler subroutine
@@ -852,7 +852,7 @@ and letting Mason create its own ApacheHandler objects internally.
=head2 Preloading Components
You can tell Mason to preload a set of components in the parent
-process, rather than loading them on demand, using the P<preloads>
+process, rather than loading them on demand, using the L<preloads|HTML::Mason::Params/preloads>
parameter. Each child server will start with those components loaded
in the memory cache. The trade-offs are:
@@ -877,7 +877,7 @@ to reload it from scratch.)
=head2 Preallocating the Output Buffer
-You can set P<buffer_preallocate_size> to set the size of the
+You can set L<buffer_preallocate_size|HTML::Mason::Params/buffer_preallocate_size> to set the size of the
preallocated output buffer for each request. This can reduce the
number of reallocations Perl performs as components output text.
@@ -901,12 +901,12 @@ message go to the error logs.
The first behavior is ideal for development, where you want immediate
feedback on the error. The second behavior is usually desired for
production so that users are not exposed to messy error messages. You
-choose the behavior by setting P<error_mode> to "output" or "fatal"
+choose the behavior by setting L<error_mode|HTML::Mason::Params/error_mode> to "output" or "fatal"
respectively.
-Error formatting is controlled by the P<error_format> parameter. When
+Error formatting is controlled by the L<error_format|HTML::Mason::Params/error_format> parameter. When
showing errors in the browser, Mason defaults to the "html" format.
-When the P<error_mode> is set to "fatal", the default format is
+When the L<error_mode|HTML::Mason::Params/error_mode> is set to "fatal", the default format is
"line", which puts the entire error message on one line in a format
suitable for web server error logs. Mason also offers other formats,
which are covered in the L<Request class|HTML::Mason::Request>
@@ -914,7 +914,7 @@ documentation.
Finally, you can use Apache's C<ErrorDocument> directive to specify a
custom error handler for 500 errors. In this case, you'd set the
-P<error_mode> to "fatal". The URL specified by the C<ErrorDocument>
+L<error_mode|HTML::Mason::Params/error_mode> to "fatal". The URL specified by the C<ErrorDocument>
directive could point to a Mason component.
=head2 Exceptions Under the Hood
@@ -1023,7 +1023,7 @@ to an RT installation, so that the error is logged in a bug tracking
system. Finally, it displays a less technical error message to the
user.
-For this to work properly, you must set P<error_mode> to "fatal", so
+For this to work properly, you must set L<error_mode|HTML::Mason::Params/error_mode> to "fatal", so
that Mason doesn't just display its own HTML error page.
=head1 RUNNING OUTSIDE OF MOD_PERL
View
6 lib/HTML/Mason/ApacheHandler.pm
@@ -1177,13 +1177,13 @@ F<httpd.conf> or F<handler.pl> file, as this will save some memory.
True or false, default is true. Indicates whether Mason should decline
directory requests, leaving Apache to serve up a directory index or a
-C<FORBIDDEN> error as appropriate. See ADMIN<allowing directory requests>
+C<FORBIDDEN> error as appropriate. See L<allowing directory requests|HTML::Mason::Admin/allowing directory requests>
for more information about handling directories with Mason.
=item interp
The interpreter object to associate with this compiler. By default a
-new object of the specified P<interp_class> will be created.
+new object of the specified L<interp_class|HTML::Mason::Params/interp_class> will be created.
=item interp_class
@@ -1253,7 +1253,7 @@ backwards compatibility from when this method was responsible for
turning a plain Apache object into an Apache::Request object.
The third item may be a CGI.pm object or C<undef>, depending on the
-value of the P<args_method> parameter.
+value of the L<args_method|HTML::Mason::Params/args_method> parameter.
=back
View
4 lib/HTML/Mason/CGIHandler.pm
@@ -292,7 +292,7 @@ about the particular details of invoking Mason on each request.
If you want to use Mason components from I<within> a regular CGI
script (or any other Perl program, for that matter), then you don't
need this module. You can simply follow the directions in
-ADMIN<Using Mason from a standalone script>.
+L<Using Mason from a standalone script|HTML::Mason::Admin/Using Mason from a standalone script>.
This module also provides an C<$r> request object for use inside
components, similar to the Apache request object under
@@ -335,7 +335,7 @@ as a templating language but not an application server.
C<handle_component()> will create a CGI query object, parse the query
parameters, and send the HTTP header and component output to STDOUT.
If you want to handle those parts yourself, see
-ADMIN<Using Mason from a standalone script>.
+L<Using Mason from a standalone script|HTML::Mason::Admin/Using Mason from a standalone script>.
=item * handle_cgi_object()
View
12 lib/HTML/Mason/Compiler.pm
@@ -770,7 +770,7 @@ valid flags are
u - escape for URL (':' => '%3A', etc.)
The developer can override default escape flags on a per-expression
-basis; see DEVEL<escaping expressions>.
+basis; see L<escaping expressions|HTML::Mason::Devel/escaping expressions>.
If you want to set I<multiple> flags as the default, this should be
given as a reference to an array of flags.
@@ -778,14 +778,14 @@ given as a reference to an array of flags.
=item enable_autoflush
True or false, default is true. Indicates whether components are
-compiled with support for P<autoflush>. The component can be compiled
+compiled with support for L<autoflush|HTML::Mason::Params/autoflush>. The component can be compiled
to a more efficient form if it does not have to check for autoflush
mode, so you should set this to 0 if you can.
=item lexer
The Lexer object to associate with this Compiler. By default a new
-object of class P<lexer_class> will be created.
+object of class L<lexer_class|HTML::Mason::Params/lexer_class> will be created.
=item lexer_class
@@ -798,7 +798,7 @@ it's magic. The sub is called with a single parameter, a scalar reference
to the script. The sub is expected to process the script in-place. This is
one way to extend the HTML::Mason syntax with new tags, etc., although a much
more flexible way is to subclass the Lexer or Compiler class. See also
-P<postprocess_text> and P<postprocess_perl>.
+L<postprocess_text|HTML::Mason::Params/postprocess_text> and L<postprocess_perl|HTML::Mason::Params/postprocess_perl>.
=item postprocess_text
@@ -807,7 +807,7 @@ compiled component, just before it is assembled into its final
subroutine form. The sub is called with a single parameter, a scalar
reference to the text portion of the component. The sub is expected
to process the string in-place. See also
-P<preprocess> and P<postprocess_perl>.
+L<preprocess|HTML::Mason::Params/preprocess> and L<postprocess_perl|HTML::Mason::Params/postprocess_perl>.
=item postprocess_perl
@@ -816,7 +816,7 @@ compiled component, just before it is assembled into its final
subroutine form. The sub is called with a single parameter, a scalar
reference to the Perl portion of the component. The sub is expected
to process the string in-place. See also
-P<preprocess> and P<postprocess_text>.
+L<preprocess|HTML::Mason::Params/preprocess> and L<postprocess_text|HTML::Mason::Params/postprocess_text>.
=item use_source_line_numbers
View
4 lib/HTML/Mason/Compiler/ToObject.pm
@@ -687,13 +687,13 @@ historical reasons, this defaults to C<HTML::Mason::Commands>.
Text given for this parameter is placed at the beginning of each
component, but after the execution of any C<< <%once> >> block. See
-also P<postamble>. The request will be available as C<$m> in preamble
+also L<postamble|HTML::Mason::Params/postamble>. The request will be available as C<$m> in preamble
code.
=item postamble
Text given for this parameter is placed at the end of each
-component. See also P<preamble>. The request will be available as
+component. See also L<preamble|HTML::Mason::Params/preamble>. The request will be available as
C<$m> in postamble code.
=item use_strict
View
6 lib/HTML/Mason/Component/FileBased.pm
@@ -29,9 +29,11 @@ sub source_dir {
sub title {
my ($self) = @_;
return $self->path
- . ( $self->{source_root_key}
+ . (
+ $self->{source_root_key}
? " [" . lc( $self->{source_root_key} ) . "]"
- : "" );
+ : ""
+ );
#return $self->path . ($self->{source_root_key} ? " [$self->{source_root_key}]" : "");
}
View
40 lib/HTML/Mason/Devel.pod
@@ -26,8 +26,7 @@ site, that is what I<most> people want to do with Mason, and is thus
the focus of this manual.
If you are planning to use Mason outside of the web, this manual will
-still be useful, of course. Also make sure to read ADMIN<running
-outside of mod_perl>.
+still be useful, of course. Also make sure to read L<running outside of mod_perl|HTML::Mason::Admin/running outside of mod_perl>.
=head1 HOW TO USE THIS MANUAL
@@ -297,7 +296,7 @@ To call one component from another, use the <& &> tag:
=item comp_path:
The component path. With a leading '/', the path is relative to the
-component root (P<comp_root>). Otherwise, it is relative to the
+component root (L<comp_root|HTML::Mason::Params/comp_root>). Otherwise, it is relative to the
location of the calling component.
=item name => value pairs:
@@ -584,8 +583,8 @@ methods normally associated with one.
To create a subrequest you simply use the C<< $m->make_subrequest >>
method. This method can take any parameters belonging to
-L<HTML::Mason::Request|HTML::Mason::Request>, such as P<autoflush> or
-P<out_method>. Once you have a new request object you simply call its
+L<HTML::Mason::Request|HTML::Mason::Request>, such as L<autoflush|HTML::Mason::Params/autoflush> or
+L<out_method|HTML::Mason::Params/out_method>. Once you have a new request object you simply call its
C<exec> method to execute it, which takes exactly the same parameters
as the C<comp> method.
@@ -602,7 +601,7 @@ Here are some examples:
</%perl>
If you want to capture the subrequest's output in a scalar, you can
-simply pass an P<out_method> parameter to C<< $m->make_subrequest >>:
+simply pass an L<out_method|HTML::Mason::Params/out_method> parameter to C<< $m->make_subrequest >>:
<%perl>
my $buffer;
@@ -624,7 +623,7 @@ attributes.
By default, output from a subrequest appears inline in the calling
component, at the point where it is executed. If you wish to do
something else, you will need to explicitly override the subrequest's
-P<out_method> parameter.
+L<out_method|HTML::Mason::Params/out_method> parameter.
Mason Request objects are only designed to handle a single call to
C<exec>. If you wish to make multiple subrequests, you must create
@@ -697,8 +696,7 @@ By default dhandlers do not get a chance to handle requests to a
directory itself (e.g. F</newsfeeds>). These are automatically
deferred to Apache, which generates an index page or a FORBIDDEN
error. Often this is desirable, but if necessary the administrator
-can let in directory requests as well; see ADMIN<allowing directory
-requests>.
+can let in directory requests as well; see L<allowing directory requests|HTML::Mason::Admin/allowing directory requests>.
A component or dhandler that does not want to handle a particular
request may defer control to the next dhandler by calling C<< $m->decline >>.
@@ -711,7 +709,7 @@ block containing a C<SetType> directive to your Apache config file, or
you can just set the content type dynamically by calling C<< $r->content_type >>.
The administrator can customize the file name used for dhandlers with
-the P<dhandler_name> parameter.
+the L<dhandler_name|HTML::Mason::Params/dhandler_name> parameter.
=head2 autohandlers
@@ -781,7 +779,7 @@ separate section, L<Object-Oriented Techniques|"Object-Oriented
Techniques">.
The administrator can customize the file name used for autohandlers
-with the P<autohandler_name> parameter.
+with the L<autohandler_name|HTML::Mason::Params/autohandler_name> parameter.
=head2 dhandlers vs. autohandlers
@@ -1394,8 +1392,8 @@ I<not> be used for this substitution.
=back
The administrator may specify a set of default escape flags via the
-P<default_escape_flags> parameter. For example, if the administrator
-sets P<default_escape_flags> to C<['h']>, then all <% %> expressions
+L<default_escape_flags|HTML::Mason::Params/default_escape_flags> parameter. For example, if the administrator
+sets L<default_escape_flags|HTML::Mason::Params/default_escape_flags> to C<['h']>, then all <% %> expressions
will automatically be HTML-escaped. In this case you would use the
C<n> flag to turn off HTML-escaping for a specific expression:
@@ -1421,7 +1419,7 @@ Besides the default escapes mentioned above, it is possible for the
user to define their own escapes or to override the built-in 'h' and
'u' escapes.
-This is done via the Interp object's P<escape_flags> parameter or
+This is done via the Interp object's L<escape_flags|HTML::Mason::Params/escape_flags> parameter or
L<set_escape()|HTML::Mason::Interp/item_set_escape> method. Escape
names may be any number of characters as long as it matches the regex
C</^[\w-]+$/>. The one exception is that you cannot override the 'n'
@@ -1514,7 +1512,7 @@ time.
Data caching is implemented on top of one of two external caching APIs:
C<Cache::Cache>, which is stable but has not changed in years, or C<CHI>,
which has picked up where C<Cache::Cache> has left off and is actively
-maintained. You control which one Mason uses with the P<data_cache_api>
+maintained. You control which one Mason uses with the L<data_cache_api|HTML::Mason::Params/data_cache_api>
parameter. C<Cache::Cache> is the default for backward compatibility
reasons, but we recommend C<CHI> for anyone doing serious caching. The APIs
are very similar for Mason users, so that most of the information below
@@ -1674,7 +1672,7 @@ calls to C<< $m->cache >>; Mason does not remember which subclass you
have used for a given component or key.
The administrator can set the default cache subclass used by all
-components with the P<data_cache_defaults> parameter.
+components with the L<data_cache_defaults|HTML::Mason::Params/data_cache_defaults> parameter.
=head2 Choosing a Cache Subclass - with CHI
@@ -1697,7 +1695,7 @@ calls to C<< $m->cache >>; Mason does not remember which subclass you
have used for a given component or key.
The administrator can set the default cache subclass used by all
-components with the P<data_cache_defaults> parameter.
+components with the L<data_cache_defaults|HTML::Mason::Params/data_cache_defaults> parameter.
=head2 Accessing a Cache Externally
@@ -1749,7 +1747,7 @@ and you are using the default file backend:
For users upgrading from 1.0x and earlier, any existing $m-E<gt>cache
code will be incompatible with the new API. However, if you wish to
continue using the 1.0x cache API for a while, you (or your
-administrator) can set P<data_cache_api> to '1.0'. All of the
+administrator) can set L<data_cache_api|HTML::Mason::Params/data_cache_api> to '1.0'. All of the
$m-E<gt>cache options with the exception of C<tie_class> should be
supported.
@@ -1766,7 +1764,7 @@ Mason automatically sends HTTP headers via C<< $r->send_http_header >>
but it will not send headers if they've already been sent manually.
To determine the exact header behavior on your system, you need to
-know whether your server's default is to have P<autoflush> on or off.
+know whether your server's default is to have L<autoflush|HTML::Mason::Params/autoflush> on or off.
Your administrator should have this information. If your administrator
doesn't know then it is probably off, the default.
@@ -1798,7 +1796,7 @@ this code will only work as long as F</shared/get_user_cookie> doesn't
output anything (given its functional nature, it shouldn't).
The administrator can turn off automatic header sending via the
-P<auto_send_headers> parameter. You can also turn it off on
+L<auto_send_headers|HTML::Mason::Params/auto_send_headers> parameter. You can also turn it off on
individual pages with
$m->auto_send_headers(0);
@@ -1924,7 +1922,7 @@ Mason normally inserts '#line' directives into compiled components so
that line numbers are reported relative to the source file. Depending
on your task, this can be a help or a hindrance when using the
debugger. The administrator can turn off '#line' directives with
-the P<use_source_line_numbers> parameter.
+the L<use_source_line_numbers|HTML::Mason::Params/use_source_line_numbers> parameter.
=head1 LOGGING
View
20 lib/HTML/Mason/Interp.pm
@@ -1211,7 +1211,7 @@ translated into
[ [ MAIN => path ] ]
-If you have turned on P<dynamic_comp_root>, you may modify the
+If you have turned on L<dynamic_comp_root|HTML::Mason::Params/dynamic_comp_root>, you may modify the
component root(s) of an interpreter between requests by calling
C<$interp-E<gt>comp_root> with a value. However, the path associated
with any given key may not change between requests. For example,
@@ -1238,7 +1238,7 @@ invalid if the associated paths were to change.
=item compiler
The Compiler object to associate with this Interpreter. By default a
-new object of class P<compiler_class> will be created.
+new object of class L<compiler_class|HTML::Mason::Params/compiler_class> will be created.
=item compiler_class
@@ -1264,7 +1264,7 @@ C<MemoryCache> instead of C<FileCache>.
=item dynamic_comp_root
-True or false, defaults to false. Indicates whether the P<comp_root>
+True or false, defaults to false. Indicates whether the L<comp_root|HTML::Mason::Params/comp_root>
can be modified on this interpreter between requests. Mason can
perform a few optimizations with a fixed component root, so you
should only set this to true if you actually need it.
@@ -1304,7 +1304,7 @@ when the interpreter initializes. e.g.
Default is the empty list. For maximum performance, this should only
be used for components that are frequently viewed and rarely updated.
-See ADMIN<preloading components> for further details.
+See L<preloading components|HTML::Mason::Admin/preloading components> for further details.
As mentioned in the developer's manual, a component's C<< <%once> >>
section is executed when it is loaded. For preloaded components, this
@@ -1320,7 +1320,7 @@ L<HTML::Mason::Request|HTML::Mason::Request>.
=item resolver
The Resolver object to associate with this Compiler. By default a new
-object of class P<resolver_class> will be created.
+object of class L<resolver_class|HTML::Mason::Params/resolver_class> will be created.
=item resolver_class
@@ -1340,7 +1340,7 @@ it will not check component source files to determine if the memory
cache or object file has expired. This can save many file stats per
request. However, in order to get Mason to recognize a component
source change, you must flush the memory cache and remove object files.
-See P<static_source_touch_file> for one easy way to arrange this.
+See L<static_source_touch_file|HTML::Mason::Params/static_source_touch_file> for one easy way to arrange this.
We recommend turning this mode on in your production sites if
possible, if performance is of any concern.
@@ -1352,7 +1352,7 @@ of every request. When the file timestamp changes, Mason will (1) clear
its in-memory component cache, and (2) remove object files if
they have not already been deleted by another process.
-This provides a convenient way to implement P<static_source> mode.
+This provides a convenient way to implement L<static_source|HTML::Mason::Params/static_source> mode.
All you need to do is make sure that a single file gets touched
whenever components change. For Mason's part, checking a single
file at the beginning of a request is much cheaper than checking
@@ -1523,16 +1523,16 @@ in the case of a list or hash. For example:
The global is set in the package that components run in: usually
C<HTML::Mason::Commands>, although this can be overridden via the
-P<in_package> parameter.
+L<in_package|HTML::Mason::Params/in_package> parameter.
The lines above, for example, are equivalent to:
$HTML::Mason::Commands::dbh = DBI->connect(...);
%HTML::Mason::Commands::session = %s;
-assuming that P<in_package> has not been changed.
+assuming that L<in_package|HTML::Mason::Params/in_package> has not been changed.
Any global that you set should also be registered with the
-P<allow_globals> parameter; otherwise you'll get warnings from
+L<allow_globals|HTML::Mason::Params/allow_globals> parameter; otherwise you'll get warnings from
C<strict>.
=back
View
30 lib/HTML/Mason/Params.pod
@@ -190,7 +190,7 @@ automatically send HTTP headers before sending content back to the
client. If you set to false, you should call C<$r-E<gt>send_http_header>
manually.
-See DEVEL<sending HTTP headers> for more details about the automatic
+See L<sending HTTP headers|HTML::Mason::Devel/sending HTTP headers> for more details about the automatic
header feature.
NOTE: This parameter has no effect under mod_perl-2, since calling
@@ -221,7 +221,7 @@ buffer (C<$m-E<gt>flush_buffer>) after every string is output. Turn on
autoflush if you need to send partial output to the client, for
example in a progress meter.
-As of Mason 1.3, autoflush will only work if P<enable_autoflush> has
+As of Mason 1.3, autoflush will only work if L<enable_autoflush|HTML::Mason::Params/enable_autoflush> has
been set. Components can be compiled more efficiently if they don't
have to check for autoflush. Before using autoflush you might consider
whether a few manual C<$m-E<gt>flush_buffer> calls would work nearly
@@ -388,7 +388,7 @@ translated into
[ [ MAIN => path ] ]
-If you have turned on P<dynamic_comp_root>, you may modify the
+If you have turned on L<dynamic_comp_root|HTML::Mason::Params/dynamic_comp_root>, you may modify the
component root(s) of an interpreter between requests by calling
C<$interp-E<gt>comp_root> with a value. However, the path associated
with any given key may not change between requests. For example,
@@ -598,7 +598,7 @@ C<MemoryCache> instead of C<FileCache>.
True or false, default is true. Indicates whether Mason should decline
directory requests, leaving Apache to serve up a directory index or a
-C<FORBIDDEN> error as appropriate. See ADMIN<allowing directory requests>
+C<FORBIDDEN> error as appropriate. See L<allowing directory requests|HTML::Mason::Admin/allowing directory requests>
for more information about handling directories with Mason.
@@ -628,7 +628,7 @@ valid flags are
u - escape for URL (':' => '%3A', etc.)
The developer can override default escape flags on a per-expression
-basis; see DEVEL<escaping expressions>.
+basis; see L<escaping expressions|HTML::Mason::Devel/escaping expressions>.
If you want to set I<multiple> flags as the default, this should be
given as a reference to an array of flags.
@@ -709,7 +709,7 @@ are turned off entirely.
=back
-True or false, defaults to false. Indicates whether the P<comp_root>
+True or false, defaults to false. Indicates whether the L<comp_root|HTML::Mason::Params/comp_root>
can be modified on this interpreter between requests. Mason can
perform a few optimizations with a fixed component root, so you
should only set this to true if you actually need it.
@@ -735,7 +735,7 @@ should only set this to true if you actually need it.
=back
True or false, default is true. Indicates whether components are
-compiled with support for P<autoflush>. The component can be compiled
+compiled with support for L<autoflush|HTML::Mason::Params/autoflush>. The component can be compiled
to a more efficient form if it does not have to check for autoflush
mode, so you should set this to 0 if you can.
@@ -1097,7 +1097,7 @@ details.
=back
Text given for this parameter is placed at the end of each
-component. See also P<preamble>. The request will be available as
+component. See also L<preamble|HTML::Mason::Params/preamble>. The request will be available as
C<$m> in postamble code.
@@ -1125,7 +1125,7 @@ compiled component, just before it is assembled into its final
subroutine form. The sub is called with a single parameter, a scalar
reference to the Perl portion of the component. The sub is expected
to process the string in-place. See also
-P<preprocess> and P<postprocess_text>.
+L<preprocess|HTML::Mason::Params/preprocess> and L<postprocess_text|HTML::Mason::Params/postprocess_text>.
=head2 postprocess_text
@@ -1152,7 +1152,7 @@ compiled component, just before it is assembled into its final
subroutine form. The sub is called with a single parameter, a scalar
reference to the text portion of the component. The sub is expected
to process the string in-place. See also
-P<preprocess> and P<postprocess_perl>.
+L<preprocess|HTML::Mason::Params/preprocess> and L<postprocess_perl|HTML::Mason::Params/postprocess_perl>.
=head2 preamble
@@ -1176,7 +1176,7 @@ P<preprocess> and P<postprocess_perl>.
Text given for this parameter is placed at the beginning of each
component, but after the execution of any C<< <%once> >> block. See
-also P<postamble>. The request will be available as C<$m> in preamble
+also L<postamble|HTML::Mason::Params/postamble>. The request will be available as C<$m> in preamble
code.
@@ -1206,7 +1206,7 @@ when the interpreter initializes. e.g.
Default is the empty list. For maximum performance, this should only
be used for components that are frequently viewed and rarely updated.
-See ADMIN<preloading components> for further details.
+See L<preloading components|HTML::Mason::Admin/preloading components> for further details.
As mentioned in the developer's manual, a component's C<< <%once> >>
section is executed when it is loaded. For preloaded components, this
@@ -1239,7 +1239,7 @@ it's magic. The sub is called with a single parameter, a scalar reference
to the script. The sub is expected to process the script in-place. This is
one way to extend the HTML::Mason syntax with new tags, etc., although a much
more flexible way is to subclass the Lexer or Compiler class. See also
-P<postprocess_text> and P<postprocess_perl>.
+L<postprocess_text|HTML::Mason::Params/postprocess_text> and L<postprocess_perl|HTML::Mason::Params/postprocess_perl>.
=head2 request_class
@@ -1318,7 +1318,7 @@ it will not check component source files to determine if the memory
cache or object file has expired. This can save many file stats per
request. However, in order to get Mason to recognize a component
source change, you must flush the memory cache and remove object files.
-See P<static_source_touch_file> for one easy way to arrange this.
+See L<static_source_touch_file|HTML::Mason::Params/static_source_touch_file> for one easy way to arrange this.
We recommend turning this mode on in your production sites if
possible, if performance is of any concern.
@@ -1348,7 +1348,7 @@ of every request. When the file timestamp changes, Mason will (1) clear
its in-memory component cache, and (2) remove object files if
they have not already been deleted by another process.
-This provides a convenient way to implement P<static_source> mode.
+This provides a convenient way to implement L<static_source|HTML::Mason::Params/static_source> mode.
All you need to do is make sure that a single file gets touched
whenever components change. For Mason's part, checking a single
file at the beginning of a request is much cheaper than checking
View
2  lib/HTML/Mason/Plugin.pm
@@ -63,7 +63,7 @@ HTML::Mason::Plugin - Plugin Base class for Mason
=head1 DESCRIPTION
Use a Mason plugin to have actions occur at the beginning or end of
-requests or components. Plugins are activated by passing P<plugins> in
+requests or components. Plugins are activated by passing L<plugins|HTML::Mason::Params/plugins> in
the interpreter or request object. Each plugin in the list can be
specified as a class name (in which case the plugin object is created
once for each request) or as an actual object of the plugin class.
View
23 lib/HTML/Mason/Request.pm
@@ -578,8 +578,7 @@ sub exec {
if ( $self->{has_plugins} ) {
# plugins called in reverse order when exiting.
- my $context = bless
- [
+ my $context = bless [
$self, $request_args,
\$self->{request_buffer}, $wantarray,
\@result, \$error
@@ -1831,7 +1830,7 @@ buffer (C<$m-E<gt>flush_buffer>) after every string is output. Turn on
autoflush if you need to send partial output to the client, for
example in a progress meter.
-As of Mason 1.3, autoflush will only work if P<enable_autoflush> has
+As of Mason 1.3, autoflush will only work if L<enable_autoflush|HTML::Mason::Params/enable_autoflush> has
been set. Components can be compiled more efficiently if they don't
have to check for autoflush. Before using autoflush you might consider
whether a few manual C<$m-E<gt>flush_buffer> calls would work nearly
@@ -2175,10 +2174,10 @@ If a component has a C<< <%filter> >> block, then the I<filtered>
output is cached.
Note: users upgrading from 1.0x and earlier can continue to use the
-old C<$m-E<gt>cache_self> API by setting P<data_cache_api> to '1.0'.
+old C<$m-E<gt>cache_self> API by setting L<data_cache_api|HTML::Mason::Params/data_cache_api> to '1.0'.
This support will be removed at a later date.
-See the DEVEL<DATA CACHING> section for more details on how to
+See the L<DATA CACHING|HTML::Mason::Devel/DATA CACHING> section for more details on how to
exercise finer control over caching.
=item caller_args
@@ -2234,7 +2233,7 @@ from an autohandler. With no arguments, the original arguments are
passed to the component. Any arguments specified here serve to
augment and override (in case of conflict) the original
arguments. Works like C<$m-E<gt>comp> in terms of return value and
-scalar/list context. See DEVEL<autohandlers> for examples.
+scalar/list context. See L<autohandlers|HTML::Mason::Devel/autohandlers> for examples.
=item call_self (output, return, error, tag)
@@ -2461,14 +2460,14 @@ undef if no such component exists.
Returns the next component in the content wrapping chain, or undef if
there is no next component. Usually called from an autohandler. See
-DEVEL<autohandlers> for usage and examples.
+L<autohandlers|HTML::Mason::Devel/autohandlers> for usage and examples.
=item fetch_next_all
=for html <a name="item_fetch_next_all"></a>
Returns a list of the remaining components in the content wrapping
-chain. Usually called from an autohandler. See DEVEL<autohandlers>
+chain. Usually called from an autohandler. See L<autohandlers|HTML::Mason::Devel/autohandlers>
for usage and examples.
=item file (filename)
@@ -2517,14 +2516,14 @@ Returns the Interp object associated with this request.
=for html <a name="item_make_subrequest"></a>
This method creates a new Request object which inherits its parent's
-settable properties, such as P<autoflush> and P<out_method>. These
+settable properties, such as L<autoflush|HTML::Mason::Params/autoflush> and L<out_method|HTML::Mason::Params/out_method>. These
values may be overridden by passing parameters to this method.
The C<comp> parameter is required, while all other parameters are
optional. It may be specified as an absolute path or as a path
relative to the current component.
-See DEVEL<subrequests> for more information about subrequests.
+See L<subrequests|HTML::Mason::Devel/subrequests> for more information about subrequests.
=item log
@@ -2656,7 +2655,7 @@ automatically send HTTP headers before sending content back to the
client. If you set to false, you should call C<$r-E<gt>send_http_header>
manually.
-See DEVEL<sending HTTP headers> for more details about the automatic
+See L<sending HTTP headers|HTML::Mason::Devel/sending HTTP headers> for more details about the automatic
header feature.
NOTE: This parameter has no effect under mod_perl-2, since calling
@@ -2696,7 +2695,7 @@ ApacheHandler or CGIHandler modules.
Returns the CGI object used to parse any CGI parameters submitted to
the component, assuming that you have not changed the default value of
-the ApacheHandler P<args_method> parameter. If you are using the
+the ApacheHandler L<args_method|HTML::Mason::Params/args_method> parameter. If you are using the
'mod_perl' args method, then calling this method is a fatal error.
See the L<ApacheHandler|HTML::Mason::ApacheHandler> and
L<CGIHandler|HTML::Mason::CGIHandler> documentation for more details.
View
2  lib/HTML/Mason/Subclassing.pod
@@ -259,7 +259,7 @@ fly.
For example, if you're subclassed the Interp object, you can still let
the ApacheHandler object create the Interp object for you, as long as
-you give it the appropriate P<interp_class> parameter. This is
+you give it the appropriate L<interp_class|HTML::Mason::Params/interp_class> parameter. This is
important because Mason may internally set up certain defaults for
contained objects. For example, the ApacheHandler, by default, will
tell the Interp object to use the
Please sign in to comment.
Something went wrong with that request. Please try again.