Re: Some notes on the Wiki

Re: Some notes on the Wiki

[Richard Kenner]

    I believe the Wiki is an invaluable documentation tool, precisely
    because it allows such an unencumbered contribution process.

I agree.  I wasn't suggesting that the Wiki has no value, but rather
that it's not a substitute for the more formal documentation.  Were it
not for copyright issues, one could view the Wiki as an ongoing draft
process for the documentation.

Re: Some notes on the Wiki

[Robert Thorpe]

 -------- Original Message --------
> From: Daniel Berlin <dberlin@dberlin.org>
> Sent: Monday, July 11, 2005 1:28 PM
> To: rthorpe@realworldtech.com
> Subject: Re: Some notes on the Wiki
> 
> On Mon, 2005-07-11 at 13:09 -0700, Robert Thorpe wrote:
> > >     I believe the Wiki is an invaluable documentation tool, precisely
> > >     because it allows such an unencumbered contribution process.
> > >    
> > > I agree.  I wasn't suggesting that the Wiki has no value, but rather
> > > that it's not a substitute for the more formal documentation.  Were it
> > > not for copyright issues, one could view the Wiki as an ongoing draft
> > > process for the documentation.
> > 
> > A comment from a user...
> > 
> > Please, please, please don't move GCC internals documentation to a Wiki.
> > 
> Nobody has suggested that we wouldn't ship docs.

Great
 
> > Even to users the internals documentation is useful.  It's useful when trying to find out why GCC is doing the things it does with the code given to it, it indicates where to look to find things in the source. 
> 
> >  This would be much harder if it were a wiki, in particular finding information on the version of GCC you're using would be much more difficult.
> 
> However, this isn't true.  The wiki stores every version of a page. We
> could make sure we know what versions of the wiki pages refer to what
> releases, and link them accordingly.

Please do that if you're going to use the wiki seriously for lots of docs.

> > Also, a web-browser is much slower than an info-browser, especially when doing searchs.
> 
> You must be close to the only user i've met who uses the info browser :)

When I said "an info-browser" I meant info-browsers in general, not standalone info in particular. Both Emacs and stand-alone info are fast (I think the Vim one is too).
I use Emacs Info, but the standalone browser is useful on Cygwin; it means you don't need to install Emacs just to read the cygwin docs.

Anyway, it doesn't matter much if your going to keep the docs in texi format,  people who want pdf's or html can generate those formats.

Re: Some notes on the Wiki

[Robert Thorpe]

>     I believe the Wiki is an invaluable documentation tool, precisely
>     because it allows such an unencumbered contribution process.
>    
> I agree.  I wasn't suggesting that the Wiki has no value, but rather
> that it's not a substitute for the more formal documentation.  Were it
> not for copyright issues, one could view the Wiki as an ongoing draft
> process for the documentation.

A comment from a user...

Please, please, please don't move GCC internals documentation to a Wiki.

Even to users the internals documentation is useful.  It's useful when trying to find out why GCC is doing the things it does with the code given to it, it indicates where to look to find things in the source.  This would be much harder if it were a wiki, in particular finding information on the version of GCC you're using would be much more difficult.

Also, a web-browser is much slower than an info-browser, especially when doing searchs.

Re: Some notes on the Wiki

[Daniel Berlin]

On Mon, 2005-07-11 at 13:09 -0700, Robert Thorpe wrote:
> >     I believe the Wiki is an invaluable documentation tool, precisely
> >     because it allows such an unencumbered contribution process.
> >    
> > I agree.  I wasn't suggesting that the Wiki has no value, but rather
> > that it's not a substitute for the more formal documentation.  Were it
> > not for copyright issues, one could view the Wiki as an ongoing draft
> > process for the documentation.
> 
> A comment from a user...
> 
> Please, please, please don't move GCC internals documentation to a Wiki.
> 
Nobody has suggested that we wouldn't ship docs.

