[rfa/doco] Srink the overlay diagram

[rfa/doco] Srink the overlay diagram

[Andrew Cagney]

[-- Attachment #1: Type: text/plain, Size: 173 bytes --]

Hello,

One of the things giving overfull hboxes is JimB's overlay diagram.  The 
attached patch srinks it a little.

ok?

Andrew

PS: This diagram isn't on the 5.1 branch.

[-- Attachment #2: diffs --]
[-- Type: text/plain, Size: 3935 bytes --]

2002-01-21  Andrew Cagney  <ac131313@redhat.com>

	* gdb.texinfo (How Overlays Work): Srink the overlay diagram.

Index: gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.76
diff -p -r1.76 gdb.texinfo
*** gdb.texinfo	2002/01/20 11:59:38	1.76
--- gdb.texinfo	2002/01/21 05:07:10
*************** there.
*** 6420,6453 ****
  
  @example
  @group
!     Data                   Instruction            Larger
! Address Space             Address Space        Address Space
! +-----------+             +-----------+        +-----------+
! |           |             |           |        |           |
! +-----------+             +-----------+        +-----------+<-- overlay 1
! | program   |             |   main    |        |           | load address
! | variables |             |  program  |        | overlay 1 |
! | and heap  |             |           |    ,---|           |
! +-----------+             |           |    |   |           |
! |           |             +-----------+    |   +-----------+
! +-----------+             |           |    |   |           |
!                mapped --->+-----------+    /   +-----------+<-- overlay 2
!                address    |  overlay  | <-'    | overlay 2 | load address
!                           |   area    |  <-----|           |
!                           |           | <---.  +-----------+
!                           |           |     |  |           |
!                           +-----------+     |  |           |
!                           |           |     |  +-----------+<-- overlay 3
!                           +-----------+     `--|           | load address
!                                                | overlay 3 |
!                                                |           |
!                                                +-----------+
!                                                |           |
!                                                +-----------+
  
!     To map an overlay, copy its code from the larger address space
!     to the instruction address space.  Since the overlays shown here
!     all use the same mapped address, only one may be mapped at a time.
  @end group
  @end example
  
--- 6420,6452 ----
  
  @example
  @group
!     Data             Instruction            Larger
! Address Space       Address Space        Address Space
! +-----------+       +-----------+        +-----------+
! |           |       |           |        |           |
! +-----------+       +-----------+        +-----------+<-- overlay 1
! | program   |       |   main    |        |           | load address
! | variables |       |  program  |   ,----| overlay 1 |
! | and heap  |       |           |   |    |           |
! +-----------+       |           |   |    +-----------+
! |           |       +-----------+   |    |           |
! +-----------+       |           |   |    +-----------+<-- overlay 2
!                     |           |   |    |           | load address
!          mapped --->+-----------+   |  .-| overlay 2 |
!          address    |  overlay  | <-'  | |           |
!                     |   area    |  <---' +-----------+
!                     |           | <---.  |           |
!                     +-----------+     |  +-----------+<-- overlay 3
!                     |           |     |  |           | load address
!                     +-----------+     `--| overlay 3 |
!                                          |           |
!                                          +-----------+
!                                          |           |
!                                          +-----------+
  
! To map an overlay, copy its code from the larger address space to the
! instruction address space.  Since the overlays shown here all use the
! same mapped address, only one may be mapped at a time.
  @end group
  @end example
  

Re: [rfa/doco] Srink the overlay diagram

[Eli Zaretskii]

On Mon, 21 Jan 2002, Andrew Cagney wrote:

> One of the things giving overfull hboxes is JimB's overlay diagram.  The 
> attached patch srinks it a little.
> 
> ok?

Yes, but:

> ! To map an overlay, copy its code from the larger address space to the
> ! instruction address space.  Since the overlays shown here all use the
> ! same mapped address, only one may be mapped at a time.
>   @end group
>   @end example

Why is this text inside the @example?  If that's because of the desire
to have the text always follow the diagram, I don't see anything that
would prevent us from using @need instead of @group.  Am I missing
something?

In general, it's bad to have free text inside @example, since TeX
doesn't fill such text.  So typesetting that is prone to unexpected
problems whenever you change the output dimensions slightly (e.g.,
with @smallbook etc.).  It's best to avoid that entirely.

Re: [rfa/doco] Srink the overlay diagram

[Andrew Cagney]

> On Mon, 21 Jan 2002, Andrew Cagney wrote:
> 
> 
>> One of the things giving overfull hboxes is JimB's overlay diagram.  The 
>> attached patch srinks it a little.
>> 
>> ok?
> 
> 
> Yes, but:
> 
> 
>> ! To map an overlay, copy its code from the larger address space to the
>> ! instruction address space.  Since the overlays shown here all use the
>> ! same mapped address, only one may be mapped at a time.
>> @end group
>> @end example
> 
> 
> Why is this text inside the @example?  If that's because of the desire
> to have the text always follow the diagram, I don't see anything that
> would prevent us from using @need instead of @group.  Am I missing
> something?


I don't know.  I just work here :-)

I think the @group is needed around the actual diagram, I don't know 
about the accompanying text.


> In general, it's bad to have free text inside @example, since TeX
> doesn't fill such text.  So typesetting that is prone to unexpected
> problems whenever you change the output dimensions slightly (e.g.,
> with @smallbook etc.).  It's best to avoid that entirely.


What do you suggest? :-)

Andrew

Re: [rfa/doco] Srink the overlay diagram

[Eli Zaretskii]

> Date: Mon, 21 Jan 2002 14:45:56 -0500
> From: Andrew Cagney <ac131313@cygnus.com>
> 
> I think the @group is needed around the actual diagram, I don't know 
> about the accompanying text.

Yes, @group should be around the diagram.

> > In general, it's bad to have free text inside @example, since TeX
> > doesn't fill such text.  So typesetting that is prone to unexpected
> > problems whenever you change the output dimensions slightly (e.g.,
> > with @smallbook etc.).  It's best to avoid that entirely.
> 
> What do you suggest? :-)

