Re: Contributing to Octave help function.

[Sergey Dudoladov]

On Thu, Jul 26, 2012 at 11:31 PM, Jordi Gutiérrez Hermoso <address@hidden> wrote:

On 26 July 2012 15:03, Sergey Dudoladov <address@hidden> wrote:
>
>
> On Mon, Jul 23, 2012 at 5:28 PM, Jordi Gutiérrez Hermoso
> <address@hidden> wrote:
>>
>> On 23 July 2012 05:09, Sergey Dudoladov <address@hidden>
>> wrote:
>> >   1) Is it OK to submit the patch if "hg import" rejects it ? Or
>> > should I try to eliminate any conflicts?
>>
>> The whole point of "hg export" is that this gives the patch metadata
>> that says *where* the patch is applied (i.e. at which hg revision).
>> Unless this is a private commit that is not in the Savannah
>> repository, it is then impossible for your patch to not apply (well,
>> impossible unless you found a way to exploit a hash collision in
>> sha1).
>>
>> >   2) Should I attach the patch to the bug report or submit it
>> > separately through a patch tracker ?
>>
>> Attached to the bug report is fine. I'll look at it now.
>

> 1) I've just added a potential patch to the bug report . Bug #36920  ;  file
> #26264

Yes, thanks, I just rebased it and applied it:

    http://hg.savannah.gnu.org/hgweb/octave/graph/ae42d5a67ed9

> 2) I didn't get the point about 'hg export' . Basically, I don't
> understand the sentence beginning "Unless this is a private .... "
> Please give me a clue where to find more information about it.

This is a good explanation of hg:

    http://hginit.com/

You can have patches in your local machine privately. You can make as
many commits as you want, and you don't have to show them to anyone.
When you do "hg export", hg records the parent of the commit you're
exporting. So when I apply your patch, hg knows which commit to apply
it to (i.e. which node in this graph):

    http://hg.savannah.gnu.org/hgweb/octave/graph/

Now, if you base your patch on a node that is not in the Savannah repo
above (i.e. a "private commit"), I will be unable to apply your patch
exactly where you based it, since I won't have this base. The base
will be in your local repo.

If you just do "diff" without export, then I don't know relative to
which hg revision to apply your patch. This is frequently not a
problem, but it's nice to know exactly *where* to apply your patch,
and "hg export" has this information.

>     e) As a last check, I applied this patch with "hg -import" to
>        another local repo. The patch got rejected.

Yes, this is what I just explained above. "hg import" may fail if you
don't use the information about *where* to apply the patch. Try

    hg import --exact

to apply the patch at the node (commit, changeset; all synonyms) that
is recorded in the patch.

If you prefer to avoid patches, you can also just host your repository
in a public server (e.g. bitbucket) and tell me which commit to pull.

I hope this wasn't confusing. Please ask again if it was.

HTH,
- Jordi G. H.

1) Thank you for the clear explanation, Jordi. Now I understand, or at least I hope so.

2) I am going to extend Octave "help" function a little bit by adding following options :

     Option                          Description

    --operators                 Lists operators. A synonym for "help ." 

    --keywords                 Lists keywords.

    --builtins                    Lists built-in functions

    --functions                 Lists other functions 

                                         

     Incomplete, but unique versions like "help --ope" (see discussion above) will also be supported.

   Questions:

   0) Is there any difference  in handling options "double-dash + word"  vs. "single dash + letter"?

   1) Do I have to provide a possibility to use several options simultaneously, e.g. as in  "help --keywords --operators" ? 

       I doubt someone will use it frequently, but what is Octave policy ?

   2) Which documentation should I alter ? Is a Texinfo comment in m-file enough ?  

   3) Any other comments before I start?