From mboxrd@z Thu Jan  1 00:00:00 1970
From: Andreas Enge <andreas@enge.fr>
Subject: Re: 01/01: doc: Typos and small stylistic changes.
Date: Sun, 6 Mar 2016 16:26:46 +0100
Message-ID: <20160306152646.GA16301@solar>
References: <20160305152745.10002.35086@vcs.savannah.gnu.org>
	<E1acE7O-0002cK-0Z@vcs.savannah.gnu.org> <877fhg38b2.fsf@gnu.org>
	<20160306131042.GA13567@solar> <87fuw3d8ip.fsf@gnu.org>
Mime-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Return-path: <guix-devel-bounces+gcggd-guix-devel=m.gmane.org@gnu.org>
Received: from eggs.gnu.org ([2001:4830:134:3::10]:45673)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <andreas@enge.fr>) id 1acaa6-0000dd-Gp
	for guix-devel@gnu.org; Sun, 06 Mar 2016 10:26:55 -0500
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <andreas@enge.fr>) id 1acaa4-0006r4-AR
	for guix-devel@gnu.org; Sun, 06 Mar 2016 10:26:54 -0500
Received: from mailrelay7.public.one.com ([91.198.169.215]:53541)
	by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <andreas@enge.fr>) id 1acaa3-0006qg-W9
	for guix-devel@gnu.org; Sun, 06 Mar 2016 10:26:52 -0500
Content-Disposition: inline
In-Reply-To: <87fuw3d8ip.fsf@gnu.org>
List-Id: "Development of GNU Guix and the GNU System distribution."
	<guix-devel.gnu.org>
List-Unsubscribe: <https://lists.gnu.org/mailman/options/guix-devel>,
	<mailto:guix-devel-request@gnu.org?subject=unsubscribe>
List-Archive: <http://lists.gnu.org/archive/html/guix-devel>
List-Post: <mailto:guix-devel@gnu.org>
List-Help: <mailto:guix-devel-request@gnu.org?subject=help>
List-Subscribe: <https://lists.gnu.org/mailman/listinfo/guix-devel>,
	<mailto:guix-devel-request@gnu.org?subject=subscribe>
Errors-To: guix-devel-bounces+gcggd-guix-devel=m.gmane.org@gnu.org
Sender: guix-devel-bounces+gcggd-guix-devel=m.gmane.org@gnu.org
To: Mathieu Lirzin <mthl@gnu.org>
Cc: guix-devel@gnu.org

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