Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Release the man page #355

Closed
spl opened this issue Jan 18, 2019 · 5 comments

Comments

@spl
Copy link

commented Jan 18, 2019

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

This comment has been minimized.

Copy link
Owner

commented Jan 20, 2019

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 rfjakob added the MacOS label Jan 20, 2019
@rfjakob

This comment has been minimized.

Copy link
Owner

commented Jan 20, 2019

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

@lechner

This comment has been minimized.

Copy link
Contributor

commented Jan 20, 2019

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

This comment has been minimized.

Copy link
Author

commented Jan 21, 2019

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 added a commit that referenced this issue Mar 2, 2019
This gives users who build from the source tarball, but
do not want to install pandoc, access to the man pages.

Requested at
#355
rfjakob added a commit that referenced this issue Mar 2, 2019
This gives users who build from the source tarball, but
do not want to install pandoc, access to the man pages.

Apperently the gocryptfs homebrew package ships without
the man pages at the moment to avoid pandoc.

Requested at
#355
@rfjakob

This comment has been minimized.

Copy link
Owner

commented Mar 2, 2019

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.

@rfjakob rfjakob closed this Mar 2, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
3 participants
You can’t perform that action at this time.