From mboxrd@z Thu Jan 1 00:00:00 1970 From: ludo@gnu.org (Ludovic =?utf-8?Q?Court=C3=A8s?=) Subject: Re: [PATCH] gnu: Add rpc-daemon service Date: Wed, 07 Sep 2016 14:17:48 +0200 Message-ID: <87r38voqdv.fsf@gnu.org> References: <8737levzyr.fsf@gnu.org> <1473180656-14742-1-git-send-email-jmd@gnu.org> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:60315) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bhbnh-0004vc-7h for guix-devel@gnu.org; Wed, 07 Sep 2016 08:17:58 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1bhbnc-0001Rg-3L for guix-devel@gnu.org; Wed, 07 Sep 2016 08:17:56 -0400 Received: from fencepost.gnu.org ([2001:4830:134:3::e]:41614) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bhbnb-0001RA-VX for guix-devel@gnu.org; Wed, 07 Sep 2016 08:17:52 -0400 In-Reply-To: <1473180656-14742-1-git-send-email-jmd@gnu.org> (John Darrington's message of "Tue, 6 Sep 2016 18:50:56 +0200") List-Id: "Development of GNU Guix and the GNU System distribution." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-devel-bounces+gcggd-guix-devel=m.gmane.org@gnu.org Sender: "Guix-devel" To: John Darrington Cc: guix-devel@gnu.org Hi! John Darrington skribis: > If I might be allowed to give my opinion though ... I think this way of= documenting=20 > things is of limited help to potential users. It does nothing more than = repeat what > is written in the code. If that is what we want, then we could use some = kind of > literate programming tool to do it. That would be less maintenence and a= voids > the possibility of code and documentation becoming out of sync. I don=E2=80=99t see anything in nfs.scm explaining, for instance, the =E2=80=98warm-start?=E2=80=99 knob; nor is anything (and rightfully so) hin= ting at what NFS is and how rpcbind relates to it. > However, what is really needed from documentation IMO, is not only a API = reference, > but also a tutorial on how to use the thing. I think this form of docume= ntation will only > leave the newcommer scratching his head. I agree. It=E2=80=99s often a good idea to (1) give context and relevant cross-references in the doc, and (2) include an example for non-trivial services. For instance, I think the =E2=80=9CDesktop Services=E2=80=9D and= =E2=80=9CScheduled Job Execution=E2=80=9D sections are doing pretty good in this regard. > * gnu/services/nfs.scm: New file. > * gnu/local.mk (GNU_SYSTEM_MODULES): Add it. [...] > +@subsubheading RPC Bind Service > +@cindex rpcbind > + > +The @code{(gnu services nfs)} module provides the following: > + > +@defvr {Scheme Variable} rpcbind-service-type > +A service type for the RPC portmapper daemon. > +@end defvr > + > + > +@deftp {Data Type} rpcbind-configuration > +Data type representing the configuration of the RPC Bind Service. > +This type has the following parameters: > +@table @asis > +@item @code{rpcbind} (default: @code{rpcbind}) > +The rpcbind package to use. > + > +@item @code{warm-start?} ^ Mention the default value here=E2=80=A6 > +If this parameter is @code{#t} (the default), then the daemon will read a ^ =E2=80=A6 and not here. Other than that, LGTM! Regarding documentation, since you asked ;-), what could work well here is to have a complete =E2=80=9CNetwork File System=E2=80=9D @subsection. I= t would start with a short intro of what NFS is, provide an example showing how to export a directory over NFS, give an overview of the services involved (rpcbind, mountd, statd), and then give the API reference. Thoughts for future work. :-) Thank you! Ludo=E2=80=99.