From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: "percy tiglao" Newsgroups: gmane.lisp.guile.bugs Subject: Re: Minor documentation layout flaws Date: Fri, 1 Sep 2006 22:31:36 -0400 Message-ID: References: <87wt8rdw71.fsf@ossau.uklinux.net> NNTP-Posting-Host: main.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit X-Trace: sea.gmane.org 1157164305 17352 80.91.229.2 (2 Sep 2006 02:31:45 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Sat, 2 Sep 2006 02:31:45 +0000 (UTC) Cc: bug-guile@gnu.org Original-X-From: bug-guile-bounces+guile-bugs=m.gmane.org@gnu.org Sat Sep 02 04:31:44 2006 Return-path: Envelope-to: guile-bugs@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by ciao.gmane.org with esmtp (Exim 4.43) id 1GJLIN-0006qX-89 for guile-bugs@m.gmane.org; Sat, 02 Sep 2006 04:31:43 +0200 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1GJLIM-0006ie-LC for guile-bugs@m.gmane.org; Fri, 01 Sep 2006 22:31:42 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1GJLIJ-0006iZ-8j for bug-guile@gnu.org; Fri, 01 Sep 2006 22:31:39 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1GJLIH-0006iI-Rc for bug-guile@gnu.org; Fri, 01 Sep 2006 22:31:38 -0400 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1GJLIH-0006iF-LU for bug-guile@gnu.org; Fri, 01 Sep 2006 22:31:37 -0400 Original-Received: from [66.249.82.237] (helo=wx-out-0506.google.com) by monty-python.gnu.org with esmtp (Exim 4.52) id 1GJLSG-0001UJ-4P for bug-guile@gnu.org; Fri, 01 Sep 2006 22:41:56 -0400 Original-Received: by wx-out-0506.google.com with SMTP id i26so1561393wxd for ; Fri, 01 Sep 2006 19:31:36 -0700 (PDT) DomainKey-Signature: a=rsa-sha1; q=dns; c=nofws; s=beta; d=gmail.com; h=received:message-id:date:from:to:subject:cc:in-reply-to:mime-version:content-type:content-transfer-encoding:content-disposition:references; b=oL9viIszrVYATkzBVYUbbeXHVX8coOijLI1mZIZVxaX/ZE/Io/GuRxR73P2vu0KgqtQAHce7SWbI6nLw8Izci44yefx1opGXjVTg2HgjhsZv3o590AQCwq0jtw8/Xxk7CD58XHoXhy3IjRLAbywg6tpnx5Fsz6cyhsiJAUOcZB8= Original-Received: by 10.70.103.12 with SMTP id a12mr3632660wxc; Fri, 01 Sep 2006 19:31:36 -0700 (PDT) Original-Received: by 10.70.21.16 with HTTP; Fri, 1 Sep 2006 19:31:36 -0700 (PDT) Original-To: "Neil Jerram" In-Reply-To: <87wt8rdw71.fsf@ossau.uklinux.net> Content-Disposition: inline X-BeenThere: bug-guile@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Bug reports for GUILE, GNU's Ubiquitous Extension Language" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: bug-guile-bounces+guile-bugs=m.gmane.org@gnu.org Errors-To: bug-guile-bounces+guile-bugs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.lisp.guile.bugs:3331 Archived-At: Okay; I'm going along just fine in removing these minor errors in documentation (a line break here; shorten some words over there...) But there is one issue that keeps comming up that I just don't know how to handle: What should I do about ouput? For example, on page 40 (the pg 40 in the ps output... maybe different) you've got the line: Type "(backtrace)" to get more information or "(debug)" to enter the debugger. This doesn't go off the page; but it nearly does. But this is obviously the output of guile. Should I just add a newline between "the" and "debugger"? Or would it be preferable to just not indent the "output" as much? On 8/29/06, Neil Jerram wrote: > "percy tiglao" writes: > > > Hello. I decided to make a print version of the reference manual; but > > there were so many stuff that ran through the right side of the page > > (technically, overfull hboxes). I'm interested in helping you guys > > remove those things so that all the stuff fits on a page; but I'm > > wondering if there are any standards and such before I start making > > major changes. > > Thanks, I'm interested in this too. Does this depend on what paper > size you are targetting? Or does Texinfo enforce a particular paper > size, so you don't really have a choice? > > > For example: one of the pages had some guile source code with > > "call-with-current-continuation" on it. But the word was so big; that > > it pushed the parameters off the page. The easiest correction is to > > just change the word into "call/cc" instead; but that might conflict > > with your standard... > > > > So I'm just wondering if you got anything like that. If not... I'll be > > working on that documentation patch! > > From a documentation point of view, I'd say the only principle is that > everything has to make sense in its own context. So in this case, > "call/cc" instead of "call-with-current-continuation" would be fine if > either (a) it is noted near the example that call/cc is a common > abbreviation for call-with-current-continuation, or (b) the section is > sufficiently advanced that it can be assumed all readers would know > (a) already. > > Regards, > Neil > > _______________________________________________ Bug-guile mailing list Bug-guile@gnu.org http://lists.gnu.org/mailman/listinfo/bug-guile