There are no man pages

[ghost]

People are making packages for Monocypher, e.g. one in AUR and the one for Void Linux in progress, which is interesting. However, Monocypher decidedly does currently not really work as a package.

• The AUR package currently installs monocypher.c into /usr/include, which is questionable at best. However, Monocypher cannot be built as a library. Maybe doing so is overkill or unnecessarily complex in terms of encumberance of the build path. It is already currently broken with BSD make and requires GNU make. Dynamic libraries should probably be discouraged as Monocypher intends to be fairly static in the first place.
• There are no man pages. Any self-respecting C library supplies man pages. The manual is currently on the website. If going down this path, mandoc is probably the way to go (supported natively by GNU man, but always puts "BSD General Commands Manual" in the heading; man on at least FreeBSD and OpenBSD natively support it because they use it; not sure about macOS/Solaris/that one guy probably running on VMS). It's semantic (e.g. .Nm inserts the program name and formats it as expected, as opposed to manual repetition and formatting on old-style man/roff pages), which allows searching by macro keys like apropos Fa=ad to find all man pages referencing a function argument ad. Sensible mandoc guidelines can be found on OpenBSD mdoc(7). Otherwise, ronn exists.

[LoupVaillant]

Disclaimer: I know nothing whatsoever about packaging for Linux distributions. I can't even autotool —nor want to.

I'm not sure what possessed the AUR packager to put a C file in /usr/include, I thought only header files belonged there. Instead, the package should put something like libmonocypher.o in /usr/lib. Compiling this library is as simple as gcc -O3 -c monocypher.c -o ./usr/lib/libmonocypher.o.

The current makefile is not intended to build Monocypher, but to test it. I should have put it in the tests folder. I won't, because I plan to drastically modify the test suite, to increase the portability of the test suite, and simplify external auditing, as I said in #14.

In any case, Monocypher can totally be built as a library. You don't even need a makefile, just use whatever compiler your platform provides.

---

I'm not sure how we should handle man pages. Perhaps converting the current manual with something like md2man would suffice?

If not, I have to confess I know nothing about writing man pages. I'll need external contributions.

[LoupVaillant]

Disclaimer: I know nothing whatsoever about packaging for Linux distributions. I can't even autotool —nor want to.

I'm not sure what possessed the AUR packager to put a C file in /usr/include, I thought only header files belonged there. Instead, the package should put something like libmonocypher.o in /usr/lib. Compiling this library is as simple as gcc -O3 -c monocypher.c -o ./usr/lib/libmonocypher.o.

The current makefile is not intended to build Monocypher, but to test it. I should have put it in the tests folder. I won't, because I plan to drastically modify the test suite, to increase the portability of the test suite, and simplify external auditing, as I said in #14.

In any case, Monocypher can totally be built as a library. You don't even need a makefile, just use whatever compiler your platform provides.

---

I'm not sure how we should handle man pages. Perhaps converting the current manual with something like md2man would suffice?

If not, I have to confess I know nothing about writing man pages. I'll need external contributions.

[ghost]

I just checked, it seems mandoc or at least semantic man pages are also understood on macOS.

---

md2man/ronn would kind of suffice with a lot of symlinks, but it'd be awkward to read as an all-in-one man page (see ev(3) for a particularly egregious example). You'd also obviously lose the semantic stuff from mandoc.

man(1) can export as HTML if desired, though mandoc gets prettier results in terms of HTML output than GNU man.

I'd like to suggest this:

I'll convert the existing manual into manual pages. Once the more touchy parts of it are handled, you should be able to work with the format as well. I'll likely do stylistic changes in tone (e.g. "Using it directly is just asking for trouble. Please don't." => "Using it directly is highly error-prone. Thus, such usage is discouraged.") to match the rest of the C library man pages. Some parts, such as general advice like "Avoid swapping secrets to disk" would get a dedicated page linked in the SEE ALSO section of every page.

If you find the format approachable enough, writing an index/overview page and using man.cgi(8) or pre-exporting HTML files may be able to replace the existing manual. This would be beneficial mainly to avoid duplicating every change in the manual, which still semi-frequently happens.

How does that sound to you?

[ghost]

I just checked, it seems mandoc or at least semantic man pages are also understood on macOS.

---

md2man/ronn would kind of suffice with a lot of symlinks, but it'd be awkward to read as an all-in-one man page (see ev(3) for a particularly egregious example). You'd also obviously lose the semantic stuff from mandoc.

man(1) can export as HTML if desired, though mandoc gets prettier results in terms of HTML output than GNU man.

I'd like to suggest this:

