Link to Syntax is easy to miss

[merchako]

Original Problem
User's may not know how to read the Syntax on a markup element page.

Attempted Solution
Turn the Syntax heading into a link to the Documentation Syntax page.

Problem
It's easy to miss, especially with the custom link color and no underline.

Proposed Solutions

• Add an information icon button that links to the same place

  <dt><a href"…">Syntax <iconify-icon icon="material-symbols:info"></iconify-icon></a>…</dt>
  

• Use more conventional (albeit not on-theme) blue, underlined link styling. See NN/g's Guidelines for Visualizing Links.

• Style your Definition List <dd> more like MDN's Technical Summary table, or else don't put Syntax (with so much content) inside a Definition List.

[klassenjm]

Added help icon after Syntax link.

[klassenjm]

Link styles for the body area has been changed to use traditional blue underline darker/no underline hover. Left navigation is unchanged. Right 'toc' link active link is bolder.

[klassenjm]

@merchako I believe I have adapted the styles here as far as necessary, for now. However - No changes have been made to the use of a definition list at this time.

[merchako]

Thank you for the color change! This is a good improvement. There's still more to do.

I like how consistent you are about styling the placeholder values (style, content, @vid), but the styles that have been chosen somehow make then more difficult to read. I believe that a code block would serve us better.

Let me take a stab at articulating something specific by suggesting a flatter way of describing syntax on these pages, modeled after MDN (example).

1. Syntax as an <h2>
2. Code blocks of pseudocode syntax in use (one each for USFM, USX, USJ)

• keywords in red
• code highlighting in appropriate language
• multiple examples of the element in use to help readers imagine the possibilities and complexities

4. Link to the Syntax explainer article under the code blocks (styled like a Caption on an image)
5. Followed by "where…" as under Syntax as a list (or under Descriptors <h3>) where you describe what the placeholders mean.
6. Maybe include a <h2>Formal Syntax</h2> section that expresses the context-free grammar in a big codeblock in some standard like Extended Backus–Naur form
7. When you find time, add examples

This format would give the meaningful aspects of the description more prominence.

I'll try to give the gist here in Markdown.

---

Paragraph-styled container

A container for context styled like a paragraph. Paragraph styles visually occupy one or more entire lines. Compare block-level elements in CSS or "Paragraph Styles" in Adobe Creative Cloud, Apple Pages, or Microsoft Word.

To style phrases within lines, consider using character styles with <Char> elements.

Syntax

<para style="paragraph-type" @vid>content</para>
<para style="p"><verse style="v"…>Jesus wen cry.…</para> /* Doesn't need @vid */
<para style="p" GEN 2:4>Dat time, wen God, da one dey call Da One In Charge, make da world an da sky.… </para> /* GEN 2:4 starts in the previous paragraph */

\p Jesus wept.

About our syntax conventions

Descriptors

style
: type of paragraph style; either identification, introductions, titles and sections, body paragraphs, poetry, lists, or tables

@vid
: a book-chapter-verse scripture reference for the current verse. Required when this para begins in the middle of a verse.

content
: content, which may include Notes (Footnotes or Cross References , Characters styles , Milestones , Figures

, or Verses .

Formal syntax

<para> 
...

How to read our formal syntax

Examples

A very simple paragraph

…

…

A verse spanning 2.5 paragraphs

…

…

---

I'm guessing this would be a big undertaking, so I invite plenty of discussion before moving forward with changes.