> Even to users the internals documentation is useful.  It's useful when trying to find out why GCC is doing the things it does with the code given to it, it indicates where to look to find things in the source. 

>  This would be much harder if it were a wiki, in particular finding information on the version of GCC you're using would be much more difficult.

However, this isn't true.  The wiki stores every version of a page. We
could make sure we know what versions of the wiki pages refer to what
releases, and link them accordingly.


> 
> Also, a web-browser is much slower than an info-browser, especially when doing searchs.

You must be close to the only user i've met who uses the info browser :)

> 
> 
> 
> 

Re: Some notes on the Wiki

[Gabriel Dos Reis]

Daniel Berlin <dberlin@dberlin.org> writes:

[...]

| > Also, a web-browser is much slower than an info-browser, especially when doing searchs.
| 
| You must be close to the only user i've met who uses the info browser :)

Ahem; is your world that small?

-- Gaby

Re: Some notes on the Wiki

[Daniel Berlin]

On Mon, 2005-07-11 at 22:47 +0200, Gabriel Dos Reis wrote:
> Daniel Berlin <dberlin@dberlin.org> writes:
> 
> [...]
> 
> | > Also, a web-browser is much slower than an info-browser, especially when doing searchs.
> | 
> | You must be close to the only user i've met who uses the info browser :)
> 
> Ahem; is your world that small?

No, i'm actually talking about ~50 users from all walk of life and no
relation to each other (which is a pretty statistically significant
sample)

In fact, a lot of projects don't even bother to distribute anything but
HTML docs anymore (regardless of how they browse it).

> 
> -- Gaby

Re: Some notes on the Wiki

[Alexandre Oliva]

On Jul 11, 2005, Daniel Berlin <dberlin@dberlin.org> wrote:

> In fact, a lot of projects don't even bother to distribute anything but
> HTML docs anymore (regardless of how they browse it).

And that's a pity, because it's a bit of a pain to turn the output of
grep -r regexp docs/HTML into something the browser will display
properly, especially when there are multiple hits.

The stand-alone info tool just rules at that; it's invaluable to
search GCC docs like that.  Having dozens of web pages instead would
make such searches intolerable.

-- 
Alexandre Oliva         http://www.lsd.ic.unicamp.br/~oliva/
Red Hat Compiler Engineer   aoliva@{redhat.com, gcc.gnu.org}
Free Software Evangelist  oliva@{lsd.ic.unicamp.br, gnu.org}

Re: Some notes on the Wiki

[Nicholas Nethercote]

On Mon, 11 Jul 2005, Daniel Berlin wrote:

>> Also, a web-browser is much slower than an info-browser, especially 
>> when doing searchs.
>
> You must be close to the only user i've met who uses the info browser :)

I use it.  Info pages suck in many ways, but they're fast to load from an 
xterm, fast to search, and even faster when you know where they are in the 
docs (eg. I find myself looking at the GCC C extensions quite often, and I 
can get there very quickly).

Nick

Re: Some notes on the Wiki

[Daniel Berlin]

On Mon, 11 Jul 2005, Nicholas Nethercote wrote:

> On Mon, 11 Jul 2005, Daniel Berlin wrote:
>
>>> Also, a web-browser is much slower than an info-browser, especially when 
>>> doing searchs.
>> 
>> You must be close to the only user i've met who uses the info browser :)
>
> I use it.  Info pages suck in many ways, but they're fast to load from an 
> xterm, fast to search, and even faster when you know where they are in the 
> docs (eg. I find myself looking at the GCC C extensions quite often, and I 
> can get there very quickly).

Most people i've met can't undertand the commands for info (pinfo is 
nicer in this regard).
Those who use info religiously seem to be emacs users, not "info browser" 
users.
Hence my surprise.

--Dan

Re: Some notes on the Wiki

[Andreas Schwab]

Daniel Berlin <dberlin@dberlin.org> writes:

