doc strings

classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|

doc strings

John W. Eaton-6
Currently, each built-in function or variable has a doc string that is
written in a C string that is an argument to the DEFUN (or DEFVAR or
similar) macro.  The problem with this is that when writing the doc
string, we have to remember to add extra "\" escapes to make the
compiler happy.

I copied this method of defining the doc strings from Emacs.  It's
always annoyed me that you have to be careful to get the escapes
right, but I wasn't sure of a better solution.  Now I see that Emacs
has switched to using something like this:

  DEFUN ("file-name-nondirectory", Ffile_name_nondirectory,
         Sfile_name_nondirectory, 1, 1, 0,
         doc: /* Return file name FILENAME sans its directory.
  For example, in a Unix-syntax file name,
  this is everything after the last slash,
  or the entire name if it contains no slash.  */)
  ...

apparently with a way to extract these comments and put them in an
external file so that they can be found by Emacs at run time
(actually, I think it has been doing that for a long time).

It seems to me that doing something similar would be useful for
Octave.  Mostly it would make it easier to write the doc strings, but
it would also make the binary a little bit smaller if the doc strings
were stored in separate files.  We could have mkoctfile do something
useful like strip the comments out and put them in a corresponding
.hlp file (or similar).  I think Matlab puts the doc strings for
built-in functions in .m files, but we'd need to be careful about
having mkoctfile do that (it would need to avoid writing over the .m
file of the same name that you are working on converting to C++).

Comments?

jwe


Reply | Threaded
Open this post in threaded view
|

Re: doc strings

JD Cole-2
Has internationalization ever been considered, using GNU gettext, or the
like? Would this be a good time to consider it? I suppose the main
problem which a solution such as gettext would cause is separation of
the documentation strings from the source files.....well, just a thought.

-JD

John W. Eaton wrote:

>Currently, each built-in function or variable has a doc string that is
>written in a C string that is an argument to the DEFUN (or DEFVAR or
>similar) macro.  The problem with this is that when writing the doc
>string, we have to remember to add extra "\" escapes to make the
>compiler happy.
>
>I copied this method of defining the doc strings from Emacs.  It's
>always annoyed me that you have to be careful to get the escapes
>right, but I wasn't sure of a better solution.  Now I see that Emacs
>has switched to using something like this:
>
>  DEFUN ("file-name-nondirectory", Ffile_name_nondirectory,
> Sfile_name_nondirectory, 1, 1, 0,
> doc: /* Return file name FILENAME sans its directory.
>  For example, in a Unix-syntax file name,
>  this is everything after the last slash,
>  or the entire name if it contains no slash.  */)
>  ...
>
>apparently with a way to extract these comments and put them in an
>external file so that they can be found by Emacs at run time
>(actually, I think it has been doing that for a long time).
>
>It seems to me that doing something similar would be useful for
>Octave.  Mostly it would make it easier to write the doc strings, but
>it would also make the binary a little bit smaller if the doc strings
>were stored in separate files.  We could have mkoctfile do something
>useful like strip the comments out and put them in a corresponding
>.hlp file (or similar).  I think Matlab puts the doc strings for
>built-in functions in .m files, but we'd need to be careful about
>having mkoctfile do that (it would need to avoid writing over the .m
>file of the same name that you are working on converting to C++).
>
>Comments?
>
>jwe
>
>
>  
>




Reply | Threaded
Open this post in threaded view
|

Re: doc strings

Paul Kienzle
In reply to this post by John W. Eaton-6
John W. Eaton wrote:

>It seems to me that doing something similar would be useful for
>Octave.  Mostly it would make it easier to write the doc strings, but
>it would also make the binary a little bit smaller if the doc strings
>were stored in separate files.  We could have mkoctfile do something
>useful like strip the comments out and put them in a corresponding
>.hlp file (or similar).  I think Matlab puts the doc strings for
>built-in functions in .m files, but we'd need to be careful about
>having mkoctfile do that (it would need to avoid writing over the .m
>file of the same name that you are working on converting to C++).
>
>Comments?
>
I've often considered suggesting something like that.  One
motivation is to separate the documentation from the
function so that interested parties can provide docs in their
own language.

However, there's nothing stopping that from happening
now other than a few lines of code in help.cc to first
search for help in a locale dependent path and interested parties.
And putting in the escapes is not that difficult.

So either way is fine for me, with the caveat that I hate
forcing an upgrade to the latest version of octave to use
octave-forge, and this would be another of those
"need at least octave 2.1.xxx" changes.  I've started
noting the required octave version on the download
page, and so long as I keep the older releases around I
suppose that isn't that big a problem either.

Paul Kienzle
[hidden email]



Reply | Threaded
Open this post in threaded view
|

Re: doc strings

Paul Kienzle
In reply to this post by JD Cole-2
J.D. Cole wrote:

> Has internationalization ever been considered, using GNU gettext, or
> the like? Would this be a good time to consider it? I suppose the main
> problem which a solution such as gettext would cause is separation of
> the documentation strings from the source files.....well, just a thought.

gettext is more for errors, warnings and the like.  In many
cases, the error message is not associated with any particular
function (e.g., errors from liboctave).

There are some tricky points about using gettext.

One is that octave is not unicode aware.  This limits
the usefulness of  i18n to European languages.

Another is that word order is not the same in all
languages, so if you are building up your strings piece
by piece (as cout demands) gettext may not give a very
good result.  Fortunately, most messages are handled
through error() or warning() which use the more convenient
printf formatting.

Don't forget to wrap the messages inside m-files as well.
Normally I would suggest _('hello') but _ is not an allowed
function name in matlab.  Maybe i18n('hello')?

There are lots of little issues, such as code that appends an
's' to a string only if it is needed.  I don't know that octave
has a lot of these.

Also, there is the question of whether the keywords of
the language can be translated.  Other projects have gone
a long way toward i18n.  If you are interested, you should
check out, e.g., http://www.python.org/sigs/i18n-sig/

Paul Kienzle
[hidden email]