From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: ludo@gnu.org (Ludovic =?iso-8859-1?Q?Court=E8s?=) Newsgroups: gmane.lisp.guile.user Subject: Re: Any advice about improving the docs? Date: Fri, 04 Nov 2011 17:44:07 +0100 Message-ID: <87lirvald4.fsf@gnu.org> References: <87ipn1coos.fsf@goof.bjgalaxy> NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Trace: dough.gmane.org 1320425075 330 80.91.229.12 (4 Nov 2011 16:44:35 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Fri, 4 Nov 2011 16:44:35 +0000 (UTC) To: guile-user@gnu.org Original-X-From: guile-user-bounces+guile-user=m.gmane.org@gnu.org Fri Nov 04 17:44:31 2011 Return-path: Envelope-to: guile-user@m.gmane.org Original-Received: from lists.gnu.org ([140.186.70.17]) by lo.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1RMMsX-0007Lx-Ig for guile-user@m.gmane.org; Fri, 04 Nov 2011 17:44:29 +0100 Original-Received: from localhost ([::1]:42508 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1RMMsX-0008QW-3K for guile-user@m.gmane.org; Fri, 04 Nov 2011 12:44:29 -0400 Original-Received: from eggs.gnu.org ([140.186.70.92]:47269) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1RMMsS-0008Q7-D5 for guile-user@gnu.org; Fri, 04 Nov 2011 12:44:25 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1RMMsR-0003Fh-1G for guile-user@gnu.org; Fri, 04 Nov 2011 12:44:24 -0400 Original-Received: from lo.gmane.org ([80.91.229.12]:56731) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1RMMsQ-0003Ez-IW for guile-user@gnu.org; Fri, 04 Nov 2011 12:44:22 -0400 Original-Received: from list by lo.gmane.org with local (Exim 4.69) (envelope-from ) id 1RMMsN-0007HL-Ec for guile-user@gnu.org; Fri, 04 Nov 2011 17:44:19 +0100 Original-Received: from 193.50.110.167 ([193.50.110.167]) by main.gmane.org with esmtp (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Fri, 04 Nov 2011 17:44:19 +0100 Original-Received: from ludo by 193.50.110.167 with local (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Fri, 04 Nov 2011 17:44:19 +0100 X-Injected-Via-Gmane: http://gmane.org/ Original-Lines: 97 Original-X-Complaints-To: usenet@dough.gmane.org X-Gmane-NNTP-Posting-Host: 193.50.110.167 X-URL: http://www.fdn.fr/~lcourtes/ X-Revolutionary-Date: 14 Brumaire an 220 de la =?iso-8859-1?Q?R=E9volution?= X-PGP-Key-ID: 0xEA52ECF4 X-PGP-Key: http://www.fdn.fr/~lcourtes/ludovic.asc X-PGP-Fingerprint: 83C4 F8E5 10A3 3B4C 5BEA D15D 77DD 95E2 EA52 ECF4 X-OS: x86_64-unknown-linux-gnu User-Agent: Gnus/5.110018 (No Gnus v0.18) Emacs/24.0.90 (gnu/linux) Cancel-Lock: sha1:pvmaWfaj+Difr6MHWSFTAgDV8ZU= X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 3) X-Received-From: 80.91.229.12 X-BeenThere: guile-user@gnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: General Guile related discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guile-user-bounces+guile-user=m.gmane.org@gnu.org Original-Sender: guile-user-bounces+guile-user=m.gmane.org@gnu.org Xref: news.gmane.org gmane.lisp.guile.user:8930 Archived-At: Hi, 42toes@gmail.com skribis: > I seek advice on making the Guile manual and docstrings clearer and more > consistent, two qualities that I think novices especially appreciate. Thanks for looking into it! > ---------------------------------------------------------------------- > @deffn {Scheme Procedure} eval exp module_or_state > @deffnx {C Function} scm_eval (exp, module_or_state) > Evaluate @var{exp}, a list representing a Scheme expression, > in the top-level environment specified by @var{module}. > ---------------------------------------------------------------------- > > I recall seeing several @deffn's w/ hyphentated variable names. So would > I change in the @deffn line "module_or_state" to "module-or-state"? I > assume that I would then change "@var{module}" to > "@var{module-or-state}". Three considerations: it has to be the same name for the Scheme proc and the C function, it has to be a valid C identifier, and of course it has to be descriptive. So in this example I would stick to ‘module_or_state’. > ---------------------------------------------------------------------- > @deffn {Scheme Procedure} symbol-set! o s v > @deffnx {C Function} scm_symbol_set_x (o, s, v) > Find the symbol in @var{obarray} whose name is @var{string}, and rebind > ---------------------------------------------------------------------- > > Just spell out the names in the @deffn? I.e., > "... obarray string value" ? Yes, definitely. > ---------------------------------------------------------------------- > @deffn {Scheme Procedure} seek fd_port offset whence > @deffnx {C Function} scm_seek (fd_port, offset, whence) > Sets the current position of @var{fd/port} to the integer > ---------------------------------------------------------------------- > > Why not, in keeping w/ the first example above, just "... seek > fd-or-port", "... scm_seek (fd_or_port", and "@var{fd-or-port}"? Agreed. > ---------------------------------------------------------------------- > @deffn {Scheme Procedure} get-char port > Reads from @var{textual-input-port}, blocking as necessary, until a > ---------------------------------------------------------------------- > > "textual-input-port" implies the type of port, but why not just say > "Reads from textual input port @var{port} ..."? Agreed. > B. Minor issues > > 1. Case errors (e.g., unnecessary caps in a @var or on a @deffn line) Like @var{VAR}? Did you find it? If so, it probably needs to be fixed, yes. > 2. Redundant plurals (e.g., bindings @dots{} instead of binding @dots{}) It’s not necessary redundant, I think. As in ‘args ...’. > 3. Bad option notation on variables (non-keyword names) > (e.g., ... pointer->string pointer [length] [encoding] (bad) > instead of ... pointer->string pointer [length [encoding]] (good) Indeed, should be fixed. > 4. Typographical problems (e.g., using "..." instead of "@dots{}") > > OK to fix these? Yes! > C. Things not to fix > > 1. doc/maint/guile.texi -- seems neglected > 2. Variable name mismatches for a proc in the manual versus its docstring > > Don't bother with these? Don’t bother! We’d be happy to accept a patch. It may be necessary to assign copyright to the FSF, if this is not a problem for you. We can discuss this off-line if you want. Thanks, Ludo’.