[PATCH] Symbol Separation - Take 2

[Gerald Pfeifer]

Thanks for the updated patch and the add documentation.

I'm not a native speaker, but there seem to be quite a couple of issues
with the documentation.  Below I'm trying to help with some of them, but
I think it would be best if some technical writer or fellow developer at
Apple could have another look as well.

On Mon, 14 Jul 2003, Devang Patel wrote:
> This patch is same as previous patch. Only difference is in
> documentation.

+ @item -grepository
+ @opindex grepository
+ Instructs compiler to find and validate symbol repository available
+ in include paths.

"Instructs the compiler to..."

Though, perhaps just "Consider symbol repositories available..."?

"symbol repositories" (Plural) ?

+ @item -fsave-repository=@var{location}
+ @opindex fsave-repository
+ Creates a separate symbol repository at @var{location} for given input
+ header file.

Again, _how_ is that input header file given? Note that this sentence
states that there is just a single such file.

+ This new separate repository contains only debugging symbols.

Omit separate.

+ In a typical large project, every source file includes very large
+ headers. Usually such large headers do not change frequently but
+ they add their overhead in standard compile-link-debug cycle. As

"...but still add overhead to the standard compile-link-debug cycle..."

+ far as debugging information is concerned, it adds overheads in
+ 4 steps:

"overhead" (singular)

+ (1) GCC has to generate redundant debugging information for types
+     while compiling every source file.
+ (2) GCC has to dump this redundant info in .s files.
+ (3) Assembler has to chew more bytes and emit bigger .o files.
+ (4) Linker has to chew more bytes and do more work to reduce redundant
+     info.

I don't think this will show up properly in info or DVI formats.

"The assembler has to process larger input and emits bigger
@file{.o} files."

"The linker has to process larger input and reduce redundant information."

+ In many cases precompiled header (@pxref{Precompiled Headers}) helps to
+ reduce step(1) overhead.

"precompiled headers...help...to reduce the overhead from item (1) above."

+ In this new model, symbol repositories containing debugging informations
+ are created in advance.

"information" (singular)

+ While compiling source files, GCC consults these
+ repositories before generating debugging information for each header and
+ avoids redundant debugging info.

Omit "while compiling source files"?

+ It is user's responsibility to supply
+ these repositories (they are simple .o files) to link editor so that
+ final image contains all debugging information.

"It is the user's"
"@file{.o}"
"to the link editor"
"the final image"

+ This creates two files.
+ (1) MyHeader.h.o: Object file with debugging info. This is created
+     in current working directory or its name and location can be
+     controlled using -o option. User needs to supply this file to
+     link editor during linking.

"@file{MyHeader.h.o}, an object file with debugging info."
"the current..."
"The user"
"the link editor" and omit "during linking".

+ (2) MyHeader.cinfo: Context info file to validate MyHeader.h.o. It
+     will be created in /my_ss/ directory.

@file{/my_sss/}

"in the...directory"

+ This file contains context information for header. GCC uses it to
+ validate symbol repository.

Something is wrong with "for header".

"...which GCC uses to...the symbol respository."

+ To use repository

"the repository"

+ Current implementation works with STABS debugging format only.

"The current implementation supports the STABS debugging format only."

+ It is
+ recommonded to make symbol repository before making precompiled header.

typo

"making" doesn't seem right.

+ See @option{-grepository} for more information.

Gerald