From: Nicolas Goaziou <mail@nicolasgoaziou.fr>
To: Lambda Coder <sjlambda@gmail.com>
Cc: emacs-orgmode@gnu.org
Subject: Re: org.texi edits, patch attached
Date: Tue, 20 Dec 2016 17:58:45 +0100 [thread overview]
Message-ID: <87vauezge2.fsf@nicolasgoaziou.fr> (raw)
In-Reply-To: <CAM5gNT1vBFsqrbeVi_pOOkwSowEgiCRNfvn+pop+8_+BxZ7nOw@mail.gmail.com> (Lambda Coder's message of "Mon, 19 Dec 2016 19:31:15 -0800")
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
next prev parent reply other threads:[~2016-12-20 16:58 UTC|newest]
Thread overview: 21+ messages / expand[flat|nested] mbox.gz Atom feed top
2016-11-07 23:30 org.texi edits, patch attached Lambda Coder
2016-11-11 10:18 ` Nicolas Goaziou
2016-11-11 13:38 ` Bastien Guerry
2016-11-14 12:02 ` Lambda Coder
2016-11-15 7:47 ` Nicolas Goaziou
2016-11-15 20:10 ` Lambda Coder
2016-11-15 20:44 ` Nicolas Goaziou
2016-11-16 23:30 ` Lambda Coder
2016-11-17 22:56 ` Nicolas Goaziou
2016-11-18 0:51 ` Lambda Coder
2016-11-18 8:21 ` Nicolas Goaziou
2016-11-19 4:09 ` Lambda Coder
2016-11-24 1:46 ` Lambda Coder
2016-11-26 22:42 ` Nicolas Goaziou
2016-12-02 20:33 ` Lambda Coder
2016-12-03 23:46 ` Nicolas Goaziou
2016-12-15 6:45 ` Lambda Coder
2016-12-18 23:39 ` Nicolas Goaziou
2016-12-20 3:31 ` Lambda Coder
2016-12-20 16:58 ` Nicolas Goaziou [this message]
2017-02-23 13:24 ` Nicolas Goaziou
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
List information: https://www.orgmode.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87vauezge2.fsf@nicolasgoaziou.fr \
--to=mail@nicolasgoaziou.fr \
--cc=emacs-orgmode@gnu.org \
--cc=sjlambda@gmail.com \
/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 public inbox
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).