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

[Jonathan Wakely <jwakely at redhat dot com>]

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. <option> or <filename> instead of using <code> 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.

Attachment: patch-1.txt
Description: Text document

Attachment: patch-2.txt
Description: Text document

Attachment: patch-3.txt
Description: Text document

Attachment: patch-4.txt
Description: Text document