Re: [PATCH] Clean up references to Subversion in documentation sources.

Re: [PATCH] Clean up references to Subversion in documentation sources.

[Sandra Loosemore]

On 1/13/20 7:02 AM, Eric S. Raymond wrote:
> Clean up references to SVN in in the GCC docs, redirecting to Git
> documentation as appropriate.

This is OK, although the set of changes for the libstdc++ manual like 
this gave me pause:

> diff --git a/libstdc++-v3/doc/xml/manual/status_cxx1998.xml b/libstdc++-v3/doc/xml/manual/status_cxx1998.xml
> index 2b05ff6601a..cf5722377a6 100644
> --- a/libstdc++-v3/doc/xml/manual/status_cxx1998.xml
> +++ b/libstdc++-v3/doc/xml/manual/status_cxx1998.xml
> @@ -18,7 +18,7 @@ This status table is based on the table of contents of ISO/IEC 14882:2003.
>   </para>
>   
>   <para>
> -This page describes the C++ support in mainline GCC SVN, not in any
> +This page describes the C++ support in mainline GCC, not in any
>   particular release.
>   </para>

IIUC the statements being modified here are incorrect; since the manuals 
are packaged with the GCC sources, they go in lock step with the source 
version, and the text of the manual describes the GCC version being 
built, not mainline.  Perhaps the libstdc++ documentation maintainers 
would like to correct this separately?

For similar reasons, I suggest backporting this patch to all active GCC 
release branches, namely GCC 8 and GCC 9, so that manuals packaged with 
upcoming releases from those branches will correctly point to the GIT 
repository instead of SVN.

-Sandra

Re: [PATCH] Clean up references to Subversion in documentation sources.

[Joseph Myers]

On Mon, 13 Jan 2020, Sandra Loosemore wrote:

> On 1/13/20 7:02 AM, Eric S. Raymond wrote:
> > Clean up references to SVN in in the GCC docs, redirecting to Git
> > documentation as appropriate.
> 
> This is OK, although the set of changes for the libstdc++ manual like this
> gave me pause:

I think you'll need to commit this for Eric (using --author= to set the 
git author, whenever you commit a patch for someone else).  The libstdc++ 
maintainers can probably handle regenerating the HTML version of the 
libstdc++ documentation.

-- 
Joseph S. Myers
joseph@codesourcery.com

Re: [PATCH] Clean up references to Subversion in documentation sources.

[Jonathan Wakely]

On 13/01/20 09:09 -0700, Sandra Loosemore wrote:
>On 1/13/20 7:02 AM, Eric S. Raymond wrote:
>>Clean up references to SVN in in the GCC docs, redirecting to Git
>>documentation as appropriate.
>
>This is OK, although the set of changes for the libstdc++ manual like 
>this gave me pause:
>
>>diff --git a/libstdc++-v3/doc/xml/manual/status_cxx1998.xml b/libstdc++-v3/doc/xml/manual/status_cxx1998.xml
>>index 2b05ff6601a..cf5722377a6 100644
>>--- a/libstdc++-v3/doc/xml/manual/status_cxx1998.xml
>>+++ b/libstdc++-v3/doc/xml/manual/status_cxx1998.xml
>>@@ -18,7 +18,7 @@ This status table is based on the table of contents of ISO/IEC 14882:2003.
>>  </para>
>>  <para>
>>-This page describes the C++ support in mainline GCC SVN, not in any
>>+This page describes the C++ support in mainline GCC, not in any
>>  particular release.
>>  </para>
>
>IIUC the statements being modified here are incorrect; since the 
>manuals are packaged with the GCC sources, they go in lock step with 
>the source version, and the text of the manual describes the GCC 
>version being built, not mainline.  Perhaps the libstdc++ 
>documentation maintainers would like to correct this separately?

I did so on the gcc-7 branch, so it says "This page describes the
C++11 support in the GCC 7 series." I have forgotten to do that on the
gcc-8 and gcc-9 branches though, so they lie. I'll do that.

>For similar reasons, I suggest backporting this patch to all active 
>GCC release branches, namely GCC 8 and GCC 9, so that manuals packaged 
>with upcoming releases from those branches will correctly point to the 
>GIT repository instead of SVN.

Agreed.

Re: [PATCH] Clean up references to Subversion in documentation sources.

