[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH] Import `octave-mode' manual from GNU Octave.
From: |
Eli Zaretskii |
Subject: |
Re: [PATCH] Import `octave-mode' manual from GNU Octave. |
Date: |
Sat, 07 Dec 2013 10:31:01 +0200 |
> From: Rüdiger Sonderfeld <address@hidden>
> 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 <address@hidden>
^^^^
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.
> address@hidden copied from GNU Octave's macros.texi.
> address@hidden The following macro works around the Info/plain text expansion
> of @code{XXX}
> address@hidden which is `XXX'. This looks particularly bad when the macro
> body is
> address@hidden single or double-quoted text, such as a property value
> `"position"'
> address@hidden
> address@hidden qcode{arg}
> +\arg\
> address@hidden macro
> address@hidden ifinfo
> address@hidden
> address@hidden qcode{arg}
> address@hidden
> address@hidden macro
> address@hidden 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.
> address@hidden Using Octave Mode
> address@hidden Using Octave Mode
There should be a @cindex entry here.
> address@hidden 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 address@hidden
^^^^^^^^^^^
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.
> address@hidden 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.
> address@hidden 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.
> +
> address@hidden @code
> address@hidden 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.
> +
> address@hidden @kbd
> address@hidden C-c C-i l
The keys here should be indexed with @kindex.
> address@hidden Index
> address@hidden Index
> +
> address@hidden cp
> +
> address@hidden
> +
> address@hidden Using the Emacs Info Reader for Octave
> address@hidden 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.