Feature request: filling of long captions

Feature request: filling of long captions

[Andreas Leha]

Hi all,

a currently active thread about filling
(http://permalink.gmane.org/gmane.emacs.orgmode/77700) reminded me of a
long standing wish of mine:  Filling of captions.

Would it be possible to have filling of captions?  Ideally that would
mean at least two things: auto-fill and M-q working on long captions.

Example:
--8<---------------cut here---------------start------------->8---
#+name: test
#+begin_src R :results graphics :file tettr.png
  plot(1:10, 1:10)
#+end_src

#+results: test
[[file:tettr.png]]


#+caption: A very long long long long long long long long long long long long long long long long long long long long long long long long long long caption.
[[file:tettr.png]]


It would be very convenient if that could be automatically broken to

#+caption: A very long long long long long long long long long long long long long long
#+caption: long long long long long long long long long long long long caption.
[[file:tettr.png]]
--8<---------------cut here---------------end--------------->8---


Regards,
Andreas

Re: Feature request: filling of long captions

[Bastien]

Hi Andreas,

Andreas Leha <andreas.leha@med.uni-goettingen.de> writes:

> Would it be possible to have filling of captions?

I guess so.

> Ideally that would mean at least two things: auto-fill and M-q
> working on long captions.

Yes.

Could you list other options that are good candidates for such
auto-filling fonctionality?  We'd better implement them all at
once.

Thanks,

-- 
 Bastien

Re: Feature request: filling of long captions

[Andreas Leha]

Hi Bastien,

Bastien <bzg@gnu.org> writes:

> Hi Andreas,
>
> Andreas Leha <andreas.leha@med.uni-goettingen.de> writes:
>
>> Would it be possible to have filling of captions?
>
> I guess so.
>

Thanks for the good news!  Now I am waiting for christmas ;-)

>> Ideally that would mean at least two things: auto-fill and M-q
>> working on long captions.
>
> Yes.
>
> Could you list other options that are good candidates for such
> auto-filling fonctionality?  We'd better implement them all at
> once.
>

Do you mean (1) other places in org files (other than #+caption) or
(2) other functionality that should be supported at #+caption filling?

If (2) than the only other functionality that comes to my mind is M-^
(delete-indentation), which could remove the #+caption on joining with
the previous line.

If (1) than I can't think of anything too obvious.  Other candidates
such as '#+header[s]:' or '#+latex_header[_extra]:' might benefit from
some level of additional support, but autofill is not suitable here.

Regards,
Andreas

Re: Feature request: filling of long captions

[Bastien]

Andreas Leha <andreas.leha@med.uni-goettingen.de> writes:

> Do you mean (1) other places in org files (other than #+caption) or
> (2) other functionality that should be supported at #+caption
> filling?

Normally lines matching the regexp ^#\+\S-+ (like #+CAPTION) should
not be filled.  We would introduce an exception where successive
#+CAPTION lines are correctly parsed by Org -- so the question is
how many of such options should fill like #+CAPTION will do (maybe
before Christmas.)

-- 
 Bastien

Re: Feature request: filling of long captions

[Andreas Leha]

Hi Bastien,

Bastien <bzg@gnu.org> writes:

> Andreas Leha <andreas.leha@med.uni-goettingen.de> writes:
>
>> Do you mean (1) other places in org files (other than #+caption) or
>> (2) other functionality that should be supported at #+caption
>> filling?
>
> Normally lines matching the regexp ^#\+\S-+ (like #+CAPTION) should
> not be filled.  We would introduce an exception where successive
> #+CAPTION lines are correctly parsed by Org -- so the question is
> how many of such options should fill like #+CAPTION will do (maybe
> before Christmas.)

Well, I am not sure that I understand this.  #+CAPTION lines are IMO
parsed correctly by Org -- just the filling is missing.

I do not (at the moment) see other 'options' like #+CAPTION that are
missing auto-fill capabilities.

Regards,
Andreas

Re: Feature request: filling of long captions

[Thomas Holst]

Hi,

· Andreas Leha <andreas.leha@med.uni-goettingen.de> wrote:

> Hi Bastien,
>
> Bastien <bzg@gnu.org> writes:
>
>> Andreas Leha <andreas.leha@med.uni-goettingen.de> writes:
>>
>>> Do you mean (1) other places in org files (other than #+caption) or
>>> (2) other functionality that should be supported at #+caption
>>> filling?
>>
>> Normally lines matching the regexp ^#\+\S-+ (like #+CAPTION) should
>> not be filled.  We would introduce an exception where successive
>> #+CAPTION lines are correctly parsed by Org -- so the question is
>> how many of such options should fill like #+CAPTION will do (maybe
>> before Christmas.)
>
> Well, I am not sure that I understand this.  #+CAPTION lines are IMO
> parsed correctly by Org -- just the filling is missing.
>
> I do not (at the moment) see other 'options' like #+CAPTION that are
> missing auto-fill capabilities.

what about #+HEADER: for source code blocks. Filling might be difficult since
I don't know if something like:

#+HEADER: :var foo=
#+HEADER: "bar"

is handled correctly by babel parser.

The same holds true for #+ATTR_LATEX:
-- 
Mit freundlichen Grüßen / Best regards 

Thomas Holst 
DGS-EC/ESE4

Tel.   +49 (711) 811-40681
PC-Fax +49 (711) 811-5182208

Re: Feature request: filling of long captions

[Scott Randby]

On Thu, Feb 6, 2014 at 3:43 AM, Bastien <bzg@gnu.org> wrote:
> Hi Andreas,
>
> Andreas Leha <andreas.leha@med.uni-goettingen.de> writes:
>
>> Would it be possible to have filling of captions?
>
> I guess so.
>
>> Ideally that would mean at least two things: auto-fill and M-q
>> working on long captions.
>
> Yes.
>
> Could you list other options that are good candidates for such
> auto-filling fonctionality?  We'd better implement them all at
> once.

Filling of table formulas would be nice.

Scott Randby

>
> Thanks,
>
> --
>  Bastien
>

Re: Feature request: filling of long captions

[Andrea Rossetti]

Hello Bastien and everyone reading,

Bastien <bzg@gnu.org> writes:
> Could you list other options that are good candidates for such
> auto-filling fonctionality?  We'd better implement them all at
> once.

  I'd suggest to split the wish-list in two buckets, i.e. 

1) some "#+..." commands would benefit of a line-continuation
mechanism (like the backslash at EOL in a multilined C/C++
#define macro)

2) some line-continuation-aware "#+..." commands (thanks to
implementations for step 1) would benefit of auto-filling

  To me #+TBLFM seems to fit into bucket 1, #+CAPTION into
bucket 2. My Christmas wish is #+MACRO into bucket 1.

  Kindest regards,

  Andrea

Re: Feature request: filling of long captions

[Eric Schulte]

Andrea Rossetti <andrea.rossetti@gmail.com> writes:

> Hello Bastien and everyone reading,
>
> Bastien <bzg@gnu.org> writes:
>> Could you list other options that are good candidates for such
>> auto-filling fonctionality?  We'd better implement them all at
>> once.
>
>   I'd suggest to split the wish-list in two buckets, i.e. 
>
> 1) some "#+..." commands would benefit of a line-continuation
> mechanism (like the backslash at EOL in a multilined C/C++
> #define macro)
>
> 2) some line-continuation-aware "#+..." commands (thanks to
> implementations for step 1) would benefit of auto-filling
>
>   To me #+TBLFM seems to fit into bucket 1, #+CAPTION into
> bucket 2. My Christmas wish is #+MACRO into bucket 1.
>
>   Kindest regards,
>
>   Andrea
>

