From mboxrd@z Thu Jan 1 00:00:00 1970 From: Nicolas Goaziou Subject: Re: org.texi edits, patch attached Date: Tue, 20 Dec 2016 17:58:45 +0100 Message-ID: <87vauezge2.fsf@nicolasgoaziou.fr> References: <874m3efhfw.fsf@nicolasgoaziou.fr> <87d1hxp4kk.fsf@nicolasgoaziou.fr> <87vavoo4lz.fsf@nicolasgoaziou.fr> <87mvgxoguq.fsf@nicolasgoaziou.fr> <877f81nqpe.fsf@nicolasgoaziou.fr> <87bmx1euca.fsf@nicolasgoaziou.fr> <87k2bgbmol.fsf@nicolasgoaziou.fr> <87wpew24e5.fsf@nicolasgoaziou.fr> Mime-Version: 1.0 Content-Type: text/plain Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:47835) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1cJNkW-0004dJ-9Q for emacs-orgmode@gnu.org; Tue, 20 Dec 2016 11:58:49 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1cJNkS-0001Pb-A9 for emacs-orgmode@gnu.org; Tue, 20 Dec 2016 11:58:48 -0500 Received: from relay4-d.mail.gandi.net ([217.70.183.196]:40329) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1cJNkS-0001Ol-43 for emacs-orgmode@gnu.org; Tue, 20 Dec 2016 11:58:44 -0500 In-Reply-To: (Lambda Coder's message of "Mon, 19 Dec 2016 19:31:15 -0800") List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Sender: "Emacs-orgmode" To: Lambda Coder Cc: emacs-orgmode@gnu.org Hello, Lambda Coder writes: > See attached patch for Exporting chapter against maint. Thank you. Unfortunately, I cannot apply it. Could you send create it with format-patch against maint's tip, without gzipping it? > Also my notes to your comments. Answers follow. >> +Org has export facilities for printing, format conversions, and general >> +sharing of Org documents with the outside world. Org export supports >> +pretty-printing, web publishing, slide shows, and quick exports of lists and >> +tables to many foreign formats while retaining as much structure >> +(@pxref{Document structure}) and markup (@pxref{Markup}) as possible. The >> +many features of Org exports are constantly being improved and expanded and >> +they are all explained in this chapter. > > I would remove "are constantly being improved and expanded and they" > > [why?] It sounds like a commercial ad. > Shouldn't we leave that for a docstring? > > [Perhaps, but all three conditions have to be together.] Fair enough. >> +@example >> +#+ATTR_BEAMER: :options [Lagrange] >> +Let $G$ be a finite group, and let $H$ be >> +a subgroup of $G$. Then the order of $H$ divides the order of $G$. >> +@end example > > The example above does nothing useful, does it? :options do not apply to > paragraphs AFAIK. > > [I did not put it there, edit it as you see fit.] OK, will do, if I remember about it. >> +Options for MathJax (@code{org-html-mathjax-options}). MathJax is used to >> +typeset @LaTeX{} math in HTML documents. @ref{Math formatting in HTML >> +export} has an example. > > @xref{Math formatting in HTML export}, for an example. > > [commas don't make grammatical sense here after xref] It is not about English grammar, but about Texinfo syntax. @xref{whatever}, for example. produces See Section 3.1 [whatever], page 24, for example. whereas @xref{whatever} for example. produces See Section 3.1 [whatever], page 24 for example. which is awkward. >> #+BEGIN_SRC emacs-lisp >> - (defun Fib (n) ; Count rabbits. >> + (defun Fib (n) >> (if (< n 2) n (+ (Fib (- n 1)) (Fib (- n 2))))) >> #+END_SRC > > You ruined the joke :) > > ["count rabbit pairs" makes it more accurate but still nothing funny] Too bad. I found it hilarious (!). Let's remove it then. >> @example >> -#+attr_texinfo: :options org-org-export-to-org ... >> +#+attr_texinfo: :options opt1 opt2 opt3 ... >> #+begin_defun >> A somewhat obsessive function. >> #+end_defun >> @end example > > You also ruined the joke :) You need to replace the contents of the > defun, which do not make sense anymore. > > [I did not know that was a joke.] Ah well. I find names following specific schemes funny, at times. > Also, #+begin_defun expects a function name, not arguments. > > [That's what I thought but see the original block was like that without options] The original is correct since it provides a name for the function being defined. >> @noindent >> -becomes >> +exports to >>=20=20 >> @example >> -@@defun org-org-export-to-org ... >> +@@defun opt1 opt2 opt3 ... >> A somewhat obsessive function. >> @@end defun >> @end example > > Ditto. > > [Restored the previous example. Strongly suggest re-editing this > example or removing it entirely. It's neither informative nor funny.] You may not find it funny, but it's definitely informative, since it illustrates the :options attribute. Regards, -- Nicolas Goaziou