Spurious exporting of text before first header

Spurious exporting of text before first header

[François Pinard]

Hi, Org people.

This is an old annoyance of the Org exporter, yet I'm not sure what
would be its best resolution.

Whenever I use :export: tags on headers within an Org file, I expect
only those headers and their contents to be exported (to HTML in my
case), and almost nothing else, which I then consider private.

However, if I have text and other contents prior to the first header of
a file, those contents are indeed exported, while I would prefer not.

Of course, #+TITLE and some other directives prior to the first header
should be honored for their effect.  One might surely debate on the best
way to handle #+INCLUDE directive.

I wish the above comments might generate either a correction in Org, or
an advice for me! :-)

François

P.S. Some might suggest me that I avoid text prior to the first header.
Surely, I have hundreds of Org files and for them all, have some
personal conventions for their format and structure.  For regularity
reasons, I would much like to continue having private initial text.

Re: Spurious exporting of text before first header

[Sebastien Vauban]

Hi François,

François Pinard wrote:
> This is an old annoyance of the Org exporter, yet I'm not sure what
> would be its best resolution.
>
> Whenever I use :export: tags on headers within an Org file, I expect
> only those headers and their contents to be exported (to HTML in my
> case), and almost nothing else, which I then consider private.
>
> However, if I have text and other contents prior to the first header of
> a file, those contents are indeed exported, while I would prefer not.
>
> Of course, #+TITLE and some other directives prior to the first header
> should be honored for their effect.  One might surely debate on the best
> way to handle #+INCLUDE directive.
>
> I wish the above comments might generate either a correction in Org, or
> an advice for me! :-)
>
> P.S. Some might suggest me that I avoid text prior to the first header.
> Surely, I have hundreds of Org files and for them all, have some
> personal conventions for their format and structure.  For regularity
> reasons, I would much like to continue having private initial text.

If you like text without initial heading in the exported file, but don't mind
adding an heading in the Org buffer, you could add this:

--8<---------------cut here---------------start------------->8---
* Initial text                             :ignoreheading:
--8<---------------cut here---------------end--------------->8---

and get what you want in the exported file.

I thought that the filter to ignore the heading only was already in Org, but a
quick test with the ASCII backend makes me thing it isn't. Anyway, you can find
recent posts on this.

Best regards,
  Seb

-- 
Sebastien Vauban

Re: Spurious exporting of text before first header

[François Pinard]

"Sebastien Vauban" <sva-news-D0wtAvR13HarG/iDocfnWg@public.gmane.org>
writes:

> Hi François,

Hello, Sebastien! :-)

>> [...] if I have text and other contents prior to the first header of
>> a file, those contents are indeed exported, while I would prefer not.
>> [...] I have hundreds of Org files and for them all, have some
>> personal conventions for their format and structure. [...}

> If you like text without initial heading in the exported file, but don't mind
> adding an heading in the Org buffer, you could add this:
> * Initial text                             :ignoreheading:
> and get what you want in the exported file.

I might have no other choice, but it would be sad.  As I said, I have
hundreds of Org files, all carefully crafted, rather nice to my eyes,
most of them using initial text for useful and special purpose.  Adding
an initial header everywhere would disrupt this nicety, for the sole
purpose of getting around what I consider to be an Org bug, or
limitation, or lack of happiness, depending on how you want to call it!

The spirit behind :export: is that it marks exactly what is going to be
exported.  This implies, in my understanding, that everything else does
not get exported.  If the lines prior to the first header are exported
whenever there is an :export: tag somewhere, it goes against the spirit
and intent of :export: in my opinion.

François

Re: Spurious exporting of text before first header

[Nicolas Goaziou]

Hello,

François Pinard <pinard@iro.umontreal.ca> writes:

> The spirit behind :export: is that it marks exactly what is going to be
> exported.  This implies, in my understanding, that everything else does
> not get exported.  If the lines prior to the first header are exported
> whenever there is an :export: tag somewhere, it goes against the spirit
> and intent of :export: in my opinion.

I agree, this is a misfeature. This should be fixed in master.

Thank you for bringing it out.


Regards,

-- 
Nicolas Goaziou

Re: Spurious exporting of text before first header

[François Pinard]

Nicolas Goaziou <n.goaziou@gmail.com> writes:

> François Pinard <pinard@iro.umontreal.ca> writes:

>> The spirit behind :export: is [...]

> I agree, this is a misfeature. This should be fixed in master.  Thank
> you for bringing it out.

Thanks as well. :-)

François

Re: Spurious exporting of text before first header

[Nicolas Goaziou]

Hello,

