New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Man pages #69
Comments
I would recommend to use standard sections rather than making a custom one. User commands (e.g. client tools) are generally expected in section 1, while service admin tools and daemons are typically in section 8. Configuration file documentation is typically in section 5 (and the man page name makes sense). Concept documentation probably makes sense in section 7. Your idea of prefixing them makes sense. I would be fine with |
@Conan-Kudo Thanks! I got the idea of In valkey we have command names like |
Haven't had a chance to review this yet but @remicollet may have some insight too. |
Is |
Yes, |
This can be problematic, but if you want to supply manual pages for the protocol commands then this is better than not namespacing the section. One problem is that sections that are not listed in for example I guess the other option is to use something along the lines of
Section 7 seems good to me. I think prefixing them here makes more sense, than namespacing the section. Also because with some man implementations (
I think providing the man pages for the programs alongside the implementation themselves would be better, otherwise you need to install an additional docs package to get these, which are unlike protocol commands or other development documentation that might be fine as independent packages.
Yes, this is standard practice I'd say.
Depends on the section used, you can get some inspiration from
|
@guillemj Are you saying I find this This scheme
Right, but we already have some docs of these in our doc repo which is under a CC-SA license, so I don't think we can move it to the code repo. An alternative would be to include minimal man pages for the programs (identical to the output of Can you as a packager include some content from our doc repo (man pages for programs) in a binary package? That would solve this issue, if it's acceptable.
I'll massage the original too. But the situation is that some command metadata like usage syntax is in the code repo while the bulk of the text is in the doc repo. We want to avoid duplicating the metadata in both repos. |
Ah, no, sorry, my memory played tricks on me. This was a problem between two sub-sections. For
Hmm, that'd be a bit unfortunate I think.
While not ideal, I think that's better than nothing. It allows to check manual pages w/o needing to run a program, or checking them online on a place such as https://manpages.debian.org/redis-cli. Perhaps they could then be filled in by writing additional content through some clean-room process?
Someone packaging valkey, could include additional content such as manual pages, it would be akin to carrying a patch against upstream, but in this case just shipping the entire file. The problem is that then tracking any possible modification from the original becomes cumbersome and this then tends to become a distro-specific change. For example the Debian redis package includes manual pages written from scratch (see https://salsa.debian.org/lamby/pkg-redis/-/blob/debian/sid/debian/redis-server.1?ref_type=heads). Perhaps those could be used as a starting point instead? |
Good to know. Then I'll base it on the
Ok, I won't go that way then.
Interesting that Chris Lamb wrote a man Everything is crystal clear now. 💎 Thanks for all the advices! |
In general section 8 for servers is good advice, but that then needs to match the installation directory. In this particular case section 1 is being used because the redis-server executable is getting installed as
Any time! Always glad to assist upstreams making downstream work easier. :D |
Thanks again for more enlightenment. Makes sense. I wonder if changing can cause trouble though. We already have a release installing |
There's no real reason to move it from For the issue of having the man pages come out of this repo, as long as we have synchronized tags, it's fine for @jonathanspw and I, as we can just pull two tarballs in our spec file. |
@Conan-Kudo I can add some variable to tweak the man page section (1 or 8) and leave the decision to you. :) We don't have synchronized doc tags. We don't have doc tags at all actually. No versioned docs. We could consider tagging versions in the docs repo though, if you think it's important. |
If you want to have the man pages come out of this repo, then it would make sense that this repo gets tagged the same time the code is with matching tags. That way it's easy for us to pull it in. |
I would like to build man pages from the markdown docs and I need some advice.
I know man pages are important for distro packaging, so I'm reaching out to you @jonathanspw and @lamby for advice. Should I include anyone else? I have a few ideas for building man pages for the entire Valkey documentation and I would like to know if these ideas make sense or if there are any other ways.
I'm willing to restructure the valkey-doc repo a bit to better fit the needs for man-pages and other formats, rather than just being a repo backing a website. (The website is one place where we publish docs, but I don't the website use case to make us pollute the doc repo with website-specific content, etc.)
One man page per command. Section
3valkey
. Is this a good idea?One man page for each of the markdown files under topics/ in this repo. Man page section 7, right?
Many of these pages have generic names like
transactions
, so I'm thinking that we could prefix them withvalkey-
(e.g.valkey-transactions
). Would that be a good idea? An alternative could be to use a section like7valkey
and no prefix on the page names. Any advice or preferences?One man page for each of the executables
valkey-server
,valkey-cli
,valkey-benchmark
,valkey-check-rdb
,valkey-check-aof
. (Section 1.)There are already some pages under topics/ that document the binaries
valkey-cli
,valkey-benchmark
under topics. I'd like to adapt these to a man page structure used for programs and I think it would be a good idea to move them to its own directory, like programs/ or so, so topics correspond to section 7 and programs to section 1.One man page for the configuration. Would it make sense to call it
valkey.conf
? (Section 5)What man page fields should I use and how would you populate them? If there are
I'm considering using
pandoc
or some other tool that can convert markdown to man pages. (Any advice here?) In addition to that, I'll need to use some preprocessing of the markdown files (some python script, maybe some sed, etc.) and a dependency on valkey's code repo to fetch some metadata about commands. A Makefile with targets to build and install the man pages.WDYT?
The text was updated successfully, but these errors were encountered: