From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: [PATCH] Import `octave-mode' manual from GNU Octave. Date: Sat, 07 Dec 2013 10:31:01 +0200 Message-ID: <8338m512re.fsf@gnu.org> References: <3807544.WvD2aUL9KJ@descartes> <2192615.kd7q2JU1gN@descartes> Reply-To: Eli Zaretskii NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: QUOTED-PRINTABLE X-Trace: ger.gmane.org 1386405078 27530 80.91.229.3 (7 Dec 2013 08:31:18 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sat, 7 Dec 2013 08:31:18 +0000 (UTC) Cc: emacs-devel@gnu.org To: =?utf-8?Q?R=C3=BCdiger?= Sonderfeld Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sat Dec 07 09:31:24 2013 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1VpDIK-0004Nj-4Z for ged-emacs-devel@m.gmane.org; Sat, 07 Dec 2013 09:31:24 +0100 Original-Received: from localhost ([::1]:34991 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VpDIJ-0005Xd-MA for ged-emacs-devel@m.gmane.org; Sat, 07 Dec 2013 03:31:23 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:49873) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VpDIC-0005Wk-CI for emacs-devel@gnu.org; Sat, 07 Dec 2013 03:31:21 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1VpDI7-0001m2-Ir for emacs-devel@gnu.org; Sat, 07 Dec 2013 03:31:16 -0500 Original-Received: from mtaout22.012.net.il ([80.179.55.172]:58528) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VpDI7-0001ly-55 for emacs-devel@gnu.org; Sat, 07 Dec 2013 03:31:11 -0500 Original-Received: from conversion-daemon.a-mtaout22.012.net.il by a-mtaout22.012.net.il (HyperSendmail v2007.08) id <0MXF00300GVHU300@a-mtaout22.012.net.il> for emacs-devel@gnu.org; Sat, 07 Dec 2013 10:31:09 +0200 (IST) Original-Received: from HOME-C4E4A596F7 ([87.69.4.28]) by a-mtaout22.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0MXF0030FGZXFNB0@a-mtaout22.012.net.il>; Sat, 07 Dec 2013 10:31:09 +0200 (IST) In-reply-to: <2192615.kd7q2JU1gN@descartes> X-012-Sender: halo1@inter.net.il X-detected-operating-system: by eggs.gnu.org: Solaris 10 X-Received-From: 80.179.55.172 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:166185 Archived-At: > From: R=C3=BCdiger Sonderfeld > Date: Fri, 06 Dec 2013 23:50:57 +0100 >=20 > If this is acceptable I'll push it to trunk. I'm not sure if I sho= uld > put Kurt Hornik as the author of the change. Thanks. Please allow me a few comments. > +2013-12-06 R=C3=83=C2=BCdiger Sonderfeld ^^^^ 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=3DC3=3D83=3DC2=3DBCdiger", which looks wrong.) > --- a/doc/misc/Makefile.in > +++ b/doc/misc/Makefile.in > @@ -63,14 +63,13 @@ MAKEINFO_OPTS =3D --force -I$(emacsdir) > DOCMISC_W32 =3D @DOCMISC_W32@ > =20 > ## Info files to build and install on all platforms. > -INFO_COMMON =3D ada-mode auth autotype bovine calc ccmode cl \ > -=09dbus dired-x ebrowse ede ediff edt eieio \ > -=09emacs-mime epa erc ert eshell eudc efaq \ > -=09flymake forms gnus emacs-gnutls htmlfontify idlwave ido info.in= fo \ > -=09mairix-el message mh-e newsticker nxml-mode \ > -=09org pcl-cvs pgg rcirc remember reftex sasl \ > -=09sc semantic ses sieve smtpmail speedbar srecode todo-mode tramp= \ > -=09url vip viper widget wisent woman > +INFO_COMMON =3D ada-mode auth autotype bovine calc ccmode cl dbus= =09=09\ > +=09dired-x ebrowse ede ediff edt eieio emacs-mime epa erc ert=09\ > +=09eshell eudc efaq flymake forms gnus emacs-gnutls htmlfontify= =09\ > +=09idlwave ido info.info mairix-el message mh-e newsticker=09=09\ > +=09nxml-mode octave-mode org pcl-cvs pgg rcirc remember reftex= =09\ > +=09sasl sc semantic ses sieve smtpmail speedbar srecode=09=09\ > +=09todo-mode tramp url vip viper widget wisent woman Nitpicking: if possible, try not to change more than one line when al= l 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 bod= y is > +@c single or double-quoted text, such as a property value `"positi= on"' > +@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, thi= s macro is used for two purposes: . buffer name "*Inferior Octave*", for which the alternative would b= e @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 A= bbrev > +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 begi= nning > +of a function. No need to capitalize N in @var. It will be automatically capitalize= d 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 com= ment > +line, simply go to its beginning; otherwise, move backwards to the > +beginning of the first code line which is not inside a continuatio= n > +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 Bar= ry > +A. Warsaw @email{bwarsaw@@cnri.reston.va.us} says in the documenta= tion 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 yo= ur copy of > +Octave. ^^^^^^^^^^^^^^^^^^ Shell scripts are files, so should use @file markup. > +You can also communicate with an inferior Octave process from with= in > +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} fu= nction. 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.