> Most people i've met can't undertand the commands for info (pinfo is 
> nicer in this regard).

There exist many alternative info browsers (this includes konqueror).

> Those who use info religiously seem to be emacs users, not "info browser" 
> users.

I bet you have never used any recent version of info (the program).

Andreas.

-- 
Andreas Schwab, SuSE Labs, schwab@suse.de
SuSE Linux Products GmbH, Maxfeldstraße 5, 90409 Nürnberg, Germany
Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: Some notes on the Wiki

[Daniel Berlin]

On Mon, 11 Jul 2005, Andreas Schwab wrote:

> Daniel Berlin <dberlin@dberlin.org> writes:
>
>> Most people i've met can't undertand the commands for info (pinfo is
>> nicer in this regard).
>
> There exist many alternative info browsers (this includes konqueror).

Yet the amount of docs available in info is dwindling :)
And in fact, most of the ones i see on my system are mostly for the gnu 
development things (ddd, gdb, gcc, make, gmp, glibc) and emacs packages 
(viper, gnus).

>
>> Those who use info religiously seem to be emacs users, not "info browser"
>> users.
>
> I bet you have never used any recent version of info (the program).

Let's see. The last time i tried to use info (the program) was about 6 
weeks ago, 
when i was trying to get info about a function in glibc.
I could not for the life of me determine why it felt the need to jump 
topics when i was just trying to scroll up or down more.

I'm in the "I hate info" camp, and happily so.  I'm happy that most docs 
i want to view are either hyperlinked pdf or searchable html.

Anyhoo, this is offtopic

--Dan

Re: Some notes on the Wiki

[Andreas Schwab]

Daniel Berlin <dberlin@dberlin.org> writes:

> Let's see. The last time i tried to use info (the program) was about 6 
> weeks ago, 

I was refering to a recent version, not a recent use.

Andreas.

-- 
Andreas Schwab, SuSE Labs, schwab@suse.de
SuSE Linux Products GmbH, Maxfeldstraße 5, 90409 Nürnberg, Germany
Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: Some notes on the Wiki

[Gabriel Dos Reis]

Daniel Berlin <dberlin@dberlin.org> writes:

| On Mon, 11 Jul 2005, Nicholas Nethercote wrote:
| 
| > On Mon, 11 Jul 2005, Daniel Berlin wrote:
| >
| >>> Also, a web-browser is much slower than an info-browser,
| >>> especially when doing searchs.
| >> You must be close to the only user i've met who uses the info
| >> browser :)
| >
| > I use it.  Info pages suck in many ways, but they're fast to load
| > from an xterm, fast to search, and even faster when you know where
| > they are in the docs (eg. I find myself looking at the GCC C
| > extensions quite often, and I can get there very quickly).
| 
| Most people i've met can't undertand the commands for info (pinfo is
| nicer in this regard).

maybe the conclusion to draw is that you've met some special people in
a small part of the community.

-- Gaby

Re: Some notes on the Wiki

[chris jefferson]

Gabriel Dos Reis wrote:

>Daniel Berlin <dberlin@dberlin.org> writes:
>
>| On Mon, 11 Jul 2005, Nicholas Nethercote wrote:
>| 
>| > On Mon, 11 Jul 2005, Daniel Berlin wrote:
>| >
>| >>> Also, a web-browser is much slower than an info-browser,
>| >>> especially when doing searchs.
>| >> You must be close to the only user i've met who uses the info
>| >> browser :)
>| >
>| > I use it.  Info pages suck in many ways, but they're fast to load
>| > from an xterm, fast to search, and even faster when you know where
>| > they are in the docs (eg. I find myself looking at the GCC C
>| > extensions quite often, and I can get there very quickly).
>| 
>| Most people i've met can't undertand the commands for info (pinfo is
>| nicer in this regard).
>
>maybe the conclusion to draw is that you've met some special people in
>a small part of the community.
>
>  
>
I just had a quick quiz in the C++ IRC channel I was in, and very few
people there like info, and very few are comfortable using it. There was
a general agreement HTML, PDF and docbook are the best ways to recieve
documentation.

