4.1 news item

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

[Mark Mitchell]

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? ;-)

I was going to wait until midnight to officially announce Stage 3, but, 
heck, let's just consider it pre-announced for 6.75 hours from now, and 
go ahead and update the web site.

Thanks!

-- 
Mark Mitchell
CodeSourcery, LLC
mark@codesourcery.com
(916) 791-8304

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.

Re: 4.1 news item

[Gerald Pfeifer]

On Fri, 8 Jul 2005, Daniel Berlin wrote:
> Here's a patch.

Thanks.

There are a couple of commas between items missing (usually when
there is a line break) and some of the lines are too long (as with
GCC sources we generally prefer lines no longer than ~77 characters).

Is the new stack checking infrastructure really a port of IBM Pro
Police, or a reimplementation by RTH and Jakub?

Gerald

Re: 4.1 news item

[Steven Bosscher]

On Sunday 10 July 2005 00:16, Gerald Pfeifer wrote:
> On Fri, 8 Jul 2005, Daniel Berlin wrote:
> > Here's a patch.
>
> Thanks.
>
> There are a couple of commas between items missing (usually when
> there is a line break) and some of the lines are too long (as with
> GCC sources we generally prefer lines no longer than ~77 characters).
>
> Is the new stack checking infrastructure really a port of IBM Pro
> Police, or a reimplementation by RTH and Jakub?

RTH said (http://gcc.gnu.org/ml/gcc-patches/2005-05/msg01193.html):

//
The following is a functional re-implementation of the IBM stack
smashing protection patch described here:

  http://www.research.ibm.com/trl/projects/security/ssp/

This version is *much* less intrusive than the IBM version:
//

Looks like a re-implementation to me, then! ;-)

Gr.
Steven

Re: 4.1 news item

[Daniel Berlin]

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

On Sun, 2005-07-10 at 00:16 +0200, Gerald Pfeifer wrote:
> On Fri, 8 Jul 2005, Daniel Berlin wrote:
> > Here's a patch.
> 
> Thanks.
> 
> There are a couple of commas between items missing (usually when
> there is a line break)
fixed.

>  and some of the lines are too long (as with
> GCC sources we generally prefer lines no longer than ~77 characters).

Fixed.

> 
> Is the new stack checking infrastructure really a port of IBM Pro
> Police, or a reimplementation by RTH and Jakub?

Reimplementation, but that was the item listed in the wiki.
I'll change both.

How about now?

> 
> Gerald

