Improve documentation for 'pairs' syntax and evaluate alternative encodings

[coderabbitai]

Context

The pairs key in CharLib YAML configuration files uses a space-within-element convention inside a YAML flow sequence to encode differential pair groupings. For example:

pairs: [Q QN]          # one pair: (Q, QN)
pairs: [T TN, K KN]    # two pairs: (T, TN) and (K, KN)

Each whitespace-separated group is a single YAML scalar string, so this is valid YAML — but the convention is not immediately obvious to new users and current documentation coverage is considered insufficient.

Problem

• The space-within-element grouping is not self-documenting and could surprise users unfamiliar with the convention.
• Existing documentation does not adequately explain the pairs syntax or its encoding rules.

Alternatives to consider

1. Nested flow sequences (most YAML-idiomatic for "list of pairs"):

   pairs: [[Q, QN], [T, TN]]

   Each inner list explicitly represents one pair.

2. List of maps (explicit, but verbose):

   pairs:
     - {pos: Q, neg: QN}
     - {pos: T, neg: TN}

3. Slash-delimited strings (compact, common in Liberty/EDA tooling):

   pairs: [Q/QN, T/TN]

4. Keep current syntax, but improve docs — document the convention clearly in the YAML syntax reference and add inline comments to example files.

Requested actions

• Evaluate the alternatives above and decide whether to change the syntax or keep the current approach.
• Improve documentation in the YAML syntax reference chapter to clearly describe the pairs encoding.
• Update example YAML files with inline comments if the current syntax is retained.

References

• PR: docs: Add chapter describing CharLib procedures #5
• Discussion: docs: Add chapter describing CharLib procedures #5 (comment)

/cc @infinitymdm