Leave the text outside the @example, and instead put "@need NUMBER"
before the @example which starts the diagram, where NUMBER is enough
to allow for both the diagram and the text after it.  I'd use 10000
for NUMBER, but if you can easily print that page after TeXing it,
simply measure how many inches of vertical space does the diagram and
the text take, and multiply that by 1000.

Re: [rfa/doco] Srink the overlay diagram

[Jim Blandy]

Andrew Cagney <ac131313@cygnus.com> writes:
> One of the things giving overfull hboxes is JimB's overlay diagram.
> The attached patch srinks it a little.

One of the points of the original diagram was that the unmapped
overlays (the ones in the "larger address space") weren't all the same
size --- they were all just no larger than the overlay area.  Now
they're all the same size.

Aside from that, yes, it's fine.

Re: [rfa/doco] Srink the overlay diagram

[Jim Blandy]

"Eli Zaretskii" <eliz@is.elta.co.il> writes:
> Leave the text outside the @example, and instead put "@need NUMBER"
> before the @example which starts the diagram, where NUMBER is enough
> to allow for both the diagram and the text after it.  I'd use 10000
> for NUMBER, but if you can easily print that page after TeXing it,
> simply measure how many inches of vertical space does the diagram and
> the text take, and multiply that by 1000.

As to the original "what's that doing there?" question: It's a
caption.  Diagrams often have explanatory text, outside of the main
flow of text.

As to the formatting: anything that keeps that text immediately after
the diagram is fine.

Re: [rfa/doco] Srink the overlay diagram

[Andrew Cagney]

> "Eli Zaretskii" <eliz@is.elta.co.il> writes:
> 
>> Leave the text outside the @example, and instead put "@need NUMBER"
>> before the @example which starts the diagram, where NUMBER is enough
>> to allow for both the diagram and the text after it.  I'd use 10000
>> for NUMBER, but if you can easily print that page after TeXing it,
>> simply measure how many inches of vertical space does the diagram and
>> the text take, and multiply that by 1000.
> 
> 
> As to the original "what's that doing there?" question: It's a
> caption.  Diagrams often have explanatory text, outside of the main
> flow of text.


They tend to be just figure titles.


> As to the formatting: anything that keeps that text immediately after
> the diagram is fine


It currently reads:

``To map an overlay, copy its code from the larger address space to the
instruction address space.  Since the overlays shown here all use the
same mapped address, only one may be mapped at a time.

This diagram shows a system with separate data and instruction address
spaces.  For a system with a single address space for data and
instructions, the diagram would be similar, except that the program
variables and heap would share an address space with the main program
and the overlay area.''


which to me is a little strange.  ``This diagram ...'' is the text 
straight after the diagram (but appears on the following page in the 
printed document).

I think:

	@example @group
	<figure>
	@anchor{x-spot the title}<title>
	@end end

Diagram @xref{x-spot the title} .... would work better.

Andrew

--

PS: I've adjusted the diagram to have different size overlays.  Also 
added an @c comment explaining that it was intentional.  The reason for 
srinking the diagram height was to get it all onto one page.

PPS: Suggestions for a figure title welcome.

Re: [rfa/doco] Srink the overlay diagram

[Andrew Cagney]

