Document how to turn off / disable all kind of captions

[Ardemius]

Hi,

I think it would be useful to add a dedicated section in the user manual explaining how to disable all kind of caption (and numbering) for figures, examples, images, etc.

Right now, we can find many mentions to using some :XXX-caption!: attributes in the document header, but all those are splitted in the whole doc.

Moreover, I think there is an misprint in some part of the answers to issues #847 and #1563, related to this point.
If you want to disable captions and numbering for ALL elements, you need to set the caption attribute in the document header, but without exclamation mark:

:caption:

On my side, it has never worked when using :caption!: instead.

Thanks,
Thomas

[rockyallen]

This is a documentation issue, so it would be better filed against asciidoctor-org.

:caption: is not currently documented. From experiment (1.5.7.1),
:caption: x
Causes table-caption, example-caption and figure-caption to be set to "x", and switches off numbering for those elements. listing-caption is not affected (possibly because the only way to display listing captions is to set listing-caption specifically?)
So you use :caption: (rather than the more consistent :caption!: or :captions!:) because it sets those captions to blank (invisible). This feels like a hack that should be deprecated, especially since the specific attributes (eg table-caption) are available, so should it be documented?
If it is to be documented, perhaps a new section "Captions" under "Enriching your content" that also points to internationalisation and section numbering.

[rockyallen]

Sorry - should have made it clear that my questions are for Dan, but I am happy to do a PR if he agrees.

[mojavelinux]

It's a bit inconsistent as to when you set the caption to blank or when you unset it. Ideally, it should always work if you unset it. Let's treat cases when that doesn't work as a bug.

The one exception is the caption attribute. That must be set to blank because unsetting it doesn't actually reverse any built-in value. But I really don't like this attribute and I would generally discourage its usage.

[mojavelinux]

This is a documentation issue, so it would be better filed against asciidoctor-org.

The documentation is going to be moving into this repository, so at this point it doesn't matter where it is filed.