Permalink
Browse files

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

  • Loading branch information...
1 parent 0dcd410 commit 6de479ae5b1894a42a4355b2db8fd0e32ff30878 @jonswar committed Jul 11, 2012
View
@@ -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
@@ -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,20 +901,20 @@ 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>
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
@@ -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
@@ -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
@@ -770,22 +770,22 @@ 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.
=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
@@ -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
@@ -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}]" : "");
}
Oops, something went wrong.

0 comments on commit 6de479a

Please sign in to comment.