Re: Documentation cleanup questions

[Jaroslav Hajek]

On Sun, Mar 15, 2009 at 10:06 PM, Rik <address@hidden> wrote:
> 3/15/09
>
> All,
>
> I want to help contribute back to Octave by reviewing and cleaning up
> the documentation.  To be most useful, however, I need a little guidance
> on the practical side.
>
> First, I really like bug trackers and I note that there is a
> quasi-unofficial shift towards using one:
> http://www.nabble.com/Using-the-Savannah-tracker-td22199236.html.  I am
> willing to be a guinea pig and file my patches against the Savannah
> tracker and see what happens.
>

OK. If you're talking about the bug tracker, then I'm all for using
it. But to spread the word we'd probably need to update some docs.
Also, you're welcome to move bug reports from the mailing list to
savannah, should you find the time for it.

I don't think we tried the Savannah patch manager yet, so I'm not sure
how usable it is.

>
> My first question is how fine-grained do you want the patches for
> documentation to be?  Ordinarily, I understand trying to have one patch
> do a single thing but if I modify the Texinfo for a single .m file and
> report that as a bug then the overhead will be enormous.  I estimate it
> would probably take 2 minutes to file a bug which means 1 hour to open
> bugs on 30 files.  Then there would be the time on your side to apply
> each patch and close the bug which would probably also average 2
> minutes.  My proposal is to do all the documentation changes for a
> directory, such as signal or sparse, and submit one bug and changeset
> for the entire directory.  Any guidance on how to set the slider between
> 1 patch/1 problem and 1 patch/all_found_problems?
>
> The second question is the format of the patches.  According to the web
> pages 'diff -c' is preferred but I have downloaded Mercurial and could
> easily use 'hg export' to create patches that might be easier to apply.
> Which format, context diff or Mercurial export, would you prefer?
>
> Cheers,
> Rik
>

Mercurial-created is certainly preferred. If anything else is written
anywhere, that information is outdated.
Concerning the patch/problem balance question, split according to your
best judgment. There's no problem having a patch update 50 files if
the changes are somehow related - for instance, they "update docs for
sparse functions".
What you shouldn't send is "Rik's cool improvements to Octave", but
you know that.

regards


-- 
RNDr. Jaroslav Hajek
computing expert & GNU Octave developer
Aeronautical Research and Test Institute (VZLU)
Prague, Czech Republic
url: www.highegg.matfyz.cz