Re: Some notes on the Wiki

Re: Some notes on the Wiki

[Michael Cieslinski]

I converted this patch because I thought it would be helpful after
reading this message from Giovanni Bajo:
http://gcc.gnu.org/ml/gcc/2005-03/msg00552.html
> 
> I had provided this patch in the past, but was rejected:
> http://gcc.gnu.org/ml/gcc-patches/2004-06/msg00313.html
> 
> I never had time to split, rewrite in tex, and update it as requested.
> Janis recently incorporated some parts into the internal manuals, but I
> believe that we still nedd provide a "tutorial for GCC testcase 
> writing". Like I'm trying to explain in another thread, I believe that
> we are being way too picky on www/documentation patches than we should
> be.
> 
> For instance, my patch could have been committed immediatly and been
> refined over time. In fact, I should find a couple of hours to add it
> to the Wiki.
> -- 
> Giovanni Bajo
> 

From my point of view the wiki is THE place for documentation. It is very
easy to put new things in, edit or correct it. I'm familiar with it but I
never used texinfo nor did I ever sent a patch.

I look daily at the wiki and check if somebody puts spam in it. 

I would also propose to make the wiki the primary source of documentation
and derive a static html page from it which could be downloaded and used
locally.

I volunteer to convert the 104 page RTL pdf into wiki pages (if Daniel
sends it to me).

I also could convert parts of the ggcinternals manual into wiki pages.
But only if there is a consensus about this being the way to go.


Michael Cieslinski

Re: Re: Some notes on the Wiki

[Joseph S. Myers]

On Mon, 11 Jul 2005, Michael Cieslinski wrote:

> I also could convert parts of the ggcinternals manual into wiki pages.
> But only if there is a consensus about this being the way to go.

I'm sure it's the wrong way to go.  I find a properly formatted and 
indexed book far more convenient for learning about substantial areas of 
compiler internals, or for finding what some particular macro is specified 
to do, than a wiki.  And since some people seem to think the internal 
manual is of no use: it's the first place I refer to for information on 
the areas of internals it covers; after that source code and mailing list 
archives, the wiki very rarely.

I think the wiki is certainly useful for rough notes such as 
<http://gcc.gnu.org/wiki/general%20backend%20cleanup>, synthesised from 
mailing list discussions.

It may be useful as an intermediate step in putting together 
reverse-engineered information about internals in order to specify it 
properly in the internals manual - but only provided authorship and 
copyright assignment information is rigorously tracked as required by the 
FSF.

But in general internals documentation should include the *specification* 
written before the implementation and submitted with it for review 
together, and the specification should not need to be reverse-engineered 
later (see Kenner's comments passim about the importance of comments being 
written at the time of code or at least by its author, not backfilled 
later).

-- 
Joseph S. Myers               http://www.srcf.ucam.org/~jsm28/gcc/
    jsm@polyomino.org.uk (personal mail)
    joseph@codesourcery.com (CodeSourcery mail)
    jsm28@gcc.gnu.org (Bugzilla assignments and CCs)

Re: Some notes on the Wiki

[Russell Shaw]

Joseph S. Myers wrote:
> On Mon, 11 Jul 2005, Michael Cieslinski wrote:
> 
>>I also could convert parts of the ggcinternals manual into wiki pages.
>>But only if there is a consensus about this being the way to go.
> 
> I'm sure it's the wrong way to go.  I find a properly formatted and 
> indexed book far more convenient for learning about substantial areas of 
> compiler internals, or for finding what some particular macro is specified 
> to do, than a wiki.  And since some people seem to think the internal 
> manual is of no use: it's the first place I refer to for information on 
> the areas of internals it covers; after that source code and mailing list 
> archives, the wiki very rarely.
> 
> I think the wiki is certainly useful for rough notes such as 
> <http://gcc.gnu.org/wiki/general%20backend%20cleanup>, synthesised from 
> mailing list discussions.
> 
> It may be useful as an intermediate step in putting together 
> reverse-engineered information about internals in order to specify it 
> properly in the internals manual - but only provided authorship and 
> copyright assignment information is rigorously tracked as required by the 
> FSF.

