Formatting of local links in text; Lists of Figures, Tables and Examples

[larsbarring]

Formatting of local links in text; Lists of Figures, Tables and Examples

Moderator

not yet

Requirement Summary

Currently there are some formatting deficiences in local links that affects the Lists of Tables, Figures, and Examples. These need to be fixed and preferably harmonised so that the three Lists have a similar style.

Technical Proposal Summary

• The formatting of Lists of Tables, Figures and Examples should be harmonised. In my view the List of Tables and List of Examples are good (however, see below). The List of Figures should be changed to conform to these two. This is done by changing the format of the Figure captions.
• Several items are not included in the list of Tables and Figures because of formatting problems, cf. details below.

Benefits

Readers will find the information as intended by the authors.

Associated pull request

not yet (I do not have enough insight in asciidoc to initiate one)

Detailed Proposal

Tables missing in the List of Tables

• Table 7.1
• Table 9.1
• Table 9.2
• Table 9.3
• Table 9.4
• Table D.2
• Table J.1

Table caption formatting issues

• Table 3.1: -- which Example; 3.8?
• Table 3.2: -- which Example; 3.8?
• Table D.1: -- "Table D.1" is missing, and complex entry in the List of Tables
• Table D.2: -- "Table D.2" is missing
• Table I.1: -- complex entry in the List of Tables, -- contains malformed figure reference
• Table I.2: -- complex entry in the List of Tables, -- contains malformed figure references
• Table J.1: -- no table caption at all, is currently formatted as subsection "Common Conversions and Formulas"

Text issues

• Section 1.3, first sentence: -- check reference NUG for formatting (appears three times)
• Section 1.3, "coordinate variable": -- change square brackets to parentheses in "[e.g., time(time)]"
• 4.3.1. Dimensional Vertical Coordinate, first sentence: -- does not make sense, something is missing
• Check many references to "[NUG]" and to "[UDUNITS]" for consistency
• Section "Bounds Tie Point Attribute and Bounds Tie Point Variable" under ch.8.3.8: -- contains malformed reference
  to Example 8.7 ====>>> see next point
• Example 8.7 caption: -- contains malformed figure reference
• Section 8.3.10 -- table contains double "[[" and "]]"
• Appx. F, Polar Stereographic: -- internal link to Snyder not active

[JonathanGregory]

Dear @larsbarring

Thanks a lot for this careful investigation. I certainly agree that these defects should be fixed, and also that the list of figures would more useful if it contained the fig titles too. Perhaps like you, I find the asciidoc syntax rather opaque when it gets beyond obvious text formatting.

Best wishes

Jonathan