Slight change in README, or a suggestion to really add manual.

[secworks]

Aloha!

The README.md states "There is a html version in doc/html/, that you can regenerate by executing the doc/man2html.sh script (this requires mandoc)."

the first part "There is a html version in doc/html/" is not really correct. The html version of the manual is not there. The html pages aren't that big so could we please add them instead of either (1) having users generate the pages, or (2) leave the repo (on Github) to go to the Monocypher to find the manual? Having the html files included would make the repo self contained manual-wise.

If not adding the pages, I would suggest changing the README text to state: "The html version of the manual can be regenerated by running the..." etc.

[LoupVaillant]

Well, it was written with the assumption that users would mostly grab the official release tarball. (Which by the way I should probably add to github). I still hesitate to add the generated files to the repo, but I could change the phrasing.

How about providing a link to the online manual in addition to mention something like "(If you pulled this from github, the html version must be generated with mandoc—see contributor notes below.)"?

[secworks]

(I come from a background where we used Perforce for everything (including GB large netlists and blobs) so I may have a different attitude towards storing generated files in repos than what most devs seem to have - I prefer knowing where a build is and is even able to put a label on released blobs.)

I think you should add the tarball to the repo. It can't be that big. And I think you should expect people to grab the repo from Github. Your home page is #1 on Google. But the repo is #2 and the search result gives a better summary. Github may well be the first place for Monocypher people goes to.

And add the generated documentation as part of the repo (can't be big and then people don't need to have mandoc). One thing it would allow is for people to easily add issues to specific points in the documentation directly at Github in a nice way. The online manual is good. Having the online manual online as part of the repo (which you can) is imho even better in many ways.

[secworks]

Markdown is a nice format too. ;-)

[ghost]

Note: Because this is probably a fairly bikeshed-y discussion, none of this is to be interpreted as a "+1" or "-1" to anything said. Do not think you now have to coordinate with my opinion as well. I'm in favor of a BDFL-style, top-down decision.

I think you should add the tarball to the repo. It can't be that big.

I'm fairly certain you're supposed to use the GitHub Releases feature to put tarballs and binaries onto GitHub, rather than putting them into the repository. I personally don't need two copies of the same code. I fail to see the added benefit of the tarball in the repo, but I'm more than willing to hear arguments in favor.

Wouldn't linking to the download page or to the latest tarball in the README.md solve your issue?

And add the generated documentation as part of the repo (can't be big and then people don't need to have mandoc). One thing it would allow is for people to easily add issues to specific points in the documentation directly at Github in a nice way. The online manual is good. Having the online manual online as part of the repo (which you can) is imho even better in many ways.

At this point, I'm wondering if the README.md just doesn't express Loup's thoughts accurately:

Well, it was written with the assumption that users would mostly grab the official release tarball. (Which by the way I should probably add to github).

Maybe make it very, very clear in the README.md, right after the "Manual" section that users are supposed to download the tarball, the repo is for people who want to work on Monocypher itself or its man pages.

The tarball contains the man pages and everything else you could ask for.

One thing it would allow is for people to easily add issues to specific points in the documentation directly at Github in a nice way.

I'm not sure how putting HTML or Markdown output into the repo would help that in any way, but maybe I just don't know how to use GitHub.

---

I'll just leave Raymond Chen's post on the FCIB here for your entertainment.

[LoupVaillant]

First, I don't like putting generated files in the repository. This isn't just a matter of size, this is a matter of mistaking generated files for source files. Hand made patches and other such ugliness.

Second, end users are supposed to grab an official release. Hopefully Especially now, we have all the bells and whistles associated with proper releases. The git repository is reserved for (aspiring) contributors. Most other projects I'm aware of do the same. Libsodium for instance does not keep generated makefiles in the repository. You need the autotools to build from it.

Third, I don't want to rely on GitHub. I don't control it, so it's the least I can do to not let it control me. The social network is amazing here but the flip side is the network effect. I'd rather not be part of the problem. Which is why I very much prefer linking to the official website than GitHub—even when linking from GitHub.

I've made some modifications to the README to help users find the tarball if they need it. I also make clear there are differences between the repository and the releases. (I do not mention that a cloned repository doesn't run the tests out of the box, but the error message I put in the makefile will do that, see #36).

But the repo is [2nd] and the search result gives a better summary.

Searching "monocypher" DuckDuckGo yiels these summaries:

• monocypher.org: Monocypher is a small, auditable, easy to use crypto library.
• github: Monocypher - An easy to use, easy to deploy crypto library

Google doesn't show monocypher.org at all in the results, it just points to my personal web site. I'll set up a redirection right away. Users will click on https://moncypher.org first.