broken check: You should edit tm.texi.in rather than tm.texi

broken check: You should edit tm.texi.in rather than tm.texi

[Martin Liška]

Hello.

I hit the following issue:
/bin/sh /home/marxin/Programming/gcc/gcc/../move-if-change tmp-tm.texi tm.texi
You should edit /home/marxin/Programming/gcc/gcc/doc/tm.texi.in rather than /home/marxin/Programming/gcc/gcc/doc/tm.texi .

Steps to reproduce:
1) modify target.def
2) you will see:

Verify that you have permission to grant a GFDL license for all
new text in /dev/shm/objdir/gcc/tm.texi, then copy it to /home/marxin/Programming/gcc/gcc/doc/tm.texi.

I copy and commit the changes.

3) I made another modification to target.def

Now I face the issue as
	elif test $(srcdir)/doc/tm.texi -nt $(srcdir)/doc/tm.texi.in \
	  && ( test $(srcdir)/doc/tm.texi -nt $(srcdir)/target.def \

So tm.texi.in is older that tm.texi, but it's fine as both tm.texi.in
and tm.texi are not modified.

Ideas how to improve the error message? It took me some time to realize
that 'touch tm.texi.in' is what I need.

Martin

Re: broken check: You should edit tm.texi.in rather than tm.texi

[H.J. Lu]

On Fri, Nov 20, 2020 at 5:24 AM Martin Liška <mliska@suse.cz> wrote:
>
> Hello.
>
> I hit the following issue:
> /bin/sh /home/marxin/Programming/gcc/gcc/../move-if-change tmp-tm.texi tm.texi
> You should edit /home/marxin/Programming/gcc/gcc/doc/tm.texi.in rather than /home/marxin/Programming/gcc/gcc/doc/tm.texi .
>
> Steps to reproduce:
> 1) modify target.def
> 2) you will see:
>
> Verify that you have permission to grant a GFDL license for all
> new text in /dev/shm/objdir/gcc/tm.texi, then copy it to /home/marxin/Programming/gcc/gcc/doc/tm.texi.
>
> I copy and commit the changes.
>
> 3) I made another modification to target.def
>
> Now I face the issue as
>         elif test $(srcdir)/doc/tm.texi -nt $(srcdir)/doc/tm.texi.in \
>           && ( test $(srcdir)/doc/tm.texi -nt $(srcdir)/target.def \
>
> So tm.texi.in is older that tm.texi, but it's fine as both tm.texi.in
> and tm.texi are not modified.
>
> Ideas how to improve the error message? It took me some time to realize
> that 'touch tm.texi.in' is what I need.

Should contrib/gcc_update handle it?

-- 
H.J.

Re: broken check: You should edit tm.texi.in rather than tm.texi

[Martin Liška]

On 11/20/20 2:42 PM, H.J. Lu wrote:
> Should contrib/gcc_update handle it?

I don't know how publicly known is the script?
I personally do not used it.

Martin

Re: broken check: You should edit tm.texi.in rather than tm.texi

[Martin Liška]

On 11/20/20 4:26 PM, Martin Liška wrote:
> On 11/20/20 2:42 PM, H.J. Lu wrote:
>> Should contrib/gcc_update handle it?
> 
> I don't know how publicly known is the script?
> I personally do not used it.
> 
> Martin

... or we can add a hint:

diff --git a/gcc/Makefile.in b/gcc/Makefile.in
index 778ec09c75d..f079930dade 100644
--- a/gcc/Makefile.in
+++ b/gcc/Makefile.in
@@ -2580,6 +2580,7 @@ s-tm-texi: build/genhooks$(build_exeext) $(srcdir)/doc/tm.texi.in
  	  ); then \
  	  echo >&2 ; \
  	  echo You should edit $(srcdir)/doc/tm.texi.in rather than $(srcdir)/doc/tm.texi . >&2 ; \
+	  echo "(or you may need to touch $(srcdir)/doc/tm.texi.in if $(srcdir)/doc/tm.texi is not modified)" >&2 ; \
  	  false; \
  	else \
  	  echo >&2 ; \

Thoughs?
Martin

Re: broken check: You should edit tm.texi.in rather than tm.texi

[H.J. Lu]

On Fri, Nov 20, 2020 at 7:26 AM Martin Liška <mliska@suse.cz> wrote:
>
> On 11/20/20 2:42 PM, H.J. Lu wrote:
> > Should contrib/gcc_update handle it?
>
> I don't know how publicly known is the script?
> I personally do not used it.
>

I always run

$ ./contrib/gcc_update --touch

after rebase.

-- 
H.J.

Re: broken check: You should edit tm.texi.in rather than tm.texi

[Martin Sebor]

