Re: 01/01: doc: Typos and small stylistic changes.

[Mathieu Lirzin]

Andreas Enge <address@hidden> writes:

> On Sat, Mar 05, 2016 at 10:48:33PM +0100, Ludovic Courtès wrote:
>> This commit modifies some of the service documentation, which is also
>> available in docstrings in gnu/services/*.scm.  Could you update them
>> accordingly?
>
> Oh dear, correcting typos in the texinfo manual is already close to more
> work than what the result is worth (but well, I am not complaining, I did it
> voluntarily); now looking up where I marked my paper copy, checking how I
> changed things in guix.texi and modifying the source code accordingly sounds
> very tedious. I will give it a try.
>
> I suppose it is not easily possible to import the doc strings automatically
> into the texinfo file, in a way that we would keep a hand-written manual,
> but with small pieces automatically extracted from the source code?
> Maintaining two separate documents is always a bit painful.

It is painful but necessary:

  
https://www.gnu.org/prep/standards/html_node/Doc-Strings-and-Manuals.html#Doc-Strings-and-Manuals

A way to understand why this is important is to read some of the
"documentation" used by the Java APIs.

-- 
Mathieu Lirzin