Re: [patch] New libstdc++ docs on testing and library versioning

2016-08-18 Thread Jonathan Wakely 

On 07/08/16 23:36 -0600, Sandra Loosemore wrote:

On 08/04/2016 06:37 PM, Jonathan Wakely wrote:

I've been working on some changes to the libstdc++ manual recently.

A lot of the changes are just using DocBook markup with more semantic
meaning (e.g.  or  instead of using  for
everything that should use a monospace font) but there are some
changes to content too.

I've added a new subsection documenting the steps needed to bump the
library version when adding new symbols, and rewritten the section on
writing testcases. The main reason for the latter is to encourage the
use of { dg-do run { target c++11 } } rather than the { dg-options
"-std=gnu++11" } approach used until now. I've also started
documenting the libstdc++-specific dg-require-SUPPORT directives
available for our tests.

[snip]


I tried to look over this patch and my eyes started glazing over

I suggest trying to separate the markup changes (possibly multiple 
patches, for different kinds of changes) from the new content.  From 
my perspective, I think formatting cleanups and minor copy-editing can 
go in under the obvious patch rule as long as you are satisfied with 
the way it looks and have self-reviewed the patch to make sure you 
didn't accidentally delete some chunk of text or introduce some other 
unintended change.


The new material should be reviewed by someone knowledgeable enough to 
catch problems with the content.


I've committed the changes as four patches, attached.

1 only changes markup.

   Improve markup in libstdc++ manual
   
   * doc/xml/manual/build_hacking.xml: Improve markup.

   * doc/xml/manual/test.xml: Likewise. Change section title from "Test"
   to "Testing".
   * doc/xml/faq.xml: Change link text to "Testing".


2 adds the new section to the configure hacking docs.

   Document libstdc++.so versioning in manual
   
   * doc/xml/manual/build_hacking.xml: New section on shared library

   versioning.

3 is mostly markup, but documents some more makefile targets from the
testsuite sub-dir.

   Improve documentation of libstdc++ test targets
   
   * doc/xml/manual/test.xml: Improve documentation of test targets.

   Document new-abi-baseline, check-debug, and check-parallel targets.


4 rewrites the docs on writing tests.

   Expand libstdc++ docs on testing
   
   * doc/xml/manual/test.xml (test.run.permutations): Expand section.

   (test.new_tests): Rewrite section.
   (tests.dg.directives): New section.
   * doc/html/*: Regenerate.


The result of 2 is at:
https://gcc.gnu.org/onlinedocs/libstdc++/manual/appendix_porting.html#build_hacking.configure.version

And the result of 4 starts at:
https://gcc.gnu.org/onlinedocs/libstdc++/manual/test.html#test.run.permutations

The previous version was identical to:
https://gcc.gnu.org/onlinedocs/gcc-6.1.0/libstdc++/manual/manual/test.html#test.run.permutations

If anyone wants to review that content I'll happily make changes, but
I thought I'd go ahead and commit it. It's much easier to read the
HTML in a browser than to read patches against the Docbook XML.


commit 1305655217385a4b315236c83a0da7ba4e81ca3a
Author: Jonathan Wakely 
Date:   Thu Aug 18 14:04:24 2016 +0100

Improve markup in libstdc++ manual

* doc/xml/manual/build_hacking.xml: Improve markup.
* doc/xml/manual/test.xml: Likewise. Change section title from "Test"
to "Testing".
* doc/xml/faq.xml: Change link text to "Testing".

diff --git a/libstdc++-v3/doc/xml/faq.xml b/libstdc++-v3/doc/xml/faq.xml
index b24ee22..9466231 100644
--- a/libstdc++-v3/doc/xml/faq.xml
+++ b/libstdc++-v3/doc/xml/faq.xml
@@ -328,7 +328,7 @@
 performance testing. Please consult the 
 http://www.w3.org/1999/xlink; 
xlink:href="http://gcc.gnu.org/install/test.html;>testing
 documentation for GCC and
-Test in the libstdc++
+Testing in the libstdc++
 manual for more details.
  
 
diff --git a/libstdc++-v3/doc/xml/manual/build_hacking.xml 
b/libstdc++-v3/doc/xml/manual/build_hacking.xml
index 1b789d3..0bcd879 100644
--- a/libstdc++-v3/doc/xml/manual/build_hacking.xml
+++ b/libstdc++-v3/doc/xml/manual/build_hacking.xml
@@ -93,7 +93,7 @@ in the build directory starts the build process. The 
all targ
 
   
 Regenerate all generated files by using the command 
-autoreconf at the top level of the libstdc++ source
+autoreconf at the top level of the libstdc++ source
 directory.
   
 
@@ -108,10 +108,10 @@ in the build directory starts the build process. The 
all targ
 
 
   
-Until that glorious day when we can use AC_TRY_LINK with a
-cross-compiler, we have to hardcode the results of what the tests
+Until that glorious day when we can use AC_TRY_LINK
+with a cross-compiler, we have to hardcode the results of what the tests
 would have shown if they could be run.  So we have an inflexible
-mess like crossconfig.m4.
+mess like crossconfig.m4.
   
 
   
@@

Re: [patch] New libstdc++ docs on testing and library versioning

2016-08-07 Thread Sandra Loosemore 

On 08/04/2016 06:37 PM, Jonathan Wakely wrote:

I've been working on some changes to the libstdc++ manual recently.

A lot of the changes are just using DocBook markup with more semantic
meaning (e.g.  or  instead of using  for
everything that should use a monospace font) but there are some
changes to content too.

I've added a new subsection documenting the steps needed to bump the
library version when adding new symbols, and rewritten the section on
writing testcases. The main reason for the latter is to encourage the
use of { dg-do run { target c++11 } } rather than the { dg-options
"-std=gnu++11" } approach used until now. I've also started
documenting the libstdc++-specific dg-require-SUPPORT directives
available for our tests.

[snip]


I tried to look over this patch and my eyes started glazing over

I suggest trying to separate the markup changes (possibly multiple 
patches, for different kinds of changes) from the new content.  From my 
perspective, I think formatting cleanups and minor copy-editing can go 
in under the obvious patch rule as long as you are satisfied with the 
way it looks and have self-reviewed the patch to make sure you didn't 
accidentally delete some chunk of text or introduce some other 
unintended change.


The new material should be reviewed by someone knowledgeable enough to 
catch problems with the content.


-Sandra

Re: [patch] New libstdc++ docs on testing and library versioning

2016-08-05 Thread Jonathan Wakely 

On 05/08/16 01:37 +0100, Jonathan Wakely wrote:

The core of the new guidelines for writing tests is this:

[begin]
Test cases that use features of a particular C++ standard should
specify the minimum required standard as an effective target:

  // { dg-do run { target c++11 } }

or

  // { dg-require-effective-target c++11 }

Specifying the minimum required standard for a test allows it to be
run using later standards, so that we can verify that C++11
components still work correctly when compiled as C++14 or later.


I forgot to say that this is the main reason for all the testsuite
work I've been doing for the last couple of weeks. We have hundreds of
tests using { dg-options "-std=gnu++11" } which means that we're not
testing huge chunks of the library with the default -std=gnu++14
option.

By using { dg-do what { target c++11 } } the default testsuite options
will run the test with the default -std setting, but we can optionally
also run them with -std=gnu++11, and -std=gnu++17, and other
variations (which I'm going to be doing nightly).

So I want the docs to describe how I think we should be writing tests.