On 11/20/20 6:23 AM, Martin Liška wrote:
> Hello.
> 
> I hit the following issue:
> /bin/sh /home/marxin/Programming/gcc/gcc/../move-if-change tmp-tm.texi 
> tm.texi
> You should edit /home/marxin/Programming/gcc/gcc/doc/tm.texi.in rather 
> than /home/marxin/Programming/gcc/gcc/doc/tm.texi .
> 
> Steps to reproduce:
> 1) modify target.def
> 2) you will see:
> 
> Verify that you have permission to grant a GFDL license for all
> new text in /dev/shm/objdir/gcc/tm.texi, then copy it to 
> /home/marxin/Programming/gcc/gcc/doc/tm.texi.
> 
> I copy and commit the changes.
> 
> 3) I made another modification to target.def
> 
> Now I face the issue as
>      elif test $(srcdir)/doc/tm.texi -nt $(srcdir)/doc/tm.texi.in \
>        && ( test $(srcdir)/doc/tm.texi -nt $(srcdir)/target.def \
> 
> So tm.texi.in is older that tm.texi, but it's fine as both tm.texi.in
> and tm.texi are not modified.
> 
> Ideas how to improve the error message? It took me some time to realize
> that 'touch tm.texi.in' is what I need.

I don't know if it was the same problem but I spent a bunch of time
just last week wrestling with this error before it finally went away.

I never did understand what it was complaining about, or the point
of making us jump through these hoops for updates to the internals
manual when the (arguably far more impactful) changes to GCC source
code or the user-visible manual aren't subject to the same check.
Could we dispense with this altogether?  If not, can we implement
something less obtrusive (e.g., looking up the authors email in
MAINTAINERS first)?

Martin

Re: broken check: You should edit tm.texi.in rather than tm.texi

[Joseph Myers]

On Mon, 23 Nov 2020, Martin Sebor via Gcc wrote:

> I never did understand what it was complaining about, or the point
> of making us jump through these hoops for updates to the internals
> manual when the (arguably far more impactful) changes to GCC source
> code or the user-visible manual aren't subject to the same check.

The point of this check is that the FSF was unable to come up with a dual 
licensing notice allowing a single source file with content explicitly 
dual-licensed under the GPL and GFDL, so instead both GPL and GFDL copies 
of that content (doc strings for target hooks) need to be checked into the 
repository, and the check makes sure that the two copies are in sync.  The 
person contributing such documentation should commit it with both copies 
in sync to ensure it's properly available under both licenses.  Otherwise, 
e.g. moving existing internals manual text documenting a target macro into 
such a doc string for a target hook and so making it available under a new 
license, a global reviewer or docstring relicensing maintainer can approve 
the move.

-- 
Joseph S. Myers
joseph@codesourcery.com

Re: broken check: You should edit tm.texi.in rather than tm.texi

[Martin Sebor]

On 11/23/20 12:45 PM, Joseph Myers wrote:
> On Mon, 23 Nov 2020, Martin Sebor via Gcc wrote:
> 
>> I never did understand what it was complaining about, or the point
>> of making us jump through these hoops for updates to the internals
>> manual when the (arguably far more impactful) changes to GCC source
>> code or the user-visible manual aren't subject to the same check.
> 
> The point of this check is that the FSF was unable to come up with a dual
> licensing notice allowing a single source file with content explicitly
> dual-licensed under the GPL and GFDL, so instead both GPL and GFDL copies
> of that content (doc strings for target hooks) need to be checked into the
> repository, and the check makes sure that the two copies are in sync.  The
> person contributing such documentation should commit it with both copies
> in sync to ensure it's properly available under both licenses.  Otherwise,
> e.g. moving existing internals manual text documenting a target macro into
> such a doc string for a target hook and so making it available under a new
> license, a global reviewer or docstring relicensing maintainer can approve
> the move.

I'd expect the best way to ensure the two copies of the contributed
text are in sync is to copy it automatically.  If the only point of
asking the author to do it by hand each time they change the file
is to "Verify that they have permission to grant a GFDL license"
than that step could be done once, the result recorded somewhere
(e.g., in the MAINTAINERS file), and automated when making changes
by having the script look it up.

Is making this change feasible?

Martin

Re: broken check: You should edit tm.texi.in rather than tm.texi

[Joseph Myers]

On Mon, 23 Nov 2020, Martin Sebor via Gcc wrote:

> I'd expect the best way to ensure the two copies of the contributed
> text are in sync is to copy it automatically.  If the only point of
> asking the author to do it by hand each time they change the file
> is to "Verify that they have permission to grant a GFDL license"
> than that step could be done once, the result recorded somewhere
> (e.g., in the MAINTAINERS file), and automated when making changes
> by having the script look it up.

That permission is a function of the particular change being made (if it 
involves text previously in GPL-only parts of GCC being copied into the 
GFDL manual, that needs a docstring relicensing review), not just of the 
person making the change.

-- 
Joseph S. Myers
joseph@codesourcery.com

Re: broken check: You should edit tm.texi.in rather than tm.texi

[Martin Sebor]

On 11/23/20 1:25 PM, Joseph Myers wrote:
> On Mon, 23 Nov 2020, Martin Sebor via Gcc wrote:
> 
>> I'd expect the best way to ensure the two copies of the contributed
>> text are in sync is to copy it automatically.  If the only point of
>> asking the author to do it by hand each time they change the file
>> is to "Verify that they have permission to grant a GFDL license"
>> than that step could be done once, the result recorded somewhere
>> (e.g., in the MAINTAINERS file), and automated when making changes
>> by having the script look it up.
> 
> That permission is a function of the particular change being made (if it
> involves text previously in GPL-only parts of GCC being copied into the
> GFDL manual, that needs a docstring relicensing review), not just of the
> person making the change.

I see.  So this check is in place just for the case of copying
someone else's text from some other manual to the internals manual.

Either way, though, asking the person making the change to verify
they have a permission to do it isn't sufficient.  If they're not
the author of the text being copied or one of the two roles above
then how can they verify it?  I wouldn't know how and I'd be
shocked if I was alone.

Even if we could verify it, it's unnecessary to make the build
fail every time we change the file and force us to copy it by
hand.  It seems to me a better time/place to do this, now that
we have Git, is by a commit hook, advising the committer that
they should seek the licensing review.  Even this could be
avoided if the commit message somehow indicated the licensing
review was done (e.g., by a Reviewed-By tag naming one of
the special reviewers).

Is implementing something like this feasible?

Martin