Carousel doesn't work, or ambiguous syntax

[gavinleroy]

Trying to use a carousel results in all children being shown at the same time.

It's possible I've gotten the syntax wrong due to a lack of examples, in which case I'd say: add an example :)

How I'm using it

{carousel}
> <img src="....svg" />
> {pause change-page}
> <img src="....svg" />

[nilsbecker]

I agree that a minimal example in the docs would help. It's about the nesting syntax. The following should work:

{carousel #carouselid}
>> ![first image text](firstimg.png)
> {change-page=carouselid}
>> ![second image text](secimg.png)

The point being that the outer > after the carousel tag groups the entire carousel, while the second > indicates child elements to flip through. I agree it's not obvious.

[gavinleroy]

Thanks for the pointer! I definitely wouldn't have figured that out from the current documentation ...

I may be misunderstanding what a "carousel" actually does in this context. I assumed it was: here are N children, I will show one of them at a time. Even using the above syntax I don't get that behavior, but what I wanted was a short script away and it's working great now.

[panglesd]

Indeed, sorry, many new features only have very minimal documentation! But a considerable documentation refactor, that will make it easier to add documentation for new feature, is coming.

I may be misunderstanding what a "carousel" actually does in this context. I assumed it was: here are N children, I will show one of them at a time

That's exactly that!

The only problem you had is syntactic. The carousel attribute tells slipshow that the element is a carousel: therefore it should display only its first element.
The change-page action tells slipshow to change the element displayed. The syntax is the following: change-page='~n:"<pages>" <ID>' where:

• <ID> is the ID of the carousel element. It is optional and will use the carousel it is attached to if it is attached to a carousel (in {carousel change-page='~n:...'} the action changes the page of the carousel it's attached to). You had this
• ~n:"<pages>" tells which element to display. ~n:3 for instance displays the third element when executed. ~n:'+1 +1 for instance displays the first the next element, then the next element. The syntax for <pages> is inspired from the syntax to print pages ^^. One notable is ~n:"all"which shows the next one one after the other. It is also optional and its default default is +1.

The second problem you had is how to separate a block. In

{carousel}
> <img src="....svg" />
> {change-page}
> <img src="....svg" />

the carousel contains only one paragraph, so only one children (one "page"). You should make it several children:

{carousel change-page}
> ![](....svg)
>
> ![](....svg)

(It's also better to use the markdown syntax for including images (it makes them inlined in the HTML, for a standalone file))

And if you have more files:

{carousel change-page=~n:all}
> ![](....svg)
>
> ![](....svg)
>
> ![](....svg)
>
> ![](....svg)

Warning

While testing there is a bug in the above: blank lines are treated as children, so the code above is considered as having 7 children: 4 images and 3 blank lines...

You can use the other "block separation" of slipshow:

{carousel change-page=~n:all}
----
![](....svg)

---

![](....svg)

---

![](....svg)

---

![](....svg)

----

or if you find it more readable mix the two

{carousel change-page=~n:all}
> ![](....svg)
>
> ---
>
> ![](....svg)
>
> ---
>
> ![](....svg)
>
> ---
>
> ![](....svg)

[panglesd]

By the way, I should add more examples in the doc, but sometimes it can be nice as a workaround to look at the tests: for instance for carousel it can give an example of syntax.

[nilsbecker]

Ah, I learned something. It was not clear to me from the current docs that {carousel change-page} would enable automatic change page actions on the children. i find it a bit misleading that {change-page} as child attribute does exactly what it says, while change-page at the carousel wrapper level is an overall setting; maybe the top level attributes should be called differently? change-pages ?

As a side note: because the nested blockquotes can be unergonomic I initially preferred the block separation by lines. But it seemed that without an empty line before the --- it does not work, which was confusing to me. I encountered a lot of unexpected behavior and then switched to the less ergonomic blockquotes.

[panglesd]

As a side note: because the nested blockquotes can be unergonomic I initially preferred the block separation by lines. But it seemed that without an empty line before the --- it does not work, which was confusing to me. I encountered a lot of unexpected behavior and then switched to the less ergonomic blockquotes.

Yes, that's because markdown syntax treats:

Something
-----

as a (level 2) title...

But I think I'll remove support for this alternative syntax anyway.