From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 130144 invoked by alias); 24 Dec 2018 02:28:19 -0000 Mailing-List: contact gcc-patches-help@gcc.gnu.org; run by ezmlm Precedence: bulk List-Id: List-Archive: List-Post: List-Help: Sender: gcc-patches-owner@gcc.gnu.org Received: (qmail 129769 invoked by uid 89); 24 Dec 2018 02:28:15 -0000 Authentication-Results: sourceware.org; auth=none X-Spam-SWARE-Status: No, score=-26.9 required=5.0 tests=BAYES_00,GIT_PATCH_0,GIT_PATCH_1,GIT_PATCH_2,GIT_PATCH_3,RCVD_IN_DNSWL_NONE autolearn=ham version=3.3.2 spammy=Hx-spam-relays-external:sk:smtp21., rendered, manual, H*r:sk:smtp21. X-HELO: smtp97.iad3b.emailsrvr.com Received: from smtp97.iad3b.emailsrvr.com (HELO smtp97.iad3b.emailsrvr.com) (146.20.161.97) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Mon, 24 Dec 2018 02:28:12 +0000 Received: from smtp21.relay.iad3b.emailsrvr.com (localhost [127.0.0.1]) by smtp21.relay.iad3b.emailsrvr.com (SMTP Server) with ESMTP id DE466201DA; Sun, 23 Dec 2018 21:28:10 -0500 (EST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=honermann.net; s=20180930-2j89z3ji; t=1545618490; bh=Odn1C7R7+aAjgL81ixcJduModEmDLq9t/1/xGpSU7g4=; h=Subject:To:From:Date:From; b=ksP9SiQhtLLsaz2wxksRq2oVf5ZIvXVI57spiTZWdZVgN+uzDFlSvrDhmwlIMc6Hd meGJqfdzlg5EZFQP3nKZIdMLMMbw/lQWiwN/B3gpF1Tm3E4pUSQaLMNbI7IMOFqD4l 7uuPd+PFsfDf0/pXFVW22wRljv03VuY8HBHgTGHk= X-Auth-ID: tom@honermann.net Received: by smtp21.relay.iad3b.emailsrvr.com (Authenticated sender: tom-AT-honermann.net) with ESMTPSA id B381B2015A; Sun, 23 Dec 2018 21:28:10 -0500 (EST) X-Sender-Id: tom@honermann.net Received: from [192.168.1.22] (pool-71-176-235-158.rcmdva.fios.verizon.net [71.176.235.158]) (using TLSv1.2 with cipher AES128-SHA) by 0.0.0.0:25 (trex/5.7.12); Sun, 23 Dec 2018 21:28:10 -0500 Subject: Re: [PATCH 1/9]: C++ P0482R5 char8_t: Documentation updates To: Sandra Loosemore , gcc-patches References: <1de934a1-cc14-26fe-a18c-5de855271187@honermann.net> <4d199236-5ec8-dc2d-a8c8-ae0ffb822c76@codesourcery.com> From: Tom Honermann Message-ID: Date: Mon, 24 Dec 2018 02:28:00 -0000 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101 Thunderbird/60.2.1 MIME-Version: 1.0 In-Reply-To: <4d199236-5ec8-dc2d-a8c8-ae0ffb822c76@codesourcery.com> Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: 8bit X-IsSubscribed: yes X-SW-Source: 2018-12/txt/msg01658.txt.bz2 Thank you, Sandra!  I just sent a revised patch to the list that I believe addresses all of your comments.  Thanks for the suggestion to generate and check the pdf, that was helpful to ensure the changes rendered correctly. Tom. On 12/11/18 6:35 PM, Sandra Loosemore wrote: > On 11/5/18 12:39 PM, Tom Honermann wrote: >> This patch adds documentation for new -fchar8_t and -fno-char8_t >> options. >> >> gcc/ChangeLog: >> >> 2018-11-04  Tom Honermann  >>       * doc/invoke.texi (-fchar8_t): Document new option. >> > > My comments are all about nitpicky formatting things. > >> diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi >> index 57491f1033c..cd3a2a715db 100644 >> --- a/gcc/doc/invoke.texi >> +++ b/gcc/doc/invoke.texi >> @@ -206,7 +206,7 @@ in the following sections. >>  @item C++ Language Options >>  @xref{C++ Dialect Options,,Options Controlling C++ Dialect}. >>  @gccoptlist{-fabi-version=@var{n}  -fno-access-control @gol >> --faligned-new=@var{n}  -fargs-in-order=@var{n}  -fcheck-new @gol >> +-faligned-new=@var{n}  -fargs-in-order=@var{n}  -fchar8_t >> -fcheck-new @gol > > Please consistently use 2 spaces (not just 1) to separate options on > the same line in a @gccoptlist environment. > >>  -fconstexpr-depth=@var{n} -fconstexpr-loop-limit=@var{n} @gol >>  -fno-elide-constructors @gol >>  -fno-enforce-eh-specs @gol >> @@ -2432,6 +2432,53 @@ but few users will need to override the >> default of >> >>  This flag is enabled by default for @option{-std=c++17}. >> >> +@item -fchar8_t >> +@itemx -fno-char8_t >> +@opindex fchar8_t >> +@opindex fno-char8_t >> +Enable support for the P0482 proposal including the addition of a >> +new @code{char8_t} fundamental type, changes to the types of UTF-8 >> +string and character literals, new signatures for user defined >> +literals, and new specializations of standard library class templates >> +@code{std::numeric_limits}, @code{std::char_traits}, >> +and @code{std::hash}. >> + >> +This option enables functions to be overloaded for ordinary and UTF-8 >> +strings: >> + >> +@smallexample >> +int f(const char *);    // #1 >> +int f(const char8_t *); // #2 >> +int v1 = f("text");     // Calls #1 >> +int v2 = f(u8"text");   // Calls #2 >> +@end smallexample >> + >> +and introduces new signatures for user defined literals: > > @noindent immediately before the continued sentence of the paragraph > before the example. > > Also please hyphenate "user-defined" here. > >> + >> +@smallexample >> +int operator""_udl1(char8_t); >> +int v3 = u8'x'_udl1; >> +int operator""_udl2(const char8_t*, std::size_t); >> +int v4 = u8"text"_udl2; >> +template int operator""_udl3(); >> +int v5 = u8"text"_udl3; >> +@end smallexample >> + >> +The change to the types of UTF-8 string and character literals >> introduces >> +incompatibilities with ISO C++11 and later standards.  For example, the >> +following code is well-formed under ISO C++11, but is ill-formed when >> +@option{-fchar8_t} is specified. >> + >> +@smallexample >> +char ca[] = u8"text";       // error: char-array initialized from >> wide string >> +const char *cp = u8"text";  // error: invalid conversion from 'const >> char8_t*' to 'const char*' >> +int f(const char*); >> +auto v = f(u8"text");       // error: invalid conversion from 'const >> char8_t*' to 'const char*' >> +std::string s1@{u8"text"@};   // error: no matching function for >> call to 'std::basic_string::basic_string()' >> +using namespace std::literals; >> +std::string s2 = u8"text"s; // error: conversion from >> 'basic_string' to non-scalar type 'basic_string' >> requested >> +@end smallexample > > The formatting of this code example is way too wide to fit on the page > of the printed/PDF manual.  I suggest putting the comments on separate > lines from the code and breaking them across multiple lines where > necessary.  If you format the example for <80 columns it will probably > fit, although you should check the PDF if at all possible. > >> + >>  @item -fcheck-new >>  @opindex fcheck-new >>  Check that the pointer returned by @code{operator new} is non-null >> > > -Sandra