[-- Attachment #1: Type: text/plain, Size: 228 bytes --]

> I think:
> 
>     @example @group
>     <figure>
>     @anchor{x-spot the title}<title>
>     @end end
> 
> Diagram @xref{x-spot the title} .... would work better.


The attached does this.  I ended up using @pxref{}.

Andrew

[-- Attachment #2: diffs --]
[-- Type: text/plain, Size: 5333 bytes --]

2002-01-21  Andrew Cagney  <ac131313@redhat.com>

	* gdb.texinfo (How Overlays Work): Srink the overlay diagram.

Index: gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.76
diff -p -r1.76 gdb.texinfo
*** gdb.texinfo	2002/01/20 11:59:38	1.76
--- gdb.texinfo	2002/01/29 21:55:57
*************** overlay's machine code from the large me
*** 6418,6461 ****
  for it in the instruction memory, and then jump to its entry point
  there.
  
  @example
  @group
!     Data                   Instruction            Larger
! Address Space             Address Space        Address Space
! +-----------+             +-----------+        +-----------+
! |           |             |           |        |           |
! +-----------+             +-----------+        +-----------+<-- overlay 1
! | program   |             |   main    |        |           | load address
! | variables |             |  program  |        | overlay 1 |
! | and heap  |             |           |    ,---|           |
! +-----------+             |           |    |   |           |
! |           |             +-----------+    |   +-----------+
! +-----------+             |           |    |   |           |
!                mapped --->+-----------+    /   +-----------+<-- overlay 2
!                address    |  overlay  | <-'    | overlay 2 | load address
!                           |   area    |  <-----|           |
!                           |           | <---.  +-----------+
!                           |           |     |  |           |
!                           +-----------+     |  |           |
!                           |           |     |  +-----------+<-- overlay 3
!                           +-----------+     `--|           | load address
!                                                | overlay 3 |
!                                                |           |
!                                                +-----------+
!                                                |           |
!                                                +-----------+
  
!     To map an overlay, copy its code from the larger address space
!     to the instruction address space.  Since the overlays shown here
!     all use the same mapped address, only one may be mapped at a time.
  @end group
  @end example
  
! This diagram shows a system with separate data and instruction address
! spaces.  For a system with a single address space for data and
! instructions, the diagram would be similar, except that the program
! variables and heap would share an address space with the main program
! and the overlay area.
  
  An overlay loaded into instruction memory and ready for use is called a
  @dfn{mapped} overlay; its @dfn{mapped address} is its address in the
--- 6418,6465 ----
  for it in the instruction memory, and then jump to its entry point
  there.
  
+ @c NB:  In the below the mapped area's size is greater or equal to the
+ @c size of all overlays.  This is intentional to remind the developer
+ @c overlays don't necessarily need to be the same size.
+ 
  @example
  @group
!     Data             Instruction            Larger
! Address Space       Address Space        Address Space
! +-----------+       +-----------+        +-----------+
! |           |       |           |        |           |
! +-----------+       +-----------+        +-----------+<-- overlay 1
! | program   |       |   main    |   .----| overlay 1 | load address
! | variables |       |  program  |   |    +-----------+
! | and heap  |       |           |   |    |           |
! +-----------+       |           |   |    +-----------+<-- overlay 2
! |           |       +-----------+   |    |           | load address
! +-----------+       |           |   |  .-| overlay 2 |
!                     |           |   |  | |           |
!          mapped --->+-----------+   |  | +-----------+
!          address    |           |   |  | |           |
!                     |  overlay  | <-'  | |           |
!                     |   area    |  <---' +-----------+<-- overlay 3
!                     |           | <---.  |           | load address
!                     +-----------+     `--| overlay 3 |
!                     |           |        |           |
!                     +-----------+        |           |
!                                          +-----------+
!                                          |           |
!                                          +-----------+
  
!                     @anchor{A code overlay}A code overlay
  @end group
  @end example
  
! The diagram (@pxref{A code overlay}) shows a system with separate data
! and instruction address spaces.  To map an overlay, the program copies
! its code from the larger address space to the instruction address space.
! Since the overlays shown here all use the same mapped address, only one
! may be mapped at a time.  For a system with a single address space for
! data and instructions, the diagram would be similar, except that the
! program variables and heap would share an address space with the main
! program and the overlay area.
  
  An overlay loaded into instruction memory and ready for use is called a
  @dfn{mapped} overlay; its @dfn{mapped address} is its address in the

Re: [rfa/doco] Srink the overlay diagram

[Andrew Cagney]

> 2002-01-21  Andrew Cagney  <ac131313@redhat.com>
> 
> * gdb.texinfo (How Overlays Work): Srink the overlay diagram.
> 
> Index: gdb.texinfo
> 

I've checked this in.

Andrew