Turn off auto-number for figures in header

[kcopas]

On a related note, "block images are prefixed by a caption label (Figure) and number automatically."

I suggest we turn off auto-numbering and labelling—particularly for non-English languages, but perhaps as a default GBIF style—by unsetting the figure-caption attribute in the document header with:

:figure-caption!:

[MattBlissett]

Was the motivation for this

1. To avoid English "Figure 1" in the Spanish document. That's fixed by https://github.com/gbif/doc-openrefine-guide/commit/17e869672268f7ee4328e236c660b966b359b751 and will be fixed properly later.

2. To avoid having to change numbers (and thus the translations) when a new figure is inserted?

For this you can use crossreferences, for example:

[#img-fig-open-file]
.Open a file
image::img/es.figure-01.jpg[Opening a file,align=center]

See <<img-fig-open-file>>

Would render as "See Open a file", or in combination with customizing the cross-reference text :xrefstyle: short as "See Figure 1".

Note that the global attributes can be different for HTML and PDF.

[kcopas]

'Yes' to both of those questions.

[kcopas]

Possible third reason—auto numbering restarts when viewing source on any given subsection, so when viewing chapter subsection 2b, one sees this: https://github.com/gbif/doc-openrefine-guide/blob/master/ch02b.es.adoc

The compiled document DOES fix this automatically, but it might confuse some authors.

---

Just meant to comment, not close

[MattBlissett]

Possible third reason—auto numbering restarts when viewing source on any given subsection, so when viewing chapter subsection 2b, one sees this:

It's inevitable that GitHub's rendering will differ from our own. It will have English labels ("figure" etc) since it doesn't know the document is in Spanish.

[MattBlissett]

I've added

:xrefstyle: short

to the document's header, so a link like <<img-something>> will now show up as "Figure N" in the HTML, with a link to the figure. The figure itself needs to have a title/caption, so this is currently

.TODO This figure needs a caption

The choice of anchor, in this case img-fig-01, is arbitrary. The same issues about remembering numbers vs renumbering vs not bothering apply as for the chapter numbers.

[pzermoglio]

@MattBlissett Got a little lost here, sorry. Would it be better for me to create captions as a separate document?

[MattBlissett]

@MattBlissett Got a little lost here, sorry. Would it be better for me to create captions as a separate document?

There's no need for that, but if we're to take advantage of automatic numbering of figures, it's best if the figures have titles/captions. We can then write this:

…las acciones que OpenRefine está realizando (<<img-fig-01>>). No cierre esta ventana mientras esté trabajando con el programa.
[#img-fig-01]
.Caption text goes here
image::img/es.figure-01.jpg[align=center]

It will show as either "está realizando Figura 1", "está realizando Caption text goes here" or "está realizando Figura 1, Caption text goes here", depending what setting we give to Asciidoctor.

If we want numbers without titles, we can set the image title to something like .Figura {counter:figure}. (This is a bit of a kludge.)

[MattBlissett]

I have set this now to the simplest case, as proposed by Kyle:

:figure-caption!:

This means each figure is labelled "Figura 1", and that text will be part of the translation. Since the figures don't have their own titles, I think this is the least confusing option.