Warning about section named "Footnotes"

Warning about section named "Footnotes"

[Arni Magnusson]

Dear Org maintainers,

I was using Org to write a software manual with a structure along the 
lines of:


* Equations

How to write equations in software FOO.

* Footnotes

How to write footnotes in software FOO.

* Images

How to insert images in software FOO.


When I exported the document (to LaTeX and HTML), I was puzzled to find 
that one of the sections was not exported at all...

After investigating the problem for a while, I realized that if a section 
is named "Footnotes" the default behavior of Org is to ignore it silently.

My solution was to set `org-footnote-section' to nil.


I think it would help Org users if:

1. Org export (to LaTeX, HTML, etc.) emits an error or a prominent warning
    when it ignores an entire section like this.

2. The manual would warn the user about this behavior with a prominent
    warning.


Thanks for maintaining Org-mode. I'm finding it quite convenient for a 
variety of tasks.

Arni

Re: Warning about section named "Footnotes"

[Nicolas Goaziou]

Hello,

Arni Magnusson <arnima@hafro.is> writes:

> I was using Org to write a software manual with a structure along the
> lines of:
>
>
> * Equations
>
> How to write equations in software FOO.
>
> * Footnotes
>
> How to write footnotes in software FOO.
>
> * Images
>
> How to insert images in software FOO.
>
>
> When I exported the document (to LaTeX and HTML), I was puzzled to
> find that one of the sections was not exported at all...
>
> After investigating the problem for a while, I realized that if
> a section is named "Footnotes" the default behavior of Org is to
> ignore it silently.
>
> My solution was to set `org-footnote-section' to nil.
>
>
> I think it would help Org users if:
>
> 1. Org export (to LaTeX, HTML, etc.) emits an error or a prominent warning
>    when it ignores an entire section like this.

It shouldn't. This is the expected behaviour.

> 2. The manual would warn the user about this behavior with a prominent
>    warning.

Would you mind suggesting a change to the manual?


Regards,

-- 
Nicolas Goaziou

Re: Warning about section named "Footnotes"

[Arni Magnusson]

Sure.

I suggest inserting a short paragraph into section 2.2, both in the manual 
and the compact guide. Working from today's snapshot of the repository, 
the two patches are as follows.


$ diff org-before.texi org-after.texi

1212c1212,1217
< @noindent Some people find the many stars too noisy and would prefer an
---
> @vindex org-footnote-section
> @noindent Note that the headline @samp{Footnotes} is a @emph{reserved}
> name. A subtree with this headline will be silently ignored by exporting
> functions, unless the value of @code{org-footnote-section} is modified.
>
> Some people find the many stars too noisy and would prefer an


$ diff orgguide-before.texi orgguide-after.texi

< @noindent
---
> @noindent Note that the headline @samp{Footnotes} is a @emph{reserved}
> name. A subtree with this headline will be silently ignored by exporting
> functions, unless the value of @code{org-footnote-section} is modified.
>


Best regards,

Arni



On Sat, 29 Nov 2014, Nicolas Goaziou wrote:

>> I think it would help Org users if:
>>
>> 1. Org export (to LaTeX, HTML, etc.) emits an error or a prominent
>>    warning when it ignores an entire section like this.
>
> It shouldn't. This is the expected behaviour.
>
>> 2. The manual would warn the user about this behavior with a prominent
>>    warning.
>
> Would you mind suggesting a change to the manual?
>
>
> Regards,
>
> --
> Nicolas Goaziou
>

Re: Warning about section named "Footnotes"

[Arni Magnusson]

The location of the second patch (in orgguide.texi) is line 348:

348c348,351

Arni



---------- Forwarded message ----------

Sure.

I suggest inserting a short paragraph into section 2.2, both in the manual 
and the compact guide. Working from today's snapshot of the repository, 
the two patches are as follows.


$ diff org-before.texi org-after.texi

1212c1212,1217
< @noindent Some people find the many stars too noisy and would prefer an
---
> @ vindex org-footnote-section
> @ noindent Note that the headline @samp{Footnotes} is a @emph{reserved}
> name. A subtree with this headline will be silently ignored by exporting
> functions, unless the value of @code{org-footnote-section} is modified.
>
> Some people find the many stars too noisy and would prefer an


