Re: [PATCH] Import `octave-mode' manual from GNU Octave.

[Eli Zaretskii <eliz@gnu.org>]

> From: Rüdiger Sonderfeld <ruediger@c-plusplus.de>
> Date: Fri, 06 Dec 2013 23:50:57 +0100
> 
> If this is acceptable I'll push it to trunk.  I'm not sure if I should
> put Kurt Hornik as the author of the change.

Thanks.  Please allow me a few comments.

> +2013-12-06  Rüdiger Sonderfeld  <ruediger@c-plusplus.de>
               ^^^^

Something's wrong here with the encoding.  (I received the mail
encoded in UTF-8, so it's not the Latin-vs-UTF messup.  The mail in
mbox format has "R=C3=83=C2=BCdiger", which looks wrong.)

> --- a/doc/misc/Makefile.in
> +++ b/doc/misc/Makefile.in
> @@ -63,14 +63,13 @@ MAKEINFO_OPTS = --force -I$(emacsdir)
>  DOCMISC_W32 = @DOCMISC_W32@
>  
>  ## Info files to build and install on all platforms.
> -INFO_COMMON = ada-mode auth autotype bovine calc ccmode cl \
> -	dbus dired-x ebrowse ede ediff edt eieio \
> -	emacs-mime epa erc ert eshell eudc efaq \
> -	flymake forms gnus emacs-gnutls htmlfontify idlwave ido info.info \
> -	mairix-el message mh-e newsticker nxml-mode \
> -	org pcl-cvs pgg rcirc remember reftex sasl \
> -	sc semantic ses sieve smtpmail speedbar srecode todo-mode tramp \
> -	url vip viper widget wisent woman
> +INFO_COMMON = ada-mode auth autotype bovine calc ccmode cl dbus		\
> +	dired-x ebrowse ede ediff edt eieio emacs-mime epa erc ert	\
> +	eshell eudc efaq flymake forms gnus emacs-gnutls htmlfontify	\
> +	idlwave ido info.info mairix-el message mh-e newsticker		\
> +	nxml-mode octave-mode org pcl-cvs pgg rcirc remember reftex	\
> +	sasl sc semantic ses sieve smtpmail speedbar srecode		\
> +	todo-mode tramp url vip viper widget wisent woman

Nitpicking: if possible, try not to change more than one line when all
you do is add a single manual name.

> +@c copied from GNU Octave's macros.texi.
> +@c The following macro works around the Info/plain text expansion of @code{XXX}
> +@c which is `XXX'.  This looks particularly bad when the macro body is
> +@c single or double-quoted text, such as a property value `"position"'
> +@ifinfo
> +@macro qcode{arg}
> +\arg\
> +@end macro
> +@end ifinfo
> +@ifnotinfo
> +@macro qcode{arg}
> +@code{\arg\}
> +@end macro
> +@end ifnotinfo

Yuck!  Please don't do that, it's ugly and non-standard.  AFAICS, this
macro is used for two purposes:

 . buffer name "*Inferior Octave*", for which the alternative would be
   @file{*Inferior Octave*}, as we do with "*scratch*"

 . a list of strings such as '("octave") or '("-q" "--traditional"),
   for which we use @code{("octave")} (note that the convention is to
   not place the quote ' before literal lists)

So please use our usual practices instead of this macro.

> +@node Using Octave Mode
> +@chapter Using Octave Mode

There should be a @cindex entry here.

> +@item LFD

"LFD" is a key, not a string of 3 characters, so you should give it
the @key markup.

> +Reindent the current Octave line, insert a newline and indent the new
> +line (@code{octave-reindent-then-newline-and-indent}).  An abbrev before
> +point is expanded if @code{abbrev-mode} is non-@code{nil}.
                              ^^^^^^^^^^^

It is useful to have cross-references for where the features you
mention are described, in this case abbrev-mode.  This is so the
reader could consult those places if she doesn't have a clear idea of
what abbrev-mode is.

In addition, every function and variable from Octave mode that you
mention should have a corresponding @findex or @vindex entry before
the text that mentions it.

> +Start entering an abbreviation (@code{octave-abbrev-start}).  If Abbrev
> +mode is turned on, typing @kbd{`C-h} or @kbd{`?} lists all abbrevs.

Please remove those ` from keys inside @kbd.

> +@item M-C-a
> +Move backward to the beginning of a function
> +(@code{octave-beginning-of-defun}).
> +With prefix argument @var{N}, do it that many times if @var{N} is
> +positive; otherwise, move forward to the @var{N}-th following beginning
> +of a function.

No need to capitalize N in @var.  It will be automatically capitalized
in Info output, but in other formats will get the slant typeface.

> +@item C-c C-a
> +Move to the `real' beginning of the current line

Not sure why "real" is in quotes.  If you wanted to emphasize it, use
@emph.

> +(@code{octave-beginning-of-line}).  If point is in an empty or comment
> +line, simply go to its beginning; otherwise, move backwards to the
> +beginning of the first code line which is not inside a continuation
> +statement, i.e., which does not follow a code line ending in @samp{...}
> +or @samp{\}, or is inside an open parenthesis list.

This suggests that perhaps "beginning of the physical line" is a
better term than "`real' beginning of the line".

> +considerations apply for using @key{M-RET} as @key{M-LFD}.  As Barry
> +A. Warsaw @email{bwarsaw@@cnri.reston.va.us} says in the documentation for his

@email accepts 2 arguments; I suggest to use that feature.

> +The following variables can be used to customize Octave mode.
> +
> +@table @code
> +@item octave-auto-indent

If you use @vtable instead of @table @code, all the variables you
mention will be automatically added to the variable index, as they
should be.

> +You can generate TAGS files for Emacs from Octave @file{.m} files using
> +the shell script @code{octave-tags} that is installed alongside your copy of
> +Octave.          ^^^^^^^^^^^^^^^^^^

Shell scripts are files, so should use @file markup.

> +You can also communicate with an inferior Octave process from within
> +files with Octave code (i.e., buffers in Octave mode), using the
> +following commands.
> +
> +@table @kbd
> +@item C-c C-i l

The keys here should be indexed with @kindex.

> +@node Index
> +@unnumbered Index
> +
> +@printindex cp
> +
> +@bye
> +
> +@node Using the Emacs Info Reader for Octave
> +@chapter Using the Emacs Info Reader for Octave
> +
> +You may also use the Emacs Info reader with Octave's @code{doc} function.

Anything after "@bye" will be ignored, so this last node will not be
in the output.  Is this what you meant?

Thanks again for working on this.