Re: [PATCH] Doc: Introduction: rewrite for style and clarity.

[Ludovic Courtès]

Alex Sassmannshausen <address@hidden> 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’.