Re: org.texi edits, patch attached

[Nicolas Goaziou <mail@nicolasgoaziou.fr>]

Hello,

Lambda Coder <sjlambda@gmail.com> 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