* [rfa/doco] Srink the overlay diagram
@ 2002-01-20 21:11 Andrew Cagney
2002-01-21 1:59 ` Eli Zaretskii
2002-01-24 18:54 ` Jim Blandy
0 siblings, 2 replies; 9+ messages in thread
From: Andrew Cagney @ 2002-01-20 21:11 UTC (permalink / raw)
To: gdb-patches
[-- 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
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [rfa/doco] Srink the overlay diagram
2002-01-20 21:11 [rfa/doco] Srink the overlay diagram Andrew Cagney
@ 2002-01-21 1:59 ` Eli Zaretskii
2002-01-21 11:46 ` Andrew Cagney
2002-01-24 18:54 ` Jim Blandy
1 sibling, 1 reply; 9+ messages in thread
From: Eli Zaretskii @ 2002-01-21 1:59 UTC (permalink / raw)
To: Andrew Cagney; +Cc: gdb-patches
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.
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [rfa/doco] Srink the overlay diagram
2002-01-21 1:59 ` Eli Zaretskii
@ 2002-01-21 11:46 ` Andrew Cagney
2002-01-22 1:13 ` Eli Zaretskii
0 siblings, 1 reply; 9+ messages in thread
From: Andrew Cagney @ 2002-01-21 11:46 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: gdb-patches
> 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
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [rfa/doco] Srink the overlay diagram
2002-01-21 11:46 ` Andrew Cagney
@ 2002-01-22 1:13 ` Eli Zaretskii
2002-01-24 18:55 ` Jim Blandy
0 siblings, 1 reply; 9+ messages in thread
From: Eli Zaretskii @ 2002-01-22 1:13 UTC (permalink / raw)
To: ac131313; +Cc: gdb-patches
> 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.
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [rfa/doco] Srink the overlay diagram
2002-01-22 1:13 ` Eli Zaretskii
@ 2002-01-24 18:55 ` Jim Blandy
2002-01-29 7:58 ` Andrew Cagney
0 siblings, 1 reply; 9+ messages in thread
From: Jim Blandy @ 2002-01-24 18:55 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: ac131313, gdb-patches
"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.
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [rfa/doco] Srink the overlay diagram
2002-01-24 18:55 ` Jim Blandy
@ 2002-01-29 7:58 ` Andrew Cagney
2002-01-29 13:58 ` Andrew Cagney
0 siblings, 1 reply; 9+ messages in thread
From: Andrew Cagney @ 2002-01-29 7:58 UTC (permalink / raw)
To: Jim Blandy; +Cc: Eli Zaretskii, gdb-patches
> "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.
^ permalink raw reply [flat|nested] 9+ messages in thread* Re: [rfa/doco] Srink the overlay diagram
2002-01-29 7:58 ` Andrew Cagney
@ 2002-01-29 13:58 ` Andrew Cagney
2002-02-07 15:51 ` Andrew Cagney
0 siblings, 1 reply; 9+ messages in thread
From: Andrew Cagney @ 2002-01-29 13:58 UTC (permalink / raw)
To: Andrew Cagney; +Cc: Jim Blandy, Eli Zaretskii, gdb-patches
[-- 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
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [rfa/doco] Srink the overlay diagram
2002-01-20 21:11 [rfa/doco] Srink the overlay diagram Andrew Cagney
2002-01-21 1:59 ` Eli Zaretskii
@ 2002-01-24 18:54 ` Jim Blandy
1 sibling, 0 replies; 9+ messages in thread
From: Jim Blandy @ 2002-01-24 18:54 UTC (permalink / raw)
To: Andrew Cagney; +Cc: gdb-patches
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.
^ permalink raw reply [flat|nested] 9+ messages in thread
end of thread, other threads:[~2002-02-07 23:51 UTC | newest]
Thread overview: 9+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2002-01-20 21:11 [rfa/doco] Srink the overlay diagram Andrew Cagney
2002-01-21 1:59 ` Eli Zaretskii
2002-01-21 11:46 ` Andrew Cagney
2002-01-22 1:13 ` Eli Zaretskii
2002-01-24 18:55 ` Jim Blandy
2002-01-29 7:58 ` Andrew Cagney
2002-01-29 13:58 ` Andrew Cagney
2002-02-07 15:51 ` Andrew Cagney
2002-01-24 18:54 ` Jim Blandy
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox