From: Eli Zaretskii <eliz@gnu.org>
To: "Rüdiger Sonderfeld" <ruediger@c-plusplus.de>
Cc: emacs-devel@gnu.org
Subject: Re: [PATCH] Import `octave-mode' manual from GNU Octave.
Date: Sat, 07 Dec 2013 10:31:01 +0200 [thread overview]
Message-ID: <8338m512re.fsf@gnu.org> (raw)
In-Reply-To: <2192615.kd7q2JU1gN@descartes>
> 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.
next prev parent reply other threads:[~2013-12-07 8:31 UTC|newest]
Thread overview: 12+ messages / expand[flat|nested] mbox.gz Atom feed top
2013-11-21 16:36 Moving octave-mode manual from GNU Octave to GNU Emacs Rüdiger Sonderfeld
2013-11-21 17:36 ` Rüdiger Sonderfeld
2013-11-22 1:38 ` Stefan Monnier
2013-11-22 1:59 ` Rüdiger Sonderfeld
2013-11-22 2:44 ` Stefan Monnier
2013-11-21 18:53 ` Glenn Morris
2013-11-21 20:16 ` Rüdiger Sonderfeld
2013-11-22 3:01 ` Glenn Morris
2013-12-06 22:50 ` [PATCH] Import `octave-mode' manual from GNU Octave Rüdiger Sonderfeld
2013-12-07 8:31 ` Eli Zaretskii [this message]
2013-12-07 18:21 ` [PATCH v2] " Rüdiger Sonderfeld
2013-12-11 13:53 ` Rüdiger Sonderfeld
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=8338m512re.fsf@gnu.org \
--to=eliz@gnu.org \
--cc=emacs-devel@gnu.org \
--cc=ruediger@c-plusplus.de \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.