Release the man page

[spl]

I discovered MANPAGE.md and MANPAGE-render.bash for rendering the Markdown file using Pandoc. I think it would be nice to have this man page included along with gocryptfs, whichever way it is installed.

I suppose there are two basic ways for getting the rendered man page into a target installation:

1. Require packagers to use Pandoc as a build dependency and run MANPAGE-render.bash to generate the man page. For source packaging, this means that Pandoc must be installed on the user's computer.
2. Generate the man page with Pandoc as part of the release process and include it in the release archives.

From a packaging and user's perspective, avoiding an extra dependency such as Pandoc is nice. There is, of course, plenty of software that requires an extra dependency for building documentation, so this is not that unusual.

From a gocryptfs developer's perspective, depending on the release process, it might be nice to avoid installing yet another tool and adding this extra step.

(For my own context, I installed gocryptfs on macOS with Homebrew. The current formula uses the gocryptfs_v1.6.1_src-deps.tar.gz release archive. I don't know how the Homebrew folk generally view having a build dependency for documentation, but if that is the preferred goal, it doesn't hurt to ask.)

It seems like option 1 is the current situation, but I think option 2 is better, esp. if it can be automated to ease the maintenance burden.

[rfjakob]

So the "usual way" is (1), which is what Debian, Arch and Ubuntu do. I'm surprised that installing through homebrew does not install the man page.

I see the point of avoiding the pandoc dependency. Looking at https://formulae.brew.sh/formula/gocryptfs , what does "bottle" mean? Pre-built binaries?

[rfjakob]

PS: The binary releases at https://github.com/rfjakob/gocryptfs/releases do include the man page.

[lechner]

In Debian, we call pandoc a build dependency and not a regular dependency. It is used only once, on each architecture, to generate the man pages. We do that on our build servers. A user of your software will not need to install pandoc to use gocryptfs.

[spl]

Looking at https://formulae.brew.sh/formula/gocryptfs , what does "bottle" mean? Pre-built binaries?

@rfjakob Yes, pretty much. Homebrew, in general, is a build-from-source distribution but provides binaries of homebrew-core formulae for multiple macOS versions as a convenience.

The binary releases at https://github.com/rfjakob/gocryptfs/releases do include the man page.

@rfjakob What is the difference in the way the linux-static, src, and src-deps releases are built? Could these be unified such that all of them include the man page?

In Debian, we call pandoc a build dependency and not a regular dependency.

@lechner Right, that is the same terminology I used in the report above.

A user of your software will not need to install pandoc to use gocryptfs.

@lechner It's true that a user does not need Pandoc to use gocryptfs, but I'm guessing you mean that a user will not need Pandoc to render the man page. That depends on how the user obtains gocryptfs. A user obtaining a .deb may not need Pandoc, but a user downloading a GitHub source release or using a source-based package (such as the one from Homebrew) does not currently have access to the man page without Pandoc.

I guess the question comes down to whether the GitHub release process for gocryptfs should be changed to include rendering and releasing the man page. If the answer is no, I'll go over to Homebrew and query about adding Pandoc as a build dependency to include the man page.

[rfjakob]

As it does not really cause extra work during the release process, I will include the man pages in the source tarball ( commit 61940a9 ).

What is the difference in the way the linux-static, src, and src-deps releases are built

Well, linux-static is the compiled binary plus the generated man pages, while "src" and "src-deps" only zips up the source files. Now it also generates the man pages and includes them.