There is no or very poor documentation for openrc configs in gentoo. There is no way to know what to read if you want to configure something like ipv6 address. There is only handbook and /usr/share/doc/openrc-*/net.example, which means "if every gentoo user and network is unreachable, you suck". Is there any policy for Gentoo which requires ebuild maintainer to place manuals for every binary and config file? Maybe we should look into this point? Reproducible: Always Steps to Reproduce: 1. cd /usr/share/doc/openrc* && ls 2. man <something like hwclock, net, or any other config> 3. Cry. Actual Results: there is only /usr/share/doc/openrc-*/net.example here. Expected Results: manual pages for config files in section 5 complete documentation for openrc inside /usr/share/doc/openrc-* It is not good way to point someone to google/irc/forums instead writing docs :)
(In reply to comment #0) > It is not good way to point someone to google/irc/forums instead writing docs > :) Hi, I understand your concern but openrc is not written by Gentoo devs. So, filing a bug here is not really appropriate. By the way, I have found the comments in the files adequate for all except net. :)
(In reply to comment #1) > (In reply to comment #0) > Hi, I understand your concern but openrc is not written by Gentoo devs. So, > filing a bug here is not really appropriate. By the way, I have found the > comments in the files adequate for all except net. :) Agreed, I am marking this as upstream.
net.example seems pretty complete to me. it certainly covers adding ipv6 addresses to interfaces. so you need to be clear in what is missing.
i kinda can second on that. while /usr/share/doc/${P}/net.example is nice detailed piece of text it's frustrating that there is no symlink to it in /etc/conf.d nor there is a man page about gentoo networking ways. also it's inconvenient that structure of config files so fragile because directives in them combined with documentation about, well, those config files and directives. while documenting a config file is common and good practice it would be much better if there were man pages with this and even more detailed info on every (or base ones, at least) gentoo-specific config and users could freely replace those config files with simple directive-only ones manually or via their own scripts (i don't know for sure but in my understanding right now if some directive missing from file altogether its value will not be replaced by openrc on some default one and it will end badly for system init) example of how i mean it should look like is samba config. this is all OpenRC's business but since it is gentoo init system, people like base-system herd must be concerned.
(In reply to comment #4) > i kinda can second on that. > while /usr/share/doc/${P}/net.example is nice detailed piece of text it's > frustrating that there is no symlink to it in /etc/conf.d nor there is a man > page about gentoo networking ways. Technically, /usr/share/doc/${P}/net.example should be installed as /etc/conf.d/net. But if we do that it is very easy to wipe out your network configuration when you update to a newer version of openrc. That is why it is in /usr/share/doc. > also it's inconvenient that structure of config files so fragile because > directives in them combined with documentation about, well, those config files > and directives. > while documenting a config file is common and good practice it would be much > better if there were man pages with this and even more detailed info on every > (or base ones, at least) gentoo-specific config and users could freely replace > those config files with simple directive-only ones manually or via their own > scripts > (i don't know for sure but in my understanding right now if some directive > missing from file altogether its value will not be replaced by openrc on some > default one and it will end badly for system init) This is exactly why we have /usr/share/doc/${P}/net.example. It is an example of the configuration file which should be copied over to /etc/conf.d/net if you want to use it and that copy can be edited once and /etc/conf.d/net will not be touched by openrc updates. > example of how i mean it should look like is samba config. > this is all OpenRC's business but since it is gentoo init system, people like > base-system herd must be concerned. Again, if you want better documentation for networking setup, including man pages, that documentation needs to be written upstream. openrc is a platform independent init system which can be used on multiple systems, so you are talking about openrc networking, not gentoo specific networking. William
and this, as i already pointed out, is simply _inconvenient way_ of learning and configuring. i also can see Roy in CC here, so he (upstream) is obviously keep up in this and ,as i also said, it is an _init_ system, pretty important thing, so he really could use a hand. particularly, a hand from one of those (two ?) "multiple systems". should i say that seems "openrc networking" and "gentoo networking", in fact, are the same thing ?
(In reply to comment #5) > (In reply to comment #4) > Again, if you want better documentation for networking setup, including man > pages, that documentation needs to be written upstream. openrc is a platform > independent init system which can be used on multiple systems, so you are > talking about openrc networking, not gentoo specific networking. I'm sorry, but if openrc will be official part of gentoo base system, this _will_ be also gentoo networking (and not only networking) configuration. I think this is not bad idea at least to place examples (defaults?) for another configuration files in /usr/share/doc/openrc also. # equery files openrc | grep conf.d /etc/conf.d /etc/conf.d/bootmisc /etc/conf.d/consolefont /etc/conf.d/dmesg /etc/conf.d/fsck /etc/conf.d/hostname /etc/conf.d/hwclock /etc/conf.d/keymaps /etc/conf.d/local /etc/conf.d/localmount /etc/conf.d/modules /etc/conf.d/net /etc/conf.d/network /etc/conf.d/staticroute /etc/conf.d/urandom Why? :) Just because someone can edit them and change something by accident wrong way. After that it will be not so simple to look into some file and find: * Which quotes he should use in config file * Is directive should be written in CAPS or not (some configs in conf.d use CAPS, some of them not using CAPS in names or values of options. * Should he use brackets around options or not. This will be minumum for documentation which can cover almost all questions about configuration.
it has nothing to do with upstream. the comments here are simply misinformed. the default /etc/conf.d/net *does* reference the net.example file. but as William mentioned, we make sure the /etc/conf.d/net file is taken from $ROOT so that a fat finger during etc-update doesnt take down your system. after all, the default /etc/conf.d/net is *only* a comment referencing the net.example file. unless you have usable suggestions for how to address this, nothing is going to change.
i already gave you suggestion to convert it into a man page form and to provide any further openrc\gentoo init text documentation in that form.
i dont see man pages being viable at this point in time. no other conf.d has a man page, and if we're going to start such a project, it'd make a lot more sense to automate it with a standard syntax like the eclass man pages (all of that is generated from comments in the eclass itself). considering the non-standard aspect, i dont think a man page would solve much either. people are still going to complain that they are unable to locate appropriate documentation.
it is indeed a way to go with conf.d documentation. i believe that if something man pages can solve it is a searching problem. with thing like whatis\apropos (sys-apps/man-db) this will be no issue. but you can't search something if it does not exist. and right now no gentoo configuration documentation exists unless you can call comments and online guidance as documentation. the only reason why net.example here is that configuring network is complex and sophisticated thing you cannot possible just put in comments which makes it presence mandatory BUT place where it reside as well as format of simple text file suggests that no-one though about how to document those config files properly yet. my point being that it's not "non-standard" but just haven't been done yet and worth of doing so.
comments in conf.d and online documentation are the Gentoo standard
which is exactly the point - not a very good one. could be better: more unified and accessible... hell, with mans even localization is possible !