Just put in a clause that copyright of all additions automatically
reverts to FSF.

Re: Re: Some notes on the Wiki

[Paul Koning]

>>>>> "Joseph" == Joseph S Myers <joseph@codesourcery.com> writes:

 Joseph> On Mon, 11 Jul 2005, Michael Cieslinski wrote:
 >> I also could convert parts of the ggcinternals manual into wiki
 >> pages.  But only if there is a consensus about this being the way
 >> to go.

 Joseph> I'm sure it's the wrong way to go.  I find a properly
 Joseph> formatted and indexed book far more convenient for learning
 Joseph> about substantial areas of compiler internals, or for finding
 Joseph> what some particular macro is specified to do, than a wiki.

I'll second that.  Unlike some other major GNU projects, GCC's
internals manual is substantial and very good.  Yes, it needs ongoing
improvement, but I'd prefer that rather than flipping to Twiki.

	     paul

Re: Some notes on the Wiki

[Steven Bosscher]

On Monday 11 July 2005 15:54, Paul Koning wrote:
> >>>>> "Joseph" == Joseph S Myers <joseph@codesourcery.com> writes:
>
>  Joseph> On Mon, 11 Jul 2005, Michael Cieslinski wrote:
>  >> I also could convert parts of the ggcinternals manual into wiki
>  >> pages.  But only if there is a consensus about this being the way
>  >> to go.
>
>  Joseph> I'm sure it's the wrong way to go.  I find a properly
>  Joseph> formatted and indexed book far more convenient for learning
>  Joseph> about substantial areas of compiler internals, or for finding
>  Joseph> what some particular macro is specified to do, than a wiki.
>
> I'll second that.  Unlike some other major GNU projects, GCC's
> internals manual is substantial and very good.  Yes, it needs ongoing
> improvement, but I'd prefer that rather than flipping to Twiki.

So, contribute to the manual then.  And let the folks who prefer to
work on the wiki work on the wiki.

Unless we are going to require reviewing for wiki changes now, too,
there is no point in this entire discussion.  And if we are going
to require reviewing for the wiki, there is no point in having the
wiki.

Gr.
Steven

Re: Some notes on the Wiki

[Diego Novillo]

On Mon, Jul 11, 2005 at 04:10:56PM +0200, Steven Bosscher wrote:

> So, contribute to the manual then.  And let the folks who prefer to
> work on the wiki work on the wiki.
> 
I believe the Wiki is an invaluable documentation tool, precisely
because it allows such an unencumbered contribution process.
Also, some of the things documented in the wiki are either
inappropriate for the manual or too dynamic in nature.  I can see
both co-existing for a long time.

However, it would be very useful for us to transfer information
from the wiki into the manual from time to time.  And we cannot
do that if we don't have cleared out the copyright assignment of
wiki content.

Would a blanket statement at the start of the wiki be enough?
Who gets to decide this?


Diego.

Re: Some notes on the Wiki

[Steven Bosscher]

On Monday 11 July 2005 16:19, Diego Novillo wrote:
> Would a blanket statement at the start of the wiki be enough?
> Who gets to decide this?

I guess that, apart from the legal discussion of whether this enough,
such a statement would not apply to existing content.  It was certainly
not my intention to sign over the various Wiki contributions I have
made to the FSF.

Gr.
Steven

Re: Some notes on the Wiki

[Haren Visavadia]

--- Diego Novillo wrote:
> And we cannot
> do that if we don't have cleared out the copyright
> assignment of
> wiki content.

And so?




		
___________________________________________________________ 
How much free photo storage do you get? Store your holiday 
snaps for FREE with Yahoo! Photos http://uk.photos.yahoo.com

Re: Some notes on the Wiki

[Diego Novillo]

On Mon, Jul 11, 2005 at 03:41:25PM +0100, Haren Visavadia wrote:
> --- Diego Novillo wrote:
> > And we cannot
> > do that if we don't have cleared out the copyright
> > assignment of
> > wiki content.
> 
> And so?
> 
Sorry, I don't understand what you're asking.

