Closed ethamck closed 11 months ago
Thank you @ethamck for packaging wiki-tui!
The generation of a man page would certainly be possible. After a bit of research, I've found a documentation page detailing the automatic generation of a man page with the clap_mangen
crate. If we can get around the problem of packaging it with our release (I'm not familiar with the installation / packaging of man pages, do you know more about it?), we can automatically generate the man page for the CLI arguments.
For the man page of the documentation, we cannot generate it automatically as the documentation is formatted for the website. We can, however, generate it manually with the man crate (see here). If we then consistently update the generation script when we make changes to the documentation, it should work. Again, what do you think about it?
@all-contributors please add @ethamck for platform
Note: did not work the first time, deleted my first comment
@Builditluc
I've put up a pull request to add @ethamck! :tada:
@ethamck would you mind adding the installation instructions to the docs and opening a PR?
cp wiki-tui.1 /usr/share/man/man1/wiki-tui.1
into the packaging script. Void has a wrapper function (vman()
) for this.
wiki-tui.1
for command information and wiki-tui.5
for config information.
wiki-tui/usr/share/man/...
directory, though I'm not sure that this would help other package formats. It may be slightly more "correct" and what is encouraged in Void.pandoc
can convert Markdown to mandoc/roff
% wiki-tui(1) | User Commands
or something similar (can't remember the exact spec necessary) into the top of the fileNAME
, SYNOPSIS
, DESCRIPTION
, etc.man
knows what to boldWith all that said, I'm not sure that any of the documentation would be appropriate to convert to man
anyway. Most of the information is littered about multiple pages, rather than the API-spec-esque format that you'd expect with a man page. I suppose to that end it is up to you in what way the pages should be maintained.
sway may be worth looking into as an example of a configuration file man page. They use the scd
format, which appears similar to Markdown to write. I haven't investigated this further.
- "Packaging a man page"
Okay, so when we include the generated man page in the cargo binary, the packaging script of each individual platform can then copy the man page to the designated location (or not if it doesn't want to). For the sake of simplicity, I would prefer having the man pages either in the root directory (but that's already pretty crowded) or in the docs/
folder. About the build script: It basically allows us to generate the CLI man page directly from the rust code defining it.
pandoc
Thank you for the information on pandoc, it sounds very interesting! Basically, I want to prevent having to maintain two different file(s) for the configuration docs so we need a tool / format that: a compiles into a man page and b can be displayed in a documentation site on the web. I'm open to any suggestions from your end for what we can use for it.
After looking a while on the web on how some other tools do this, I found not all that much. From what I can see, the program either exclusively uses man pages or exclusively uses a website for documentation (the website generated from some custom markdown).
I believe I've found something to work with.
It would definitely require a bit more research and testing into it to see whether this would work out the way we want it to. Also we would have to structure the configuration documentation more like a man page (that would probably be advisable anyways).
Currently, I don't have the time to do that alone because of the changes in the UI, but if you want you can try to get it working or develop a better solution!
I've packaged
wiki-tui
into the Void Linux repositories and it should now be freely installable for users of the distro via# xbps-install -S wiki-tui
.https://github.com/void-linux/void-packages/pull/45438
P.S. I'm not well versed on generating one from Rust, but a man page would be handy to generate for the program going forward. From what I can tell, the
wiki-tui -h
function returns text that would need to be converted to mandoc. Additionally, multiple sections of a program document can be specified, so it could be possible to runman 5 wiki-tui
for information on itsconfig.toml
format without having to find the website for documentation (which as of current you'd need to look up yourself if you installed the package just by browsing the repos).