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

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

[Ludovic Courtès]

Andreas Enge <andreas@enge.fr> skribis:

> commit 1068f26b797ed7c1475d93cab6eed53c9097c7f6
> Author: Andreas Enge <andreas@enge.fr>
> Date:   Sat Mar 5 16:26:55 2016 +0100
>
>     doc: Typos and small stylistic changes.
>     
>     * guix.texi: Correct typos and make minor changes.

This commit modifies some of the service documentation, which is also
available in docstrings in gnu/services/*.scm.  Could you update them
accordingly?

Thanks!

Ludo’.

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

[Andreas Enge]

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.

Andreas

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

[Mathieu Lirzin]

Andreas Enge <andreas@enge.fr> 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

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

[Andreas Enge]

On Sun, Mar 06, 2016 at 02:46:06PM +0100, Mathieu Lirzin wrote:
> 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.

I agree. However, here we _do_ copy verbatim docstrings from the source code
into the manual, which is also fine. And then we are expected to back-port
changes to the supposedly manually written manual :-)  back to the docstrings.
So it would be nice if there were a system to just include selected
docstrings; a texinfo command @docstring{guix-service-type} or something like
that. But I think it does not exist.

Andreas

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

[Andreas Enge]

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?

Finally, I think this is unreasonable. I already spent 20 minutes just
trying to organise a work-flow: Some of the strings in the manual are
taken from docstrings (I think the procedures), others are not (I think
the variables and data types).

Altogether, I think I would spend an hour updating comments in the source
code, together with writing detailed commit messages.

If you think it is important that both match, please just revert my patch
(and I will not be offended); I did not make important changes anyway.
I do not have the energy right now to wade through the docstrings. Instead,
I would rather investigate things around installation that I wanted to
look at.

Andreas

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

[Mathieu Lirzin]

Andreas Enge <andreas@enge.fr> writes:

> On Sun, Mar 06, 2016 at 02:46:06PM +0100, Mathieu Lirzin wrote:
>> 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.

> I agree. However, here we _do_ copy verbatim docstrings from the source code
> into the manual, which is also fine. And then we are expected to back-port
> changes to the supposedly manually written manual :-)  back to the docstrings.
> So it would be nice if there were a system to just include selected
> docstrings; a texinfo command @docstring{guix-service-type} or something like
> that. But I think it does not exist.

OK.  Then my "generic" response would be that this is a symptom of a
problem in the manual or the docstring or both.

The only desirable automations I see for documentation, are a thing that
checks that procedure signatures from the manual are matching the actual
implementation, and a way for your editor to retrieve the doc strings
(more conveniently than grep), in order to manually check if something
should be updated in both.

If another problem is lack of time for writing documentation.  I think
the correct fix is to replace the copy/pasted doc-strings with something
like:

--8<---------------cut here---------------start------------->8---
FIXME: Document this part.

Please refer to source file ‘$foo/bar.scm’ for details.
--8<---------------cut here---------------end--------------->8---

:)

-- 
Mathieu Lirzin

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

[Ludovic Courtès]

Andreas Enge <andreas@enge.fr> skribis:

> 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

Ultimately I think we should at least have a way to extract docstrings.
There’s an Emacs Lisp file somewhere in the Guile tree that does that.

Ludo’.

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

[Alex Kost]

Andreas Enge (2016-03-05 18:27 +0300) wrote:

> commit 1068f26b797ed7c1475d93cab6eed53c9097c7f6
> Author: Andreas Enge <andreas@enge.fr>
> Date:   Sat Mar 5 16:26:55 2016 +0100
>
>     doc: Typos and small stylistic changes.
>
>     * guix.texi: Correct typos and make minor changes.

[...]
> @@ -5928,7 +5928,7 @@ system} command, specifically:
>  guix system disk-image --image-size=850MiB gnu/system/install.scm
>  @end example
>
> -@xref{Invoking guix system}, for more information.  See
> +@xref{Invoking guix system} and
>  @file{gnu/system/install.scm} in the source tree for more information
>  about the installation image.

I think this should be rephrased, because after this change, makeinfo
complains:

  ./doc/guix.texi:5937: warning: `.' or `,' must follow @xref

And in the generated guix.info there is a dot before "and".

--
Alex

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

[Ludovic Courtès]

Alex Kost <alezost@gmail.com> skribis:

> Andreas Enge (2016-03-05 18:27 +0300) wrote:
>
>> commit 1068f26b797ed7c1475d93cab6eed53c9097c7f6
>> Author: Andreas Enge <andreas@enge.fr>
>> Date:   Sat Mar 5 16:26:55 2016 +0100
>>
>>     doc: Typos and small stylistic changes.
>>
>>     * guix.texi: Correct typos and make minor changes.
>
> [...]
>> @@ -5928,7 +5928,7 @@ system} command, specifically:
>>  guix system disk-image --image-size=850MiB gnu/system/install.scm
>>  @end example
>>
>> -@xref{Invoking guix system}, for more information.  See
>> +@xref{Invoking guix system} and
>>  @file{gnu/system/install.scm} in the source tree for more information
>>  about the installation image.
>
> I think this should be rephrased, because after this change, makeinfo
> complains:
>
>   ./doc/guix.texi:5937: warning: `.' or `,' must follow @xref
>
> And in the generated guix.info there is a dot before "and".

Agreed.

I think makeinfo 6.1 automatically introduces a comma here, but that was
not the case with previous versions.

Andreas, could you look into it?

Ludo’.

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

[Andreas Enge]

On Wed, Mar 09, 2016 at 12:02:44PM +0300, Alex Kost wrote:
> I think this should be rephrased, because after this change, makeinfo
> complains:
>   ./doc/guix.texi:5937: warning: `.' or `,' must follow @xref
> And in the generated guix.info there is a dot before "and".

Fixed in commit 6e6a04016d292991dcae02bbbe5a3bde616b9092, thanks for
the report!

Andreas

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

[Ludovic Courtès]

[-- Attachment #1: Type: text/plain, Size: 405 bytes --]

Andreas Enge <andreas@enge.fr> skribis:

> On Wed, Mar 09, 2016 at 12:02:44PM +0300, Alex Kost wrote:
>> I think this should be rephrased, because after this change, makeinfo
>> complains:
>>   ./doc/guix.texi:5937: warning: `.' or `,' must follow @xref
>> And in the generated guix.info there is a dot before "and".
>
> Fixed in commit 6e6a04016d292991dcae02bbbe5a3bde616b9092, thanks for
> the report!


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: Type: text/x-patch, Size: 263 bytes --]

-@xref{Invoking guix system} and
-@file{gnu/system/install.scm} in the source tree for more information
+Have a look at @file{gnu/system/install.scm} in the source tree,
+and see also @ref{Invoking guix system} for more information
 about the installation image.

[-- Attachment #3: Type: text/plain, Size: 324 bytes --]


No big deal, but in general I think it’s best to just leave the comma
after the closing brace.  Quoth the manual (info "(texinfo) @ref"):

     The '@ref' command can tempt writers to express themselves in a
  manner that is suitable for a printed manual but looks awkward in the
  Info format.  […]

Ludo’.