> Documentation of core and library classs is written in the source code
> (be it C or Ruby). Thus to contribute, you want to avail yourself of
> (anonymous) CVS access (it's easy). Then you edit files, create a
> patch, and get it committed. That last step has been the problem in
> the past; mea culpa. Suggested process: email the patch to me and/or
> James Gray (sorry, James!). Bug me mercilessly if nothing's being
> done.
BTW, what is the copyright on submitted docs, and is it made clear to
those submitting documentation?
I have no idea what the copyright situation is. Of the few people who
have submitted documentation, none have raised the question of
copyright.
Is there a reason to believe the documentation is treated differently
from the source code of which it's part? If the documentation is "Ruby
Licence", which I expect it is, what implication does that have for
copyright?
Is there a case for having a $Doc: Name $ in the header ?
Perhaps also a standard way to add contributors names to doc updates
which doesn't wipe out the original documentor's name (as seems to
happen with $Author: Name $ in many patched core files).
The main reason for asking is that, if anyone is going to spend a deal
of time and effort on documentation, recognition should be recorded.
(I hope that's only obvious.)
It would give us somewhere to direct our appreciation, spiritually
(or, perhaps, e-mail-ially).
$Doc: Dave Thomas; gs; jeg; kj $ - which magically expands to HTML
links for each member on ruby-doc-squad-wiki.org might be possible
(later?).
Documentation of core and library classs is written in the source code
(be it C or Ruby). Thus to contribute, you want to avail yourself of
(anonymous) CVS access (it's easy). Then you edit files, create a
patch, and get it committed. That last step has been the problem in
the past; mea culpa. Suggested process: email the patch to me and/or
James Gray (sorry, James!). Bug me mercilessly if nothing's being
done.
BTW, what is the copyright on submitted docs, and is it made clear to
those submitting documentation?
I have no idea what the copyright situation is. Of the few people who
have submitted documentation, none have raised the question of
copyright.
Is there a reason to believe the documentation is treated differently
from the source code of which it's part? If the documentation is "Ruby
Licence", which I expect it is, what implication does that have for
copyright?
Could someone sell a book that included the text from the std-lib docs? Would the book have to be released under Ruby's license (whatever that means)?
Is there a case for having a $Doc: Name $ in the header ?
What would that do?
Perhaps also a standard way to add contributors names to doc updates
which doesn't wipe out the original documentor's name (as seems to
happen with $Author: Name $ in many patched core files).
But author and documenter are often different people. Recording the
credits in plain text (as above) ensures they are not lost as CVS tags
come and go.
$Doc: Dave Thomas; gs; jeg; kj $ - which magically expands to HTML
links for each member on ruby-doc-squad-wiki.org might be possible
(later?).
Are you suggesting that every person who cvs commits a file is
recorded?
> Is there a reason to believe the documentation is treated differently
> from the source code of which it's part? If the documentation is "Ruby
> Licence", which I expect it is, what implication does that have for
> copyright?
Could someone sell a book that included the text from the std-lib docs?
Would the book have to be released under Ruby's license (whatever that
means)?
Gavin Sinclair wrote:
> James Britt wrote:
>
>>>Documentation of core and library classs is written in the source code
>>>(be it C or Ruby). Thus to contribute, you want to avail yourself of
>>>(anonymous) CVS access (it's easy). Then you edit files, create a
>>>patch, and get it committed. That last step has been the problem in
>>>the past; mea culpa. Suggested process: email the patch to me and/or
>>>James Gray (sorry, James!). Bug me mercilessly if nothing's being
>>>done.
>>
>>BTW, what is the copyright on submitted docs, and is it made clear to
>>those submitting documentation?
>
>
> I have no idea what the copyright situation is. Of the few people who
> have submitted documentation, none have raised the question of
> copyright.
>
> Is there a reason to believe the documentation is treated differently
> from the source code of which it's part? If the documentation is "Ruby
> Licence", which I expect it is, what implication does that have for
> copyright?
>
Could someone sell a book that included the text from the std-lib docs?
Would the book have to be released under Ruby's license (whatever that
means)?
The Pickaxe pp. 653-759
brian
···
On 20/10/05, James Britt <james_b@neurogami.com> wrote:
daz wrote:
>
>
> Is there a case for having a $Doc: Name $ in the header ?
What would that do?
Probably nothing but harm
It's a searchable string, isn't it?
Documentation is part of authorship, isn't it?
> Perhaps also a standard way to add contributors names to doc updates
> which doesn't wipe out the original documentor's name (as seems to
> happen with $Author: Name $ in many patched core files).
But author and documenter are often different people.
Hence the separation into $Doc: Name $
Documentation by Yukihiro Matsumoto and Gavin Sinclair.
[...]
Recording the credits in plain text (as above) ensures they are
not lost as CVS tags come and go.
Nothing wrong with that unless someone wants to parse it.
I assume that's the purpose of the $ $ delimeters in header fields.
> $Doc: Dave Thomas; gs; jeg; kj $ - which magically expands to HTML
> links for each member on ruby-doc-squad-wiki.org might be possible
> (later?).
Are you suggesting that every person who cvs commits a file is
recorded?
Not commits; - significantly contributes to documentation.
Yeah - whatever could I have been thinking?
On 20/10/05, James Britt <james_b@neurogami.com> wrote:
Gavin Sinclair wrote:
James Britt wrote:
Documentation of core and library classs is written in the source code
(be it C or Ruby). Thus to contribute, you want to avail yourself of
(anonymous) CVS access (it's easy). Then you edit files, create a
patch, and get it committed. That last step has been the problem in
the past; mea culpa. Suggested process: email the patch to me and/or
James Gray (sorry, James!). Bug me mercilessly if nothing's being
done.
BTW, what is the copyright on submitted docs, and is it made clear to
those submitting documentation?
I have no idea what the copyright situation is. Of the few people who
have submitted documentation, none have raised the question of
copyright.
Is there a reason to believe the documentation is treated differently
from the source code of which it's part? If the documentation is "Ruby
Licence", which I expect it is, what implication does that have for
copyright?
Could someone sell a book that included the text from the std-lib docs?
Would the book have to be released under Ruby's license (whatever that
means)?
The Pickaxe pp. 653-759
They do not appear to be part of the Ruby source distro.
For example, look at the rdoc for the rss library in 1.8.3. Then look at page 728 of pickaxe 2nd Ed.
> Documentation by Yukihiro Matsumoto and Gavin Sinclair.
> [...]
> Recording the credits in plain text (as above) ensures they are
> not lost as CVS tags come and go.
>
Nothing wrong with that unless someone wants to parse it.
I assume that's the purpose of the $ $ delimeters in header fields.
The purpose of those delimiters is so CVS treats them specially. The
content between the delimiters is created by CVS.
I.e. you put $Author$ in the source code, and CVS later expands that to
$Author: whoever$. To the best of my knowledge, CVS doesn't recognise
$Doc$, and you can't make it do so.
