-isoC-2017 patch

-isoC-2017 patch

[maya]

Index: mdoc.7
===================================================================
RCS file: /cvs/mandoc/mdoc.7,v
retrieving revision 1.270
diff -u -r1.270 mdoc.7
--- mdoc.7	23 Oct 2017 13:54:41 -0000	1.270
+++ mdoc.7	27 Jul 2018 13:40:36 -0000
@@ -2451,6 +2451,11 @@
 .St -isoC-2011
 .br
 The third major version of the C language standard.
+.Pp
+.It \-isoC-2017
+.St -isoC-2017
+.br
+The fourth major version of the C language standard.
 .El
 .It POSIX.1 before the Single UNIX Specification
 .Pp
Index: st.in
===================================================================
RCS file: /cvs/mandoc/st.in,v
retrieving revision 1.30
diff -u -r1.30 st.in
--- st.in	5 Apr 2018 09:17:26 -0000	1.30
+++ st.in	27 Jul 2018 13:40:36 -0000
@@ -50,6 +50,7 @@
 LINE("-isoC-tcor2",	"ISO/IEC 9899/TCOR2:1995 (\\(lqISO\\~C90, Technical Corrigendum 2\\(rq)")
 LINE("-isoC-99",	"ISO/IEC 9899:1999 (\\(lqISO\\~C99\\(rq)")
 LINE("-isoC-2011",	"ISO/IEC 9899:2011 (\\(lqISO\\~C11\\(rq)")
+LINE("-isoC-2017",	"ISO/IEC 9899:2017 (\\(lqISO\\~C17\\(rq)")
 LINE("-iso9945-1-90",	"ISO/IEC 9945-1:1990 (\\(lqPOSIX.1\\(rq)")
 LINE("-iso9945-1-96",	"ISO/IEC 9945-1:1996 (\\(lqPOSIX.1\\(rq)")
 LINE("-iso9945-2-93",	"ISO/IEC 9945-2:1993 (\\(lqPOSIX.2\\(rq)")

--
 To unsubscribe send an email to tech+unsubscribe@mandoc.bsd.lv

Re: -isoC-2017 patch

[Ingo Schwarze]

[Cc:ing two developers who know a lot about documentation and standards]


Hello Maya,

thanks for your patch!

However, i'm not sure i understand.

  https://www.iso.org/standard/74528.html

seems to indicate the existence of a brand new standard called

  ISO/IEC 9899:2018
  Information technology -- Programming languages -- C

but i failed to find any evidence that an official standard
called ISO/IEC 9899:2017 might exist.

Can you provide a reference to such a standard?


Even if it does exist (or if you suggest s/17/18/), note that mandoc
does not aim to provide macro arguments for all the standards under
the sun.  A new major revision of the C programming language is no
doubt an excellent candidate for addition, but i would still welcome
solid evidence that it will actually see substantial use in practice.

Does the NetBSD base system implement the C18 standard, and are you
going to update all the relevant NetBSD manual pages to refer to it,
where appropriate?  How many manual pages, approximately, do you
expect will reference it in NetBSD in the short term?

Note the in OpenBSD, the only references even to -isoC-2011 are
in mdoc(7) and groff_mdoc(7), and

  https://man.openbsd.org/?query=St%3DC11&apropos=1&manpath=NetBSD-7.1
  https://man.openbsd.org/?query=St%3DC11&apropos=1&manpath=FreeBSD-11.1

only return minimal additional content, which implies to me that even
the addition of -isoC-2011 may have been premature.

Thanks again,
  Ingo


maya@netbsd.org wrote on Fri, Jul 27, 2018 at 01:49:15PM +0000:

> Index: mdoc.7
> ===================================================================
> RCS file: /cvs/mandoc/mdoc.7,v
> retrieving revision 1.270
> diff -u -r1.270 mdoc.7
> --- mdoc.7	23 Oct 2017 13:54:41 -0000	1.270
> +++ mdoc.7	27 Jul 2018 13:40:36 -0000
> @@ -2451,6 +2451,11 @@
>  .St -isoC-2011
>  .br
>  The third major version of the C language standard.
> +.Pp
> +.It \-isoC-2017
> +.St -isoC-2017
> +.br
> +The fourth major version of the C language standard.
>  .El
>  .It POSIX.1 before the Single UNIX Specification
>  .Pp
> Index: st.in
> ===================================================================
> RCS file: /cvs/mandoc/st.in,v
> retrieving revision 1.30
> diff -u -r1.30 st.in
> --- st.in	5 Apr 2018 09:17:26 -0000	1.30
> +++ st.in	27 Jul 2018 13:40:36 -0000
> @@ -50,6 +50,7 @@
>  LINE("-isoC-tcor2",	"ISO/IEC 9899/TCOR2:1995 (\\(lqISO\\~C90, Technical Corrigendum 2\\(rq)")
>  LINE("-isoC-99",	"ISO/IEC 9899:1999 (\\(lqISO\\~C99\\(rq)")
>  LINE("-isoC-2011",	"ISO/IEC 9899:2011 (\\(lqISO\\~C11\\(rq)")
> +LINE("-isoC-2017",	"ISO/IEC 9899:2017 (\\(lqISO\\~C17\\(rq)")
>  LINE("-iso9945-1-90",	"ISO/IEC 9945-1:1990 (\\(lqPOSIX.1\\(rq)")
>  LINE("-iso9945-1-96",	"ISO/IEC 9945-1:1996 (\\(lqPOSIX.1\\(rq)")
>  LINE("-iso9945-2-93",	"ISO/IEC 9945-2:1993 (\\(lqPOSIX.2\\(rq)")
--
 To unsubscribe send an email to tech+unsubscribe@mandoc.bsd.lv

