From mboxrd@z Thu Jan 1 00:00:00 1970 From: Mathieu Lirzin Subject: Re: 01/01: doc: Typos and small stylistic changes. Date: Sun, 06 Mar 2016 14:46:06 +0100 Message-ID: <87fuw3d8ip.fsf@gnu.org> References: <20160305152745.10002.35086@vcs.savannah.gnu.org> <877fhg38b2.fsf@gnu.org> <20160306131042.GA13567@solar> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:48335) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1acZ0k-0001FB-MF for guix-devel@gnu.org; Sun, 06 Mar 2016 08:46:19 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1acZ0j-0002bm-EH for guix-devel@gnu.org; Sun, 06 Mar 2016 08:46:18 -0500 In-Reply-To: <20160306131042.GA13567@solar> (Andreas Enge's message of "Sun, 6 Mar 2016 14:10:42 +0100") List-Id: "Development of GNU Guix and the GNU System distribution." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-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: Andreas Enge Cc: guix-devel@gnu.org Andreas Enge writes: > On Sat, Mar 05, 2016 at 10:48:33PM +0100, Ludovic Court=C3=A8s 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 sou= nds > very tedious. I will give it a try. > > I suppose it is not easily possible to import the doc strings automatical= ly > 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. --=20 Mathieu Lirzin