[PATCH] Update documentation for :exports (applicable to blocks only, not inline)

[PATCH] Update documentation for :exports (applicable to blocks only, not inline)

[John Hendy]

[-- Attachment #1: Type: text/plain, Size: 412 bytes --]

Per Eric's comment to a previous thread, I took a stab at updating two
locations in the documentation that discuss using the :exports options
so that users (like myself!) don't try to use them on inline code
blocks.
- http://lists.gnu.org/archive/html/emacs-orgmode/2014-03/msg00285.html

Patch is attached.

Feel free to counter my changes with suggestions/improvements and I'll
re-submit.


Best regards,
John

[-- Attachment #2: 0001-updated-documentation-for-exports-argument-to-specif.patch --]
[-- Type: text/x-patch, Size: 1219 bytes --]

From 0b178a22c29c7abe02a30aece6731ce3f77ac12e Mon Sep 17 00:00:00 2001
From: John Henderson <jw.hendy@gmail.com>
Date: Tue, 11 Mar 2014 20:33:36 -0500
Subject: [PATCH] updated documentation for :exports argument to specify that
 it's only relevant for blocks, no inline code

---
 doc/org.texi | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/doc/org.texi b/doc/org.texi
index 7e66034..cd9aa35 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -13828,7 +13828,8 @@ results of code block evaluation.  For information on exporting code block
 bodies, see @ref{Literal examples}.
 
 The @code{:exports} header argument can be used to specify export
-behavior:
+behavior (note that these arguments are only relevant for code blocks, not
+inline code):
 
 @subsubheading Header arguments:
 
@@ -14828,7 +14829,8 @@ which the link does not point.
 @cindex @code{:exports}, src header argument
 
 The @code{:exports} header argument specifies what should be included in HTML
-or @LaTeX{} exports of the Org mode file.
+or @LaTeX{} exports of the Org mode file.  Note that the @code{:exports}
+option is only relevant for code blocks, not inline code.  
 
 @itemize @bullet
 @item @code{code}
-- 
1.9.0

Re: [PATCH] Update documentation for :exports (applicable to blocks only, not inline)

[Bastien]

Hi John,

John Hendy <jw.hendy@gmail.com> writes:

> Feel free to counter my changes with suggestions/improvements and I'll
> re-submit.

Looks good, except for the trailing whitespaces on a line.

Can you resubmit this with a proper ChangeLog entry?

Thanks!

-- 
 Bastien

Re: [PATCH] Update documentation for :exports (applicable to blocks only, not inline)

[John Hendy]

Whoops, completely glossed over the ChangeLog bit of the patch
submission guide. Sorry about that; I'll resubmit shortly.

The trailing whitespace is the result of my texi ignorance. In a
previous patch, Nicolas clarified that sentences needed to end in two
spaces, and I add them at the end of my last sentence thinking they
might be required to identify a new next bit. Understanding now that
an endline/carriage return is sufficient and the spaces are not
needed.


Thanks,
John

On Wed, Mar 12, 2014 at 10:23 AM, Bastien <bzg@gnu.org> wrote:
> Hi John,
>
> John Hendy <jw.hendy@gmail.com> writes:
>
>> Feel free to counter my changes with suggestions/improvements and I'll
>> re-submit.
>
> Looks good, except for the trailing whitespaces on a line.
>
> Can you resubmit this with a proper ChangeLog entry?
>
> Thanks!
>
> --
>  Bastien

Re: [PATCH] Update documentation for :exports (applicable to blocks only, not inline)

[Bastien]

Hi John,

John Hendy <jw.hendy@gmail.com> writes:

> The trailing whitespace is the result of my texi ignorance. In a
> previous patch, Nicolas clarified that sentences needed to end in two
> spaces, and I add them at the end of my last sentence thinking they
> might be required to identify a new next bit. Understanding now that
> an endline/carriage return is sufficient and the spaces are not
> needed.

Yes, two spaces are only needed to separate sentences on the same
line.

Thanks in advance for rewriting the patch, I know it can be tiresome.

-- 
 Bastien

Re: [PATCH] Update documentation for :exports (applicable to blocks only, not inline)

[John Hendy]

[-- Attachment #1: Type: text/plain, Size: 822 bytes --]

On Thu, Mar 13, 2014 at 3:17 AM, Bastien <bzg@gnu.org> wrote:
> Hi John,
>
> John Hendy <jw.hendy@gmail.com> writes:
>
>> The trailing whitespace is the result of my texi ignorance. In a
>> previous patch, Nicolas clarified that sentences needed to end in two
>> spaces, and I add them at the end of my last sentence thinking they
>> might be required to identify a new next bit. Understanding now that
>> an endline/carriage return is sufficient and the spaces are not
>> needed.
>
> Yes, two spaces are only needed to separate sentences on the same
> line.
>
> Thanks in advance for rewriting the patch, I know it can be tiresome.

No problem. Is the attached satisfactory? I worked along with the
ChangeLog documentation, but will start a new thread as I don't think
it's *that* clear :)

Thanks,
John

> --
>  Bastien

[-- Attachment #2: 0001-clarified-documentation-for-exports-only-applicable-.patch --]
[-- Type: text/x-patch, Size: 1679 bytes --]

Header arguments: clarify that `:exports' is only applicable to blocks, not inline code

* doc/org.texi (Exporting code blocks): add clarification; relevant for blocks ony.

* doc/org.texi (exports): add clarification; relevant for blocks only.

The documentation change resulted from the expectation that `:exports' could be used with inline code blocks, which is not the case. Clarification was added to avoid future confusion on this Babel block specific header argument.

TINYCHANGE

From d92c30116602a97f2b11684cf5c66de3972d147b Mon Sep 17 00:00:00 2001
From: John Henderson <jw.hendy@gmail.com>
Date: Fri, 14 Mar 2014 10:29:33 -0500
Subject: [PATCH] clarified documentation for :exports; only applicable to
 blocks, not inline code

---
 doc/org.texi | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/doc/org.texi b/doc/org.texi
index 93d5fd2..04be009 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -13828,7 +13828,8 @@ results of code block evaluation.  For information on exporting code block
 bodies, see @ref{Literal examples}.
 
 The @code{:exports} header argument can be used to specify export
-behavior:
+behavior (note that these arguments are only relevant for code blocks, not
+inline code):
 
 @subsubheading Header arguments:
 
@@ -14831,7 +14832,8 @@ which the link does not point.
 @cindex @code{:exports}, src header argument
 
 The @code{:exports} header argument specifies what should be included in HTML
-or @LaTeX{} exports of the Org mode file.
+or @LaTeX{} exports of the Org mode file. Note that the @code{:exports}
+option is only relevant for code blocks, not inline code.
 
 @itemize @bullet
 @item @code{code}
-- 
1.9.0

Re: [PATCH] Update documentation for :exports (applicable to blocks only, not inline)

[Bastien]

Hi John,

thanks for the patch -- some comments below.

John Hendy <jw.hendy@gmail.com> writes:

> Header arguments: clarify that `:exports' is only applicable to
> blocks, not inline code

This first line should include "org.texi:" to tell that the change
happens in org.texi.  See other commits for examples.

> * doc/org.texi (Exporting code blocks): add clarification; relevant for blocks ony.

Start with a capitalized letter: "Add clarification."
Don't use semi-column.  "Clarify" is enough IMO.

> * doc/org.texi (exports): add clarification; relevant for blocks only.

When two changes get the same description use this:

* doc/org.texi (Exporting code blocks, exports): Clarify.

In general, you can make it easier for you by reviewing the patch (hit
`C-x v =' in the modified org.texi buffer), and then hit `C-x 4 a' on
each change to create a Changelog buffer that you can safely edit.
        
> The documentation change resulted from the expectation that
> `:exports' could be used with inline code blocks, which is not the
> case. Clarification was added to avoid future confusion on this
> Babel block specific header argument.

Please use auto-fill and fill-column to something between 72 and 80.

> TINYCHANGE

Thanks again for the patch, HTH,

-- 
 Bastien

Re: [PATCH] Update documentation for :exports (applicable to blocks only, not inline)

[John Hendy]

[-- Attachment #1: Type: text/plain, Size: 1669 bytes --]

On Fri, Mar 14, 2014 at 10:51 AM, Bastien <bzg@altern.org> wrote:
> Hi John,
>
> thanks for the patch -- some comments below.
>
> John Hendy <jw.hendy@gmail.com> writes:
>
>> Header arguments: clarify that `:exports' is only applicable to
>> blocks, not inline code
>
> This first line should include "org.texi:" to tell that the change
> happens in org.texi.  See other commits for examples.
>

Gotcha. That wasn't in the manual example for the first line. I've
added it to my re-attempt attached.

>> * doc/org.texi (Exporting code blocks): add clarification; relevant for blocks ony.
>
> Start with a capitalized letter: "Add clarification."
> Don't use semi-column.  "Clarify" is enough IMO.
>

Even after reading the instructions, I *still* missed the capitalization bit...

>> * doc/org.texi (exports): add clarification; relevant for blocks only.
>
> When two changes get the same description use this:
>
> * doc/org.texi (Exporting code blocks, exports): Clarify.
>

Awesome. I wondered about that as well.

> In general, you can make it easier for you by reviewing the patch (hit
> `C-x v =' in the modified org.texi buffer), and then hit `C-x 4 a' on
> each change to create a Changelog buffer that you can safely edit.
>

Thanks for the tips.

>> The documentation change resulted from the expectation that
>> `:exports' could be used with inline code blocks, which is not the
>> case. Clarification was added to avoid future confusion on this
>> Babel block specific header argument.
>
> Please use auto-fill and fill-column to something between 72 and 80.
>

Done.

>> TINYCHANGE
>
> Thanks again for the patch, HTH,
>

No problem.


John

> --
>  Bastien

[-- Attachment #2: 0001-clarified-documentation-for-exports-only-applicable-.patch --]
[-- Type: text/x-patch, Size: 1612 bytes --]

Header arguments: clarify in doc/org.texi that `:exports' is only applicable to
blocks, not inline code

* doc/org.texi (Exporting code blocks, exports): Clarify.

The documentation change resulted from the expectation that `:exports'
could be used with inline code blocks, which is not the case.
Clarification was added to avoid future confusion on this header
argument, which is applicable only to blocks.

TINYCHANGE

From d92c30116602a97f2b11684cf5c66de3972d147b Mon Sep 17 00:00:00 2001
From: John Henderson <jw.hendy@gmail.com>
Date: Fri, 14 Mar 2014 10:29:33 -0500
Subject: [PATCH] clarified documentation for :exports; only applicable to
 blocks, not inline code

---
 doc/org.texi | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/doc/org.texi b/doc/org.texi
index 93d5fd2..04be009 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -13828,7 +13828,8 @@ results of code block evaluation.  For information on exporting code block
 bodies, see @ref{Literal examples}.
 
 The @code{:exports} header argument can be used to specify export
-behavior:
+behavior (note that these arguments are only relevant for code blocks, not
+inline code):
 
 @subsubheading Header arguments:
 
@@ -14831,7 +14832,8 @@ which the link does not point.
 @cindex @code{:exports}, src header argument
 
 The @code{:exports} header argument specifies what should be included in HTML
-or @LaTeX{} exports of the Org mode file.
+or @LaTeX{} exports of the Org mode file. Note that the @code{:exports}
+option is only relevant for code blocks, not inline code.
 
 @itemize @bullet
 @item @code{code}
-- 
1.9.0

Re: [PATCH] Update documentation for :exports (applicable to blocks only, not inline)

[Bastien]

John Hendy <jw.hendy@gmail.com> writes:

> No problem.

I installed the patch in master, thanks.

Last nitpick: I added a space in the change, as sentences in the
manual should end with two spaces... sorry to repeat this :)

-- 
 Bastien

Re: [PATCH] Update documentation for :exports (applicable to blocks only, not inline)

[John Hendy]

On Fri, Mar 14, 2014 at 11:17 AM, Bastien <bzg@gnu.org> wrote:
> John Hendy <jw.hendy@gmail.com> writes:
>
>> No problem.
>
> I installed the patch in master, thanks.
>
> Last nitpick: I added a space in the change, as sentences in the
> manual should end with two spaces... sorry to repeat this :)

I caught it too, after I submitted (the first one; hopefully the last
one had them!). Lots of things to keep track of at once, but I'll get
there.

Thanks for the patience!
John

>
> --
>  Bastien