Hello,

Étienne Mollier is creating a deb package for offpunk and pushing it
into Debian (Yeah!). That’s awesome, thanks to him :-)

But one point needed for a Debian package is a man page. Étienne created
one here:
https://salsa.debian.org/python-team/packages/offpunk/-/blob/debian/master/debian/offpunk.1

But I feel it would be a lot better to maintain our own upstream
manpage.

One option is having the groff man page in the repository.
Advantage: straightforward to do
Problem: groff is quite painful to read/edit.

Another option is maintaining a markdown file that would be converted to
groff by packagers using Pandoc
see :
https://www.howtogeek.com/682871/how-to-create-a-man-page-on-linux/

Advantage: lot easier to maintain
Problem: this is an extra step for packagers and I have no idea if they
are willing to do it.

What is your opinion on the matter? Do you have any previous experience
dealing with manpages?

Thanks for any feedback (and, yes, patch creating the manpage are
accepted)


--
Ploum - Lionel Dricot
Blog: https://www.ploum.net
Livres: https://ploum.net/livres.html

Ploum wrote:

> But I feel it would be a lot better to maintain our own upstream manpage.

I agree.

> Another option is maintaining a markdown file that would be converted to groff by packagers using Pandoc

A third option is to use scdoc¹ to convert a markdown'ish file to the man page format. Not that it is easier or better than using pandoc, it's just another possibility.

I use scdoc for timestamp(1)'s manpages, if someone wants to take a look:

 🔗 https://codeberg.org/kas/timestampit

I've given them a *.1.md extension as most hubs and forges thinks that *.scd is a super collider file, whatever that is.

> Problem: this is an extra step for packagers and I have no idea if they are willing to do it.

I'm maintaining the ArchLinux package for offpunk, and I _could_ include a “makedepend” of either pandoc or scdoc to compile the manpage. However, this has to be done for every distro offpunk is being packaged for.

Somehow I feel a better solution would be for the author to compile a man page (from pandoc, scdoc, …) and distribute the *.1 in the git repo.

I assume that such a man page doesn't change a lot, so the biggest workload will be to decide between groff, pandoc, scdoc (or something else entirely) and write the thing, possibly using Debian's version as a starting point.

Cheers,

  // Klaus

----
1. https://git.sr.ht/~sircmpwn/scdoc
-- 
Kʟᴀᴜꜱ Aʟᴇxᴀɴᴅᴇʀ Sᴇɪꜱᴛʀᴜᴘ 🇩🇰
https://magnetic-ink.dk/kas

On Fri, Mar 03, 2023 at 14:48:18 +0000, Ploum wrote:
> But one point needed for a Debian package is a man page. Étienne created
> one here:
> https://salsa.debian.org/python-team/packages/offpunk/-/blob/debian/master/debian/offpunk.1
> 
> But I feel it would be a lot better to maintain our own upstream
> manpage.

Manpages are essential in my opinion. Étienne's manpage is written in
man(7), the historical markup in which you use formatting to describe
syntax. I prefer mdoc(7), which uses _semantic markup_ which is then
formatted consistently. mdoc is designed to be easy to write. It is just
as portable as man, and generally better documented.

mdoc: https://mandoc.bsd.lv/

> One option is having the groff man page in the repository.
> Advantage: straightforward to do
> Problem: groff is quite painful to read/edit.

mdoc is very nice to write - there's an excellent introduction/guide
here: https://manpages.bsd.lv/mdoc.html
I write all my new manpages in it, and I have even written blog posts in
it.
The reference compiler, mandoc (well-written by OpenBSD folk) even has
an HTML output device, meaning you could view the manpage online - for
an example of this, see OpenBSD's online manpages, eg:
https://man.openbsd.org/

> Another option is maintaining a markdown file that would be converted to
> groff by packagers using Pandoc
> see :
> https://www.howtogeek.com/682871/how-to-create-a-man-page-on-linux/
> 
> Advantage: lot easier to maintain
> Problem: this is an extra step for packagers and I have no idea if they
> are willing to do it.

Pandoc is a huge dependency for a simple manpage. scdoc would be not as
bad, but for a simple manpage, there should not be a "compilation" step.
Zero dependencies is better than one.

Attached I have written a manpage in mdoc (largely based on the man one
above), and you may view the generated HTML page here:
https://tmp.bvnf.space/offpunk.1.html

~phoebos

On 23/03/03 09:54, phoebos - ben at bvnf.space wrote:
>Attached I have written a manpage in mdoc (largely based on the man one
>above), and you may view the generated HTML page here:
>https://tmp.bvnf.space/offpunk.1.html
>
Thanks a lot, I’ve committed that page, I feel it’s really good and it
could be improved later.


That means I will probably soon release 1.9 if there’s no objection




--
Ploum - Lionel Dricot
Blog: https://www.ploum.net
Livres: https://ploum.net/livres.html