Refine Xrefstyle Rules in Disco

[AryaHassanli]

PR Description: Refine Xrefstyle Rules in Disco

This PR refines the XrefStyleOnlyInRoot feature in the disco package to enforce stricter rules for :xrefstyle: attribute management in AsciiDoc files.

Summary of Logic

The goal is to ensure consistent cross-reference styling across the specification by managing the :xrefstyle: attribute based on whether a document is a root document or a sub-document (non-root).

Rules Enforced:

1. Non-Root Documents:

   • Strict Removal: Removes all occurrences of :xrefstyle: attributes from the document, regardless of where they appear or what value they have.

2. Root Documents:

   • Ensure Presence: Ensures that :xrefstyle: basic exists in the document.
   • If missing:
     • It searches for a section with a title containing "Copyright Notice" (case-insensitive).
     • If found, it adds :xrefstyle: basic immediately after that section.
     • If not found, it adds :xrefstyle: basic before the first section in the document.
     • If there are no sections, it adds it at the top.
   • If already present: It leaves it as is (does not modify or duplicate).

Changes

disco Package

• ./disco/baller.go: Implemented the refined logic in discoBallTopLevelSection. Added TestHelperDiscoBall to facilitate testing from the tests package.
• ./disco/option.go: Kept XrefStyleOnlyInRoot enabled by default.

tests Package

• ./tests/baller_test.go: Added a new test suite specifically for this logic, covering all edge cases (root with/without copyright, non-root removal).

Verification

Ran all tests in the tests package, and they passed successfully:

go test -v ./tests/

Output confirmed that TestXrefStyleOnlyInRoot passed along with all other tests.

[gemini-code-assist]

Code Review

This pull request introduces the XrefStyleOnlyInRoot option to ensure the xrefstyle attribute is exclusively present in root documents, adding it after the copyright notice if missing and removing it from non-root files. The review feedback suggests using SectionName() for more robust title parsing, optimizing slice manipulations for better performance, and moving test-only helper functions out of the production source files.