For a while now I've been wishing that keywords (namely #+Caption:)
could be equivalently specified as blocks (e.g., #+begin/end_Caption:).

Would that be another possible solution here?

Best,

-- 
Eric Schulte
https://cs.unm.edu/~eschulte
PGP: 0x614CA05D

Re: Feature request: filling of long captions

[Andreas Leha]

Eric Schulte <schulte.eric@gmail.com> writes:

> Andrea Rossetti <andrea.rossetti@gmail.com> writes:
>
>> Hello Bastien and everyone reading,
>>
>> Bastien <bzg@gnu.org> writes:
>>> Could you list other options that are good candidates for such
>>> auto-filling fonctionality?  We'd better implement them all at
>>> once.
>>
>>   I'd suggest to split the wish-list in two buckets, i.e. 
>>
>> 1) some "#+..." commands would benefit of a line-continuation
>> mechanism (like the backslash at EOL in a multilined C/C++
>> #define macro)
>>
>> 2) some line-continuation-aware "#+..." commands (thanks to
>> implementations for step 1) would benefit of auto-filling
>>
>>   To me #+TBLFM seems to fit into bucket 1, #+CAPTION into
>> bucket 2. My Christmas wish is #+MACRO into bucket 1.
>>
>>   Kindest regards,
>>
>>   Andrea
>>
>
> For a while now I've been wishing that keywords (namely #+Caption:)
> could be equivalently specified as blocks (e.g., #+begin/end_Caption:).
>
> Would that be another possible solution here?

I can not think of any downside, so I guess it would work at least
as well for me.

It might be harder to implement, since multiple caption lines are
already parsed correctly by Org.

The begin/end_caption blocks would have their advantages in terms of
syntax highlighting / readability of the Org buffer.

Regards,
Andreas

Re: Feature request: filling of long captions

[Nicolas Goaziou]

Hello,

Eric Schulte <schulte.eric@gmail.com> writes:

> For a while now I've been wishing that keywords (namely #+Caption:)
> could be equivalently specified as blocks (e.g., #+begin/end_Caption:).
>
> Would that be another possible solution here?

That would defeat the purpose of the distinction between a block and an
affiliated keyword (i.e., a property added to that block). Besides the
change of paradigm, it would introduce a lot of problems (handle syntax
limitation in such block, for example, since I assume plain lists would
be forbidden).

Also, current syntax also handles short captions, so you would have to
rely on another trick for them.

I'm sure this idea wouldn't be a net benefit for Org syntax clarity,
even for the occasional three lines caption need.


Regards,

-- 
Nicolas Goaziou

Re: Feature request: filling of long captions

[Bastien]

Hi all,

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

> I'm sure this idea wouldn't be a net benefit for Org syntax clarity,
> even for the occasional three lines caption need.

I agree.

Nicolas, what do you think of enhancing the auto-filling (and
delete-indentation) capabilities for some affiliated keywords?

#+CAPTION:
#+HEADER:
#+TBLFM:

The last two would require special auto-filling functions,
but at least for #+TBLFM I see the point of enabling this.

Thanks,

-- 
 Bastien

Re: Feature request: filling of long captions

[Nicolas Goaziou]

Hello,

> Nicolas, what do you think of enhancing the auto-filling (and
> delete-indentation) capabilities for some affiliated keywords?
>
> #+CAPTION:
> #+HEADER:
> #+TBLFM:

Not that it matters much, but "TBLFM" is not an affiliated keyword per
se, it belongs to the table syntax. OTOH, you can have "CAPTION" and
"HEADER" keywords on top of almost any element type.

Anyway, the three keywords are very different.

To start with the one I know the most, CAPTION can have an optional
value, and multiple caption lines can have as many optional values.

  #+CAPTION[short caption]: long caption
  #+CAPTION[short caption, continued]: long caption, continued.

Therefore, filling it can be tricky since you have to pay attention to
both values.

Moreover, if the "short" caption is too long to fit on one line, that
line still needs to end with "]:" to be valid.

  #+CAPTION[very very ... long "short" caption]:
  #+CAPTION[continued even here]: long caption
  #+CAPTION: long caption continued.

The difficulty lies elsewhere for "HEADER" and "TBLFM". The question is:
can we split a HEADER or TBLFM line anywhere, e.g., in the between
a keyword and its value (or at a space in the middle of a value) for the
former, and in the middle of a formula in the latter? It depends on how
"org-table.el" and "ob.el" read these keywords. I didn't check.

Also, please bear in mind that filling functions have unit tests, so any
new feature ought to be also tested.


Regards,

-- 
Nicolas Goaziou

Re: Feature request: filling of long captions

[Andreas Leha]

Hello,

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

> Hello,
>
>> Nicolas, what do you think of enhancing the auto-filling (and
>> delete-indentation) capabilities for some affiliated keywords?
>>
>> #+CAPTION:
>> #+HEADER:
>> #+TBLFM:
>
> Not that it matters much, but "TBLFM" is not an affiliated keyword per
> se, it belongs to the table syntax. OTOH, you can have "CAPTION" and
> "HEADER" keywords on top of almost any element type.
>
> Anyway, the three keywords are very different.
>
> To start with the one I know the most, CAPTION can have an optional
> value, and multiple caption lines can have as many optional values.
>
>   #+CAPTION[short caption]: long caption
>   #+CAPTION[short caption, continued]: long caption, continued.
>
> Therefore, filling it can be tricky since you have to pay attention to
> both values.
>
> Moreover, if the "short" caption is too long to fit on one line, that
> line still needs to end with "]:" to be valid.
>
>   #+CAPTION[very very ... long "short" caption]:
>   #+CAPTION[continued even here]: long caption
>   #+CAPTION: long caption continued.
>

This is something, that I had not thought about when I expressed my
wish.  I did not even know, that consecutive #+CAPTION lines could also
have consecutive short captions.  I see the difficulty here.

Usually, my votes are in favour of backwards compatibility.  So, I am
not too sure about this suggestion myself: But here an obvious
'solution' would be to move the short caption to #+SHORT_CAPTION.

I see that such change would bring its own difficulties besides breaking
the backwards compatibility.  Like what to do when there is a short
caption but no 'long' caption.

I am just continuing this discussion, as I do not have 'the occasional
three lines caption need' but the 'always multi-lines caption need'.  In
my opinion, images in an article/paper/thesis/... should tell their
story independently of the text referring to them.  So, my captions
tend to be (too?) long.
So, I would benefit a lot from whatever filling mechanism might get
implemented.

[...]

Regards,
Andreas

Re: Feature request: filling of long captions

[Bastien]

Andreas Leha <andreas.leha@med.uni-goettingen.de> writes:

> But here an obvious
> 'solution' would be to move the short caption to #+SHORT_CAPTION.

Yes.  #+CAPTION[...]: is clumsy.

-- 
 Bastien

Re: Feature request: filling of long captions

[Nicolas Goaziou]

Bastien <bzg@gnu.org> writes:

> Yes.  #+CAPTION[...]: is clumsy.

It follows #+RESULTS[...]: model.

-- 
Nicolas Goaziou

Re: Feature request: filling of long captions

[Bastien]

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

> Bastien <bzg@gnu.org> writes:
>
>> Yes.  #+CAPTION[...]: is clumsy.
>
> It follows #+RESULTS[...]: model.

Which I feel clumsy too :)  No offense to either Eric or you.

The important difference is that #+RESULTS[...] is generated,
while #+CAPTION[...] is manually entered.  As a user, I'm more
tolerant to generated clumsy syntax than to the one I need to
*learn*.

Anyway, that's kinda bikeshed for now.

-- 
 Bastien

Re: Feature request: filling of long captions

[Eric Schulte]

Bastien <bzg@gnu.org> writes:

> Hi all,
>
> Nicolas Goaziou <n.goaziou@gmail.com> writes:
>
>> I'm sure this idea wouldn't be a net benefit for Org syntax clarity,
>> even for the occasional three lines caption need.
>
> I agree.
>
> Nicolas, what do you think of enhancing the auto-filling (and
> delete-indentation) capabilities for some affiliated keywords?
>

I did not realize that consecutive caption lines would be merged.  This
largely addresses my problem (no more Org-mode files going to column
600).

If Org-mode had been thoughtful enough to autofill my #+Column lines as
they got too long then I would have been completely satisfied.

Thanks,

>
> #+CAPTION:
> #+HEADER:
> #+TBLFM:
>
> The last two would require special auto-filling functions,
> but at least for #+TBLFM I see the point of enabling this.
>
> Thanks,

-- 
Eric Schulte
https://cs.unm.edu/~eschulte
PGP: 0x614CA05D