OpenRC notoriously lacks appropriate documentation that should come with it. The best place to find information about the init.d scripts and OpenRC is the Wiki, particularly https://wiki.gentoo.org/wiki/Handbook:AMD64/Working/Initscripts I suggest: * Add a reference to man openrc-run(8) and possibly others in the "See Also" section of openrc(8) * Add documentation of "usesme", "needsme", etc. arguments to openrc-run(8) (they seem not to be mentioned anywhere, including online synopsis) * Document the exact semantics and syntax of rc_..._...="..." definitions. E.g., "." in filenames map to "_", omitting the specification given my "." defines a superclass, how do "!..." negations work - why does rc_use="!net" in rc.conf not cancel all "use net" from init scripts, for example? * Possibly incorporate the Wiki Text into an "overview" manpage
The advice in the handbook is actually pretty outdated. I'm slowly working on this, see e.g. https://github.com/OpenRC/openrc/pull/162 Afterwards, some of that stuff should be incorporated in guide.md and/or the man page of openrc-run. The Gentoo wiki and devmanual should ultimately point to the official OpenRC docs, because those won't get outdated so easily.
(In reply to Cedric Sodhi from comment #0) > OpenRC notoriously lacks appropriate documentation that should come with it. > The best place to find information about the init.d scripts and OpenRC is > the Wiki, particularly > > https://wiki.gentoo.org/wiki/Handbook:AMD64/Working/Initscripts I haven't looked at this information, but I imagine it is significantly out of date. > I suggest: > > * Add a reference to man openrc-run(8) and possibly others in the "See Also" > section of openrc(8) I can look into adding these. > * Add documentation of "usesme", "needsme", etc. arguments to openrc-run(8) > (they seem not to be mentioned anywhere, including online synopsis) That's correct, you don't use these when you write a script, so there wouldn't be anything to document. The dependencies you use to write a script are use, need, want, before, after, and keyword. These are documented. > * Document the exact semantics and syntax of rc_..._...="..." definitions. > E.g., "." in filenames map to "_", omitting the specification given my "." > defines a superclass, how do "!..." negations work - why does rc_use="!net" > in rc.conf not cancel all "use net" from init scripts, for example? I'm not following you here. What would you change? > * Possibly incorporate the Wiki Text into an "overview" manpage The official OpenRC documentation is in the *.md files and man pages in the distribution. The *.md files are installed in /usr/share/doc/openrc-* on Gentoo. Any suggestions for improving these are welcome. :-)
IMO the handbook is the wrong place for "how to write an init script" documentation, because you will never need to write one in your capacity as a user. We already have pretty good "how to write an init script" documentation, but right now it's in three places, * the man page for openrc-run * guide.md * the new service-script-guide.md (thanks William) It's not perfect, but you should at least be able to write a decent script after reading all three of those. What I think is missing is a "user guide" document that's targeted only at end users of OpenRC. The guide.md document partially covers this. For example, it starts out with a nice introduction, and talks about starting, stopping and runlevels. But then it takes a detour into "Syntax of Service Scripts" that is only useful for developers before returning to "The Magic of conf.d" which is again needed by end users. In the short term, I think it would be useful to move the developer-oriented portions of guide.md into service-script-guide.md, and then to take all of the user-oriented documentation floating around (in e.g. the wiki) and move that into guide.md, which then becomes the "user guide." At that point, we can eliminate the duplication (and outdated information) on the wiki by pointing people towards the official documentation. Information about overriding the "rc_" variables now clearly fits into the user guide as well. After that, I think there are some portions of the openrc-run man page that could go in service-script-guide.md, too. The only question then is what to do with the openrc-run man page. There are two obvious options; we could make it comprehensive (contain all user/developer information), or try to eliminate everything that isn't directly relevant to the openrc-run command itself. In the latter case we would of course have pointers to the other markdown files. I don't like removing information from man pages, but I also don't like duplicating it, so I'm not sure which one sounds better yet.
Is there anything else we need in this bug? It seems a bit general, so if it is cool, I would like to close it and we can open bugs for individual documentation issues as they come up.
I am closing this due to no responses. I' assuming that everyone on the bug is ok with my suggestion for individual bugs for each documentation issue.
