Direct Answer
To provide a rendering path that preserves structural semantics for screen readers, perldoc should implement an opt-in --accessible flag. This flag would trigger a formatter that emits plain text augmented with lightweight semantic markers (e.g., # for headings, - for lists, and ``` for code blocks). To maintain backward compatibility, this must be a strictly opt-in feature that does not alter the output of existing --text or --nopager commands.
Technical Explanation
Currently, perldoc relies on Pod::Text for terminal output and Pod::Html for browser output. Pod::Text focuses on visual layout (indentation and line breaks), which screen readers often interpret as flat text, losing the hierarchy of the original POD (Plain Old Documentation). Pod::Html provides structure but often lacks the specific ARIA roles needed for high-quality assistive technology navigation.
A structured plain-text mode fills this gap by providing a predictable, machine-readable syntax that screen readers can announce as structural changes without requiring a full browser environment or breaking existing terminal-based workflows.
Implementation Steps
- Create a Formatter Subclass: Develop a
Pod::Text::Accessible class that overrides standard output methods to inject semantic prefixes (e.g., ## for level-2 headers) instead of relying solely on whitespace.
- Integrate CLI Flag: Add the
--accessible option to the perldoc script. When active, it should force the use of the Pod::Text::Accessible formatter and imply --nopager to ensure the markers are delivered directly to the assistive tool.
- Environment Variable Support: Implement support for
PERLDOC_ACCESSIBLE=1 to allow users to enable this mode globally across their environment without modifying every command call.
- Coexistence Logic: Ensure the logic follows a priority chain: if
--accessible is absent, perldoc defaults to standard Pod::Text behavior, ensuring no breakage for scripts parsing --text output.
Verification and Safety
To verify the implementation without impacting existing systems, use the following scoped commands (assuming a Perl 5.32+ environment):
# Verify semantic markers are present
perldoc --accessible List::Util | grep -E "^#|^```"
# Ensure standard text output remains unchanged
perldoc --text List::Util > standard.txt
perldoc --accessible List::Util > accessible.txt
diff standard.txt accessible.txt # Should show differences (markers added)
Assumptions and Uncertainty
- Assumption: It is assumed that the target users prefer a Markdown-like structural syntax, as it is widely recognized by modern screen readers.
- Uncertainty: The exact markers (e.g.,
# vs *) may require further validation with actual screen-reader software to ensure they are announced as structural elements rather than literal characters.
Missing Diagnostic Detail
To finalize the implementation, please specify the minimum supported Perl version. If support for versions prior to 5.32 is required, the subclassing approach for Pod::Text may need to be adjusted to accommodate older API signatures.
perl