I'll convert the existing manual into manual pages. Once the more touchy parts of it are handled, you should be able to work with the format as well. I'll likely do stylistic changes in tone (e.g. "Using it directly is just asking for trouble. Please don't." => "Using it directly is highly error-prone. Thus, such usage is discouraged.") to match the rest of the C library man pages. Some parts, such as general advice like "Avoid swapping secrets to disk" would get a dedicated page linked in the SEE ALSO section of every page.

If you find the format approachable enough, writing an index/overview page and using man.cgi(8) or pre-exporting HTML files may be able to replace the existing manual. This would be beneficial mainly to avoid duplicating every change in the manual, which still semi-frequently happens.

How does that sound to you?

[LoupVaillant]

That actually sounds pretty good. It will take time however. First, I need to sort out this whole packaging issue. Second, I need to learn how to write and index man pages.

[LoupVaillant]

That actually sounds pretty good. It will take time however. First, I need to sort out this whole packaging issue. Second, I need to learn how to write and index man pages.

[ghost]

Alright. Just tell me when I should get started and I'll get on the manpagification.

[ghost]

Alright. Just tell me when I should get started and I'll get on the manpagification.

[LoupVaillant]

Actually, the manpagification and the packaging work I want to do can be done in parallel. The only reason I wanted to do the packaging first is because I think it's more urgent.

So, you can start right away. 😄

[LoupVaillant]

Actually, the manpagification and the packaging work I want to do can be done in parallel. The only reason I wanted to do the packaging first is because I think it's more urgent.

So, you can start right away. 😄

[ghost]

I've tried to transform the current manual into a set of manual pages, see https://github.com/CuleX/Monocypher/commit/04c6b9d31a97ef2995f5c7df0f1dfe54a2f39ca5. Symlinks pending. Do you think this would be workable, especially for future maintenance of the manual by you? Note I've made some changes to the text in some places and added an example to crypto_lock.

I've also compiled an amalgamation of the man pages onto a single HTML page for more convenient reading of the current state; a proper deployment would probably auto-generate links for inter-man-page navigation. This would require multiple files, of course. I didn't look too closely into this since I'm not sure how you want to handle generation of the HTML version in the first place and especially on what OS. OpenBSD mandoc -T html probably needs different CSS and parameters for link generation than Linux man -T html. mandoc -T markdown (on OpenBS) version has proven itself shaky with the code listings and list handling.

[ghost]

I've tried to transform the current manual into a set of manual pages, see https://github.com/CuleX/Monocypher/commit/04c6b9d31a97ef2995f5c7df0f1dfe54a2f39ca5. Symlinks pending. Do you think this would be workable, especially for future maintenance of the manual by you? Note I've made some changes to the text in some places and added an example to crypto_lock.

I've also compiled an amalgamation of the man pages onto a single HTML page for more convenient reading of the current state; a proper deployment would probably auto-generate links for inter-man-page navigation. This would require multiple files, of course. I didn't look too closely into this since I'm not sure how you want to handle generation of the HTML version in the first place and especially on what OS. OpenBSD mandoc -T html probably needs different CSS and parameters for link generation than Linux man -T html. mandoc -T markdown (on OpenBS) version has proven itself shaky with the code listings and list handling.

[LoupVaillant]

Excellent work, thank you.

This is definitely workable. I'm not sure I like the markup language, but I can work with it. Your changes are very good (especially those for Argon2i). Apart from a word here and there I may want to change, I think we should keep them as they are.

I found a small copy paste error in man/3monocypher/crypto_argon2i.3monocypher.

The HTML page should be workable. I'll need to think of better solutions in the long run, but it is probably good enough to replace the current manual.

[LoupVaillant]

Excellent work, thank you.

This is definitely workable. I'm not sure I like the markup language, but I can work with it. Your changes are very good (especially those for Argon2i). Apart from a word here and there I may want to change, I think we should keep them as they are.

I found a small copy paste error in man/3monocypher/crypto_argon2i.3monocypher.

The HTML page should be workable. I'll need to think of better solutions in the long run, but it is probably good enough to replace the current manual.

[ghost]

I'm not sure where you found that copy/paste error. Line 131 you linked is a cross-reference to crypto_memcmp. This seems correct to me.

---

The HTML page, as I said, can be generated (with some manual intervention because otherwise the separation between each man page makes the all-in-one confusing). I'll put the aux file (style.css) into the repo as well.

Using mandoc is highly recommended as the groff HTML output is fairly terrible, even though everything looks fine on console (i.e. man 3monocypher crypto_argon2i looks okay, groff -mandoc -Thtml crypto_argon2i.3monocypher > crypto_argon2i.3monocypher.html looks awful).

I've used mandoc as packaged in Debian (package name "mandoc") this time, it looks like that produces similar results as OpenBSD mandoc; it uses emph over Em as CSS class for emphasized elements and the id fields are randomly generated, but those will probably be fixed in a newer mandoc synced with OpenBSD. I am on Debian stable after all.

