Add hexyl.1 man page to source tree?

[0323pin]

Hi,

Thank you for a new release. I was looking into updating the package for NetBSD and realized the man page is provided in markdown.
Would it possible to provide the man page in the man page Unix format, i.e. like hexyl.1 or hexyl.1.gz ? It would be desirable to avoid the need of external build dependencies for a simple man page.

TIA

[sharkdp]

Thank you for packaging hexyl for NetBSD! The idea is that we auto-generate the man page from that markdown document. The tarballs on the release page will include the generated hexyl.1 file. If you want to build from source, please see the instructions here, which include a paragraph about the man page.

Hope this workflow works for package maintainers.

[0323pin]

@sharkdp Thank you for your reply. This doesn't solve the issue, though.
pandoc is in haskell and non-portable to all the arch's supported by NetBSD.
This leaves me with 3 choices:

• ignore the existence of the man page
• generate it locally at every update and upload it to the servers
• ask you (upstream) to provide it in the desired format.

[sharkdp]

ping @sorairolake: what do you think?

[sorairolake]

@sharkdp I think it can be solved by including the generated file in the repo. This makes both maintainability and portability.

[0323pin]

@sorairolake and @sharkdp from our perspective this is the most welcome solution.

[sharkdp]

So.. how would we ensure that they are in sync? Change the CI stage to also generate the manpage to a temp file and then compare the output with the checked in hexyl.1 version?

[Rondom]

May I ask what kind of architectures we are talking about? What architecture has a working Rust compiler but no working Haskell compiler? I cannot speak for NetBSD, but at least in Debian, pandoc (and ghc) is not only available on arm, aarch64, x86 , x86_64, riscv64 but also on older and less common architectures like ia64, m68k, sparc64, s390x, ppc64, hppa, mipsel, mips64el...

I am tempted to argue that any solution that increases the cost of maintenance has to be balanced against the number of users trying to run hexyl on for instance a VAX running NetBSD (insert your architecture here).

Don't get me wrong, I really appreciate the work in keeping old or obscure architectures alive. I have been a user of Debian's powerpcspe port for years and was devastated to see the support for it in GCC go....

[0323pin]

@Rondom

What architecture has a working Rust compiler but no working Haskell compiler?

Honestly, I wouldn't know. I use plain x86_64 and don't keep track of the status for all the other architectures. But, I had a similar issue with another project a week earlier and asked internally on thoughts on how to handle this. Fortunately, in the other case, upstream just decided to provide the man page in the desired format.

I am tempted to argue that any solution that increases the cost of maintenance has to be balanced against the number of users trying to run hexyl on for instance a VAX running NetBSD (insert your architecture here).

Maybe but, that's not the point. I don't think a bunch of if ... then ... else ... endif at the packaging end is the best way to go. But, if you guys think so, I'll respect that. I can always define the package to install the markdown file into /share/doc/hexyl.
Also, as mentioned, I could convert it locally and upload a stand alone distfile. I'm just trying to get some form of consensus and understand the position of hexyl as a project.

[0323pin]

@sharkdp Could it simply be extracted back from one of the various tarballs you already provide as packages for different OS's?

[sharkdp]

I don't understand. The problem is not to generate the man page somehow. The question is whether we want the source file and the autogenerated man page to be in the repo. Accepting the risk that (1) contributors accidentally change the autogenerated file and (2) things are out of sync.

Both things can be solved somehow, but I'm personally not going to work on this. If someone wants to implement this, I'm happy to integrate a PR.

[Aaron-Rumpler]

Could we just have the CI add the generated man page separately alongside the existing release tarballs and deb packages?

[sharkdp]

@0323pin would that work for you?

[0323pin]

@0323pin would that work for you?

Yes, as long as it's in the release tarball (source code tar.gz, not a pre-packed binary), I can extract it and install.

Btw, one of todays commits :)
https://mail-index.netbsd.org/pkgsrc-changes/2022/12/05/msg264814.html

[sharkdp]

Yes, as long as it's in the release tarball, I can extract it and install.

But... that should already be the case?

▶ wget https://github.com/sharkdp/hexyl/releases/download/v0.11.0/hexyl-v0.11.0-x86_64-unknown-linux-gnu.tar.gz
▶ unp hexyl-v0.11.0-x86_64-unknown-linux-gnu.tar.gz  
hexyl-v0.11.0-x86_64-unknown-linux-gnu/CHANGELOG.md
hexyl-v0.11.0-x86_64-unknown-linux-gnu/LICENSE-APACHE
hexyl-v0.11.0-x86_64-unknown-linux-gnu/LICENSE-MIT
hexyl-v0.11.0-x86_64-unknown-linux-gnu/README.md
hexyl-v0.11.0-x86_64-unknown-linux-gnu/hexyl
hexyl-v0.11.0-x86_64-unknown-linux-gnu/hexyl.1  # <----

[0323pin]

But... that should already be the case?

Not really, we fetch Source code (tar.gz) and build it natively (the very last file in https://github.com/sharkdp/hexyl/releases/tag/v0.11.0)

~ > cd Downloads/
~/Downloads > tar -xf hexyl-0.11.0.tar.gz
~/Downloads > ls -a hexyl-0.11.0/doc/
drwxr-xr-x pin wheel 512 B  Mon Dec  5 09:52:27 2022  .
drwxr-xr-x pin wheel 512 B  Mon Dec  5 09:52:27 2022  ..
.rw-r--r-- pin wheel 3.4 KB Mon Dec  5 09:52:27 2022  hexyl.1.md
.rw-r--r-- pin wheel  12 KB Mon Dec  5 09:52:27 2022  logo.svg

It would be awesome if hexyl.1 would be in this tarball instead of hexyl.1.md. I understand if this is not possible.

[sharkdp]

I understand. But would it be feasible to download a second file? Either the man page directly (assuming it would be attached separately), or one of the existing tarballs (and you would simply only extraxct hexyl.1)...

[0323pin]

... would it be feasible to download a second file?

Yes, this is possible. I can look into this and fetch a second distfile, extract it and add it to the install.

[sharkdp]

Thank you. I'll tentatively close this, but feel free to comment here in case you need help. Thank you for packaging hexyl.

[0323pin]

@sharkdp Finally took the time to fix this and merged the change, http://mail-index.netbsd.org/pkgsrc-changes/2023/09/10/msg282373.html

I'm using go-md2man to generate hexyl.1 from the Markdown file.