Re: -isoC-2017 patch

[maya]

On Fri, Jul 27, 2018 at 04:23:26PM +0200, Ingo Schwarze wrote:
> [Cc:ing two developers who know a lot about documentation and standards]
> 
> 
> Hello Maya,
> 
> thanks for your patch!
> 
> However, i'm not sure i understand.
> 
>   https://www.iso.org/standard/74528.html
> 
> seems to indicate the existence of a brand new standard called
> 
>   ISO/IEC 9899:2018
>   Information technology -- Programming languages -- C
> 
> but i failed to find any evidence that an official standard
> called ISO/IEC 9899:2017 might exist.
> 
> Can you provide a reference to such a standard?

I was reading
http://www.open-std.org/jtc1/sc22/wg14/www/abq/c17_updated_proposed_fdis.pdf

which is a draft and unofficial, so yours is more correct.
(looks like a lot of s/17/18/ will have to be done elsewhere...)

> Even if it does exist (or if you suggest s/17/18/), note that mandoc
> does not aim to provide macro arguments for all the standards under
> the sun.  A new major revision of the C programming language is no
> doubt an excellent candidate for addition, but i would still welcome
> solid evidence that it will actually see substantial use in practice.
> 
> Does the NetBSD base system implement the C18 standard, and are you
> going to update all the relevant NetBSD manual pages to refer to it,
> where appropriate?  How many manual pages, approximately, do you
> expect will reference it in NetBSD in the short term?

There's not going to be many references to it like C11 because it
doesn't add new things, only makes changes to existing stuff.

I made the first reference to newer-than-C11 to document some change.
It's not critical, it just felt like the right change to do.
--
 To unsubscribe send an email to tech+unsubscribe@mandoc.bsd.lv

Re: -isoC-2017 patch

[Ingo Schwarze]

Hi Maya,

maya@netbsd.org wrote on Fri, Jul 27, 2018 at 03:02:04PM +0000:
> On Fri, Jul 27, 2018 at 04:23:26PM +0200, Ingo Schwarze wrote:

>>   https://www.iso.org/standard/74528.html
>> 
>> seems to indicate the existence of a brand new standard called
>> 
>>   ISO/IEC 9899:2018
>>   Information technology -- Programming languages -- C
>> 
>> but i failed to find any evidence that an official standard
>> called ISO/IEC 9899:2017 might exist.
>> 
>> Can you provide a reference to such a standard?

> I was reading
> http://www.open-std.org/jtc1/sc22/wg14/www/abq/c17_updated_proposed_fdis.pdf

Aha.  That appears to be outdated.

> which is a draft and unofficial, so yours is more correct.
> (looks like a lot of s/17/18/ will have to be done elsewhere...)

Possibly.

>> Even if it does exist (or if you suggest s/17/18/), note that mandoc
>> does not aim to provide macro arguments for all the standards under
>> the sun.  A new major revision of the C programming language is no
>> doubt an excellent candidate for addition, but i would still welcome
>> solid evidence that it will actually see substantial use in practice.
>> 
>> Does the NetBSD base system implement the C18 standard, and are you
>> going to update all the relevant NetBSD manual pages to refer to it,
>> where appropriate?  How many manual pages, approximately, do you
>> expect will reference it in NetBSD in the short term?

> There's not going to be many references to it

That sounds like a strong argument to *not* add it.
There is value in keeping programming languages small (including
mdoc(7)) and avoiding the introduction of low-utility syntax.

> like C11

After looking at the draft, it seems to me that there will likely
even be fewer references to C18 than to C11, given that C11 did
define a small number of new features, which at least in theory
might get implemented and documented.

> because it doesn't add new things, only makes changes to existing
> stuff.

I see.

> I made the first reference to newer-than-C11 to document some change.

I'm not sure i understand that sentence.

You mean, so far, you committed one single change to one single
NetBSD manual page (which one?) using the new macro argument,
to document a change you committed to the NetBSD source code
(which source code commit specifically?).

> It's not critical, it just felt like the right change to do.

Foc comparison, we decided to not add -p1003.1-2017 because it
is not a new version of the standard but merely incorporates
technical corrigenda into -p1003.1-2008.

For the case of the C standard, if differences between C11 and C18
matter for a specific feature, i would consider recommending a
wording like the following:

The
.Fn foobar
function conforms to
.St -isoC-2011  \" or -isoC-99 or -ansiC where appropriate
including the corrections with respect to BARFOO applied by
ISO/IEC 9899:2018
.Pq Dq ISO C18 .

I expect such cases to remain rare.  If it turns out they become
very numerous, *that* would establish a reason to add a new macro
argument.

Does that make sense to you?

Yours,
  Ingo
--
 To unsubscribe send an email to tech+unsubscribe@mandoc.bsd.lv

Re: -isoC-2017 patch

[maya]

On Fri, Jul 27, 2018 at 05:49:44PM +0200, Ingo Schwarze wrote:
> > like C11
> 
> After looking at the draft, it seems to me that there will likely
> even be fewer references to C18 than to C11, given that C11 did
> define a small number of new features, which at least in theory
> might get implemented and documented.

Off the top of my head, C11 adds atomics, generics and threads. it's
pretty big.
--
 To unsubscribe send an email to tech+unsubscribe@mandoc.bsd.lv