Bug 41634

Summary: We should add podtidy to our tidying
Product: Koha Reporter: Martin Renvoize (ashimema) <martin.renvoize>
Component: Architecture, internals, and plumbingAssignee: Martin Renvoize (ashimema) <martin.renvoize>
Status: ASSIGNED --- QA Contact: Testopia <testopia>
Severity: enhancement    
Priority: P5 - low CC: jonathan.druart
Version: unspecified   
Hardware: All   
OS: All   
GIT URL: Initiative type: ---
Sponsorship status: Unsponsored Comma delimited list of Sponsors:
Crowdfunding goal: 0 Patch complexity: Trivial patch
Documentation contact: Documentation submission:
Text to go in the release notes:
Version(s) released in:
Circulation function:
Bug Depends on: 38664    
Bug Blocks:    
Attachments: feat(tools): Add Pod::Tidy support for consistent POD documentation formatting
Bug 41634: Add Pod::Tidy support for consistent POD documentation formatting

Description Martin Renvoize (ashimema) 2026-01-15 15:07:16 UTC
I've notices a lot of inconsistency in our pod documentation and this leads to poor display in POD display tools.

We should add the podtidy tool to our xt scripts and require pod to be tidy the same way we now require everything else to be tidy.
Comment 1 Martin Renvoize (ashimema) 2026-01-15 15:36:54 UTC
Created attachment 191507 [details] [review]
feat(tools): Add Pod::Tidy support for consistent POD documentation formatting

This implements bug 41634 by integrating Pod::Tidy into Koha's development workflow, similar to how Perl::Tidy handles code formatting.

Changes:
- Add .podtidyrc configuration file with columns=120 and indent=4
- Update misc/devel/tidy.pl to run podtidy after perltidy on Perl files
- Add libpod-tidy-perl to Debian build dependencies
- Create xt/podtidy.t test to verify POD formatting
- Include .podtidyrc in Makefile.PL distribution manifest

Test Plan:
1. Install libpod-tidy-perl dependency
2. Run `./misc/devel/tidy.pl --perl` on Perl files containing POD
3. Verify POD sections are properly formatted (e.g., consistent indentation)
4. Run `prove xt/podtidy.t` to ensure all POD is tidy
5. Commit changes to trigger pre-commit hook which applies tidying automatically

Sponsored-by: Koha Community
Comment 2 Martin Renvoize (ashimema) 2026-01-15 15:38:35 UTC
Created attachment 191508 [details] [review]
Bug 41634: Add Pod::Tidy support for consistent POD documentation formatting

This integrates Pod::Tidy into Koha's development workflow, similar to how
Perl::Tidy handles code formatting.

Changes:
- Add .podtidyrc configuration file with columns=120 and indent=4
- Update misc/devel/tidy.pl to run podtidy after perltidy on Perl files
- Add libpod-tidy-perl to Debian build dependencies
- Create xt/podtidy.t test to verify POD formatting
- Include .podtidyrc in Makefile.PL distribution manifest

Test Plan:
1. Install libpod-tidy-perl dependency
2. Run `./misc/devel/tidy.pl --perl` on Perl files containing POD
3. Verify POD sections are properly formatted (e.g., consistent indentation)
4. Run `prove xt/podtidy.t` to ensure all POD is tidy
5. Commit changes to trigger pre-commit hook which applies tidying automatically
Comment 3 Martin Renvoize (ashimema) 2026-01-15 16:09:51 UTC
Hmm.. Pod::Tidy (and podtidy) appears to be rather challenging to get to install now I try..