I've also switched it to multi-page mode for now and generated links. This should be more convenient than manually horsing with the (manually compiled) HTML page. One issue with that is that the Xrs in intro(3) become invalid (because we have no man pages for system-specific things like mlock(2), etc.). Tell me if you want those to be Fn instead to

for i in *.3monocypher; do
  mandoc -Oman=%N.%S.html -Ostyle=style.css -Thtml $i > $i.html
done

Result: https://culex.github.io/Monocypher/intro.3monocypher.html

[ghost]

I'm not sure where you found that copy/paste error. Line 131 you linked is a cross-reference to crypto_memcmp. This seems correct to me.

---

The HTML page, as I said, can be generated (with some manual intervention because otherwise the separation between each man page makes the all-in-one confusing). I'll put the aux file (style.css) into the repo as well.

Using mandoc is highly recommended as the groff HTML output is fairly terrible, even though everything looks fine on console (i.e. man 3monocypher crypto_argon2i looks okay, groff -mandoc -Thtml crypto_argon2i.3monocypher > crypto_argon2i.3monocypher.html looks awful).

I've used mandoc as packaged in Debian (package name "mandoc") this time, it looks like that produces similar results as OpenBSD mandoc; it uses emph over Em as CSS class for emphasized elements and the id fields are randomly generated, but those will probably be fixed in a newer mandoc synced with OpenBSD. I am on Debian stable after all.

I've also switched it to multi-page mode for now and generated links. This should be more convenient than manually horsing with the (manually compiled) HTML page. One issue with that is that the Xrs in intro(3) become invalid (because we have no man pages for system-specific things like mlock(2), etc.). Tell me if you want those to be Fn instead to

for i in *.3monocypher; do
  mandoc -Oman=%N.%S.html -Ostyle=style.css -Thtml $i > $i.html
done

Result: https://culex.github.io/Monocypher/intro.3monocypher.html

[LoupVaillant]

I'm not sure where you found that copy/paste error. Line 131 you linked is a cross-reference to crypto_memcmp. This seems correct to me.

Oops, sorry, that was me misreading the man source (I haven't tried to view it normally).

The HTML page, as I said, can be generated. I'll put the aux file (style.css) into the repo as well.

Of course, I was just wondering whether we could delete the current MANUAL.md. I'm now convinced that we can.

The auxiliary style.css is a good idea, this will help users view the doc offline. (I won't use it for my own web site, but that's just me wanting to use my own style sheet.)

I've also switched it to multi-page mode for now and generated links.

This looks perfect. I'm sold. I'll try to compile them myself, shouldn't be a problem. Worst case, I'll use sed to correct any weird stuff and adapt it to my web site.

One issue with that is that the Xrs in intro(3) become invalid (because we have no man pages for system-specific things like mlock(2), etc.).

Yeah, making those Fn is probably best, especially if it doesn't affect console users. Wouldn't like to have dead links.

[LoupVaillant]

I'm not sure where you found that copy/paste error. Line 131 you linked is a cross-reference to crypto_memcmp. This seems correct to me.

Oops, sorry, that was me misreading the man source (I haven't tried to view it normally).

The HTML page, as I said, can be generated. I'll put the aux file (style.css) into the repo as well.

Of course, I was just wondering whether we could delete the current MANUAL.md. I'm now convinced that we can.

The auxiliary style.css is a good idea, this will help users view the doc offline. (I won't use it for my own web site, but that's just me wanting to use my own style sheet.)

I've also switched it to multi-page mode for now and generated links.

This looks perfect. I'm sold. I'll try to compile them myself, shouldn't be a problem. Worst case, I'll use sed to correct any weird stuff and adapt it to my web site.

One issue with that is that the Xrs in intro(3) become invalid (because we have no man pages for system-specific things like mlock(2), etc.).

Yeah, making those Fn is probably best, especially if it doesn't affect console users. Wouldn't like to have dead links.

[ghost]

See #22. This does not fix this issue entirely since you want to sort out this whole packaging issue.

I'm not sure what else you want to see done, though, or alternatively, what information you need to make the relevant decisions.

[ghost]

See #22. This does not fix this issue entirely since you want to sort out this whole packaging issue.

I'm not sure what else you want to see done, though, or alternatively, what information you need to make the relevant decisions.

[LoupVaillant]

Merged, thanks.

The current issue ended up being about man pages only, so I'm closing it and open #24 to deal with the packaging issue.

[LoupVaillant]

Merged, thanks.

The current issue ended up being about man pages only, so I'm closing it and open #24 to deal with the packaging issue.