$ diff orgguide-before.texi orgguide-after.texi

< @noindent
---
> @ noindent Note that the headline @samp{Footnotes} is a @emph{reserved}
> name. A subtree with this headline will be silently ignored by exporting
> functions, unless the value of @code{org-footnote-section} is modified.
>


Best regards,

Arni



On Sat, 29 Nov 2014, Nicolas Goaziou wrote:

>> I think it would help Org users if:
>>
>> 1. Org export (to LaTeX, HTML, etc.) emits an error or a prominent
>>    warning when it ignores an entire section like this.
>
> It shouldn't. This is the expected behaviour.
>
>> 2. The manual would warn the user about this behavior with a prominent
>>    warning.
>
> Would you mind suggesting a change to the manual?
>
>
> Regards,
>
> --
> Nicolas Goaziou
>

Re: Warning about section named "Footnotes"

[Nicolas Goaziou]

Arni Magnusson <arnima@hafro.is> writes:

> The location of the second patch (in orgguide.texi) is line 348:

Thanks for the patch.

>> @ vindex org-footnote-section
>> @ noindent Note that the headline @samp{Footnotes} is a @emph{reserved}
>> name. A subtree with this headline will be silently ignored by exporting
>> functions, unless the value of @code{org-footnote-section} is
>>modified.

I think we should emphasize `org-footnote-section' over "Footnotes"
which is but its default value. E.g.,

  Note that a headline named after `org-footnote-section', which defaults
  to @samp{Footnotes}, is considered as special...

Also, Texinfo requires two spaces after a sentence.

Enventually, could you provide the patch with a proper commit message,
using "git format-patch"? You need to add "TINYCHANGE" at the end of the
message if you haven't signed FSF papers yet.


Regards,

Re: Warning about section named "Footnotes"

[Arni Magnusson]

Dear Nicolas,

I have revised the paragraph following your suggestion, and prepared the 
patch using the 'git format-patch' command. See below.

In the past, I have signed FSF papers for Emacs and Texinfo contributions. 
Does that cover this contribution as well? If not, I'm happy with the 
TINYCHANGE stamp.

Best regards,

Arni



From 95f8aeead236eb6920fe315d9fe6348fb19ab975 Mon Sep 17 00:00:00 2001
From: Arni Magnusson <arnima@hafro.is>
Date: Mon, 8 Dec 2014 01:27:36 +0000
Subject: [PATCH] Warning about section named "Footnotes"

---
  doc/org.texi      | 8 +++++++-
  doc/orgguide.texi | 6 +++++-
  2 files changed, 12 insertions(+), 2 deletions(-)

diff --git a/doc/org.texi b/doc/org.texi
index ed2eb5a..8368916 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -1209,7 +1209,13 @@ headings indented less then 30 stars.}.  For example:
  * Another top level headline
  @end example

-@noindent Some people find the many stars too noisy and would prefer an
+@vindex org-footnote-section
+@noindent Note that a headline named after @code{org-footnote-section},
+which defaults to @samp{Footnotes}, is considered as special.  A subtree
+with this headline will be silently ignored by exporting functions,
+unless the value of @code{org-footnote-section} is modified.
+
+Some people find the many stars too noisy and would prefer an
  outline that has whitespace followed by a single star as headline
  starters.  @ref{Clean view}, describes a setup to realize this.

diff --git a/doc/orgguide.texi b/doc/orgguide.texi
index e32fa7c..7308d32 100644
--- a/doc/orgguide.texi
+++ b/doc/orgguide.texi
@@ -345,7 +345,11 @@ of @kbd{C-a} and @kbd{C-e} in headlines.}.  For example:
  * Another top level headline
  @end smallexample

-@noindent 
+@noindent Note that a headline named after @code{org-footnote-section},
+which defaults to @samp{Footnotes}, is considered as special.  A subtree
+with this headline will be silently ignored by exporting functions,
+unless the value of @code{org-footnote-section} is modified.
+
  Some people find the many stars too noisy and would prefer an
  outline that has whitespace followed by a single star as headline
  starters.  @ref{Clean view}, describes a setup to realize this.
