Sender: rich AT phekda DOT freeserve DOT co DOT uk
Message-ID: <3A6B08A1.D3F04FDE@phekda.freeserve.co.uk>
Date: Sun, 21 Jan 2001 16:04:49 +0000
From: Richard Dawe <rich AT phekda DOT freeserve DOT co DOT uk>
X-Mailer: Mozilla 4.51 [en] (X11; I; Linux 2.2.17 i586)
X-Accept-Language: de,fr
MIME-Version: 1.0
To: djgpp-workers AT delorie DOT com
Subject: Describe @portability in develop.txi [Was: Re: mkdoc patch, take 2]
References: <Pine DOT SUN DOT 3 DOT 91 DOT 1000711100538 DOT 19180B-100000 AT is> <396B6BB3 DOT 49C1F993 AT phekda DOT freeserve DOT co DOT uk>
Content-Type: text/plain; charset=us-ascii
Content-Transfer-Encoding: 7bit
Reply-To: djgpp-workers AT delorie DOT com

Hello.

I have written a section for src/docs/kb/develop.txi to describe the use
of @portability and @port-note. Please find the diff at the end of the
mail. If it's OK, I will commit it.

Since the discussion that motivated me to write this diff was last year,
I've quoted a relevant mail on the meaning of @portability and @port-note.

Bye, Rich =]

Richard Dawe wrote:
> 
> Eli Zaretskii wrote:
> > I think you are mixing two different things.  The ANSI/non-ANSI
> > indication in the docs means that the relevant feature is specified in
> > the ANSI Standard.
> 
> Really? I always thought "portability" meant that I could recompile my
> program unchanged under another OS which supported the standards listed.
> You are quite right - I am mixing things here.
> 
> > Whether our implementation complies to the letter of that
> > specification is irrelevant here.  (In general, where there's no
> > strict compliance, we have a bug on our hands ;-)
> 
> Are these things mentioned anywhere in the documentation? If not,
> perhaps it is a good idea to add a section to the libc documentation
> that describes the format of each page? Maybe some kind of introduction?

*** src/docs/kb/develop.txi.orig        Sun Jan 21 15:25:48 2001
--- src/docs/kb/develop.txi     Sun Jan 21 15:56:04 2001
***************
*** 96,101 ****
--- 96,127 ----
  @end itemize
  
  @item
+ Under the subheading @samp{Portability}, @samp{@@portability} should be
+ used to indicate whether a feature is specified in the ANSI C and POSIX
+ standards.  For example:
+ 
+ @example
+ @@subheading Portability
+ 
+ @@portability !ansi, posix
+ @end example
+ 
+ Please note that @samp{@@portability} is not used to indicate whether
+ the DJGPP implementation complies with the standards listed.  Instead,
+ @samp{@@port-note} may be used to describe implementation-specific
details:
+ 
+ @example
+ @@port-note ansi The buffer size limit is imposed by DJGPP.
+ @end example
+ 
+ @samp{@@portability} and @samp{@@port-note} are DJGPP-specific
extensions
+ of texinfo (@pxref{Top, , texinfo}) that are expanded into normal
texinfo by
+ @code{mkdoc}.  @code{mkdoc} is part of the DJGPP sources.  It is used
+ to build the C library documentation (@pxref{Top, , libc}).  Therefore,
+ @samp{@@portability} and @samp{@@port-note} should only be used in
+ DJGPP's C library documentation.
+ 
+ @item
  Finally, for some relevant texinfo technique, look at the source
  of this page in the DJGPP sources--- AT file{src/docs/kb/contrib.txi}.
  @end itemize