François Pinard <pinard@iro.umontreal.ca> writes:

> Nicolas Goaziou <n.goaziou@gmail.com> writes:
>
>> François Pinard <pinard@iro.umontreal.ca> writes:
>
>>> The spirit behind :export: is [...]
>
>> I agree, this is a misfeature. This should be fixed in master.  Thank
>> you for bringing it out.
>
> Thanks as well. :-)

OTOH, this "fix" introduces another problem.

What if a user wants to both use :export: tag and export text before
first headline? An almost equivalent solution for him would be to add
a headline before that text and append it an :export: tag. But in that
case, he will get the additional headline in the output, which isn't
desirable. IOW, it is easier to make that text disappear than to make it
appear.

IOW, even though the new behaviour is more logical, in the end, I'm not
sure it is desirable. It's the old "good" versus "best" story.

WDYT?


Regards,

-- 
Nicolas Goaziou

Re: Spurious exporting of text before first header

[Sebastien Vauban]

Hello Nicolas,

Nicolas Goaziou wrote:
> François Pinard <pinard-CRDzTM1onBSWkKpYnGOUKg@public.gmane.org> writes:
>> Nicolas Goaziou <n.goaziou-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> writes:
>>> François Pinard <pinard-CRDzTM1onBSWkKpYnGOUKg@public.gmane.org> writes:
>>
>>>> The spirit behind :export: is [...]
>>
>>> I agree, this is a misfeature. This should be fixed in master.  Thank
>>> you for bringing it out.
>>
>> Thanks as well. :-)
>
> OTOH, this "fix" introduces another problem.
>
> What if a user wants to both use :export: tag and export text before
> first headline? An almost equivalent solution for him would be to add
> a headline before that text and append it an :export: tag. But in that
> case, he will get the additional headline in the output, which isn't
> desirable.

He would have to add as well the tag ":ignoreheading:", right, and would have
no problem in the output?

Though, he would see the headline in his Org buffer, what he'd dislike anyway
(like François).

> IOW, it is easier to make that text disappear than to make it
> appear.
>
> IOW, even though the new behaviour is more logical, in the end, I'm not
> sure it is desirable. It's the old "good" versus "best" story.
>
> WDYT?

At this stage, I don't have any preference for one over the other.

Best regards,
  Seb

-- 
Sebastien Vauban

Re: Spurious exporting of text before first header

[Nicolas Goaziou]

Hello,

"Sebastien Vauban" <sva-news-D0wtAvR13HarG/iDocfnWg@public.gmane.org>
writes:

> Nicolas Goaziou wrote:
>>
>> What if a user wants to both use :export: tag and export text before
>> first headline? An almost equivalent solution for him would be to add
>> a headline before that text and append it an :export: tag. But in that
>> case, he will get the additional headline in the output, which isn't
>> desirable.
>
> He would have to add as well the tag ":ignoreheading:", right, and would have
> no problem in the output?

AFAIK, there is no such thing as a :ignoreheading: tag, at least not in
the general case (Beamer export back-end has this feature, but it's
a kludge). You may be referring to a personal export filter.


Regards,

-- 
Nicolas Goaziou

Re: Spurious exporting of text before first header

[Sebastien Vauban]

Hello Nicolas,

