7

I am writing a few custom man pages and I would like to include things that might change often such as the date of the man page's writing.

For example, one is in a git repo that I would like to update the man page's date whenever a change is made to it without having to do it by hand.

Is there a possibility to #include or call shell variables in the *roff file, or perhaps a markdown file and then use pandoc to "compile" the man page with?

I understand this is a strange question, but I haven't come across anything similar.

Please note this is different than simply including a man page in the $MANPATH to be called by man.

I.E., I want to use something like:

.TH foo 10 "$(git log -n1 | grep Date | tail -c 31)" "$(git branch | grep "*")"

in place of having to manually change the date and branch/head name every time. Whether this is in markdown and given to pandoc or something else or just in the roff file itself, I am okay with either.

agc
  • 7,973
  • 2
  • 29
  • 50
Tropical_Peach
  • 1,143
  • 3
  • 16
  • 29

2 Answers2

2

I see from your example line that you're using Git - I believe you can use a 'pre-commit' git hook (basically a script that runs before your commit is processed) to update the contents of the manpage (and stage the changes) on every commit.

For example, you could put the following commands in your .git/hooks/pre-commit file to update the contents of the manpage in place whenever you commit:

sed -i "" "s/^.TH foo 1 \".*/.TH foo 1 \"$(date)\"/" path/to/manpage.roff git add path/to/manpage.roff

Note that the path is relative to the root of the git repository.

Artemish
  • 21
  • 1
  • Only three of the man pages are in git repos. I am also not the only contributor to these repos, and the man pages need to be updated every time a change is made. Distributing these pre-commands isn't really a solution for these. It's a good idea if the number of contributors were small, and if all of my pages were on Git. Good suggestion though. – Tropical_Peach Aug 01 '17 at 23:38
2

Consider composing the content of the man page using a documentation generator language like asciidoc, which has most of the desired features. The asciidoc format can include external input files, and change all sorts of things on-the-fly as needed.

To include shell script, see Substitutions inside literals in Asciidoc .

Or one could use a shell script to generate a config file, then include that file.

Apologies in advance if this answer is at present little vague, in that it's more of a software recommendation (without any actual code) than a real answer.

agc
  • 7,973
  • 2
  • 29
  • 50
  • This is a very good recommendation as well. Unfortunately this requires external software to be downloaded, which I can't really do. I was hoping for something that was in the roff code. Though it seems to be that this is impossible and I'll just have to distribute an update script to be patched at every change. – Tropical_Peach Aug 07 '17 at 16:49