Support for Device Frames

[ronnqvist (David Rönnqvist)]

@ethankusters

@Lancelotbronner

how about:

@Image(source: “images/example.png”) {
    caption for the image here
    @DeviceFrame(*params*)
}

Thank you for bringing this up! It's definitely something we should consider and there's a lot of precedent for this in Tutorials. @Chapter for example takes an optional Image directive as a child but the @Image isn't rendered inline, it's instead configuration for an image associated with the Chapter itself.

Thinking about this some more. I'm leaning towards this as the preferred syntax among what's currently available. Like you pointed out there's a really strong precedent for this from Tutorials and I'm not convinced that device framing is special enough that it should deviate from this convention.

@ethankusters

Again though, I'd refer to my earlier point:

@ethankusters

It's less discoverable to the user but is more composable and easily expanded upon. So in order to justify the reduced discoverability and usability we should have an idea of how that composability and expansion might be used in the future.

I don't think that this feature (especially in its experimental phase) justifies introducing a new way of writing directives to DocC articles. I'd really like to ensure that the directive use in DocC articles is consistently approachable and understandable without much prior knowledge – this isn't true for Tutorials but Tutorials justify that by offering a significantly different and more powerful user-experience.

It's true that this convention is new to DocC articles but it's frequent in Tutorial content.

From what I understand from the pitch device frames would be supported in both articles and in tutorials. I don't think it's a good idea to have different syntax for directives in articles and tutorials and I don't think the device frame is special enough that it should deviate from the established patterns for tutorial content.

---

We may want to have a broader conversation about directive syntax in articles but I think that should be its own dedicated topic, outside the scope of a pitch for a specific directive addition.

[jack (Jack Lawrence)]

Tutorial directives, and in particular children that influence parents, are possibly my biggest syntax regret FWIW