Nicolas Goaziou wrote:
> "Sebastien Vauban" writes:
>> Nicolas Goaziou wrote:
>>
>>> What if a user wants to both use :export: tag and export text before
>>> first headline? An almost equivalent solution for him would be to add
>>> a headline before that text and append it an :export: tag. But in that
>>> case, he will get the additional headline in the output, which isn't
>>> desirable.
>>
>> He would have to add as well the tag ":ignoreheading:", right, and would
>> have no problem in the output?
>
> AFAIK, there is no such thing as a :ignoreheading: tag, at least not in the
> general case (Beamer export back-end has this feature, but it's a kludge).
> You may be referring to a personal export filter.

Entirely possible: I've seen that while reading posts of this ML.

Wouldn't it be worth to make such a filter officially present in Org, not only
for Beamer?

Best regards,
  Seb

-- 
Sebastien Vauban

Re: Spurious exporting of text before first header

[Nicolas Goaziou]

"Sebastien Vauban" <sva-news-D0wtAvR13HarG/iDocfnWg@public.gmane.org>
writes:

> Wouldn't it be worth to make such a filter officially present in Org, not only
> for Beamer?

Here we are.

No it wouldn't. As I said, it's a kludge used as a workaround in
Beamer-specific syntax because headlines, which are not blocks, can only
be ended with another headline or the end of buffer. It's a specific
solution for a local problem. These do not usually generalize very well.
For example, visibility cycling isn't related anymore to sections in
export output:

  * H1
    Section 1
  * Ignore me! :ignoreheading:
    Section 1 (continued)
  * H2
    Section 2

You can achieve the same (and, apparently, you already do) with a simple
hook, without extending Org syntax. I _really_ think that's better.


Regards,

-- 
Nicolas Goaziou

Re: Spurious exporting of text before first header

[Sebastien Vauban]

Hello Nicolas,

Nicolas Goaziou wrote:
> "Sebastien Vauban" writes:
>
>> Wouldn't it be worth to make such a filter officially present in Org, not
>> only for Beamer?
>
> Here we are.
>
> No it wouldn't. As I said, it's a kludge used as a workaround in
> Beamer-specific syntax because headlines, which are not blocks, can only be
> ended with another headline or the end of buffer. It's a specific solution
> for a local problem.

I understand it *is* needed for Beamer.

> These do not usually generalize very well. For example,
> visibility cycling isn't related anymore to sections in export output:
>
>   * H1
>     Section 1
>   * Ignore me! :ignoreheading:
>     Section 1 (continued)
>   * H2
>     Section 2

For me, visibility in the original Org buffer and sections in export output
are orthogonal things. They don't impact each other.

> You can achieve the same (and, apparently, you already do) with a simple
> hook, without extending Org syntax. I _really_ think that's better.

Yes, but that would solve the problem of having "preliminary" notes well or not
exported in the output, depending on the fact you tag the section or not. That
was what you said: there is no good solution between saying that preliminary
notes will always be exported (as François wished) or never, if we can't
customize that.

And that would be not only for me: by putting a hook locally, my file won't
produce the same output for all the other users. That was the point of having
it in Org, as it seems it is a common request.

That said, that's not something I need; so I don't mind that much.

Best regards,
  Seb

-- 
Sebastien Vauban

Re: Spurious exporting of text before first header

[Carsten Dominik]

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


On 26.9.2013, at 13:26, Nicolas Goaziou <n.goaziou@gmail.com> wrote:

> Hello,
> 
> François Pinard <pinard@iro.umontreal.ca> writes:
> 
>> Nicolas Goaziou <n.goaziou@gmail.com> writes:
>> 
>>> François Pinard <pinard@iro.umontreal.ca> writes:
>> 
>>>> The spirit behind :export: is [...]
>> 
>>> I agree, this is a misfeature. This should be fixed in master.  Thank
>>> you for bringing it out.
>> 
>> Thanks as well. :-)
> 
> OTOH, this "fix" introduces another problem.
> 
> What if a user wants to both use :export: tag and export text before
> first headline? An almost equivalent solution for him would be to add
> a headline before that text and append it an :export: tag. But in that
> case, he will get the additional headline in the output, which isn't
> desirable. IOW, it is easier to make that text disappear than to make it
> appear.
> 
> IOW, even though the new behaviour is more logical, in the end, I'm not
> sure it is desirable. It's the old "good" versus "best" story.

The new behavior is the correct one.  :export: selects stuff to be exported.
A way to have initial text and some trees would be to add :noexport: to the
ones that should not be exported.

If there is string desire to be able to export initial text with :export: tags,
the only solutions I see would be an additional variable with an #+OPTIONS
equivalent, like org-export-force-initial-content.  Default obviously off,
setting the variable to t with list or customize not recommended, but
possible to set it on a per file basis with #+OPTIONS

- Carsten

> 
> WDYT?
> 
> 
> Regards,
> 
> -- 
> Nicolas Goaziou
> 


[-- Attachment #2: Message signed with OpenPGP using GPGMail --]
[-- Type: application/pgp-signature, Size: 455 bytes --]

Re: Spurious exporting of text before first header

[Marcin Borkowski]

Dnia 2013-09-25, o godz. 19:25:53
Nicolas Goaziou <n.goaziou@gmail.com> napisał(a):

> I agree, this is a misfeature. This should be fixed in master.
                     ^^^^^^^^^^
I love this word!!!

-- 
Marcin Borkowski
http://octd.wmi.amu.edu.pl/en/Marcin_Borkowski
Adam Mickiewicz University

Re: Spurious exporting of text before first header

[François Pinard]

"Sebastien Vauban" <sva-news-D0wtAvR13HarG/iDocfnWg@public.gmane.org>
writes:

> If you like text without initial heading in the exported file, but don't mind
> adding an heading in the Org buffer, you could add this:

> * Initial text                             :ignoreheading:

> and get what you want in the exported file.

As I had to move on this, I just added such headings everywhere.  Sigh! :-)

François