Re: Minor documentation layout flaws

From: "percy tiglao" <prtiglao@gmail.com>
Cc: bug-guile@gnu.org
Subject: Re: Minor documentation layout flaws
Date: Fri, 1 Sep 2006 22:31:36 -0400	[thread overview]
Message-ID: <aec19dbb0609011931g3b23a60eo2e5f1c0f3b0c25df@mail.gmail.com> (raw)
In-Reply-To: <87wt8rdw71.fsf@ossau.uklinux.net>

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 <neil@ossau.uklinux.net> wrote:
> "percy tiglao" <prtiglao@gmail.com> 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