[v3,2/2] float128: Add strfromf128, strtof128, and wcstof128 to the manual

Changes since v2:

  - Fix typos and grammatical errors.
  - Move @var{N} into the @code{} blocks
  - Remove @var{N} from the function names and return types in the
    @deftypefun and @deftypefunx blocks, because @var{N} causes errors in
    'make html' and 'make info' (make 'pdf' was working fine).

Changes since v1:

  - Added _FloatN and _FloatNx to the section that discusses C
    floating-point types in the section Mathematics.
  - Reworded the descriptions of strfromf128 etc. into descriptions of
    strfromfN etc., to ease the changes needed in the manual when more
    types from TS 18661-3 get added to glibc.

-- 8< --
2016-11-14  Gabriel F. T. Gomes  <gftg@linux.vnet.ibm.com>

	* manual/math.texi (Mathematics): Add description for _FloatN and
	_FloatNx types and mentions that they are not support in glibc for
	any architecture, so far.
	* manual/arith.texi (wcstof, wcstold): Replace the mention to
	stdlib.h with wchar.h.
	(Parsing of Floats): Add descriptions for strtofN and wcstofN.
	(Printing of Floats): Add description for strfromfN.
---
 manual/arith.texi | 45 ++++++++++++++++++++++++++++++++++++++++-----
 manual/math.texi  | 11 +++++++++++
 2 files changed, 51 insertions(+), 5 deletions(-)

On Wed, 7 Jun 2017, Gabriel F. T. Gomes wrote:

>   - Remove @var{N} from the function names and return types in the
>     @deftypefun and @deftypefunx blocks, because @var{N} causes errors in
>     'make html' and 'make info' (make 'pdf' was working fine).

The patch is OK, fixed as noted, provided this issue is reported to 
upstream Texinfo (after all, at some point we'd like to use @var{N} 
properly in the names and types once the minimum Texinfo version for glibc 
is high enough to ensure a fix).

> +@comment stdlib.h
> +@comment ISO/IEC TS 18661-3
> +@deftypefun _FloatN strtofN (const char *@var{string}, char **@var{tailptr})
> +@deftypefunx _FloatNx strtofN (const char *@var{string}, char **@var{tailptr})

The second one should be strtofNx.

Of course a subsequent patch before the float128 support is actually 
enabled will need to document all the libm interfaces, both functions and 
macros, for the new type.  (That is, where the corresponding interfaces 
for existing types are documented, documentation needs adding for the new 
type; this is not a requirement to document things where the float / 
double / long double interfaces aren't documented either.)

On 06/07/2017 02:35 PM, Gabriel F. T. Gomes wrote:
> diff --git a/manual/arith.texi b/manual/arith.texi
> index dec12a0..1f13769 100644
> --- a/manual/arith.texi
> +++ b/manual/arith.texi
> @@ -2990,23 +2990,45 @@ double} is a separate type).
>  These functions have been GNU extensions and are new to @w{ISO C99}.
>  @end deftypefun
>  
> +@comment stdlib.h
> +@comment ISO/IEC TS 18661-3
> +@deftypefun _FloatN strtofN (const char *@var{string}, char **@var{tailptr})
> +@deftypefunx _FloatNx strtofN (const char *@var{string}, char **@var{tailptr})

Both @defs should have @comments.

The second @def should be strtofNx.

> +@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}

See thoughts on safety comments below.

> +These functions are like @code{strtod}, except for the return type.
> +
> +They were introduced in @w{ISO/IEC TS 18661-3} and are available on machines
> +that support the related types, as described in @ref{Mathematics}.

"that support the related types; @pxref{Mathematics}."

@ref should almost never be used, because it doesn't render correctly
across all the documentation types.

> +@end deftypefun
> +
>  @comment wchar.h
>  @comment ISO
>  @deftypefun double wcstod (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr})
> -@comment stdlib.h
> +@comment wchar.h
>  @comment ISO
>  @deftypefunx float wcstof (const wchar_t *@var{string}, wchar_t **@var{tailptr})
> -@comment stdlib.h
> +@comment wchar.h
>  @comment ISO
>  @deftypefunx {long double} wcstold (const wchar_t *@var{string}, wchar_t **@var{tailptr})

Thanks for fixing.

