Re: Plotting with Octave 3.0

[Matthias Brennwald]

On 26.09.2008, at 11:18, David Bateman wrote:

> Matthias Brennwald wrote:
> > On 26.09.2008, at 09:27, David Bateman wrote:
> >
> > > Matthias Brennwald wrote:
> > > > On 26.09.2008, at 00:23, address@hidden wrote:
> > > >
> > > >
> > > > > | It seems that
> > > > > | html manual at www.octave.org is outdated (but I'm not Octave
> > > > > | developer, just user, so I don't know why is that).
> > > > >
> > > > > Because there are many things to do and not enough users who  
> > > > > are also
> > > > > helping out as developers?
> > > > >
> > > > > jwe
> > > >
> > > > True. But I have the impression it is not obvious for most  
> > > > useres how  to contribute code or improved documentation in a  
> > > > way that will be  useful and acceptable to the 'inner circle' of  
> > > > Octave developers.  Maybe a short document 'Contributing to  
> > > > Octave for dummies' would be  useful. Or, if such a thing exists  
> > > > already, moving this to a  prominent place would be in order.
> > > >
> > > > Thinking of it, I might be open to contribute to the  
> > > > documentation a  bit. I guess the plotting stuff is one area  
> > > > that really needs  improvement. But how do I go about this?
> > >
> > > Such a document was recently added to the manual so I suppose it  
> > > will end up on the website eventually. For now the raw text is at
> > >
> > > http://velveeta.che.wisc.edu/cgi-bin/hgwebdir.cgi/octave/file/ 
> > > a8fb37ae61b8/doc/interpreter/contrib.txi
> > >
> > > D.
> >
> > Thanks, this is very useful!
> >
> > As far as I can tell, though, there is hardly any information on  
> > how to work on the manual itself. Would it make sense to include  
> > this information, too?
>
> Well the manual itself is a set of files like any other in the HG  
> repository, so that same notes apply. Look in the the doc/ 
> interpreter/*.txi files in the repository.

Aha, ok. This is of course true (and obvious, once you told me), but  
a quick note in the document wouldn't hurt (for dummies like me).

> > Also, according to the document you mentioned, people are expected  
> > to know diff, texinfo, and mercurial. I am sure that most Octave  
> > users who would agree to submit their stuff are not used to  
> > working with these tools, so they won't submit their work. Is  
> > there a way to get around this? If so, this should be explained in  
> > the above document, too.
> diff you don't really need to understand.

The document says to use diff if Mercurial is not an option. But it  
is needed to create a patch

> If you are modifying the manual then yes you do need some basic  
> understanding of texinfo, and the conventions that are used in  
> Octave for the use of texinfo. Some of that is explained in
>
> http://www.gnu.org/software/octave/doc/interpreter/Documentation- 
> Tips.html#Documentation-Tips

Ok.

> As for mercurial, you have to understand the concepts of an SCM  
> system in general and then just a few basic commands
>
> ## Only need to do the clone once
> hg clone http://www.octave.org/hg/octave
>
> cd octave/doc/interpreter
> <edit doc files>
> cd ..
> <edit Changelog>
> cd ..
> hg commit -u "A. User <address@hidden>" -m "Modified foobar  
> documentation"
> hg export tip > ../MyChangeset
> ## Mail MyChangeset to the octave lists with an explanation
>
>
> ## If there are changes in the Octave repository
> hg pull
> hg merge tip
> hg commit -m "merge"
> ## Might need to resolve conflicts here mainly in the Changelogs
>
> and that is about all I ever use.

Ok.

However, apart from knowing how to work with diff, texinfo and  
mercurial, users als need to INSTALL the stuff and make it work. This  
is propably not an issue for Linux advocates with long-term  
experience in hacking around in their Linux boxes, but there are  
other, "lesser" OSes (and users) which don't have diff, texinfo or  
mercurial installed by default and installing is not always  
straightforward.

While I for myself think that I _might_ be able to manage all this  
(because I somehow like to poke around with this stuff), I am sure  
that all my colleagues working with Octave wouldn't want to waste  
their time with messing around all this, even if they'd like to  
contribute to Octave. So, all in all, I still think contributing to  
Octave should be easier in order to convince more users to contribute  
their work.

Cheers
Matthias