Chris

Re: Some notes on the Wiki

[Daniel Berlin]

> >  
> >
> I just had a quick quiz in the C++ IRC channel I was in, and very few
> people there like info, and very few are comfortable using it. There was
> a general agreement HTML, PDF and docbook are the best ways to recieve
> documentation.
> 
> Chris

It's possible these people ride the short development bus too, which
apparently i do :(

Re: Some notes on the Wiki

[Kurt Wall]

On Mon, Jul 11, 2005 at 04:27:58PM -0400, Daniel Berlin took 34 lines to write:
> On Mon, 2005-07-11 at 13:09 -0700, Robert Thorpe wrote:
> > Also, a web-browser is much slower than an info-browser, especially 
> > when doing searchs.
> 
> You must be close to the only user i've met who uses the info browser :)

We haven't met, but I use the info browser. :-) I used to hate it but
finally decided that since texi was the format that existed, I might
as well suck it up and learn to use it.

Kurt
-- 
"I thought you were trying to get into shape."
"I am. The shape I've selected is a triangle."

Re: Some notes on the Wiki

[Bernd Schmidt]

Kurt Wall wrote:
> On Mon, Jul 11, 2005 at 04:27:58PM -0400, Daniel Berlin took 34 lines to write:
> 
>>On Mon, 2005-07-11 at 13:09 -0700, Robert Thorpe wrote:
>>
>>>Also, a web-browser is much slower than an info-browser, especially 
>>>when doing searchs.
>>
>>You must be close to the only user i've met who uses the info browser :)
> 
> 
> We haven't met, but I use the info browser. :-) I used to hate it but
> finally decided that since texi was the format that existed, I might
> as well suck it up and learn to use it.

I learned how to use it more than a decade ago when I was playing with 
gcc-2.3.3 on my Amiga :-)  Can't say I really really like it, but at 
least you can quickly search through the whole file, which isn't so easy 
with most browsers when you have multiple pages of HTML documentation.


Bernd

Re: Some notes on the Wiki

[Haren Visavadia]

> --- Diego Novillo wrote:
> > 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."
> > 
I am suggesting is if the content is on Wiki and not
in the manual and you can not get the copyright
assignment, there is nothing you can do about it
except live with it.
 
In fact, you would be lucky to have the content on
Wiki.
 


		
___________________________________________________________ 
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