[Jonathan Wakely]

[-- Attachment #1: Type: text/plain, Size: 1568 bytes --]

On 13/01/20 16:21 +0000, Jonathan Wakely wrote:
>On 13/01/20 09:09 -0700, Sandra Loosemore wrote:
>>On 1/13/20 7:02 AM, Eric S. Raymond wrote:
>>>Clean up references to SVN in in the GCC docs, redirecting to Git
>>>documentation as appropriate.
>>
>>This is OK, although the set of changes for the libstdc++ manual 
>>like this gave me pause:
>>
>>>diff --git a/libstdc++-v3/doc/xml/manual/status_cxx1998.xml b/libstdc++-v3/doc/xml/manual/status_cxx1998.xml
>>>index 2b05ff6601a..cf5722377a6 100644
>>>--- a/libstdc++-v3/doc/xml/manual/status_cxx1998.xml
>>>+++ b/libstdc++-v3/doc/xml/manual/status_cxx1998.xml
>>>@@ -18,7 +18,7 @@ This status table is based on the table of contents of ISO/IEC 14882:2003.
>>> </para>
>>> <para>
>>>-This page describes the C++ support in mainline GCC SVN, not in any
>>>+This page describes the C++ support in mainline GCC, not in any
>>> particular release.
>>> </para>
>>
>>IIUC the statements being modified here are incorrect; since the 
>>manuals are packaged with the GCC sources, they go in lock step with 
>>the source version, and the text of the manual describes the GCC 
>>version being built, not mainline.  Perhaps the libstdc++ 
>>documentation maintainers would like to correct this separately?
>
>I did so on the gcc-7 branch, so it says "This page describes the
>C++11 support in the GCC 7 series." I have forgotten to do that on the
>gcc-8 and gcc-9 branches though, so they lie. I'll do that.

Here's what I've committed to releases/gcc-9, I'll do something
similar for gcc-8.



[-- Attachment #2: patch.txt --]
[-- Type: text/x-patch, Size: 4640 bytes --]

commit c6f60a62b0b89a0f8c252970f3a4cf0bc2d220ce
Author: Jonathan Wakely <jwakely@redhat.com>
Date:   Mon Jan 13 16:25:01 2020 +0000

    libstdc++: Fix documentation claiming to refer to mainline
    
            * doc/xml/manual/status_cxx1998.xml: Replace incorrect statement
            about documenting mainline.
            * doc/xml/manual/status_cxx2011.xml: Likewise.
            * doc/xml/manual/status_cxx2014.xml: Likewise.
            * doc/xml/manual/status_cxx2017.xml: Likewise.
            * doc/xml/manual/status_cxx2020.xml: Likewise.
            * doc/xml/manual/status_cxxtr1.xml: Likewise.
            * doc/xml/manual/status_cxxtr24733.xml: Likewise.
            * doc/html/*: Regenerate.

diff --git a/libstdc++-v3/doc/xml/manual/status_cxx1998.xml b/libstdc++-v3/doc/xml/manual/status_cxx1998.xml
index 2b05ff6601a..44a042c2724 100644
--- a/libstdc++-v3/doc/xml/manual/status_cxx1998.xml
+++ b/libstdc++-v3/doc/xml/manual/status_cxx1998.xml
@@ -18,8 +18,7 @@ This status table is based on the table of contents of ISO/IEC 14882:2003.
 </para>
 
 <para>
-This page describes the C++ support in mainline GCC SVN, not in any
-particular release.
+This page describes the C++ support in the GCC 9 series.
 </para>
 
 <!-- Status is Yes or No, Broken/Partial-->
diff --git a/libstdc++-v3/doc/xml/manual/status_cxx2011.xml b/libstdc++-v3/doc/xml/manual/status_cxx2011.xml
index 0fa4bc0dffe..568102823b0 100644
--- a/libstdc++-v3/doc/xml/manual/status_cxx2011.xml
+++ b/libstdc++-v3/doc/xml/manual/status_cxx2011.xml
@@ -27,8 +27,7 @@ presence of the required flag.
 </para>
 
 <para>
-This page describes the C++11 support in mainline GCC SVN, not in any
-particular release.
+This page describes the C++11 support in the GCC 9 series.
 </para>
 
 <!-- Status is Yes or No, Broken/Partial-->
diff --git a/libstdc++-v3/doc/xml/manual/status_cxx2014.xml b/libstdc++-v3/doc/xml/manual/status_cxx2014.xml
index a33b4ec1611..7b604307c8e 100644
--- a/libstdc++-v3/doc/xml/manual/status_cxx2014.xml
+++ b/libstdc++-v3/doc/xml/manual/status_cxx2014.xml
@@ -20,8 +20,7 @@ presence of the required flag.
 </para>
 
 <para>
-This page describes the C++14 and library TS support in mainline GCC SVN,
-not in any particular release.
+This page describes the C++14 and library TS support in the GCC 9 series.
 </para>
 
 <table frame="all" xml:id="table.cxx14_status">
diff --git a/libstdc++-v3/doc/xml/manual/status_cxx2017.xml b/libstdc++-v3/doc/xml/manual/status_cxx2017.xml
index 40fe7cd2037..e1513142415 100644
--- a/libstdc++-v3/doc/xml/manual/status_cxx2017.xml
+++ b/libstdc++-v3/doc/xml/manual/status_cxx2017.xml
@@ -20,8 +20,7 @@ presence of the required flag.
 </para>
 
 <para>
-This section describes the C++17 and library TS support in mainline GCC SVN,
-not in any particular release.
+This section describes the C++17 and library TS support in the GCC 9 series.
 </para>
 
 <para>
diff --git a/libstdc++-v3/doc/xml/manual/status_cxx2020.xml b/libstdc++-v3/doc/xml/manual/status_cxx2020.xml
index ccf38185a6c..fc7fe0a3d9f 100644
--- a/libstdc++-v3/doc/xml/manual/status_cxx2020.xml
+++ b/libstdc++-v3/doc/xml/manual/status_cxx2020.xml
@@ -20,8 +20,7 @@ presence of the required flag.
 </para>
 
 <para>
-This section describes the C++20 and library TS support in mainline GCC SVN,
-not in any particular release.
+This section describes the C++20 and library TS support in the GCC 9 series.
 </para>
 
 <para>
diff --git a/libstdc++-v3/doc/xml/manual/status_cxxtr1.xml b/libstdc++-v3/doc/xml/manual/status_cxxtr1.xml
index 32ad20a2fb2..c1e65752156 100644
--- a/libstdc++-v3/doc/xml/manual/status_cxxtr1.xml
+++ b/libstdc++-v3/doc/xml/manual/status_cxxtr1.xml
@@ -22,8 +22,7 @@ In this implementation the header names are prefixed by
 </para>
 
 <para>
-This page describes the TR1 support in mainline GCC SVN, not in any particular
-release.
+This page describes the TR1 support in the GCC 9 series.
 </para>
 
 <!-- Status is Yes or No, Broken/Partial-->
diff --git a/libstdc++-v3/doc/xml/manual/status_cxxtr24733.xml b/libstdc++-v3/doc/xml/manual/status_cxxtr24733.xml
index e8d445116a2..a3ea8b285f6 100644
--- a/libstdc++-v3/doc/xml/manual/status_cxxtr24733.xml
+++ b/libstdc++-v3/doc/xml/manual/status_cxxtr24733.xml
@@ -16,8 +16,7 @@ decimal floating-point arithmetic
 </para>
 
 <para>
-This page describes the TR 24733 support in mainline GCC SVN, not in any
-particular release.
+This page describes the TR 24733 support in the GCC 9 series.
 </para>
 
 <!-- Status is Yes or No, Broken/Partial-->

Re: [PATCH] Clean up references to Subversion in documentation sources.

[Eric S. Raymond]

Joseph Myers <joseph@codesourcery.com>:
> I think you'll need to commit this for Eric (using --author= to set the 
> git author, whenever you commit a patch for someone else).  The libstdc++ 
> maintainers can probably handle regenerating the HTML version of the 
> libstdc++ documentation.

I'm hesitant to request push access this soon, but...you don't seem to
have an MR capability, and I have some other housekeeping/documentation
patches in mind.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

Re: [PATCH] Clean up references to Subversion in documentation sources.

[Jonathan Wakely]

On 13/01/20 12:24 -0500, Eric S. Raymond wrote:
>Joseph Myers <joseph@codesourcery.com>:
>> I think you'll need to commit this for Eric (using --author= to set the
>> git author, whenever you commit a patch for someone else).  The libstdc++
>> maintainers can probably handle regenerating the HTML version of the
>> libstdc++ documentation.
>
>I'm hesitant to request push access this soon, but...you don't seem to
>have an MR capability, and I have some other housekeeping/documentation
>patches in mind.

Email the patches to gcc-patches@gcc.gnu.org, that's how things get
merged.

We're not looking to change any workflows now.

Re: [PATCH] Clean up references to Subversion in documentation sources.

[Eric S. Raymond]

Jonathan Wakely <jwakely@redhat.com>:
> Email the patches to gcc-patches@gcc.gnu.org, that's how things get
> merged.
> 
> We're not looking to change any workflows now.

Roger that.

Once the dust from the conversion has settled, though, there is a
related issue I intend to bring up on the main list.

You've only collected about 60% of the potential benefits from git
by adopting git itself.  The other 40% would come from moving
to to one of the modern git-centric forges like GitHub or GitLab.

I'm as old-school as any of you guys, so take me seriously when I say
these are not popular for merely faddish reasns. The integration of
repository management, issue tracking, and continuous integration they
offer really does offer a major step up in productivity and
auditability.

I *will* be nudging the GCC project community to think about this.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

Re: [PATCH] Clean up references to Subversion in documentation sources.

[Gerald Pfeifer]

On Mon, 13 Jan 2020, Jonathan Wakely wrote:
> Here's what I've committed to releases/gcc-9, I'll do something
> similar for gcc-8.

Cool, thank you.  

That was a good catch, even without the conversion to GIT; I'll
see that I'll contribute to the conversion on the wwwdocs side
over the coming evenings.

Gerald

Re: [PATCH] Clean up references to Subversion in documentation sources.

[Sandra Loosemore]

On 1/13/20 9:12 AM, Joseph Myers wrote:
> On Mon, 13 Jan 2020, Sandra Loosemore wrote:
> 
>> On 1/13/20 7:02 AM, Eric S. Raymond wrote:
>>> Clean up references to SVN in in the GCC docs, redirecting to Git
>>> documentation as appropriate.
>>
>> This is OK, although the set of changes for the libstdc++ manual like this
>> gave me pause:
> 
> I think you'll need to commit this for Eric (using --author= to set the
> git author, whenever you commit a patch for someone else).  The libstdc++
> maintainers can probably handle regenerating the HTML version of the
> libstdc++ documentation.

I've pushed this patch to mainline and the gcc8 and gcc9 branches now.

-Sandra

Re: [PATCH] Clean up references to Subversion in documentation sources.

[Jonathan Wakely]

[-- Attachment #1: Type: text/plain, Size: 833 bytes --]

On 19/01/20 20:06 -0700, Sandra Loosemore wrote:
>On 1/13/20 9:12 AM, Joseph Myers wrote:
>>On Mon, 13 Jan 2020, Sandra Loosemore wrote:
>>
>>>On 1/13/20 7:02 AM, Eric S. Raymond wrote:
>>>>Clean up references to SVN in in the GCC docs, redirecting to Git
>>>>documentation as appropriate.
>>>
>>>This is OK, although the set of changes for the libstdc++ manual like this
>>>gave me pause:
>>
>>I think you'll need to commit this for Eric (using --author= to set the
>>git author, whenever you commit a patch for someone else).  The libstdc++
>>maintainers can probably handle regenerating the HTML version of the
>>libstdc++ documentation.
>
>I've pushed this patch to mainline and the gcc8 and gcc9 branches now.

This fixes the broken grammar in the patch. Committed to trunk so far,
I'll backport it too.



[-- Attachment #2: patch.txt --]
[-- Type: text/x-patch, Size: 3497 bytes --]

commit c784f1620498f78cfb9075a4696f2813722eb547
Author: Jonathan Wakely <jwakely@redhat.com>
Date:   Mon Jan 20 20:37:52 2020 +0000

    libstdc++: Fix recent documentation changes
    
            * doc/xml/faq.xml: Fix grammar.
            * doc/xml/manual/appendix_contributing.xml: Improve instructions.
            * doc/xml/manual/spine.xml: Update copyright years.
            * doc/html/*: Regenerate.

diff --git a/libstdc++-v3/doc/xml/faq.xml b/libstdc++-v3/doc/xml/faq.xml
index 21c312dce35..aff6c8d6004 100644
--- a/libstdc++-v3/doc/xml/faq.xml
+++ b/libstdc++-v3/doc/xml/faq.xml
@@ -34,8 +34,8 @@
      clauses 20 through 33 and annex D (prior to the 2017 standard
      the library clauses started with 17).  For those who want to see
      exactly how far the project has come, or just want the latest
-     bleeding-edge code, the up-to-date source , and can be cloned via Git: see
-     <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/git.html">web</link>.
+     bleeding-edge code, the up-to-date source can be cloned via
+     <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/git.html">Git</link>.
     </para> 
 
     <para>
@@ -295,15 +295,11 @@
     download sites</link> is provided on the main GCC site.
     </para>
     <para>
-    Current libstdc++ sources can always be checked out of the main
-    GCC source repository using the appropriate version control
-    tool. At this time, that tool
-    is <application>Git</application>.
-    </para>
-    <para>
-    For more information
-    see <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/git.html">
-    details</link>.
+    Current libstdc++ sources can always be found in the main GCC source
+    repository, available using the appropriate version control tool.
+    At this time, that tool is <application>Git</application>.
+    For more details see the documentation on
+    <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/git.html">using the Git repository</link>.
     </para>
   </answer>
 </qandaentry>
diff --git a/libstdc++-v3/doc/xml/manual/appendix_contributing.xml b/libstdc++-v3/doc/xml/manual/appendix_contributing.xml
index d2913b1663c..79fa0ed32b8 100644
--- a/libstdc++-v3/doc/xml/manual/appendix_contributing.xml
+++ b/libstdc++-v3/doc/xml/manual/appendix_contributing.xml
@@ -170,9 +170,10 @@
 
       <listitem>
 	<para>
-	  The patch itself. If you are accessing the Git
-	  repository use <command>git pull; git diff &gt;NEW</command>;
-	  else, use <command>diff -cp OLD NEW</command> ... If your
+	  The patch itself. If you are using the Git repository use
+	  <command>git diff</command> or <command>git format-patch</command>
+	  to produce a patch;
+	  otherwise, use <command>diff -cp OLD NEW</command>. If your
 	  version of diff does not support these options, then get the
 	  latest version of GNU diff.
 	</para>
diff --git a/libstdc++-v3/doc/xml/manual/spine.xml b/libstdc++-v3/doc/xml/manual/spine.xml
index a2cc1294e73..4db3037ac4d 100644
--- a/libstdc++-v3/doc/xml/manual/spine.xml
+++ b/libstdc++-v3/doc/xml/manual/spine.xml
@@ -27,6 +27,7 @@
     <year>2017</year>
     <year>2018</year>
     <year>2019</year>
+    <year>2020</year>
     <holder>
       <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.fsf.org">FSF</link>
     </holder>

Re: [PATCH] Clean up references to Subversion in documentation sources.

[Segher Boessenkool]

On Mon, Jan 13, 2020 at 01:12:15PM -0500, Eric S. Raymond wrote:
> Jonathan Wakely <jwakely@redhat.com>:
> > Email the patches to gcc-patches@gcc.gnu.org, that's how things get
> > merged.
> > 
> > We're not looking to change any workflows now.
> 
> Roger that.
> 
> Once the dust from the conversion has settled, though, there is a
> related issue I intend to bring up on the main list.
> 
> You've only collected about 60% of the potential benefits from git
> by adopting git itself.  The other 40% would come from moving
> to to one of the modern git-centric forges like GitHub or GitLab.

NAK.

Our development model fits our needs well, even with all its warts.
A "pull request" model would not fit well *at all*.

The "everything passes through email" model is *good*, not in the least
because it puts everyone on a level playing field.  Everyone can see
everything, and comment on everything.

And if it slows you down, well, that is a good thing as well probably!
Thought and carefulness and looking at things from multiple angles is
what we need, not raw speed: we need good changes, we do not need making
it easier to get your changes included at the cost of basic quality.

Anyway, 90% of the advantages of using Git come from using it *locally*,
which many of us have been doing since forever and a day already.


Segher