[-- Attachment #2: index.diff --]
[-- Type: text/x-patch, Size: 1293 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	17 Jul 2005 01:33:55 -0000
@@ -84,6 +84,25 @@ 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 Implementation, 
+Safe Builtins, Reimplementation 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.

Re: 4.1 news item

[Gerald Pfeifer]

On Sat, 16 Jul 2005, Daniel Berlin wrote:
> How about now?

Thanks for the update, Dan!

I saw that I had forgot to preapprove this in my previous message, so I 
went ahead an installed the patch right away (after updating the date and 
removing the "Thanks" part which we haven't doing historically).

Gerald

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)

[Daniel Berlin]

Sorry for the tone, i've had a frustrating day for other reasons :)

However, my real point still stands:

1. Every developer i've talked to who wants to work on gcc finds our
current docs not useful, both the wwwdocs and the texinfo ones.  Not
because they are out of date, but because they don't give them
information on what they really want to know.
2. If they find the wiki more useful to write down interesting things
they've discovered, how to go about things, or whatever, let them, and
just export the docs from the wiki.  This is simple enough (the wiki
docs are valid xhtml transitional, except for some of the output of
plugins.  But the regular pages are)
3. We should seriously consider writing and maintaining different guides
and references than the ones we have.
I'm happy to go talk to the people who feel this way, and find out what
it is exactly that they want, though i'm pretty sure it's something like

A. Tree language reference guide (ie, semantics, etc)
B. RTL language reference guide (ie, semantics) written in a simple
format like:

RTL Instructions and how they are linked
RTL modes and what they represent.

Then
For each RTL code:

CODE - what it is used for and represents
examples of how operations are represented using CODE
valid flags for CODE
valid macros for CODE

instead of the current:

"here's a bunch of things about rtl.
here's a bunch of things about rtl flags.
Here's a bunch of things about rtl macros.
Here's a small bunch of things about rtl operations.
here's a bunch of things about rtl modes
Here's some more stuff about insns"

C. How to write a basic RTL pass
D. How to write a basic tree-ssa pass
E. Reference guides for analysis providers in tree-ssa (IE what we
provide and how to make use of provided alias info, data dependence
info, immediate uses, etc)
F. Reference guide for analysis providers in RTL.


On Sun, 2005-07-10 at 13:53 -0400, Daniel Berlin wrote:
> 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)

[Gabriel Dos Reis]

Daniel Berlin <dberlin@dberlin.org> writes:

| Sorry for the tone, i've had a frustrating day for other reasons :)
| 
| However, my real point still stands:
| 
| 1. Every developer i've talked to who wants to work on gcc finds our
| current docs not useful, both the wwwdocs and the texinfo ones.  Not
| because they are out of date, but because they don't give them
| information on what they really want to know.

Then, let see what information they want and how they can be put there.

[...]

| 3. We should seriously consider writing and maintaining different guides
| and references than the ones we have.
| I'm happy to go talk to the people who feel this way, and find out what
| it is exactly that they want, though i'm pretty sure it's something like
| 
| A. Tree language reference guide (ie, semantics, etc)
| B. RTL language reference guide (ie, semantics) written in a simple
| format like:
| 
| RTL Instructions and how they are linked
| RTL modes and what they represent.
| 
| Then
| For each RTL code:
| 
| CODE - what it is used for and represents
| examples of how operations are represented using CODE
| valid flags for CODE
| valid macros for CODE
| 
| instead of the current:
| 
| "here's a bunch of things about rtl.
| here's a bunch of things about rtl flags.
| Here's a bunch of things about rtl macros.
| Here's a small bunch of things about rtl operations.
| here's a bunch of things about rtl modes
| Here's some more stuff about insns"
| 
| C. How to write a basic RTL pass
| D. How to write a basic tree-ssa pass
| E. Reference guides for analysis providers in tree-ssa (IE what we
| provide and how to make use of provided alias info, data dependence
| info, immediate uses, etc)
| F. Reference guide for analysis providers in RTL.

I see no reason why those should not be part of our main
documentation reposotroty along with or replacing our traditional
documentation.


It appears to me that you're relating unrelated effects and causes.

-- Gaby

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

[Daniel Berlin]

> It appears to me that you're relating unrelated effects and causes.

Not really.
People don't contribute to the current docs for the following main
reasons, AFAICT and have heard from people, *in order of number of
complaints i've heard from people*:

1. They don't want to send continual incomplete patches, they'd rather
update it in small bites on their own time schedule, without getting
nitpicked to death as often happens on doc patches (hence the reason you
see stuff done on wiki, where this is easily possible)

2. The current docs don't cover what they want to talk about.

3. They don't like texinfo, they don't want to edit it.

These are all related causes of the effect that our documentation and
the process behind it hasn't worked for as long as i've been hacking gcc
(5 or 6 years now).  Everyone seems to pretend "oh, it's just the damn
lazy developers fault, they don't update docs".  Have you ever
considered there may be reasons for this, other than lazy developers,
like the above?

I'm not sure why we, as someone else put it, ignore the implicit
feedback from developers about our docs, and the process, and just try
to force everyone to do what we want, when they just end up not doing it
or doing the bare minimum as a result. 

I'm not saying a complete free for all is the best process here, but
it's pretty clear at least to me that what we do now in terms of
developer docs, and how we do it, plain old doesn't work well. So maybe
it's time to try something else, and work *with* people who want to be
writing docs, instead of just trying to hammer people into following the
current process?

--Dan

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

[Gabriel Dos Reis]

Daniel Berlin <dberlin@dberlin.org> writes:

[...]

| These are all related causes of the effect that our documentation and
| the process behind it hasn't worked for as long as i've been hacking gcc
| (5 or 6 years now).  Everyone seems to pretend "oh, it's just the damn
| lazy developers fault, they don't update docs".  Have you ever
| considered there may be reasons for this, other than lazy developers,
| like the above?

That is a question I would have loved answered did I endorse its
predicate. 

-- Gaby

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

[David Edelsohn]

>>>>> Gabriel Dos Reis writes:

Gaby> That is a question I would have loved answered did I endorse its
Gaby> predicate. 

	Then by all means continue to use the existing docs in your world
and let others create more useful documentation for developers in our
world, which appears to be on a different plane of existence.

David

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

[Gabriel Dos Reis]

David Edelsohn <dje@watson.ibm.com> writes:

| >>>>> Gabriel Dos Reis writes:
| 
| Gaby> That is a question I would have loved answered did I endorse its
| Gaby> predicate. 
| 
| 	Then by all means continue to use the existing docs in your world
| and let others create more useful documentation for developers in our
| world, which appears to be on a different plane of existence.

?

-- Gaby

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

[Gerald Pfeifer]

On Sun, 10 Jul 2005, Daniel Berlin wrote:
> 1. Every developer i've talked to who wants to work on gcc finds our
> current docs not useful, both the wwwdocs and the texinfo ones.  Not
> because they are out of date, but because they don't give them
> information on what they really want to know.

I'd like to know what's missing on wwwdocs and try to fix that.

> 3. We should seriously consider writing and maintaining different guides
> and references than the ones we have.

Nobody won't object to that, I guess.

Gerald

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

[Gabriel Dos Reis]

Gerald Pfeifer <gerald@pfeifer.com> writes:

| > 3. We should seriously consider writing and maintaining different guides
| > and references than the ones we have.
| 
| Nobody won't object to that, I guess.

Indeed.

-- Gaby

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

[Gabriel Dos Reis]

Daniel Berlin <dberlin@dberlin.org> writes:

| 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? 


I disagree with the notion that because our current documentation is
imperfect, we shall move the corrected one to the Wiki page.  I think
we've gotten too far in putting valuables bits of GCC outside our main
documentation repository.

[...]

| 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 tells us that the documentation is inaccurate; it does not tell us
that we ought to move it to the 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*.

The issue is not complaining that people do useful things.  Rather,
whether the updated and and more useful documentation of GCC shall be
moved outside GCC main docuementation sources.  


-- 
                                                       Gabriel Dos Reis 
                                           gdr@integrable-solutions.net

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

[Daniel Berlin]

On Sun, 2005-07-10 at 20:14 +0200, Gabriel Dos Reis wrote:
> Daniel Berlin <dberlin@dberlin.org> writes:
> 
> | 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? 
> 
> 
> I disagree with the notion that because our current documentation is
> imperfect, we shall move the corrected one to the Wiki page.  I think
> we've gotten too far in putting valuables bits of GCC outside our main
> documentation repository.

This happens because
1. People don't want to write texinfo, and continually submit patches to
update the docs little by little (remember, people work on docs the same
way they do on code.  Most of the time, what they have written is not
complete yet.  Which is fine for the wiki, but not for our cvs docs, it
seems), whereas this is trivial with the wiki
2. The docs people seem to want to write or use don't fit anywhere in
our current scheme.

> 
> [...]
> 
> | 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 tells us that the documentation is inaccurate; it does not tell us
> that we ought to move it to the Wiki. 
Sorry, i completely disagree that we should force people who want to
write docs to do it only on our terms, considering how many people like
writing docs and how they write them (little by little in incomplete
pieces)
If people find it easier to write on the wiki, let them.

> 
> [...]
> 
> | 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*.
> 
> The issue is not complaining that people do useful things.  Rather,
> whether the updated and and more useful documentation of GCC shall be
> moved outside GCC main docuementation sources.  
We should be taking what people do and moving it, not saying "you can't
write it where you want".

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

[Joseph S. Myers]

On Sun, 10 Jul 2005, Daniel Berlin wrote:

> This happens because
> 1. People don't want to write texinfo, and continually submit patches to
> update the docs little by little (remember, people work on docs the same
> way they do on code.  Most of the time, what they have written is not
> complete yet.  Which is fine for the wiki, but not for our cvs docs, it
> seems), whereas this is trivial with the wiki

Patches for the internals documentation don't need to be complete.  
c-tree.texi and sourcebuild.texi are both clearly marked as incomplete.

> 2. The docs people seem to want to write or use don't fit anywhere in
> our current scheme.

They can just stick a new chapter somewhere vaguely plausible in the 
internals manual - that's what's been done so far.  The structure of the 
internals manual may not be wonderfully coherent, but adding new chapters 
won't make it worse.

> We should be taking what people do and moving it, not saying "you can't
> write it where you want".

This does of course require identifying the authors of all significant 
parts and making sure they have assignments or disclaimers on file at the 
FSF.

-- 
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 (was: 4.1 news item)

[Gabriel Dos Reis]

Daniel Berlin <dberlin@dberlin.org> writes:

| On Sun, 2005-07-10 at 20:14 +0200, Gabriel Dos Reis wrote:
| > Daniel Berlin <dberlin@dberlin.org> writes:
| > 
| > | 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? 
| > 
| > 
| > I disagree with the notion that because our current documentation is
| > imperfect, we shall move the corrected one to the Wiki page.  I think
| > we've gotten too far in putting valuables bits of GCC outside our main
| > documentation repository.
| 
| This happens because
| 1. People don't want to write texinfo, and continually submit patches to
| update the docs little by little (remember, people work on docs the same
| way they do on code.  Most of the time, what they have written is not
| complete yet.  Which is fine for the wiki, but not for our cvs docs, it
| seems), whereas this is trivial with the wiki
| 2. The docs people seem to want to write or use don't fit anywhere in
| our current scheme.

Then, let's extend that scheme (no, I exclude Wiki :-))

-- Gaby

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

[Steven Bosscher]

On Sunday 10 July 2005 20:14, Gabriel Dos Reis wrote:
> The issue is not complaining that people do useful things.  Rather,
> whether the updated and and more useful documentation of GCC shall be
> moved outside GCC main docuementation sources.

This is just a matter of where a contributor wants to add it.  If you
think it should be moved else where, move it elsewhere.

Gr.
Steven

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 (was: 4.1 news item)

[Daniel Berlin]

On Sun, 2005-07-10 at 22:50 +0200, Gerald Pfeifer wrote:
> 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. 

Of course.

>  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.

Yup.

> 
> 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.

Yup.

> 
> > 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.

I understand, and you've been great about approving what is sent.
I don't mean to disrepect that 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.
I would submit them from the wiki if i felt people found more use for it
in wwwdocs.
Otherwise, why not just link from the approriate page to it in 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.

See Andrew's message.

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

[Gabriel Dos Reis]

Daniel Berlin <dberlin@dberlin.org> writes:

[...]

| > 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.
| I would submit them from the wiki if i felt people found more use for it
| in wwwdocs.
| Otherwise, why not just link from the approriate page to it in the wiki?

I would rather prefer we find a way to get the docs in sync and in
wwwdocs. 

-- Gaby

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 (was: 4.1 news item)

[Kaveh R. Ghazi]

 > 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.

So share it with the masses, put it in the wiki.

--
Kaveh R. Ghazi			ghazi@caip.rutgers.edu

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

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

[Giovanni Bajo]

Gerald Pfeifer <gerald@pfeifer.com> 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

Yes. And the review was very detailed, and suggested that I had to redone to
work almost from scratch, scattering the infos across a dozen of files in
both WWW and TeX format where they really belong (including Dejagnu's
documentation), *plus* I could also provide the existing page as a tutorial
with references.

I would like to thank you and Joseph Myers for the accurate and fast review.
The point is that it took me already long enough to prepare that patch, and
I never had time (nor will, let me admit) to go back and redo the work in a
different way.

What happened next is that I started providing the link to the gcc-patches
mail over IRC, and then in the list, and then in private mail. And people
were thanking me for it, because it was very helpful. So, I realized that,
while the improvements you suggested were legitimate and correct, that text
was already very useful *the way it is* *right now*. So, it was put in the
Wiki. And I know many people have read it and found it useful. If you want,
you can add a plea at the bottom of the Wiki page, summing the reviews and
asking volunteers to incorporate it into the documentation in the proper
places.

I already expressed my concerns about the way documentation patches work in
other threads. I myself am uninterested in contributing documentation
patches to TeX (and pretty discouraged about the WWW patches, even if I do
that regularly, as you well know). Instead, I contributed many things to the
Wiki. Given the way things like Wikipedia work out, I think we need to
either review our documentation system, or, if there is too much politics
going on with the FSF, accept the fact that the documentation *is* going to
be forked, and setup a workflow to contribute stuff back from the wiki to
the official documentation.

My personal position is that making documentation patches *blocked* by
review (as happens with code) is wrong. The worst thing it can happen is
that the documentation patch is wrong, and the doc maintainer can revert it
in literally seconds (using the Wiki; in minutes/hours using the TeX).
Nobody is going to be blocked by this; no bootstrap will be broken; no wrong
code will be generated. This ain't code. In many common cases, the
documentation will be useful effectively immediatly, and
typos/subtleties/formatting can be refined by others over time.
-- 
Giovanni Bajo

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

[Joseph S. Myers]

On Mon, 11 Jul 2005, Giovanni Bajo wrote:

> My personal position is that making documentation patches *blocked* by
> review (as happens with code) is wrong. The worst thing it can happen is
> that the documentation patch is wrong, and the doc maintainer can revert it
> in literally seconds (using the Wiki; in minutes/hours using the TeX).

It's not for the doc maintainer to know whether most doc patches are 
correct or not; it should be the maintainer of the relevant parts of the 
compiler who reviews them in general.

> Nobody is going to be blocked by this; no bootstrap will be broken; no wrong
> code will be generated. This ain't code. In many common cases, the

Wrong code will be generated when someone relies on subtly wrong 
information in the documentation.  It is a well-established failure mode 
even on the best wikis (i.e. Wikipedia) that someone inserts subtly wrong 
information because of not knowing better (or not knowing that there is 
controversy among experts about which of two versions is correct) and this 
does not get corrected soon if at all.  There may be *policies* of 
providing references to back up claims made, but (a) that can't work in 
the context of GCC and (b) I don't see Wikipedia edits routinely getting 
reverted simply for lack of substantiating evidence.  We're dealing with 
subtle matters where there may be no one expert on the subject, and where 
reversion may not in general be any better than applying the patch: where 
the proper response will involve discussion of the individual edit to 
clarify the basis for the claims made and whether things should be 
refined.

Perhaps the wiki could automatically send all changes to gcc-patches to 
assist in review?

-- 
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 (was: 4.1 news item)

[Giovanni Bajo]

Joseph S. Myers <joseph@codesourcery.com> wrote:

>> Nobody is going to be blocked by this; no bootstrap will be broken; no
>> wrong code will be generated. This ain't code. In many common cases, the
>
> Wrong code will be generated when someone relies on subtly wrong
> information in the documentation.  It is a well-established failure mode
> even on the best wikis (i.e. Wikipedia) that someone inserts subtly wrong
> information because of not knowing better (or not knowing that there is
> controversy among experts about which of two versions is correct) and this
> does not get corrected soon if at all.

That is right, but there are level of interests. The debate can be on some
small detail, while the big picture is still good enough for beginners or
intermediates. Having something which is possibly wrong on some subtle
details is still better than having nothing at all. As I said, I am a strong
sustainer of "commit now, refine later".

> (b) I don't see Wikipedia edits routinely getting
> reverted simply for lack of substantiating evidence.

Yeah, but I widely use it and it is still very useful. It may not be 1000%
correct in each word, so what? Are printed books any better? Or is there a
real only truth? We're entering philosphy here. What is certain is that
Wikipedia wouldn't be 1/1000th of that if there was a review process for
each patch being submitted.

> Perhaps the wiki could automatically send all changes to gcc-patches to
> assist in review?


I strongly support this (and was going to suggest this myself). I'd rather
it be another list though, say wiki-patches or doc-patches, because of the
amount of traffic that is going to be generated (think of all those small
typo fixes, or spam reverts).
-- 
Giovanni Bajo

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

[Gerald Pfeifer]

On Mon, 11 Jul 2005, Giovanni Bajo wrote:
>> Perhaps the wiki could automatically send all changes to gcc-patches to
>> assist in review?
> I strongly support this (and was going to suggest this myself). I'd rather
> it be another list though, say wiki-patches or doc-patches, because of the
> amount of traffic that is going to be generated (think of all those small
> typo fixes, or spam reverts).

Sounds like an interesting idea!

(For example, it might help those volunteering to integrate stuff from 
Wiki to the gcc/doc or wwwdocs documentation, modulo the open copyright
assignment question.)

Gerald

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

[Steven Bosscher]

On Monday 11 July 2005 23:34, Gerald Pfeifer wrote:
> On Mon, 11 Jul 2005, Giovanni Bajo wrote:
> >> Perhaps the wiki could automatically send all changes to gcc-patches to
> >> assist in review?
> >
> > I strongly support this (and was going to suggest this myself). I'd
> > rather it be another list though, say wiki-patches or doc-patches,
> > because of the amount of traffic that is going to be generated (think of
> > all those small typo fixes, or spam reverts).
>
> Sounds like an interesting idea!
>
> (For example, it might help those volunteering to integrate stuff from
> Wiki to the gcc/doc or wwwdocs documentation, modulo the open copyright
> assignment question.)

Another idea that was coined on IRC is to have reviewing and commit
after approval rules for the user manual, but to allow patches to the
internals manual in without review.  Is that something people are
willing to consider and discuss?

Gr.
Steven

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

[Joseph S. Myers]

On Mon, 11 Jul 2005, Steven Bosscher wrote:

> Another idea that was coined on IRC is to have reviewing and commit
> after approval rules for the user manual, but to allow patches to the
> internals manual in without review.  Is that something people are
> willing to consider and discuss?

Rather than getting rid of review for the internals manual altogether, I 
think we should appoint more maintainers who can commit without review and 
review other people's patches.

It's *already* the case that if you are the listed maintainer of part of 
the compiler you also maintain documentation related to that part and 
don't need review for such documentation.  Perhaps some parts of the 
compiler need more maintainers.  In addition, if someone makes good 
contributions to the documentation in a particular area they can be made a 
maintainer for that part of the documentation.

Note that a maintainer who isn't confident of a patch within an area they 
maintain can still ask for review if they wish.  Review isn't meant to get 
in the way of people who know what they are doing in an area and know 
enough to know when they need review.  It is meant to provide a check on 
work by people with insufficient expertise to tell when review is 
appropriate.

-- 
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 (was: 4.1 news item)

[Gerald Pfeifer]

On Mon, 11 Jul 2005, Steven Bosscher wrote:
> Another idea that was coined on IRC is to have reviewing and commit
> after approval rules for the user manual, but to allow patches to the
> internals manual in without review.  Is that something people are
> willing to consider and discuss?

I think this needs to be decided by the current maintainers in question 
(that is, those who generally make or review patches to the internals
manual), but I'd be fine with that.

On Mon, 11 Jul 2005, Joseph S. Myers wrote:
> Perhaps some parts of the compiler need more maintainers.  In addition, 
> if someone makes good contributions to the documentation in a particular 
> area they can be made a maintainer for that part of the documentation.

Absolutely, on both regards.

Gerald

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

[Joe Buck]

On Tue, Jul 12, 2005 at 12:07:01AM +0200, Gerald Pfeifer wrote:
> On Mon, 11 Jul 2005, Steven Bosscher wrote:
> > Another idea that was coined on IRC is to have reviewing and commit
> > after approval rules for the user manual, but to allow patches to the
> > internals manual in without review.  Is that something people are
> > willing to consider and discuss?
> 
> I think this needs to be decided by the current maintainers in question 
> (that is, those who generally make or review patches to the internals
> manual), but I'd be fine with that.

What if we had a clean way to flag reviewed and unreviewed text for the
internals manual?  This could be easier with a wiki; when first entered
the text might be (for example) red, and then it would change to black
when a reviewer approves it.  That way material can be added quickly by
developers and we can keep track of what has been checked or not checked.

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

[Daniel Berlin]

On Mon, 2005-07-11 at 15:21 -0700, Joe Buck wrote:
> On Tue, Jul 12, 2005 at 12:07:01AM +0200, Gerald Pfeifer wrote:
> > On Mon, 11 Jul 2005, Steven Bosscher wrote:
> > > Another idea that was coined on IRC is to have reviewing and commit
> > > after approval rules for the user manual, but to allow patches to the
> > > internals manual in without review.  Is that something people are
> > > willing to consider and discuss?
> > 
> > I think this needs to be decided by the current maintainers in question 
> > (that is, those who generally make or review patches to the internals
> > manual), but I'd be fine with that.
> 
> What if we had a clean way to flag reviewed and unreviewed text for the
> internals manual?  This could be easier with a wiki; when first entered
> the text might be (for example) red, and then it would change to black
> when a reviewer approves it.  That way material can be added quickly by
> developers and we can keep track of what has been checked or not checked.
> 
> 

This is probably possible, but may be easier with other wiki software,
but if that was the direction we wanted to take, i'm happy to convert
us.

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

[Gabriel Dos Reis]

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

| On Mon, 11 Jul 2005, Steven Bosscher wrote:
| 
| > Another idea that was coined on IRC is to have reviewing and commit
| > after approval rules for the user manual, but to allow patches to the
| > internals manual in without review.  Is that something people are
| > willing to consider and discuss?
| 
| Rather than getting rid of review for the internals manual altogether, I 
| think we should appoint more maintainers who can commit without review and 
| review other people's patches.

I 100% agree.  

-- Gaby

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

[Gabriel Dos Reis]

Steven Bosscher <stevenb@suse.de> writes:

| On Monday 11 July 2005 23:34, Gerald Pfeifer wrote:
| > On Mon, 11 Jul 2005, Giovanni Bajo wrote:
| > >> Perhaps the wiki could automatically send all changes to gcc-patches to
| > >> assist in review?
| > >
| > > I strongly support this (and was going to suggest this myself). I'd
| > > rather it be another list though, say wiki-patches or doc-patches,
| > > because of the amount of traffic that is going to be generated (think of
| > > all those small typo fixes, or spam reverts).
| >
| > Sounds like an interesting idea!
| >
| > (For example, it might help those volunteering to integrate stuff from
| > Wiki to the gcc/doc or wwwdocs documentation, modulo the open copyright
| > assignment question.)
| 
| Another idea that was coined on IRC is to have reviewing and commit
| after approval rules for the user manual, but to allow patches to the
| internals manual in without review.  Is that something people are
| willing to consider and discuss?

the idea that we don't review internal manual is worrysome.  Some
years ago, I based a work on doc/c-tree.texi (thanks Mark!).  But the
fact that it escaped continual revision as code gets added or improved
made it a dangerous documentation, because it led to writing codes
based on semantics that was no longer true.  Got bugs, but don't know
which side is not working prorperly.  Similarly, we don't really want
to let doc patches in without double-check.

-- Gaby

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

[Steven Bosscher]

On Tuesday 12 July 2005 00:06, Gabriel Dos Reis wrote:
> Steven Bosscher <stevenb@suse.de> writes:
> | Another idea that was coined on IRC is to have reviewing and commit
> | after approval rules for the user manual, but to allow patches to the
> | internals manual in without review.  Is that something people are
> | willing to consider and discuss?
>
> the idea that we don't review internal manual is worrysome.  Some
> years ago, I based a work on doc/c-tree.texi (thanks Mark!).  But the
> fact that it escaped continual revision as code gets added or improved
> made it a dangerous documentation, because it led to writing codes
> based on semantics that was no longer true.  Got bugs, but don't know
> which side is not working prorperly.  Similarly, we don't really want
> to let doc patches in without double-check.

Think about what you are saying: "Because almost nobody is working on
the internals manual, the documentation bit-rotted."

One way to get more people to work on the internals manual is by taking
away the barriers.

Gr.
Steven

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

[Gabriel Dos Reis]

Steven Bosscher <stevenb@suse.de> writes:

| On Tuesday 12 July 2005 00:06, Gabriel Dos Reis wrote:
| > Steven Bosscher <stevenb@suse.de> writes:
| > | Another idea that was coined on IRC is to have reviewing and commit
| > | after approval rules for the user manual, but to allow patches to the
| > | internals manual in without review.  Is that something people are
| > | willing to consider and discuss?
| >
| > the idea that we don't review internal manual is worrysome.  Some
| > years ago, I based a work on doc/c-tree.texi (thanks Mark!).  But the
| > fact that it escaped continual revision as code gets added or improved
| > made it a dangerous documentation, because it led to writing codes
| > based on semantics that was no longer true.  Got bugs, but don't know
| > which side is not working prorperly.  Similarly, we don't really want
| > to let doc patches in without double-check.
| 
| Think about what you are saying: "Because almost nobody is working on
| the internals manual, the documentation bit-rotted."

In fact, you just invented that and you're trying to credit me fort
it?  No, thanks.  Stick to what I wrote and if you think there is
something unclear, please ask.  But refrain from crediting me for
something I did not say.

-- Gaby

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

[Richard Kenner]

    This happens because
     1. People don't want to write texinfo,

People don't like to write comments either, but I don't think most people
would suggest we stop requiring comments.

The documentation style of the GNU project is texinfo and that choice
was made for sound reasons, which continue to be valid.

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

[Steven Bosscher]

On Sunday 10 July 2005 20:43, Richard Kenner wrote:
>     This happens because
>      1. People don't want to write texinfo,
>
> People don't like to write comments either, but I don't think most people
> would suggest we stop requiring comments.
>
> The documentation style of the GNU project is texinfo and that choice
> was made for sound reasons, which continue to be valid.

And people writing things on the Wiki have made a choice for equally
sound reasons.  Just to name two reasons:

1) they can do 1000 lines of documentation work on the Wiki now, as in
   right here right now; or go through months of patch nit-picking a 12
   line patch and work incrementally.
2) they don't have to write a copyright assignment and go through other
   barriers.

Personally I strongly prefer working on the wiki over working on the
GCC manual for internals stuff.

Gr.
Steven