From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: 42toes@gmail.com Newsgroups: gmane.lisp.guile.user Subject: Any advice about improving the docs? Date: Thu, 03 Nov 2011 09:37:07 -0400 Message-ID: <87ipn1coos.fsf@goof.bjgalaxy> Reply-To: b3timmons@speedymail.org NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain X-Trace: dough.gmane.org 1320423502 19928 80.91.229.12 (4 Nov 2011 16:18:22 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Fri, 4 Nov 2011 16:18:22 +0000 (UTC) To: guile-user@gnu.org Original-X-From: guile-user-bounces+guile-user=m.gmane.org@gnu.org Fri Nov 04 17:18:18 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 1RMMTB-0001E3-DP for guile-user@m.gmane.org; Fri, 04 Nov 2011 17:18:18 +0100 Original-Received: from localhost ([::1]:50395 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1RMMTA-0000Di-Pw for guile-user@m.gmane.org; Fri, 04 Nov 2011 12:18:16 -0400 Original-Received: from eggs.gnu.org ([140.186.70.92]:47061) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from <42toes@gmail.com>) id 1RLxXW-0008Kg-K3 for guile-user@gnu.org; Thu, 03 Nov 2011 09:41:07 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from <42toes@gmail.com>) id 1RLxXQ-0008Ed-RJ for guile-user@gnu.org; Thu, 03 Nov 2011 09:41:06 -0400 Original-Received: from mail-gx0-f169.google.com ([209.85.161.169]:43004) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from <42toes@gmail.com>) id 1RLxXQ-0008EW-Ob for guile-user@gnu.org; Thu, 03 Nov 2011 09:41:00 -0400 Original-Received: by ggnh4 with SMTP id h4so1531819ggn.0 for ; Thu, 03 Nov 2011 06:40:59 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=gamma; h=from:to:subject:reply-to:date:message-id:user-agent:mime-version :content-type; bh=7hdhLwkY5OVThpia7LQxyy9i/NDudf0LT9IBIyhqpKk=; b=WNqDAs1XyErevlC9e2GZqAGcsVJf29T7G0nZscw60tDAT5DOUe2tpIFUnzA2uDCajU apnfgWlqrnSfg7qDi2MnHbmT69GFSOL55fT+T8Xnr7SnvARkotPAy1MrmWoBio6/Aw3z qkQWJvsTiZnWKur7mc13gW6QDf7DAwfCUHmcU= Original-Received: by 10.236.124.17 with SMTP id w17mr13147631yhh.126.1320327659504; Thu, 03 Nov 2011 06:40:59 -0700 (PDT) Original-Received: from goof.bjgalaxy (dialup-4.248.249.82.Dial1.Washington2.Level3.net. [4.248.249.82]) by mx.google.com with ESMTPS id j25sm9452759yhm.12.2011.11.03.06.40.05 (version=TLSv1/SSLv3 cipher=OTHER); Thu, 03 Nov 2011 06:40:58 -0700 (PDT) Original-Received: from b3po by goof.bjgalaxy with local (Exim 4.76) (envelope-from <42toes@gmail.com>) id 1RLxU4-0007cj-8C for guile-user@gnu.org; Thu, 03 Nov 2011 09:37:32 -0400 User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.0.91 (gnu/linux) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 2) X-Received-From: 209.85.161.169 X-Mailman-Approved-At: Fri, 04 Nov 2011 12:18:13 -0400 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:8929 Archived-At: Hi, I seek advice on making the Guile manual and docstrings clearer and more consistent, two qualities that I think novices especially appreciate. Some considerations: A. Variable names of definition headers not matching those in bodies. E.g., ---------------------------------------------------------------------- @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}". ---------------------------------------------------------------------- @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" ? ---------------------------------------------------------------------- @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}"? ---------------------------------------------------------------------- @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} ..."? B. Minor issues 1. Case errors (e.g., unnecessary caps in a @var or on a @deffn line) 2. Redundant plurals (e.g., bindings @dots{} instead of binding @dots{}) 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) 4. Typographical problems (e.g., using "..." instead of "@dots{}") OK to fix these? 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? Thanks, Bake