newbie hacker question: how to add eval-to-texinfo?

newbie hacker question: how to add eval-to-texinfo?

[jemarch]

Hi,

If accepted, that will be my first patch to emacs. So i want to be sure
i write the patch in a right way.

I want to add a function called 'eval-to-texi' to emacs (i already
signed papers for that).

There are my questions:

- I suppose texinfo.el is the right way to add it. ¿It is right?.

- All functions in texinfo.el start with a 'texinfo-' prefix. May i to
  set that prefix to 'eval-to-texi' naming it 'texinfo-eval-to-texi'?

- May i to include an autoload for 'eval-to-texi'?

- To make the patch in unidiff format, would be right to generate it
  using 'cvs diff texinfo.el' on a fresh emacs cvs checkout? Or from
  the root directory: 'cvs diff listp/textmodes/texinfo.el'
 
- May i to add an entry to lisp/ChangeLog and send a patch for it too?


I think i can guess reasonable answers to that questions. But i want to
be completely sure.

Many thanks!

-- 
José E. Marchesi 

<jemarch@gnu.org>         http://www.gnu.org     GNU No es Unix!
<jemarch@es.gnu.org>      http://es.gnu.org      GNU España

.---------------.
|    .-[]--.    |
|   [] `>[]-|   |  BEE GNU/Hurd            http://bee.es.gnu.org
|    `-.[]<-'   |               
._______________.    

Re: newbie hacker question: how to add eval-to-texinfo?

[Stefan Monnier]

> I want to add a function called 'eval-to-texi' to emacs (i already
> signed papers for that).

The name does not make it very clear to me what it does.  Could you explain?

> - I suppose texinfo.el is the right way to add it. ¿It is right?.

Depends on the patch.  But it's a very minor issue.  Most patches are not
applied as is but are first sent back for a few minor changes: just send
the patch and we'll tell you what needs to be changed, if anything.

> - All functions in texinfo.el start with a 'texinfo-' prefix. May i to
>   set that prefix to 'eval-to-texi' naming it 'texinfo-eval-to-texi'?

Again, depends on the patch.

> - May i to include an autoload for 'eval-to-texi'?

I don't see why not.

> - To make the patch in unidiff format, would be right to generate it
>   using 'cvs diff texinfo.el' on a fresh emacs cvs checkout? Or from
>   the root directory: 'cvs diff lisp/textmodes/texinfo.el'

Same difference.
 
> - May i to add an entry to lisp/ChangeLog and send a patch for it too?

Better to send the ChangeLog entry separately, but in a patch is
also acceptable.  In most cases the patch is wrong (because the date
needs to be changed, the file has changed in the mean time, etc..)
so it has to be inserted by hand anyway.


        Stefan

Re: newbie hacker question: how to add eval-to-texinfo?

[jemarch]

    > I want to add a function called 'eval-to-texi' to emacs (i already
    > signed papers for that).
    
    The name does not make it very clear to me what it does.  Could you explain?

Oh, sorry. 

(defun eval-to-texi (form &optional tostring)
  "Evaluates FORM, dumping a @lisp texinfo environment with the
action.

If TOSTRING is t, then the @lisp environment is returned into a string,
rather than being inserted into the buffer."

  ...)

Examples:

@lisp
(car '(a b c))
      @result{} a
@end lisp

@lisp
(car (a b c))
      @error{} Symbol's function definition is void: a
@end lisp


    
    > - I suppose texinfo.el is the right way to add it. ¿It is right?.
    
    Depends on the patch.  But it's a very minor issue.  Most patches are not
    applied as is but are first sent back for a few minor changes: just send
    the patch and we'll tell you what needs to be changed, if anything.
    
    > - All functions in texinfo.el start with a 'texinfo-' prefix. May i to
    >   set that prefix to 'eval-to-texi' naming it 'texinfo-eval-to-texi'?
    
    Again, depends on the patch.

Ok.
    
    > - May i to include an autoload for 'eval-to-texi'?
    
    I don't see why not.
    
    > - To make the patch in unidiff format, would be right to generate it
    >   using 'cvs diff texinfo.el' on a fresh emacs cvs checkout? Or from
    >   the root directory: 'cvs diff lisp/textmodes/texinfo.el'
    
    Same difference.
     
    > - May i to add an entry to lisp/ChangeLog and send a patch for it too?
    
    Better to send the ChangeLog entry separately, but in a patch is
    also acceptable.  In most cases the patch is wrong (because the date
    needs to be changed, the file has changed in the mean time, etc..)
    so it has to be inserted by hand anyway.
    
    
Ok. Many thanks.

-- 
José E. Marchesi 

<jemarch@gnu.org>         http://www.gnu.org     GNU No es Unix!
<jemarch@es.gnu.org>      http://es.gnu.org      GNU España

.---------------.
|    .-[]--.    |
|   [] `>[]-|   |  BEE GNU/Hurd            http://bee.es.gnu.org
|    `-.[]<-'   |               
._______________.    

Re: newbie hacker question: how to add eval-to-texinfo?

[Richard Stallman]

    > - May i to include an autoload for 'eval-to-texi'?

    I don't see why not.

It would seem to me that you would normally want to visit a Texinfo
file before using this command.  Isn't that so?

If so, I think there is no use for making it autoload.  However, there
is no harm in making it autoload if that turns out to be useful.