search

stepchowfun / toast

Containerize your development and continuous integration environments. 🥂
Other
1.56k stars 39 forks source link

Add man page #419

Open hwittenborn opened 2 years ago

hwittenborn commented 2 years ago

Description It would be nice if Toast had a man page, as most big projects have them.

Alternatives considered No man page :p.

Additional context I'd be willing to set this up myself if needed. I'd probably use Asciidoctor, as it's what I'm most familiar with for writing man pages, but I'm wondering if requiring that as a build dependency would be fine by this project's maintainers.

stepchowfun commented 2 years ago

Thanks for filing this issue! I must confess, I have never written a man page before—but I'm happy to hear that Toast is now a contender among "big projects". I'm not necessarily opposed to introducing Asciidoctor into the build process (after all, Toast makes it easy to introduce dependencies!), however I would want to understand how the man page would be distributed and installed (via the installer script, Homebrew, etc.). I am also very nitpicky about things like grammar and punctuation. Would the man page essentially just contain the contents of the current README.md file (with some minor changes to account for the fact that the animations would not be included)?

Either way, I think this is a great idea.

hwittenborn commented 2 years ago

I would want to understand how the man page would be distributed and installed

Package managers that distribute Toast should be able to do it as long as you set it up in the build files of the package. Regarding GitHub releases, you could probably just add it to the Releases page or just create archives for each architecture that contain the man pages, though I'd argue that it'd be fine to have the user do all that manually anyway if they're installing from the Releases, and just leave the automatic setup to package managers.

Would the man page essentially just contain the contents of the current README.md file

I don't think the README file would be the best fit for it, just because of how man pages are usually layed out. This Wikipedia article has a brief listing of what each section might look like, and you can look at one of my projects if you'd like to see how it could work here.

Furthermore, you'd probably want to create a toast.8 and toastfile.5, the first for the manual for the CLI tool, and the latter for the manual on the toastfile file format.

The man page for man also has some good info on this if you want some more direct info.

hwittenborn commented 2 years ago

I'm happy to hear that Toast is now a contender among "big projects".

On that note, I did look at Vagrant briefly but found the utilization of YAML instead of Ruby for the config to be a lot better. I definitely think Toast has a lot going for it :)