Re: [PATCH] doc: Clarify and consolidate modify-services documentation.

[Chris Marusich]

Here's an updated patch.  First off, I added my name to the copyright
list for each file I modified.  Please let me know if I should refrain
from doing this, since the contribution is small.

address@hidden (Ludovic Courtès) writes:

> One general remark: please always leave two spaces after an
> end-of-sentence period (info "(texinfo) Ending a Sentence").  As Andy
> put it, we’re part of that two-space tribe.  ;-)

OK - I think I've used double spaces everywhere, this time.

> I prefer to put “e.g.” things between em dashes instead of parentheses,
> but have no reference supporting this choice, so…  your call!

I've changed this to match the style currently used in the manual.

> I think this should be enough:
>
>   ;; @dots{}

I agree.

> These lines may be too longer for the PDF output.  What about making it:
>
>   @lisp
>   (define %my-services
>     (modify-services …))
>
>   (operating-system
>     ;; @dots{}
>     (services %my-services))
>   @end lisp
>
> ?

I think that example with more context will better clarify how to use
the macro, so I'm inclined not to shorten that part.  To make sure, I
will check how the PDF looks once after texlive finishes downloading.
It seems I need that in order to run texi2pdf.  It'll take a little
time.

> Also I wonder if we should move this illustration (starting from “For
> the purpose of illustration”) right above the @deffn, in part because it
> deals with the general context rather than just ‘modify-services’, and
> also because it everything within @deffn is indented.
>
> WDYT?

I decided to move the example back into the operating system
configuration section, since that seems to be where the examples should
go.  New users will be looking there to learn how to write their
operating-system declarations, so it makes sense to put the example
there.  If they want more information, they can follow the link to the
detailed description of modify-services.

> I think I would keep the docstring unchanged because this one is more
> concise, which I think is important for a docstring.
>
> It’s OK to if the manual is more verbose on this topic (info
> "(standards) Doc Strings and Manuals").

Thank you for pointing this out.  It makes sense.  I've shortened the
docstring accordingly.

> Thanks a lot for your feedback!  It’s good to have a fresh eye on this
> and quality suggestions to improve it!

I'm glad to help!

Chris

0001-doc-Clarify-and-consolidate-modify-services-document.patch
Description: Text Data