Minor documentation layout flaws

Minor documentation layout flaws

[percy tiglao]

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.

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!


_______________________________________________
Bug-guile mailing list
Bug-guile@gnu.org
http://lists.gnu.org/mailman/listinfo/bug-guile

Re: Minor documentation layout flaws

[Kevin Ryde]

"percy tiglao" <prtiglao@gmail.com> writes:
>
> overfull hboxes

If tex would report them in a form that you could step through it'd be
possible to fix the worst ones.

> "call-with-current-continuation" on it. But the word was so big; that
> it pushed the parameters off the page.

Thanks, I reformatted a bit.


_______________________________________________
Bug-guile mailing list
Bug-guile@gnu.org
http://lists.gnu.org/mailman/listinfo/bug-guile

Re: Minor documentation layout flaws

[percy tiglao]

On 8/28/06, Kevin Ryde <user42@zip.com.au> wrote:
> "percy tiglao" <prtiglao@gmail.com> writes:
> >
> > overfull hboxes
>
> If tex would report them in a form that you could step through it'd be
> possible to fix the worst ones.

Actually; it does.

After you do texi2dvi, all the overful hboxes are in "guile.log" (assuming
you did "texi2dvi guile.texi")

The bigger the number (ex: overful hbox: 500pt) the worse it is.


_______________________________________________
Bug-guile mailing list
Bug-guile@gnu.org
http://lists.gnu.org/mailman/listinfo/bug-guile

Re: Minor documentation layout flaws

[Neil Jerram]

"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

Re: Minor documentation layout flaws

[percy tiglao]

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

Re: Minor documentation layout flaws

[Ludovic Courtès]

Hi,

"percy tiglao" <prtiglao@gmail.com> writes:

> 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.

I'm not sure this will help, but using `@smallexample' in the Texinfo
source rather than `@example' (if this is not already the case) might
be helpful.

Thanks,
Ludovic.


_______________________________________________
Bug-guile mailing list
Bug-guile@gnu.org
http://lists.gnu.org/mailman/listinfo/bug-guile

Re: Minor documentation layout flaws

[Kevin Ryde]

"percy tiglao" <prtiglao@gmail.com> writes:
>
> Type "(backtrace)" to get more information or "(debug)" to enter the debugger.
>
> This doesn't go off the page; but it nearly does.

It wraps in info too.

> But this is obviously the output of guile.

It's free-form though, not something you have to type, or should
expect to see exactly, so it doesn't matter too much.

> Should I just add a newline between "the" and "debugger"?

Sounds fine, I made that change.


I also fixed two spots in the "format" function showing "1x2 3x4 5x6",
which I think I introduced.


_______________________________________________
Bug-guile mailing list
Bug-guile@gnu.org
http://lists.gnu.org/mailman/listinfo/bug-guile