My line of thought was described in the text that you removed:
"However, it would be very useful for us to transfer information
from the wiki into the manual from time to time."


Diego.

Re: Some notes on the Wiki

[Bernd Schmidt]

Steven Bosscher wrote:
> I guess that, apart from the legal discussion of whether this enough,
> such a statement would not apply to existing content.  It was certainly
> not my intention to sign over the various Wiki contributions I have
> made to the FSF.

This strikes me as shortsighted.  If we're getting into a situation 
where we can't freely move documentation from one place to another, 
we're shooting ourselves in the foot.


Bernd

Re: Some notes on the Wiki

[Steven Bosscher]

On Monday 11 July 2005 16:50, Bernd Schmidt wrote:
> Steven Bosscher wrote:
> > I guess that, apart from the legal discussion of whether this enough,
> > such a statement would not apply to existing content.  It was certainly
> > not my intention to sign over the various Wiki contributions I have
> > made to the FSF.
>
> This strikes me as shortsighted.

Call it what you will.  For me it is a matter of choice and freedom.

> If we're getting into a situation 
> where we can't freely move documentation from one place to another,
> we're shooting ourselves in the foot.

We already can't do that.  We can't move documentation from the manual
into the code, and vice versa, because of the GPL vs. GFDL issue.  It
is that kind of thing that completely takes away any motivation I might
otherwise have to contribute to the manual.

And again, if you're going to require reviewing and copyright assignment
for wiki contributions, we might as well not have a wiki at all.

Gr.
Steven

Re: Some notes on the Wiki

[Joseph S. Myers]

On Mon, 11 Jul 2005, Steven Bosscher wrote:

> On Monday 11 July 2005 16:50, Bernd Schmidt wrote:
> > Steven Bosscher wrote:
> > > I guess that, apart from the legal discussion of whether this enough,
> > > such a statement would not apply to existing content.  It was certainly
> > > not my intention to sign over the various Wiki contributions I have
> > > made to the FSF.
> >
> > This strikes me as shortsighted.
> 
> Call it what you will.  For me it is a matter of choice and freedom.
> 
> > If we're getting into a situation 
> > where we can't freely move documentation from one place to another,
> > we're shooting ourselves in the foot.
> 
> We already can't do that.  We can't move documentation from the manual
> into the code, and vice versa, because of the GPL vs. GFDL issue.  It
> is that kind of thing that completely takes away any motivation I might
> otherwise have to contribute to the manual.

1. If GCC developers wish to move documentation from the GPL code to the 
GFDL manuals, or vice versa, what procedures need to be followed?

2. Do existing GCC copyright assignments cover the GCC Wiki 
<http://gcc.gnu.org/wiki/>?

-- 
Joseph S. Myers               http://www.srcf.ucam.org/~jsm28/gcc/
    jsm@polyomino.org.uk (personal mail)
    joseph@codesourcery.com (CodeSourcery mail)
    jsm28@gcc.gnu.org (Bugzilla assignments and CCs)

Re: Some notes on the Wiki

[Andrew Haley]

Steven Bosscher writes:
 > On Monday 11 July 2005 16:50, Bernd Schmidt wrote:
 > > Steven Bosscher wrote:
 > > > I guess that, apart from the legal discussion of whether this enough,
 > > > such a statement would not apply to existing content.  It was certainly
 > > > not my intention to sign over the various Wiki contributions I have
 > > > made to the FSF.
 > >
 > > This strikes me as shortsighted.
 > 
 > Call it what you will.  For me it is a matter of choice and freedom.
 > 
 > > If we're getting into a situation 
 > > where we can't freely move documentation from one place to another,
 > > we're shooting ourselves in the foot.
 > 
 > We already can't do that.  We can't move documentation from the manual
 > into the code, and vice versa, because of the GPL vs. GFDL issue.

Actually, that's not true because *we* (or to be accurate the FSF) own
the copyright on both.

 > It is that kind of thing that completely takes away any motivation
 > I might otherwise have to contribute to the manual.
 > 
 > And again, if you're going to require reviewing and copyright assignment
 > for wiki contributions, we might as well not have a wiki at all.

