search

sharkdp / hexyl

A command-line hex viewer
Apache License 2.0
8.92k stars 227 forks source link

Add hexyl.1 man page to source tree? #159

Closed 0323pin closed 1 year ago

0323pin commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

@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:

sharkdp commented 2 years ago

ping @sorairolake: what do you think?

sorairolake commented 2 years ago

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

0323pin commented 2 years ago

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

sharkdp commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

@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 commented 2 years ago

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

sharkdp commented 2 years ago

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 commented 2 years ago

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

sharkdp commented 1 year ago

@0323pin would that work for you?

0323pin commented 1 year ago

@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 commented 1 year ago

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 commented 1 year ago

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 commented 1 year ago

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 commented 1 year ago

... 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 commented 1 year ago

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

0323pin commented 9 months ago

@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.