Friday, 2 July 2021

Learning new stuff each and every day - turning Markdown into man pages

I'm tinkering with a container tool called skopeo at present, and am building it on an Ubuntu 20.04 box.

One thing that I'd not realised, until I was looking to contribute some changes back to the project, was that there's a tool that turns Markdown ( .md ) into man pages, meaning that in-line documentation can be generated on the fly.

I found this out whilst building skopeo with the make command, which borked with: -

CGO_CFLAGS="" CGO_LDFLAGS="-L/usr/lib/x86_64-linux-gnu -lgpgme -lassuan -lgpg-error" GO111MODULE=on go build -mod=vendor "-buildmode=pie" -ldflags '-X main.gitCommit=85546491235c78cf51efa1ca060f1d582d5e1ab1 ' -gcflags "" -tags "  " -o bin/skopeo ./cmd/skopeo
sed -e 's/\((skopeo.*\.md)\)//' -e 's/\[\(skopeo.*\)\]/\1/' docs/skopeo-login.1.md  | /root/go/bin/go-md2man -in /dev/stdin -out docs/skopeo-login.1
/bin/sh: 1: /root/go/bin/go-md2man: not found
make: *** [Makefile:143: docs/skopeo-login.1] Error 127

What I didn't realise is that I was missing a key dependency - go-md2man - which is described: -

go-md2man. Converts markdown into roff (man pages). Uses blackfriday to process markdown into man pages. Usage ./md2man -in /path/to/markdownfile.​md ...

This was easily fixed: -

apt-get install -y go-md2man

Reading package lists... Done
Building dependency tree       
Reading state information... Done
The following NEW packages will be installed:
  go-md2man
0 upgraded, 1 newly installed, 0 to remove and 26 not upgraded.
Need to get 655 kB of archives.
After this operation, 2,047 kB of additional disk space will be used.
Get:1 http://us.archive.ubuntu.com/ubuntu focal/universe amd64 go-md2man amd64 1.0.10+ds-1 [655 kB]
Fetched 655 kB in 1s (898 kB/s)    
Selecting previously unselected package go-md2man.
(Reading database ... 116777 files and directories currently installed.)
Preparing to unpack .../go-md2man_1.0.10+ds-1_amd64.deb ...
Unpacking go-md2man (1.0.10+ds-1) ...
Setting up go-md2man (1.0.10+ds-1) ...
Processing triggers for man-db (2.9.1-1) ...

and then validated: -

which go-md2man

/usr/bin/go-md2man

More importantly, my build completed: -

make clean

rm -rf bin docs/*.1

make

CGO_CFLAGS="" CGO_LDFLAGS="-L/usr/lib/x86_64-linux-gnu -lgpgme -lassuan -lgpg-error" GO111MODULE=on go build -mod=vendor "-buildmode=pie" -ldflags '-X main.gitCommit=85546491235c78cf51efa1ca060f1d582d5e1ab1 ' -gcflags "" -tags "  " -o bin/skopeo ./cmd/skopeo
sed -e 's/\((skopeo.*\.md)\)//' -e 's/\[\(skopeo.*\)\]/\1/' docs/skopeo-login.1.md  | /usr/bin/go-md2man -in /dev/stdin -out docs/skopeo-login.1
sed -e 's/\((skopeo.*\.md)\)//' -e 's/\[\(skopeo.*\)\]/\1/' docs/skopeo-list-tags.1.md  | /usr/bin/go-md2man -in /dev/stdin -out docs/skopeo-list-tags.1
sed -e 's/\((skopeo.*\.md)\)//' -e 's/\[\(skopeo.*\)\]/\1/' docs/skopeo-sync.1.md  | /usr/bin/go-md2man -in /dev/stdin -out docs/skopeo-sync.1
sed -e 's/\((skopeo.*\.md)\)//' -e 's/\[\(skopeo.*\)\]/\1/' docs/skopeo-copy.1.md  | /usr/bin/go-md2man -in /dev/stdin -out docs/skopeo-copy.1
sed -e 's/\((skopeo.*\.md)\)//' -e 's/\[\(skopeo.*\)\]/\1/' docs/skopeo-standalone-sign.1.md  | /usr/bin/go-md2man -in /dev/stdin -out docs/skopeo-standalone-sign.1
sed -e 's/\((skopeo.*\.md)\)//' -e 's/\[\(skopeo.*\)\]/\1/' docs/skopeo-standalone-verify.1.md  | /usr/bin/go-md2man -in /dev/stdin -out docs/skopeo-standalone-verify.1
sed -e 's/\((skopeo.*\.md)\)//' -e 's/\[\(skopeo.*\)\]/\1/' docs/skopeo-inspect.1.md  | /usr/bin/go-md2man -in /dev/stdin -out docs/skopeo-inspect.1
sed -e 's/\((skopeo.*\.md)\)//' -e 's/\[\(skopeo.*\)\]/\1/' docs/skopeo-manifest-digest.1.md  | /usr/bin/go-md2man -in /dev/stdin -out docs/skopeo-manifest-digest.1
sed -e 's/\((skopeo.*\.md)\)//' -e 's/\[\(skopeo.*\)\]/\1/' docs/skopeo-logout.1.md  | /usr/bin/go-md2man -in /dev/stdin -out docs/skopeo-logout.1
sed -e 's/\((skopeo.*\.md)\)//' -e 's/\[\(skopeo.*\)\]/\1/' docs/skopeo.1.md  | /usr/bin/go-md2man -in /dev/stdin -out docs/skopeo.1
sed -e 's/\((skopeo.*\.md)\)//' -e 's/\[\(skopeo.*\)\]/\1/' docs/skopeo-delete.1.md  | /usr/bin/go-md2man -in /dev/stdin -out docs/skopeo-delete.1

No comments:

Yay, VMware Fusion and macOS Big Sur - no longer "NAT good friends" - forgive the double negative and the terrible pun ...

After macOS 11 Big Sur was released in 2020, VMware updated their Fusion product to v12 and, sadly, managed to break Network Address Trans...