> +@comment wchar.h
> +@deftypefunx _FloatN wcstofN (const wchar_t *@var{string}, wchar_t **@var{tailptr})

Needs a standard.  "@comment GNU" should be correct if this is a GNU
extension.

> +@deftypefunx _FloatNx wcstofNx (const wchar_t *@var{string}, wchar_t **@var{tailptr})

This should have its own header and standard @comments.

>  @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}

See thoughts on safety comments below.

> -The @code{wcstod}, @code{wcstof}, and @code{wcstol} functions are
> -equivalent in nearly all aspect to the @code{strtod}, @code{strtof}, and
> -@code{strtold} functions but it handles wide character string.
> +The @code{wcstod}, @code{wcstof}, @code{wcstol}, @code{wcstof@var{N}},
> +and @code{wcstof@var{N}x} functions are equivalent in nearly all aspect

aspects (while you're at it)

> +to the @code{strtod}, @code{strtof}, @code{strtold},
> +@code{strtof@var{N}}, and @code{strtof@var{N}x} functions but they

I would put a comma after "functions", since there's a natural pause.

> +handle wide character strings.
>  
>  The @code{wcstod} function was introduced in @w{Amendment 1} of @w{ISO
>  C90}.  The @code{wcstof} and @code{wcstold} functions were introduced in
>  @w{ISO C99}.
> +
> +The @code{wcstof@var{N}} and @code{wcstof@var{N}x} functions are not in
> +any standard, but are added to provide completeness for the
> +non-deprecated interface of wide character string to floating-point
> +conversion function.  They are only available on machines that support

functions

> +the related types as described in @ref{Mathematics}.

@pxref

>  @end deftypefun
>  
>  @comment stdlib.h
> @@ -3064,6 +3086,19 @@ has been completely written if and only if the returned value is less than
>  These functions were introduced by ISO/IEC TS 18661-1.
>  @end deftypefun
>  
> +@comment stdlib.h
> +@comment ISO/IEC TS 18661-3
> +@deftypefun int strfromfN (char *restrict @var{string}, size_t @var{size}, const char *restrict @var{format}, _Float@var{N} @var{value})
> +@deftypefunx int strfromfNx (char *restrict @var{string}, size_t @var{size}, const char *restrict @var{format}, _Float@var{N}x @var{value})

@comments for both @defs.

> +@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
> +@comment this function depends on __printf_fp and __printf_fphex, which are
> +@comment AS-unsafe (ascuheap) and AC-unsafe (acsmem).

Not that it matters, but @c tends to be used for these comments.  In
light of the @errno and @standards work I've been doing, I wonder if
that's a historical habit due to external processes utilizing @comments
for various purposes...  but I like the shorter syntax anyway.

It looks like the strfrom's were a rare exception, which I'm guessing
was the template (unseen here, directly above).

At any rate, "this function depends" should be "these functions depend",
if the @safety annotation is true for both of them.  Some of the safety
commentary gets pretty detailed too, so this might be improved by being
more explicit about which function depends on what and where the safety
issues lie; i.e., something like: "strfromfN depends on __printf_fp and
strfromfNx depends on __printf_fphex, both of which are AS-unsafe
(ascuheap) and AC-unsafe (acsmem)."  (I don't actually know if that's
right, just inferring.)

