[rfa/doc] Updates to gdbint.texinfo

[rfa/doc] Updates to gdbint.texinfo

[Andrew Cagney]

Hello,

Attatched is a revised patch to doc/gdbint.texinfo that expands on 
things like GDB's coding standard.  I think I've addressed all the 
problems pointed out by Eli and Elena.

I've even managed to type the word all^(*&^(*&, al*(%&%&oca(), 
&*^(*all*&^(&*oca().

Probably the most striking thing about this patch is where I delete the 
section that gave the thumbs up to adding something like:

	#ifdef SOME_TARGET/HOST_DEPENDENCY
	do something obscure;
	#endif

to core code.

I might try a few more updates over the weekend.

	Andrew
From eliz@is.elta.co.il Fri Jun 29 12:22:00 2001
From: "Eli Zaretskii" <eliz@is.elta.co.il>
To: ac131313@cygnus.com
Cc: gdb-patches@sources.redhat.com
Subject: Re: [rfa/doc] Updates to gdbint.texinfo
Date: Fri, 29 Jun 2001 12:22:00 -0000
Message-id: <1483-Fri29Jun2001221859+0300-eliz@is.elta.co.il>
References: <3B3CC68E.3040504@cygnus.com>
X-SW-Source: 2001-06/msg00534.html
Content-length: 1058

> Date: Fri, 29 Jun 2001 14:18:54 -0400
> From: Andrew Cagney <ac131313@cygnus.com>
> 
> Attatched is a revised patch to doc/gdbint.texinfo that expands on 
> things like GDB's coding standard.  I think I've addressed all the 
> problems pointed out by Eli and Elena.

Thanks.  This is okay, except for the following nitpicking:

> + @emph{Pragmatics: By using these functions, the need to check every
> + memory allocation is removed.  These functions provide portable
> + behavour.}

There's a typo in the last word.

> ! Pointers are declared using the traditional K&R C style:
> ! 
> ! @example
> ! void *foo;
> ! @end example
> ! 
> ! and not:
>   
> + @example
> + void * foo;
> + void* foo;
> + @end example

The "and not:" part above needs a @noindent before it.

> + @subsection File Names
> + 
> + Any file that is used to build @value{GDBN} on either DJGPP or Cygwin
> + must be 8.3 compliant.

I suggest to add here that file names which match but for the letter
case will make trouble on DOS and Windows, even if long file names are
supported.

Re: [rfa/doc] Updates to gdbint.texinfo

[Christopher Faylor]

On Fri, Jun 29, 2001 at 10:18:59PM +0300, Eli Zaretskii wrote:
>> + @subsection File Names
>> + 
>> + Any file that is used to build @value{GDBN} on either DJGPP or Cygwin
>> + must be 8.3 compliant.
>
>I suggest to add here that file names which match but for the letter
>case will make trouble on DOS and Windows, even if long file names are
>supported.

Right.  Also the 8.3 rule is just for DJGPP.  Cygwin/Windows has no
problem with longer filenames.

cgf

Re: [rfa/doc] Updates to gdbint.texinfo

[Stan Shebs]

Christopher Faylor wrote:
> 
> On Fri, Jun 29, 2001 at 10:18:59PM +0300, Eli Zaretskii wrote:
> >> + @subsection File Names
> >> +
> >> + Any file that is used to build @value{GDBN} on either DJGPP or Cygwin
> >> + must be 8.3 compliant.
> >
> >I suggest to add here that file names which match but for the letter
> >case will make trouble on DOS and Windows, even if long file names are
> >supported.
> 
> Right.  Also the 8.3 rule is just for DJGPP.  Cygwin/Windows has no
> problem with longer filenames.

Differs-only-in-case names also make trouble on Mac OS 9/X, if
the filesystem has been configured to be HFS (the usual situation)
instead of UFS.

Stan

Re: [rfa/doc] Updates to gdbint.texinfo

[Andrew Cagney]

> + @subsection File Names
>> + 
>> + Any file that is used to build @value{GDBN} on either DJGPP or Cygwin
>> + must be 8.3 compliant.
> 
> 
> I suggest to add here that file names which match but for the letter
> case will make trouble on DOS and Windows, even if long file names are
> supported.


Good point, I'll cite COPYING as an example of how it can all go wrong :-)

	Andrew

Re: [rfa/doc] Updates to gdbint.texinfo

[Andrew Cagney]

>> + behavour.}
> 
> 
> There's a typo in the last word.


And I did use Ispell this time :-/


>> ! @end example
>> ! 
>> ! and not:
>> > + @example

> 
> The "and not:" part above needs a @noindent before it.


Done.

 
>> + @subsection File Names
>> + 
>> + Any file that is used to build @value{GDBN} on either DJGPP or Cygwin
>> + must be 8.3 compliant.
> 
> 
> I suggest to add here that file names which match but for the letter
> case will make trouble on DOS and Windows, even if long file names are
> supported.


I reworded it.  It talks about the build process.


@subsection File Names

Any file used when building the core of @value{GDBN} must be in lower
case. Any file used when building the core of @value{GDBN} must be 8.3
unique.  These requirements apply to both source and generated files.

@emph{Pragmatics: The core of @value{GDBN} must be buildable on many
platforms including DJGPP and MacOS/HFS.  Every time an unfriendly file
is introduced to the build process both @file{Makefile.in} and
@file{configure.in} need to be modified accordingly.  Compare the
convoluted conversion process needed to transform @file{COPYING} into
@file{copying.c} with the conversion needed to transform
@file{version.in} into @file{version.c}.}

Any file non 8.3 compliant file (that is not used when building the core
of @value{GDBN}) must be added to @file{gdb/config/djgpp/fnchange.lst}.

@emph{Pragmatics: This is clearly a compromise.}

When @value{GDBN} has a local version of a system header file (ex
@file{string.h}) the file name based on the POSIX header prefixed with
@file{gdb_} (@file{gdb_string.h}).

For other files @samp{-} is used as the separator.

Re: [rfa/doc] Updates to gdbint.texinfo

[Eli Zaretskii]

> Date: Wed, 04 Jul 2001 14:21:00 -0400
> From: Andrew Cagney <ac131313@cygnus.com>
> > 
> > I suggest to add here that file names which match but for the letter
> > case will make trouble on DOS and Windows, even if long file names are
> > supported.
> 
> I reworded it.  It talks about the build process.

This is fine with me; thanks.

Re: [rfa/doc] Updates to gdbint.texinfo

[Andrew Cagney]

> Date: Wed, 04 Jul 2001 14:21:00 -0400
>> From: Andrew Cagney <ac131313@cygnus.com>
> 
>> > 
>> > I suggest to add here that file names which match but for the letter
>> > case will make trouble on DOS and Windows, even if long file names are
>> > supported.
> 
>> 
>> I reworded it.  It talks about the build process.
> 
> 
> This is fine with me; thanks.


Ok, I've checked in the attached.  Thanks for all the feedback. 
Hopefully I won't get back to this until 5.1 is out :-)

	Andrew

PS: I found/fixed another ``{}'' in my changes.