From: ludo@gnu.org (Ludovic Courtès)
To: Alex Sassmannshausen <alex.sassmannshausen@gmail.com>
Cc: guix-devel@gnu.org
Subject: Re: [PATCH] Doc: Introduction: rewrite for style and clarity.
Date: Thu, 23 Jan 2014 14:30:47 +0100 [thread overview]
Message-ID: <87a9emesfs.fsf@gnu.org> (raw)
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")
Alex Sassmannshausen <alex.sassmannshausen@gmail.com> 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.
>
> @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 “services” and “prerequisites”?
> +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 “It is also a useful tool that assists
unprivileged users in the management of their own daemons.” I think 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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
“Subsequent chapters”?
> +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’.
next prev parent reply other threads:[~2014-01-23 13:36 UTC|newest]
Thread overview: 9+ messages / expand[flat|nested] mbox.gz Atom feed top
2014-01-23 8:15 dmd: Some improvements to the dmd manual Alex Sassmannshausen
2014-01-23 8:15 ` [PATCH] Doc: Introduction: rewrite for style and clarity Alex Sassmannshausen
2014-01-23 13:30 ` Ludovic Courtès [this message]
2014-01-23 18:00 ` (unknown), Alex Sassmannshausen
2014-01-23 18:00 ` [PATCH] Doc: Introduction: rewrite for style and clarity Alex Sassmannshausen
2014-01-24 17:11 ` Ludovic Courtès
2014-01-23 13:11 ` dmd: Some improvements to the dmd manual Ludovic Courtès
2014-01-23 15:09 ` Alex Sassmannshausen
2014-01-24 12:52 ` Ludovic Courtès
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87a9emesfs.fsf@gnu.org \
--to=ludo@gnu.org \
--cc=alex.sassmannshausen@gmail.com \
--cc=guix-devel@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/guix.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.