如何将安装路径纳入已安装Perl模块的Pod文档？

针对你遇到的问题——需要在已安装模块的Pod文档中显示示例脚本的实际安装路径，这里提供几种适配Dist::Zilla工作流的解决方案：

方案1：用Dist::Zilla插件构建阶段替换占位符 #

这是最贴合你现有工具链的方法，通过Dist::Zilla插件在构建时将Pod中的占位符替换为实际路径：

1. 在模块的Pod模板中预留占位符，比如：

   =head1 示例脚本位置
   示例脚本安装路径：{{EXAMPLE_DIR}}
   

2. 安装Dist::Zilla::Plugin::ReplacePlaceholders和Dist::Zilla::Plugin::ShareDir插件
3. 在dist.ini中添加配置：

   [ShareDir]
   dir = share
   
   [ReplacePlaceholders]
   placeholder = EXAMPLE_DIR
   EXAMPLE_DIR = %{ share_dir('Package-Name') . '/examples' }%
   

   构建时，Dist::Zilla会自动将{{EXAMPLE_DIR}}替换为实际的共享目录路径（即你提到的.../site_perl/5.34.0/auto/share/dist/Package-Name/examples/）。

方案2：在模块中添加动态路径获取函数 #

如果不需要硬编码路径到Pod，而是让用户查看Pod时动态获取最新路径，可以在模块中实现一个路径函数：

1. 在模块代码中添加：

   use File::ShareDir qw(dist_dir);
   
   sub example_directory {
       return dist_dir('Package-Name') . '/examples';
   }
   

2. 在Pod中引用该函数：

   =head1 示例脚本位置
   执行以下代码可获取示例脚本路径：
   C<< use Package::Name; print Package::Name->example_directory(); >>
   或者直接查看路径：C<< Package::Name->example_directory() >>
   

   这种方式的优势是无论模块安装到哪个位置，都能返回正确路径，无需在构建阶段修改Pod。

方案3：手动通过Makefile.PL修改Pod（非Dist::Zilla优先方案） #

如果需要脱离Dist::Zilla手动处理，可在Makefile.PL中动态修改Pod：

1. 依赖File::ShareDir::Install模块，在Makefile.PL中添加：

   use ExtUtils::MakeMaker;
   use File::ShareDir::Install;
   
   install_share 'share';
   my $example_dir = dist_share_dir('Package-Name') . '/examples';
   
   # 读取并修改模块文件中的Pod占位符
   open my $in_fh, '<', 'lib/Package/Name.pm' or die $!;
   my $content = do { local $/; <$in_fh> };
   close $in_fh;
   
   $content =~ s/{{EXAMPLE_DIR}}/$example_dir/g;
   
   open my $out_fh, '>', 'lib/Package/Name.pm' or die $!;
   print $out_fh $content;
   close $out_fh;
   
   WriteMakefile(
       NAME => 'Package::Name',
       # 其他Makefile配置...
   );
   

   这种方法需要手动处理文件读写，适合不使用Dist::Zilla的场景。

内容的提问来源于stack exchange，提问作者jimav