Confusing documentation of attributes

[chrisvire]

Comparing the documentation for \fig in 3.0: https://ubsicap.github.io/usfm/characters/index.html#fig-fig

to the new documentation for \fig: https://docs.usfm.bible/usfm-usx-docs/latest/fig/fig.html

1. The new documentation has confusing @attribute stuff. For someone new to USFM, what are they supposed to do?

2. There is no explanation about required vs. optional attributes. In the old documentation, there was a statement:

Required attributes are indicated in the list below with a red asterisk *.

This is missing from the new documentation. There are asterisks after the attribute names, but no explanation that it means they are required. I actually missed the fact that they were there until someone pointed them out.

[chrisvire]

Any comments?

[KentSpiel]

I think the content | @attr syntax should me mentioned here: https://docs.usfm.bible/usfm-usx-docs/latest/char/attributes.html along with how required and optional attributes are marked. I also suggest that we put an asterisk after the required attrs and add the line: Required attributes are indicated with an asterisk *.

Syntax

Required attributes are indicated with an asterisk *.

• USFM: \fig caption|@src* @size* @ref* @alt @loc @copy\fig*

• USX: <figure style="fig" @file* @size* @ref* @alt @loc @copy>caption</figure>

src (USFM) / file (USX)

Filename

size*

Illustration relative size. Options are col (illustration should be inserted inline within the current text column) or span (illustration should be inserted across – 'spanning' – text columns).

ref*

Scripture reference (e.g. Luke 19.5). This text may (optionally) be published together with the illustration caption.

alt

Short, free-form description of image.

. . . .

[klassenjm]

@chrisvire Thanks for reviewing and comparing the documentation (old and new), and sharing this feedback. I've been working on the new documents -- endeavoring to harmonize the USFM, USX, and USJ (at least USJ examples). It's been slow to get to completion recently -- just due to other work. I can take your feedback and Kent's suggestions (thanks @KentSpiel) and work at some improvements. I understand your points, and I'll try to get back to this soon.

[klassenjm]

Updates:

• There is a new documentation syntax page in the introduction.
• The Introduction section sub-pages are shown on the landing page (i.e. the reader would see sooner that this background info exists)
• On every page where there is a markup description, the 'Syntax' heading links to the documentation syntax page, as a help.