all messages for Guix-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
* Re: 01/01: doc: Typos and small stylistic changes.
       [not found] ` <E1acE7O-0002cK-0Z@vcs.savannah.gnu.org>
@ 2016-03-05 21:48   ` Ludovic Courtès
  2016-03-06 13:10     ` Andreas Enge
  2016-03-06 16:02     ` Andreas Enge
  2016-03-09  9:02   ` Alex Kost
  1 sibling, 2 replies; 11+ messages in thread
From: Ludovic Courtès @ 2016-03-05 21:48 UTC (permalink / raw)
  To: Andreas Enge; +Cc: guix-devel

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’.

^ permalink raw reply	[flat|nested] 11+ messages in thread

* Re: 01/01: doc: Typos and small stylistic changes.
  2016-03-05 21:48   ` 01/01: doc: Typos and small stylistic changes Ludovic Courtès
@ 2016-03-06 13:10     ` Andreas Enge
  2016-03-06 13:46       ` Mathieu Lirzin
  2016-03-06 23:10       ` Ludovic Courtès
  2016-03-06 16:02     ` Andreas Enge
  1 sibling, 2 replies; 11+ messages in thread
From: Andreas Enge @ 2016-03-06 13:10 UTC (permalink / raw)
  To: Ludovic Courtès; +Cc: guix-devel

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

^ permalink raw reply	[flat|nested] 11+ messages in thread

* Re: 01/01: doc: Typos and small stylistic changes.
  2016-03-06 13:10     ` Andreas Enge
@ 2016-03-06 13:46       ` Mathieu Lirzin
  2016-03-06 15:26         ` Andreas Enge
  2016-03-06 23:10       ` Ludovic Courtès
  1 sibling, 1 reply; 11+ messages in thread
From: Mathieu Lirzin @ 2016-03-06 13:46 UTC (permalink / raw)
  To: Andreas Enge; +Cc: guix-devel

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

^ permalink raw reply	[flat|nested] 11+ messages in thread

* Re: 01/01: doc: Typos and small stylistic changes.
  2016-03-06 13:46       ` Mathieu Lirzin
@ 2016-03-06 15:26         ` Andreas Enge
  2016-03-06 19:13           ` Mathieu Lirzin
  0 siblings, 1 reply; 11+ messages in thread
From: Andreas Enge @ 2016-03-06 15:26 UTC (permalink / raw)
  To: Mathieu Lirzin; +Cc: guix-devel

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

^ permalink raw reply	[flat|nested] 11+ messages in thread

* Re: 01/01: doc: Typos and small stylistic changes.
  2016-03-05 21:48   ` 01/01: doc: Typos and small stylistic changes Ludovic Courtès
  2016-03-06 13:10     ` Andreas Enge
@ 2016-03-06 16:02     ` Andreas Enge
  1 sibling, 0 replies; 11+ messages in thread
From: Andreas Enge @ 2016-03-06 16:02 UTC (permalink / raw)
  To: Ludovic Courtès; +Cc: guix-devel

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

^ permalink raw reply	[flat|nested] 11+ messages in thread

* Re: 01/01: doc: Typos and small stylistic changes.
  2016-03-06 15:26         ` Andreas Enge
@ 2016-03-06 19:13           ` Mathieu Lirzin
  0 siblings, 0 replies; 11+ messages in thread
From: Mathieu Lirzin @ 2016-03-06 19:13 UTC (permalink / raw)
  To: Andreas Enge; +Cc: guix-devel

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

^ permalink raw reply	[flat|nested] 11+ messages in thread

* Re: 01/01: doc: Typos and small stylistic changes.
  2016-03-06 13:10     ` Andreas Enge
  2016-03-06 13:46       ` Mathieu Lirzin
@ 2016-03-06 23:10       ` Ludovic Courtès
  1 sibling, 0 replies; 11+ messages in thread
From: Ludovic Courtès @ 2016-03-06 23:10 UTC (permalink / raw)
  To: Andreas Enge; +Cc: guix-devel

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’.

^ permalink raw reply	[flat|nested] 11+ messages in thread

* Re: 01/01: doc: Typos and small stylistic changes.
       [not found] ` <E1acE7O-0002cK-0Z@vcs.savannah.gnu.org>
  2016-03-05 21:48   ` 01/01: doc: Typos and small stylistic changes Ludovic Courtès
@ 2016-03-09  9:02   ` Alex Kost
  2016-03-11 14:19     ` Ludovic Courtès
  2016-03-14 19:58     ` Andreas Enge
  1 sibling, 2 replies; 11+ messages in thread
From: Alex Kost @ 2016-03-09  9:02 UTC (permalink / raw)
  To: guix-devel

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

^ permalink raw reply	[flat|nested] 11+ messages in thread

* Re: 01/01: doc: Typos and small stylistic changes.
  2016-03-09  9:02   ` Alex Kost
@ 2016-03-11 14:19     ` Ludovic Courtès
  2016-03-14 19:58     ` Andreas Enge
  1 sibling, 0 replies; 11+ messages in thread
From: Ludovic Courtès @ 2016-03-11 14:19 UTC (permalink / raw)
  To: Alex Kost, Andreas Enge; +Cc: guix-devel

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’.

^ permalink raw reply	[flat|nested] 11+ messages in thread

* Re: 01/01: doc: Typos and small stylistic changes.
  2016-03-09  9:02   ` Alex Kost
  2016-03-11 14:19     ` Ludovic Courtès
@ 2016-03-14 19:58     ` Andreas Enge
  2016-03-15 16:20       ` Ludovic Courtès
  1 sibling, 1 reply; 11+ messages in thread
From: Andreas Enge @ 2016-03-14 19:58 UTC (permalink / raw)
  To: Alex Kost; +Cc: guix-devel

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

^ permalink raw reply	[flat|nested] 11+ messages in thread

* Re: 01/01: doc: Typos and small stylistic changes.
  2016-03-14 19:58     ` Andreas Enge
@ 2016-03-15 16:20       ` Ludovic Courtès
  0 siblings, 0 replies; 11+ messages in thread
From: Ludovic Courtès @ 2016-03-15 16:20 UTC (permalink / raw)
  To: Andreas Enge; +Cc: guix-devel, Alex Kost

[-- 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’.

^ permalink raw reply	[flat|nested] 11+ messages in thread

end of thread, other threads:[~2016-03-15 16:20 UTC | newest]

Thread overview: 11+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
     [not found] <20160305152745.10002.35086@vcs.savannah.gnu.org>
     [not found] ` <E1acE7O-0002cK-0Z@vcs.savannah.gnu.org>
2016-03-05 21:48   ` 01/01: doc: Typos and small stylistic changes Ludovic Courtès
2016-03-06 13:10     ` Andreas Enge
2016-03-06 13:46       ` Mathieu Lirzin
2016-03-06 15:26         ` Andreas Enge
2016-03-06 19:13           ` Mathieu Lirzin
2016-03-06 23:10       ` Ludovic Courtès
2016-03-06 16:02     ` Andreas Enge
2016-03-09  9:02   ` Alex Kost
2016-03-11 14:19     ` Ludovic Courtès
2016-03-14 19:58     ` Andreas Enge
2016-03-15 16:20       ` Ludovic Courtès

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.