### ? 本地编译软件man手册配置指南  
**适用于源码编译安装的第三方应用，修复`man`命令无法识别问题**​
? 前置条件检查
# 验证man默认搜索路径  
manpath -d | tr ':' '\n'  

# 检查目标软件文档类型  
grep 'docdir=' /path/to/software/configure  # Autotools项目  
find ./ -name *.pod  # Perl模块文档特征  
​
? 关键发现：源码需包含 *.pod、*.txt或 groff文档才能生成man页

一、源码编译阶段配置
1. 配置文档生成选项
# Autotools项目  
./configure --prefix=$HOME/local --mandir=$HOME/local/share/man  

# CMake项目（添加文档生成）  
cmake -DCMAKE_INSTALL_MANDIR=$HOME/local/share/man -DBUILD_DOCS=ON ..  
​
? 参数解读：

--mandir 明确指定man文件安装目录
-DBUILD_DOCS=ON 强制启用文档编译

2. 生成man文档
make man  # 部分项目需执行特别命令  
make all  # 常规编译命令  
​
⚠️ 依赖检查：需提前安装 docbook-xsl、asciidoc等文档工具

二、man文件部署
1. 手动安装文档
# 手动复制groff格式文件  
cp doc/myapp.1 $HOME/local/share/man/man1/  
gzip $HOME/local/share/man/man1/myapp.1  # 必须gzip压缩  
​
? 目录规范：

man1(用户命令)
man8(管理员命令)
man5(配置文件格式)

2. 环境变量配置
# 持久化配置（写入Shell配置文件）  
echo 'export MANPATH=$HOME/local/share/man:$MANPATH' >> ~/.bashrc  
source ~/.bashrc  
​
✅ 验证路径：执行 manpath查看是否包含自定义目录

三、自动挂载方案（适用于多用户）
# 创建系统级man路径  
sudo mkdir /usr/local/custom_man  

# 添加全局man搜索路径  
sudo sh -c 'echo "/usr/local/custom_man" >> /etc/manpath.config'  

# 更新man数据库  
sudo mandb  
​
? 重要提醒：重启终端后生效

? 故障排除流程
1. man手册缺失检测
# 确认man文件通过安装  
tree $HOME/local/share/man | grep '.gz'  

# 检查文件格式有效性  
zcat $HOME/local/share/man/man1/myapp.1.gz | file -  
​
2. 路径调试技巧
# 实时追踪man命令搜索路径  
strace -f -e openat man 2>&1 | grep 'man/'  
​
3. 文档格式修复
# groff格式转换（适用于txt文档）  
groff -Tascii -man doc.txt | col -b > doc.1  
gzip doc.1  
​

⚙️ GCC关联文档配置
1. 指定gcc文档路径
# 配置GCC info手册路径  
echo 'INFO_PATH=$HOME/local/share/info:/usr/share/info' >> ~/.bashrc  

# 编译时开启文档生成  
CFLAGS='-g -O2' ./configure --with-docdir=$HOME/local/share/doc/gcc  
​

? 生产环境建议

版本控制：保持man目录结构 man<section>/<name>.<section>.gz
权限管理：
chmod 644 $HOME/local/share/man/man1/*.gz  # 防止误删  
​

定期更新：执行 mandb重建索引


? 使用效果验证
man -w myapp  # 显示手册完整路径  
man -a myapp  # 显示所有可用章节  
MANWIDTH=80 man myapp | col -b > manpage.txt  # 转换纯文本格式  
​

✅ 排查案例：当 man -k myapp无法搜索时：

检查 whatis数据库 mandb
验证手册页 NAME段是否存在关键词
确保man页面包含 .TH宏指令

（配置完成）⚙️