From mboxrd@z Thu Jan 1 00:00:00 1970 From: ludo@gnu.org (Ludovic =?utf-8?Q?Court=C3=A8s?=) Subject: Re: [PATCH] Doc: Introduction: rewrite for style and clarity. Date: Thu, 23 Jan 2014 14:30:47 +0100 Message-ID: <87a9emesfs.fsf@gnu.org> References: <1390464950-5967-1-git-send-email-alex.sassmannshausen@gmail.com> <1390464950-5967-2-git-send-email-alex.sassmannshausen@gmail.com> 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]:36984) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1W6KRp-0003lU-PF for guix-devel@gnu.org; Thu, 23 Jan 2014 08:36:05 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1W6KRi-0005gx-Fd for guix-devel@gnu.org; Thu, 23 Jan 2014 08:35:57 -0500 Received: from hera.aquilenet.fr ([141.255.128.1]:39364) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1W6KRi-0005ey-1Z for guix-devel@gnu.org; Thu, 23 Jan 2014 08:35:50 -0500 In-Reply-To: <1390464950-5967-2-git-send-email-alex.sassmannshausen@gmail.com> (Alex Sassmannshausen's message of "Thu, 23 Jan 2014 09:15:50 +0100") 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-bounces+gcggd-guix-devel=m.gmane.org@gnu.org To: Alex Sassmannshausen Cc: guix-devel@gnu.org Alex Sassmannshausen skribis: > * dmd.texi (Introduction): Rewrite for style and clarity. Overall looks good to me! A few comments below: > --- a/dmd.texi > +++ b/dmd.texi > @@ -78,24 +78,28 @@ the GNU system. >=20=20 > @cindex service manager > This manual documents the @dfn{dmd} service manager. It is used to [...] > +start and stop system services (typically daemons) in a reliable > +fashion---by automatically starting prerequisites (``required > +services'') and by preventing conflicting services from being started. > +dmd is designed to be flexible when choosing what services to start > +and stop. I prefer to avoid parenthetical expressions in the middle of sentences, because it breaks the rhythm when reading the sentence. Perhaps that can be achieved here by adding a sentence before to introduce =E2=80=9Cservices=E2=80=9D and =E2=80=9Cprerequisites=E2=80=9D? > +dmd is the @dfn{init system} of the GNU operating system---it is the > +first user process that gets started, typically with PID 1, and runs > +as @code{root}. Normally the purpose of init systems is to manage all > +system-wide services, but dmd can also be a useful tool assisting > +unprivileged users in the management of their own daemons. Currently the manual says =E2=80=9CIt is also a useful tool that assists unprivileged users in the management of their own daemons.=E2=80=9D I thin= k it would be nice to keep that information somewhere, though I agree it sort-of gets in the way currently. WDYT? > +Unfortunately all flexible software requires some time to master and > +dmd is no different. But don't worry: this manual should allow you to > +get started quickly. Its first chapter is designed as a practical > +introduction to dmd and should be all you need for everyday use > +(@ref{Jump Start}). In chapter two (@ref{deco and dmd}) we will Use @pxref for parenthetical cross-references (info "(texinfo) @pxref"). > +describe the deco and dmd programs, and their relationship, in more @command{deco} and @command{dmd}. > +detail. The chapters following chapter 2 provide a full reference ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ =E2=80=9CSubsequent chapters=E2=80=9D? > +manual and plenty of examples, covering all of dmd's capabilities. > +Finally, the last chapter provides information for those souls brave > +enough to hack dmd itself. I like the distinction you make between essential for normal use, advanced use, and hacking. Fine point: please use two spaces after an end-of-sentence period. Thank you! Ludo=E2=80=99.