Add more documentation: I made a writeup of the most interesting features and how things are connected in OpenRC. Document can be found here: http://dev.gentoo.org/~patrick/openrc.txt Written by me, with minor corrections from various people on IRC
Hi, some additions: 1) Shouldn't we use the same wording all over the place? See "man runscript" for example... in OpenRC files in "/etc/init.d" are named "runscript" - you call them "initscripts". I am not sure if we should mix those terms (in the end of your text you call them runscript again). 2) I don't like the wording in the default functions paragraph. For example, "All init scripts are assumed to have the following functions:" sounds wrong. Again, see "man runscript": "Here is a list of some functions that all runscripts have by default" ... that's a different meaning, not? Due to the default functions, the smallest possible runscript would be #!/sbin/runscript command="/usr/sbin/daemon" but without a pidfile, the default status function isn't very reliable. So the recommended smallest possibel runscript would be #!/sbin/runscript command="/usr/sbin/daemon" pidfile="/run/daemon.pid" These 3 lines are enough for a working default start, stop and status function. May I ask you about the purpose of the planned documentation? Don't get me wrong, but is there something wrong with the existing man pages? If we create another documentation, we have another document to keep up to date. If we start something new, chances are high that we forget something which is in the "old" documentation... Also, would we require people to read both documentations?
(In reply to Thomas D. from comment #1) > Hi, > > some additions: > > 1) Shouldn't we use the same wording all over the place? See "man runscript" > for example... in OpenRC files in "/etc/init.d" are named "runscript" - you > call them "initscripts". I am not sure if we should mix those terms (in the > end of your text you call them runscript again). I would prefer the use of one term for the scripts. It seems that they are called service scripts in OpenRC's man pages. > Due to the default functions, the smallest possible runscript would be > > #!/sbin/runscript > command="/usr/sbin/daemon" > > but without a pidfile, the default status function isn't very reliable. So > the recommended smallest possibel runscript would be > > #!/sbin/runscript > command="/usr/sbin/daemon" > pidfile="/run/daemon.pid" > > These 3 lines are enough for a working default start, stop and status > function. They are, but you really need a depend() function as well to set the boot order of the service script. > May I ask you about the purpose of the planned documentation? Don't get me > wrong, but is there something wrong with the existing man pages? If we > create another documentation, we have another document to keep up to date. > If we start something new, chances are high that we forget something which > is in the "old" documentation... Also, would we require people to read both > documentations? I wondered the same thing. I would rather see updates to the man pages, or the creation of new man pages if necessary, than creating completely separate documentation. I also found something else. In the section called "syntax of init scripts", the wording implies that the way we handle restart is a bug or limitation, which it isn't since it is possible within a service script by checking $RC_CMD to handle the restart case (again see man runscript). Keep in mind too that in openrc-0.13, every reference to runscript is about to change to openrc-run.
(In reply to William Hubbs from comment #2) > I would prefer the use of one term for the scripts. It seems that they are > called service scripts in OpenRC's man pages. ...and later you said > I also found something else. In the section called "syntax of init scripts", > the wording implies that the way we handle restart is a bug or limitation, > which it isn't since it is possible within a service script by checking > $RC_CMD to handle the restart case (again see man runscript). I would keep the word "runscript" or we have to discuss if we are going to to change "man runscript" to something else, too... But if we always refer to word "foo" but the documentation is in man page "bar"... that doesn't make sense :)
(In reply to Thomas D. from comment #3) > (In reply to William Hubbs from comment #2) > > I would prefer the use of one term for the scripts. It seems that they are > > called service scripts in OpenRC's man pages. > > ...and later you said > > > I also found something else. In the section called "syntax of init scripts", > > the wording implies that the way we handle restart is a bug or limitation, > > which it isn't since it is possible within a service script by checking > > $RC_CMD to handle the restart case (again see man runscript). > > I would keep the word "runscript" or we have to discuss if we are going to > to change "man runscript" to something else, too... That is already happening. In OpenRC 0.13, runscript will be called openrc-run. This is the interpretor for the scripts. The term "service script" or "init script" refers to the actual *script* like the ones in /etc/init.d. In OpenRC I call them "service scripts". > But if we always refer to word "foo" but the documentation is in man page > "bar"... that doesn't make sense :) I'm not understanding what you mean.
I have put the wikitext up on a wiki so I can see how it all looks. Initial paragraph is funtoo-specific, the rest is just a copy/paste of what was in openrc.txt: http://www.funtoo.org/Package:OpenRC Feel free to edit/tweak as necessary. I think it could use some real paragraphs. I will be tweaking the text here too. I have some stuff I wrote for OpenRC underneath. I will be trying to incorporate this into the flow of openrc.txt (things like History.) Let's get this looking like an honest-to-goodness wiki page! :)
Patrick, nice and well-organized write-up. Hopefully, it would finally replace the cluttered page of http://wiki.gentoo.org/wiki/OpenRC Daniel, the history section is exciting. William, how about continuing that with what happened from 2010?
(In reply to Benda Xu from comment #6) > Patrick, nice and well-organized write-up. Hopefully, it would finally > replace the cluttered page of http://wiki.gentoo.org/wiki/OpenRC I am concerned that there are so many sources of OpenRC documentation now. I would like to see the wiki pages and this document compared to the information in the OpenRC tree itself and the information in the tree be made the official source of documentation. > Daniel, the history section is exciting. William, how about continuing that > with what happened from 2010? What we need to do is take that history section and merge it into the OpenRC README history section, then I could probably add more recent information.
I have added the history from the wiki along with the original information from Roy to a new file, README.history. See commit 09d81e8. What else do folks think we should do with this bug? Thanks, William
I think OpenRC has fine reference documentation, but it has very poor User documentation. I would suggest getting a wiki set up for OpenRC (I can help with this) and start developing a full User's Guide for OpenRC. It's really important OpenRC adoption for all features to be adequately explained from a user's perpective.
My concern about using a wiki for official documentation is that does not consider the case where a user can't get online because something is broken in OpenRC on their system. If that happens, a wiki does them no good. Shouldn't we put official documentation in the package instead of on a wiki?
(In reply to William Hubbs from comment #10) > My concern about using a wiki for official documentation is that does not > consider the case where a user can't get online because something is > broken in OpenRC on their system. > > If that happens, a wiki does them no good. > > Shouldn't we put official documentation in the package instead of on a wiki? This chicken-and-egg issue could be decoupled by generating plain text from the wiki and put into the tarball.
All, I just had an idea wrt how we can add more documentation, probably using this text file, if not part of it, as a basis. I'm considering a man page openrc-service(5) which would contain the details of how to write a service script, openrc-builtins(?) which would contain all of the documentation for the builtins located in /lib*/rc/{bin,sbin}, and making the openrc-run man page just document the openrc-run interpretor. What does everyone think? Also, which man section is appropriate for openrc-builtins? Thanks, William
https://github.com/openrc/openrc/commit/e826537 This has been added with updates to master; it will be in OpenRC-0.21.