-- 
1.9.3

Re: Warning about section named "Footnotes"

[Nicolas Goaziou]

Arni Magnusson <arnima@hafro.is> writes:

> I have revised the paragraph following your suggestion, and prepared
> the patch using the 'git format-patch' command. See below.

Thank you. However, I'm unable to apply it. Could you try to update Org
first and send it again as an attachment?

Also, you need to specify the node modified in the commit message.

> In the past, I have signed FSF papers for Emacs and Texinfo
> contributions. Does that cover this contribution as well? If not, I'm
> happy with the TINYCHANGE stamp.

The stamp is not needed, then.


Regards,

Re: Warning about section named "Footnotes"

[Arni Magnusson]

[-- Attachment #1: Type: TEXT/PLAIN, Size: 742 bytes --]

Dear Nicolas,

Attached is the formatted patch. I think my email client mangled it last 
time, as I pasted it inside the email body.

Best regards,

Arni



On Tue, 9 Dec 2014, Nicolas Goaziou wrote:

>> I have revised the paragraph following your suggestion, and prepared 
>> the patch using the 'git format-patch' command. See below.
>
> Thank you. However, I'm unable to apply it. Could you try to update Org 
> first and send it again as an attachment?
>
> Also, you need to specify the node modified in the commit message.
>
>
>> In the past, I have signed FSF papers for Emacs and Texinfo 
>> contributions. Does that cover this contribution as well? If not, I'm 
>> happy with the TINYCHANGE stamp.
>
> The stamp is not needed, then.
>

[-- Attachment #2: Type: TEXT/PLAIN, Size: 1970 bytes --]

From 72bda40525eed23941046694382814e3d04d9b97 Mon Sep 17 00:00:00 2001
From: Arni Magnusson <arnima@hafro.is>
Date: Sat, 21 Feb 2015 16:08:43 +0000
Subject: [PATCH] Add documentation regarding reserved keywords in @node
 Headlines

---
 doc/org.texi      | 8 +++++++-
 doc/orgguide.texi | 6 +++++-
 2 files changed, 12 insertions(+), 2 deletions(-)

diff --git a/doc/org.texi b/doc/org.texi
index bec46a9..8c7e3c3 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -1208,7 +1208,13 @@ headings indented less than 30 stars.}.  For example:
 * Another top level headline
 @end example
 
-@noindent Some people find the many stars too noisy and would prefer an
+@vindex org-footnote-section
+@noindent Note that a headline named after @code{org-footnote-section},
+which defaults to @samp{Footnotes}, is considered as special.  A subtree
+with this headline will be silently ignored by exporting functions,
+unless the value of @code{org-footnote-section} is modified.
+
+Some people find the many stars too noisy and would prefer an
 outline that has whitespace followed by a single star as headline
 starters.  @ref{Clean view}, describes a setup to realize this.
 
diff --git a/doc/orgguide.texi b/doc/orgguide.texi
index e32fa7c..7308d32 100644
--- a/doc/orgguide.texi
+++ b/doc/orgguide.texi
@@ -345,7 +345,11 @@ of @kbd{C-a} and @kbd{C-e} in headlines.}.  For example:
 * Another top level headline
 @end smallexample
 
-@noindent 
+@noindent Note that a headline named after @code{org-footnote-section},
+which defaults to @samp{Footnotes}, is considered as special.  A subtree
+with this headline will be silently ignored by exporting functions,
+unless the value of @code{org-footnote-section} is modified.
+
 Some people find the many stars too noisy and would prefer an
 outline that has whitespace followed by a single star as headline
 starters.  @ref{Clean view}, describes a setup to realize this.
-- 
1.8.3.1

Re: Warning about section named "Footnotes"

[Nicolas Goaziou]

Hello,

Arni Magnusson <arnima@hafro.is> writes:

> Attached is the formatted patch. I think my email client mangled it
> last time, as I pasted it inside the email body.

Applied, with a small removal (last part of the sentence, which I found
unnecessary).

Thank you.

Regards,

-- 
Nicolas Goaziou