[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

[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

[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

[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

[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

[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

[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

[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

[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

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

4.1 news item

[Daniel Berlin]

I was thinking we maybe should just copy the checked in project list
from the wiki, remove the duplicates (IE struct aliasing part I and II,
etc), and add a news item saying:

"GCC 4.1 stage 2 is now closed.  The following projects were
contributed: <project list>.  Thank you to all contributors, testers,
and everyone else for making stage 2 of gcc 4.1 a success"

Re: 4.1 news item

[Gerald Pfeifer]

On Fri, 8 Jul 2005, Daniel Berlin wrote:
> I was thinking we maybe should just copy the checked in project list
> from the wiki, remove the duplicates (IE struct aliasing part I and II,
> etc), and add a news item saying:
> 
> "GCC 4.1 stage 2 is now closed.  The following projects were
> contributed: <project list>.  Thank you to all contributors, testers,
> and everyone else for making stage 2 of gcc 4.1 a success"

I like this idea.  Want to go head? ;-)

Gerald

Re: 4.1 news item

[Daniel Berlin]

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

On Fri, 2005-07-08 at 23:39 +0200, Gerald Pfeifer wrote:
> On Fri, 8 Jul 2005, Daniel Berlin wrote:
> > I was thinking we maybe should just copy the checked in project list
> > from the wiki, remove the duplicates (IE struct aliasing part I and II,
> > etc), and add a news item saying:
> > 
> > "GCC 4.1 stage 2 is now closed.  The following projects were
> > contributed: <project list>.  Thank you to all contributors, testers,
> > and everyone else for making stage 2 of gcc 4.1 a success"
> 
> I like this idea.  Want to go head? ;-)
> 

Here's a patch.


> Gerald

[-- Attachment #2: index.diff --]
[-- Type: text/x-patch, Size: 1273 bytes --]

Index: index.html
===================================================================
RCS file: /cvs/gcc/wwwdocs/htdocs/index.html,v
retrieving revision 1.507
diff -u -p -r1.507 index.html
--- index.html	8 Jul 2005 06:50:42 -0000	1.507
+++ index.html	9 Jul 2005 01:01:49 -0000
@@ -84,6 +84,24 @@ mission statement</a>.</p>
 
 <dl>
 
+<dt><b>July 8, 2005</b></dt>
+<dd>
+GCC 4.1 stage 2 has been closed.  The following projects were contributed
+during stage 1 and stage 2: 
+New C Parser, LibAda GNATTools Branch, Code Sinking, Improved phi-opt, Structure Aliasing,
+Autovectorization Enhancements, Hot and Cold Partitioning, SMS Improvements
+Integrated Immediate Uses, Tree Optimizer Cleanups, Variable-argument Optimization,
+Redesigned VEC API, IPA Infrastructure, Altivec Rewrite Warning Message Control,
+New SSA Operand Cache Implementationa, Safe Builtins, Port of IBM Pro Police Stack Detector
+New DECL hierarchy.
+
+More information about these projects can be found at 
+<a href="http://gcc.gnu.org/wiki/GCC%204.1%20Projects">GCC 4.1 projects</a>
+
+Thank you to all contributors, testers, and everyone else for making stage 1 and stage 2 
+of GCC 4.1 a success.
+</dd>
+
 <dt><b>July 7, 2005</b></dt>
 <dd>
 <a href="gcc-4.0/">GCC 4.0.1</a> has been released.

Some notes on the Wiki (was: 4.1 news item)

[Gerald Pfeifer]

I noticed that the Wiki is getting more and more of a third place where
to find documentation in addition of gcc/doc and wwwdocs, and a parallel
universe at that, with quite some duplication and inconsistencies.

The Wiki is a nice idea for project lists, "Hot Bugzillas" lists and    
similar, but when I see pages like http://gcc.gnu.org/wiki/TestingGCC  
and http://gcc.gnu.org/wiki/HowToPrepareATestcase I really start 
wondering...

Michael, why did you take a wwdocs patch and copy it to the Wiki, 
basically forking our official documentation instead of helping to
improve it?  I'd appreciate a patch to merge improvements into our
documentation and help us avoid (and get rid) of this fork.

Gerald

Re: Some notes on the Wiki (was: 4.1 news item)

[Daniel Berlin]

On Sun, 2005-07-10 at 19:31 +0200, Gerald Pfeifer wrote:
> I noticed that the Wiki is getting more and more of a third place where
> to find documentation in addition of gcc/doc and wwwdocs, and a parallel
> universe at that, with quite some duplication and inconsistencies.

Have you not yet discovered that this is because people find the
documentation we have to be hard to work with, and submitting patches to
write in texinfo and whatnot to be a pain in the ass? 

Some (maybe most, hard to say) people don't like the organization,
topics, etc of our current documentation.  They find it useless to a
large degree to understand how GCC works.

IE i'm talking about developer facing docs, not user facing docs.

In fact, i had someone recently send me a *104 page PDF file* on how RTL
really works organized in a way that most developers would probably find
better.

But it has some spelling errors, was a little rough, etc.  I'm sure if
he submitted it, it would be nitpicked to death, told to convert to
texinfo, blah blah blah.

However, the fact that he found the current documentation *entirely
worthless* enough to write a 104 page document on how everything
actually worked should tell us maybe there is something wrong with our
documentation implementation, what we cover, and how we cover it.

It's not just "out of date" or whatever, people find it fundamentally
not covering the topics they seem to care about (which is how one
actually goes about doing useful things with our intermediate
representation, etc).


> The Wiki is a nice idea for project lists, "Hot Bugzillas" lists and    
> similar, but when I see pages like http://gcc.gnu.org/wiki/TestingGCC  
> and http://gcc.gnu.org/wiki/HowToPrepareATestcase I really start 
> wondering...

It should make you wonder why people felt it easier to do that than
write it in our "official docs".
Not "why do we have a wiki"?

I find it sad that you are complaining that people have created a
resource *they* find useful, instead of one that *we think they should
find useful*.

In reality, you should be taking the docs people found useful, like on
the wiki, and moving them into our developer facing documentation, etc,
instead of saying what seems to be "we shouldn't let people write about
this stuff on the wiki".


> 
> Michael, why did you take a wwdocs patch and copy it to the Wiki, 
> basically forking our official documentation instead of helping to
> improve it?  I'd appreciate a patch to merge improvements into our
> documentation and help us avoid (and get rid) of this fork.
> 
> Gerald

Re: Some notes on the Wiki (was: 4.1 news item)

[Gerald Pfeifer]

On Sun, 10 Jul 2005, Daniel Berlin wrote:
> I find it sad that you are complaining that people have created
> a resource *they* find useful, instead of one that *we think they
> should find useful*.

I'm sure you are aware of the fact that I am not responsible for 
gcc/doc/*.texi as such.  The main reason I'm listed as doc co-maintainer 
is so that I can help, as far as I can in terms of what I know, to get 
changes approved/applied and maintain install.texi and contrib.texi.

There are, it seems, at least two different issues here: one is that our 
manuals seem not to be satisfactory, especially for new developers. And 
one is the documentation of our policies, procedures, timelines, etc. on 
the web pages.

> In reality, you should be taking the docs people found useful, like on
> the wiki, and moving them into our developer facing documentation, etc,

As far as reviewing/applying/approving patches for wwwdocs is concerned, 
and implementing suggestions sent to the GCC lists, I'm committed to do 
that, and do so within one "online day" if possible in any way.

However, I just don't have the bandwidth to dig through Wiki and port 
things over, and it's not exactly an efficient nor motivating modus 
operandi either.

> instead of saying what seems to be "we shouldn't let people write
> about this stuff on the wiki".

Really, it depends on what "this stuff" is.  Duplicating official 
information from the regular web pages simply does not seem very
fruitful (and risks inconsistencies), and taking a wwwdocs patch
and putting it into the Wiki as Michael did as opposed to providing
feeback just seems counter productive.

Gerald

Re: Some notes on the Wiki

[R Hill]

Gerald Pfeifer wrote:
> As far as reviewing/applying/approving patches for wwwdocs is concerned, 
> and implementing suggestions sent to the GCC lists, I'm committed to do 
> that, and do so within one "online day" if possible in any way.

I'd like to applaud you for that effort.

> However, I just don't have the bandwidth to dig through Wiki and port 
> things over, and it's not exactly an efficient nor motivating modus 
> operandi either.

What about considering the wiki as documentation in progress?  Once the 
author(s) is satisfied with the work it could be submitted for review 
and inclusion in the official docs.  I think someone even mentioned 
hacking up a wikisyntax to texi converter a while back that could make 
this more streamlined.

>> instead of saying what seems to be "we shouldn't let people write
>> about this stuff on the wiki".
> 
> Really, it depends on what "this stuff" is.  Duplicating official 
> information from the regular web pages simply does not seem very
> fruitful (and risks inconsistencies), and taking a wwwdocs patch
> and putting it into the Wiki as Michael did as opposed to providing
> feeback just seems counter productive.

Providing feedback takes time and requires follow-up.  Hitting edit on a 
wiki page gets it done /now/ and out of the way.  It may not be the most 
logical or correct way to do things, but it's more comfortable and 
suited to how people write (docs or otherwise).  The easier it is for 
people to write documentation, the better quality documentation they'll 
write.

One other point:  it's far less nerve-wracking for someone new to the 
project to add something to the wiki than go through the review process. 
  Yes, that might make little sense to experienced contributors.  Yes, 
it's still true.  ;)


--de.

Re: Some notes on the Wiki

[Paolo Bonzini]

> In fact, i had someone recently send me a *104 page PDF file* on how RTL
> really works organized in a way that most developers would probably find
> better.

If the guy has copyright assignment on file, I can volunteer to convert 
this.  Is the PDF made from latex?  If so I have some scripts to aid.

Paolo

Re: Some notes on the Wiki (was: 4.1 news item)

[Andrew Pinski]

On Jul 10, 2005, at 1:31 PM, Gerald Pfeifer wrote:

> I noticed that the Wiki is getting more and more of a third place where
> to find documentation in addition of gcc/doc and wwwdocs, and a 
> parallel
> universe at that, with quite some duplication and inconsistencies.
>
> The Wiki is a nice idea for project lists, "Hot Bugzillas" lists and
> similar, but when I see pages like http://gcc.gnu.org/wiki/TestingGCC
> and http://gcc.gnu.org/wiki/HowToPrepareATestcase I really start
> wondering...


HowToPrepareATestcase was submitted but never reviewed which is why it
moved to the wiki. Giovanni Bajo pinged it at least twice.  And then
someone suggesting to put into the wiki so it would be some where and
still easy to find.

-- Pinski

Re: Some notes on the Wiki (was: 4.1 news item)

[Gerald Pfeifer]

On Sun, 10 Jul 2005, Andrew Pinski wrote:
> HowToPrepareATestcase was submitted but never reviewed which is why it
> moved to the wiki.

It was reviewed the very same day it was submitted:

  http://gcc.gnu.org/ml/gcc-patches/2004-06/msg00313.html
  http://gcc.gnu.org/ml/gcc-patches/2004-06/msg00321.html

Gerald

Re: Some notes on the Wiki

[Paolo Bonzini]

> > It was reviewed the very same day it was submitted:
> > 
> >   http://gcc.gnu.org/ml/gcc-patches/2004-06/msg00313.html
> >   http://gcc.gnu.org/ml/gcc-patches/2004-06/msg00321.html

where you said:

 > (and possibly to your tutorial as a separate page if
 > it still seems desirable to have it as a coherent tutorial).

The page ended up on the wiki rather than wwwdocs.

Paolo

Re: Some notes on the Wiki

[Gerald Pfeifer]

On Mon, 11 Jul 2005, Paolo Bonzini wrote:
>>> It was reviewed the very same day it was submitted:
>>>   http://gcc.gnu.org/ml/gcc-patches/2004-06/msg00313.html
>>>   http://gcc.gnu.org/ml/gcc-patches/2004-06/msg00321.html
> where you said:
>> (and possibly to your tutorial as a separate page if
>> it still seems desirable to have it as a coherent tutorial).
> The page ended up on the wiki rather than wwwdocs.

I don't necessarily disagree, but that was Joseph, not me.

Gerald

Re: Some notes on the Wiki

[Paolo Bonzini]

> > It was reviewed the very same day it was submitted:
> > 
> >   http://gcc.gnu.org/ml/gcc-patches/2004-06/msg00313.html
> >   http://gcc.gnu.org/ml/gcc-patches/2004-06/msg00321.html

where you said:

 > (and possibly to your tutorial as a separate page if
 > it still seems desirable to have it as a coherent tutorial).

The page ended up on the wiki rather than wwwdocs.

Paolo