Good idea.

Andrew.

Re: Some notes on the Wiki

[Daniel Berlin]

On Mon, 2005-07-11 at 16:22 +0200, Steven Bosscher wrote:
> On Monday 11 July 2005 16:19, Diego Novillo wrote:
> > Would a blanket statement at the start of the wiki be enough?
> > Who gets to decide this?
> 
> I guess that, apart from the legal discussion of whether this enough,
> such a statement would not apply to existing content.  It was certainly
> not my intention to sign over the various Wiki contributions I have
> made to the FSF.
We can't get copyright assignments, we can however get effective online
estoppel agreements, like wikipedia does.

This should be enough for documentation, one would hope.

Re: Some notes on the Wiki

[Steven Bosscher]

On Monday 11 July 2005 17:21, Andrew Haley wrote:
>  > We already can't do that.  We can't move documentation from the manual
>  > into the code, and vice versa, because of the GPL vs. GFDL issue.
>
> Actually, that's not true because *we* (or to be accurate the FSF) own
> the copyright on both.

To play the Devil's advocate: One could argue that someone contributing
to the GCC code under the GPL does not agree with the GFDL, and therefore
the FSF can't live up to its promise (that iirc it makes in the copyright
assignment) to keep the code under a free license.

In practice, people have already contributed significants amount of
documentation as comment because they disagree with the GFDL.

Gr.
Steven

Re: Some notes on the Wiki

[Daniel Berlin]

On Mon, 2005-07-11 at 15:19 +0000, Joseph S. Myers wrote:
> On Mon, 11 Jul 2005, Steven Bosscher wrote:
> 
> > On Monday 11 July 2005 16:50, Bernd Schmidt wrote:
> > > Steven Bosscher wrote:
> > > > I guess that, apart from the legal discussion of whether this enough,
> > > > such a statement would not apply to existing content.  It was certainly
> > > > not my intention to sign over the various Wiki contributions I have
> > > > made to the FSF.
> > >
> > > This strikes me as shortsighted.
> > 
> > Call it what you will.  For me it is a matter of choice and freedom.
> > 
> > > If we're getting into a situation 
> > > where we can't freely move documentation from one place to another,
> > > we're shooting ourselves in the foot.
> > 
> > We already can't do that.  We can't move documentation from the manual
> > into the code, and vice versa, because of the GPL vs. GFDL issue.  It
> > is that kind of thing that completely takes away any motivation I might
> > otherwise have to contribute to the manual.
> 
> 1. If GCC developers wish to move documentation from the GPL code to the 
> GFDL manuals, or vice versa, what procedures need to be followed?
> 
> 2. Do existing GCC copyright assignments cover the GCC Wiki 
> <http://gcc.gnu.org/wiki/>?
> 

No, and again, i don't understand why we can't do what *everyone else on
the planet who transfers docs between the two do* and just make users
agree that they are giving the right to do that when they submit
contributions to the wiki.


See, for example, the wikipedia contribution page.
"
________________________________________________________________________
DO NOT SUBMIT COPYRIGHTED WORK WITHOUT PERMISSION!
      * you agree that all contributions to any page on Wikipedia are
        released under the GNU Free Documentation License (see
        Project:Copyrights for details).
      * If you do not want your writing to be edited mercilessly and
        redistributed at will, do not submit it.
      * By submitting your work you promise you wrote it yourself, or
        copied it from public domain resources—this does not include
        most web page."

Re: Some notes on the Wiki

[Steven Bosscher]

*sigh*

> To play the Devil's advocate: One could argue that someone contributing
> to the GCC code under the GPL does not agree with the GFDL, and therefore
> the FSF can't live up to its promise (that iirc it makes in the copyright
> assignment) to keep the code under a free license.
... if comments from that code are moved into the manual,

Re: Some notes on the Wiki

[Mike Stump]

