☰

编写自定义手册页时如何包含文件？

tag-icon • tag-icon bash manpage
编写自定义手册页时如何包含文件？

目前我只是将自定义手册页的源文件复制到如下位置：

SOURCE=man/myManPage.1
DEST_DIR=/usr/local/share/man/man.1
sudo install -g 0 -o 0 -m 0644 "$SOURCE" "$DEST_DIR/"
yes | sudo gzip "$DEST_DIR/myManPage.1"

工作正常。

现在我希望能够包含一个包含页脚的文件。看起来，使用.so手册页源文件中的宏可能是一种方法：

.so footer.tmac

宏.mso可能是另一种选择：

.mso footer.tmac

这两种方法的问题在于，groff当我将手册页移动到位时，我实际上并没有运行，我只是将源代码复制到一个.gz文件中，而包含文件不在用户机器上，因此页脚不会显示。

也许我需要以某种方式预处理 man 源以便生成完整的文件？

答案1

有一个索林提供的命令就是groff用来执行此操作的。

.so file soelim 读取文件并用文件内容替换形式的行 。

答案2

这是我的解决方案，使用soelim@meuh 的建议：

#!/bin/bash

# Publishes man.1 files in ~/myman/
# Preprocesses .so statements by including the specified files

INCLUDED=included

function publish {
  SOURCE="~/myman/$INCLUDED/$1"
  if [[ ! -f "$SOURCE" ]]; then
    echo "Fatal: '$SOURCE' does not exist"
    exit 2
  fi

  I="${1##*.}"
  DEST_DIR=/usr/local/share/man/man${I}
  sudo mkdir -p ${DEST_DIR}
  sudo rm -f "$DEST_DIR/$1.gz"
  sudo install -g 0 -o 0 -m 0644 "$SOURCE" "$DEST_DIR/"
  echo "Creating $DEST_DIR/$1.gz"
  yes | sudo gzip "$DEST_DIR/$1"
}

cd "~/myman"
mkdir -p ${INCLUDED}
for CMD in *.1; do
  soelim -I ./ $CMD > $INCLUDED/$CMD
  pushd ${INCLUDED} > /dev/null
  publish "${CMD}"
  popd > /dev/null
done

sudo mandb

以下是带有两个 include 指令的 man 源文件.so：

.TH man-course 1 "03 May 2019" "1.0" "cad-course man page"
.SH NAME
cad-course \- Cadenza Client command for authoring course content
.SH SYNOPSIS
cad course id aa | audioFromTitles | dw | fetch [-r] | gitNewRepo | publish | pp | status
.SH DESCRIPTION
\fBcad-course\fR is a Cadenza Client curriculum management command for authoring course-level content.
.so cad-description.tmac
.SH OPTIONS
The cad-course command takes sub-commands and options.
.SH EXAMPLES
  cad course 40 dw               # Launch DreamWeaver on content for course #40 (Intro to Scala)
.PP
  cad course 40 dw               # Launch DreamWeaver on content for course #40
.PP
  cad course 40 audioFromTitles  # Build a new Adobe Audition audio project from course #40 transcript titles
.PP
  cad course 40 gitNewRepo       # Wipe out any existing GitHub project for course #40 and make a new one,
check in current stuff. Use regular git commands as content is authored.
.PP
  cad course 40 fetch            # (Re)download all of the content for course #40's courses from the active database and the active S3 buckets.
If uncommitted changes to course's git repo, ask user if the changes should
be committed before fetching. If no git repo, makes one.
.PP
  cad course -r 40 fetch         # Also recurses by fetching sections & their lectures.
.so cad-footer.tmac

这是cad-description.tmac：

The complete list of curriculum management commands is: cad-site, cad-group, cad-course, cad-section and cad-lecture.

这是cad-footer.tmac：

.SH SEE ALSO
 cad-course(1),cad-group(1),cad-install(1),cad-lecture(1),cad-publish(1),cad-section(1),cad-site(1),cad-status(1),cad-status(1),bash(8)
.SH BUGS
No known bugs.
.SH AUTHOR
Michael Slinn ([email protected])

这是的输出man cad：

man(1)                                                                                 cad man page                                                                                man(1)

NAME
       cad - Cadenza Client command-line interface

SYNOPSIS
       cad install status  # TODO What other options might apply?

DESCRIPTION
       cad is a command-line interface for cadenzaClient

OPTIONS
       The cad command takes sub-commands and options.

EXAMPLES
       cad -h

SEE ALSO
        cad-course(1),cad-group(1),cad-install(1),cad-lecture(1),cad-publish(1),cad-section(1),cad-site(1),cad-status(1),cad-status(1),bash(8)

BUGS
       No known bugs.

AUTHOR
       Michael Slinn ([email protected])

1.0                                                                                    03 May 2019                                                                                 man(1)

相关内容