As a user, I'd like a man page available after installing Bombadillo #38

New Issue

asdf · 2019-09-20T08:02:32Z

asdf commented

2019-09-20 08:02:32 +00:00

This activity is in two parts:

Writing a man page
Packaging the man page with the application, and ensuring it is available when installed

Writing a man page could be done manually, or with the help of a tool like help2man. There are also other tools that streamline all documentation, and allow generation of a man page from existing work.

For packaging, from what I understand, go install can't be configured to install a man page. I don't think there is any Go-specific way to install non-program, supporting files. The options available might be:

install.sh or makefile to script installation
dpkg, rpm, snap, flatpak, docker or some other packaging method

For gfu I'm going to investigate a simple approach, with an install script or makefile and help2man. I know there is a suggestion for snap packaging, so that might be another option here.

Please feel free to update with any additional information or suggestions.

This activity is in two parts: 1. Writing a man page 2. Packaging the man page with the application, and ensuring it is available when installed Writing a man page could be done manually, or with the help of a tool like [help2man](https://www.gnu.org/software/help2man/). There are also other tools that streamline all documentation, and allow generation of a man page from existing work. For packaging, from what I understand, `go install` can't be configured to install a man page. I don't think there is any Go-specific way to install non-program, supporting files. The options available might be: - install.sh or makefile to script installation - dpkg, rpm, snap, flatpak, docker or some other packaging method For [gfu](https://tildegit.org/sloum/gfu) I'm going to investigate a simple approach, with an install script or makefile and help2man. I know there is a suggestion for snap packaging, so that might be another option here. Please feel free to update with any additional information or suggestions.

👍 1

asdf self-assigned this 2019-09-20 08:02:32 +00:00

asdf added the

enhancement

help wanted

labels 2019-09-20 08:02:32 +00:00

sloum commented

2019-09-20 15:20:17 +00:00

Thank you for adding this issue. We've been talking about it for awhile and I've been thinking on it for even longer. I definitely want this to happen. My preliminary look at snap packages, which seem like the lowest barrier to entry packaging, makes it seem like a makefile will be necessary there as well, but that the makefile wont need to build the go application, just handle the makefile installation. I could be wrong though. I'm going to try to find some more examples and I'll report back. If anyone reading this knows about snappy or manpages and go, please comment!

Also, thanks for the link @asdf, I'll read through it today and see what I can make happen for bombadillo. I think gfu will be a good test case for this type of thing.

Thank you for adding this issue. We've been talking about it for awhile and I've been thinking on it for even longer. I definitely want this to happen. My preliminary look at snap packages, which seem like the lowest barrier to entry packaging, makes it seem like a makefile will be necessary there as well, but that the makefile wont need to build the go application, just handle the makefile installation. I could be wrong though. I'm going to try to find some more examples and I'll report back. If anyone reading this knows about snappy or manpages and go, please comment! Also, thanks for the link @asdf, I'll read through it today and see what I can make happen for bombadillo. I think gfu will be a good test case for this type of thing.

sloum commented

2019-09-21 21:47:45 +00:00

I have a rough draft (incomplete) man page built. It is now a part of the v2-restructure branch. Once the branch is checked out/pulled you should be able to run man ./bombadillo.1 from within the main repo directory to see it.

Most of it was generated by using this script I found:
https://github.com/mvertes/txt2man

I did go in and make some edits by hand to do some things that were difficult to get to work correctly via the script.

I def recommend that script as an easy start to manpages. It looks pretty good all in all too, I think. I'll likely want to add some more sections, but it should be a good start.

That should take care of item one, at least in concept. I'll start looking into make and see what I can get to happen. If I can get it to install the man page properly, that would be a good start. Then just figure out snap packages and I'm set.

Additionally, gemini support is now live for v2-restructure along with a lot of better/more powerful/flexible command versions. I have a few more enhancements (checking settings for valid values and not allowing invalid values), but I may be getting close to the point where more input and more people using it might be valuable.

Once it seems stable enough (it should be pretty close, at least as good or better than the 1.x series currently), and the packaging is ready: 2.0 release! I may buy a domain as well and have a dedicated page for it. We'll see? Also, I plan on doing an authors section on the manpage and I'd like to list you and jboverf (who contributed to the 1.x series in really nice ways and helped me learn a lot of cool stuff). If you think that is an ok idea, let me know (here or via email or the like) what name you would like credited as (asdf is fine, or an irl name... dealers choice).

I have a rough draft (incomplete) man page built. It is now a part of the `v2-restructure` branch. Once the branch is checked out/pulled you should be able to run `man ./bombadillo.1` from within the main repo directory to see it. Most of it was generated by using this script I found: https://github.com/mvertes/txt2man I did go in and make some edits by hand to do some things that were difficult to get to work correctly via the script. I def recommend that script as an easy start to manpages. It looks pretty good all in all too, I think. I'll likely want to add some more sections, but it should be a good start. That should take care of item one, at least in concept. I'll start looking into make and see what I can get to happen. If I can get it to install the man page properly, that would be a good start. Then just figure out snap packages and I'm set. Additionally, gemini support is now live for `v2-restructure` along with a lot of better/more powerful/flexible command versions. I have a few more enhancements (checking settings for valid values and not allowing invalid values), but I may be getting close to the point where more input and more people using it might be valuable. Once it seems stable enough (it should be pretty close, at least as good or better than the 1.x series currently), and the packaging is ready: 2.0 release! I may buy a domain as well and have a dedicated page for it. We'll see? Also, I plan on doing an authors section on the manpage and I'd like to list you and jboverf (who contributed to the 1.x series in really nice ways and helped me learn a lot of cool stuff). If you think that is an ok idea, let me know (here or via email or the like) what name you would like credited as (asdf is fine, or an irl name... dealers choice).

sloum self-assigned this 2019-09-21 21:47:58 +00:00

asdf commented

2019-09-22 11:42:07 +00:00

The man file looks pretty good! It's like a mark of authenticity...real programs have man files. I'll try this for gfu next along with the makefile installer.

The content seems pretty complete as it is. Other man pages tend to have sections for 'Environment variables' and 'See also' which might not apply. It could be finalised by adding sections for:

license/copyright
bugs (link to this repo)
authors (including a link to the homepage)

When you're ready, let me know and I'll review the document for errors.

v2 is really coming together. I've used it instead of v1 for a few days now with no real issues. Gemini support is great and the release plans are exciting! Do let me know when you're ready for me to review and report any issues.

Thanks for the addition to the authors list. I'd be happy with ~asdf I guess? Not sure, but it's cool.

The man file looks pretty good! It's like a mark of authenticity...real programs have man files. I'll try this for gfu next along with the makefile installer. The content seems pretty complete as it is. Other man pages tend to have sections for 'Environment variables' and 'See also' which might not apply. It could be finalised by adding sections for: - license/copyright - bugs (link to this repo) - authors (including a link to the homepage) When you're ready, let me know and I'll review the document for errors. v2 is really coming together. I've used it instead of v1 for a few days now with no real issues. Gemini support is great and the release plans are exciting! Do let me know when you're ready for me to review and report any issues. Thanks for the addition to the authors list. I'd be happy with ~asdf I guess? Not sure, but it's cool.

sloum commented

2019-09-22 15:15:19 +00:00

I agree. It makes it feel like a real program for people to use.

Definitely let me know how things go with the makefile. Do you have experience with them? I've done a very little bit of c coding, but I never needed to put together a makefile for any of it.

Those would be good sections to add. I think I may also want to add a dependencies section (bombadillo depends on tput and stty being present on a system... which essentially means gnu coreutils or the bsd equivalent).

I want to fix relative linking (which is broken) for gemini. But then I think I'd appreciate some review/feedback on issues. I'll let you know.

~asdf sounds good.

I agree. It makes it feel like a real program for people to use. Definitely let me know how things go with the makefile. Do you have experience with them? I've done a very little bit of c coding, but I never needed to put together a makefile for any of it. Those would be good sections to add. I think I may also want to add a dependencies section (bombadillo depends on `tput` and `stty` being present on a system... which essentially means gnu coreutils or the bsd equivalent). I want to fix relative linking (which is broken) for gemini. But then I think I'd appreciate some review/feedback on issues. I'll let you know. `~asdf` sounds good.

sloum commented

2019-10-23 05:35:17 +00:00

This issue is solved by this #56

It is also addressed, as a part of the installation rather than just a file presence, by #57 and #59

I am closing the issue. This will definitely be a part of the 2.0.0 release and has made its way into develop.

This issue is solved by this #56 It is also addressed, as a part of the installation rather than just a file presence, by #57 and #59 I am closing the issue. This will definitely be a part of the 2.0.0 release and has made its way into `develop`.

sloum closed this issue

2019-10-23 05:35:17 +00:00

Sign in to join this conversation.