Looking at other safety comments in this file, the locale safety seems
to be an interesting issue ("unsafe-but-ruled-safe").  Maybe a reference
in the comment to more detailed comments would be good ("see safety
comments for strtod", or whatever's appropriate).  This would apply to
the other added functions in this patch too.

> +These functions are like @code{strfromd}, except for the type of @var{value}.

@code{value}, since you're referring to the variable.

> +
> +They were introduced in @w{ISO/IEC TS 18661-3} and are available on machines
> +that support the related types, as described in @ref{Mathematics}.

@pxref

> +@end deftypefun
> +
>  @node System V Number Conversion
>  @section Old-fashioned System V number-to-string functions
>  
> diff --git a/manual/math.texi b/manual/math.texi
> index 69a0ace..a335917 100644
> --- a/manual/math.texi
> +++ b/manual/math.texi
> @@ -53,6 +53,17 @@ usually wise to pick the narrowest type that can accommodate your data.
>  Not all machines have a distinct @code{long double} type; it may be the
>  same as @code{double}.
>  
> +On some machines, @theglibc{} also provides @code{_Float@var{N}} and
> +@code{_Float@var{N}x} types.  These types are defined in @w{ISO/IEC
> +18661-3}, which extends @w{ISO C} and defines floating-point types that

Inconsistent standard name.  "ISO/IEC TS 18661-3" is used everywhere
else (in this patch).

> +are not machine-dependent.  When such a type, e.g.  @code{_Float128}, is

I always put a comma after "e.g.", though that might be a regional
preference.  It looks like the formatting sees it as the end of a
sentence, however (two spaces), and that might impact the rendering.
What about: "When a type such as @code{_Float128} is..."

> +supported by @theglibc{}, extra variants for most of the mathematical
> +functions provided for @code{double}, @code{float}, and @code{long
> +double} are also provided for the supported type.
> +
> +Currently, support for @code{_Float@var{N}} or @code{_Float@var{N}x}
> +types is not provided for any machine.

This is dated already, and it's not even out-of-date.  Can anybody think
of a decent way to keep it up-to-date?  "@c FIXME SOMEDAY" (perhaps with
a liberal dose of exclamation points)?  I'm torn, because actually
dating it (putting the year in there or something) is still prone to the
same problem, but could help readers in 20 years recognize it as
possibly no longer true.

I'd also like to draw attention to the very first line of this patch,
which uses "new" and "ISO C99" in the same breath.

It seems important to say this, though, somehow.  Is there somewhere we
can document support for these types on various machines (or already do,
perhaps for types in general)?  We could then reference it, and it might
be easier for the group mind to remember to keep that current.

> +
>  @menu
>  * Mathematical Constants::      Precise numeric values for often-used
>                                   constants.

Rical

On Thu, 8 Jun 2017, Rical Jasan wrote:

> > +Currently, support for @code{_Float@var{N}} or @code{_Float@var{N}x}
> > +types is not provided for any machine.
> 
> This is dated already, and it's not even out-of-date.  Can anybody think
> of a decent way to keep it up-to-date?  "@c FIXME SOMEDAY" (perhaps with
> a liberal dose of exclamation points)?  I'm torn, because actually
> dating it (putting the year in there or something) is still prone to the
> same problem, but could help readers in 20 years recognize it as
> possibly no longer true.

The point is that each patch enabling the support for a new architecture 
(or a new type on an existing architecture) would update that section (as 
well as the NEWS file) - no other sections should need to duplicate that 
information.  That's Gabriel's patches for powerpc64le, which I expect to 
follow up by enabling the support for x86_64 and x86 (and probably with 
such a patch for ia64, though with compile-only testing).  And later I 
expect to implement support for _FloatN / _FloatNx where they are 
ABI-aliases of existing types (for all applicable architectures at the 
same time for each such type).  (I think the only other vaguely plausible 
case of support for such types in glibc would be _Float16 support, but I'm 
not aware of any work on that.)

On Thu, 8 Jun 2017 04:42:29 -0700
Rical Jasan <ricaljasan@pacific.net> wrote:

> Not that it matters, but @c tends to be used for these comments.  In
> light of the @errno and @standards work I've been doing, I wonder if
> that's a historical habit due to external processes utilizing @comments
> for various purposes...  but I like the shorter syntax anyway.
> 
> It looks like the strfrom's were a rare exception, which I'm guessing
> was the template (unseen here, directly above).

I tried to keep the existing style, which seems to be the use of
@comment, throughout the file.

> At any rate, "this function depends" should be "these functions depend",
> if the @safety annotation is true for both of them.  Some of the safety
> commentary gets pretty detailed too, so this might be improved by being
> more explicit about which function depends on what and where the safety
> issues lie; i.e., something like: "strfromfN depends on __printf_fp and
> strfromfNx depends on __printf_fphex, both of which are AS-unsafe
> (ascuheap) and AC-unsafe (acsmem)."  (I don't actually know if that's
> right, just inferring.)

I rewrote this phrase so that it is more clear that all strfrom*
functions depend on both __printf_fp and __printf_fphex.  That's what I
meant.  Could you check if the new wording is more clear, please?


I addressed all the comments in this thread and sent a new version of this
patch.  I am also learning how to contact the texinfo community, so that I
can comment about the use of @var{} in @deftypefun.  Thank you!