wiki-tui is now packaged in Void repositories

[ethamck]

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.

void-linux/void-packages#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 run man 5 wiki-tui for information on its config.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).

[Builditluc]

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?

[Builditluc]

@all-contributors please add @ethamck for platform

Note: did not work the first time, deleted my first comment

[allcontributors]

@Builditluc

I've put up a pull request to add @ethamck! 🎉

[Builditluc]

@ethamck would you mind adding the installation instructions to the docs and opening a PR?

[ethamck]

1. "Packaging a man page" is more or less just inserting cp wiki-tui.1 /usr/share/man/man1/wiki-tui.1 into the packaging script. Void has a wrapper function (vman()) for this.
   • Essentially you can just make the build process output a man page wiki-tui.1 for command information and wiki-tui.5 for config information.
     • Optionally, this file could be built to the package's 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.
2. pandoc can convert Markdown to mandoc/roff
   • For this, you still need to follow some mandoc formalities, and the files you use for this may need some post-processing. Some of these I can recall right now include
     1. Inserting % wiki-tui(1) | User Commands or something similar (can't remember the exact spec necessary) into the top of the file
     2. Organizing the file by appropriate headings like NAME, SYNOPSIS, DESCRIPTION, etc.
     3. Using some wonky list formats for definition lists so man knows what to bold
   • I'm not sure how this would work in a Rust build process.
   • Information about this on the internet is either terse or sparse, so it may be hard to ensure that the way you're doing any of this is correct.

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

[Builditluc]

1. "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.

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

1. We generate a documentation site (like the current one) with rust-lang/mdbook from markdown files
2. We upload the site with github-pages to the web
3. We generate multiple man pages from the mdbook site using vv9k/mdbook-man
   • Each "Chapter" in the mdbook will get its own man page
   • We can then filter out only the chapter we want (the configuration one)
4. We now should have a working documentation site and a man page for the configuration

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!