On Monday, July 11, 2005, at 08:30 AM, Steven Bosscher wrote:
> In practice, people have already contributed significants amount of
> documentation as comment because they disagree with the GFDL.

I'm of the opinion we never should have allowed the GFDL into our 
source tree, no thanks should have been our response.  I'd like to urge 
the SC to pester the FSF on this point continuously until they relent.  
I keep hoping it was just an experiment that one day the FSF will see 
the errors of their ways and just stop.  That, or they will try and 
introduce yet more non-freeisms into the source code base, we should 
uniformly reject all such incursions.

Re: Some notes on the Wiki

[Kevin Handy]

Paul Koning wrote:

>>>>>>"Joseph" == Joseph S Myers <joseph@codesourcery.com> writes:
>>>>>>            
>>>>>>
>
> Joseph> On Mon, 11 Jul 2005, Michael Cieslinski wrote:
> >> I also could convert parts of the ggcinternals manual into wiki
> >> pages.  But only if there is a consensus about this being the way
> >> to go.
>
> Joseph> I'm sure it's the wrong way to go.  I find a properly
> Joseph> formatted and indexed book far more convenient for learning
> Joseph> about substantial areas of compiler internals, or for finding
> Joseph> what some particular macro is specified to do, than a wiki.
>
>I'll second that.  Unlike some other major GNU projects, GCC's
>internals manual is substantial and very good.  Yes, it needs ongoing
>improvement, but I'd prefer that rather than flipping to Twiki.
>
>  
>
In order to show how good the internals documents are, try to
build a very simple front end using ONLY the documentation.
Make it of the order of a hardwired "int main() { return 0}".
Or better yet, find an outsider who knows C, but not GCC
internals, to write it.

No outside source can be used (i.e. no source code not included
in the documentation).

It cannot be done. Not even close. Not even if you allow tree.def.

Too much stuff exists outside of the documentation.

Re: Some notes on the Wiki

[Paul Koning]

>>>>> "Kevin" == Kevin Handy <kth@srv.net> writes:

 Kevin> Paul Koning wrote:
 >>>>>>> "Joseph" == Joseph S Myers <joseph@codesourcery.com> writes:
 >>>>>>> 
 >>>>>>> 
 >>
 Joseph> On Mon, 11 Jul 2005, Michael Cieslinski wrote:
 >> >> I also could convert parts of the ggcinternals manual into wiki
 >> >> pages.  But only if there is a consensus about this being the
 >> way >> to go.
 >> 
 Joseph> I'm sure it's the wrong way to go.  I find a properly
 Joseph> formatted and indexed book far more convenient for learning
 Joseph> about substantial areas of compiler internals, or for finding
 Joseph> what some particular macro is specified to do, than a wiki.
 >> I'll second that.  Unlike some other major GNU projects, GCC's
 >> internals manual is substantial and very good.  Yes, it needs
 >> ongoing improvement, but I'd prefer that rather than flipping to
 >> Twiki.
 >> 
 Kevin> In order to show how good the internals documents are, try to
 Kevin> build a very simple front end using ONLY the documentation.
 Kevin> Make it of the order of a hardwired "int main() { return 0}".
 Kevin> Or better yet, find an outsider who knows C, but not GCC
 Kevin> internals, to write it.

 Kevin> No outside source can be used (i.e. no source code not
 Kevin> included in the documentation).

 Kevin> It cannot be done. Not even close. Not even if you allow
 Kevin> tree.def.

Quite true.  On the other hand, for backends things are in far better
shape.  And for my comment on other projects, compare the GCC
internals doc with the internals doc for GDB -- you'll see the point.

	  paul

Re: Some notes on the Wiki

[Gerald Pfeifer]

On Mon, 11 Jul 2005, Steven Bosscher wrote:
> Unless we are going to require reviewing for wiki changes now, too,
> there is no point in this entire discussion.

I beg to disagree: first, we again raised the GFDL issue with RMS,
we may have some new volunteers to help with web pages/documentation,
got some discussions on the Wiki going (partly including RMS as well),
and put some of the true motiviations for (not) doing specific things
on the table.  All of these are useful in my book.

Gerald