Re^2: Where to place POD

Replies are listed 'Best First'.
Re^3: Where to place POD by Bod (Parson) on Jan 15, 2024 at 19:20 UTC
Is writing POD necessary when one is publishing a module or is it optional? It is both necessary and optional! It is perfectly possible to publish a module to CPAN with no POD at all. CPAN allows this. But if users have no idea how to use a module, they won't use it... If users are not going to use it, why bother publishing it? So, treat POD as mandatory for all modules you are going to publish. Would you use a module if you were given no clue about what it does or how you make it do anything?	[reply]
Re^3: Where to place POD by Polyglot (Chaplain) on Jan 15, 2024 at 03:39 UTC
You need some POD. The online documentation that you see on CPAN is harvested from the POD embedded within the module. I'm not experienced enough to know how to publish that portion via strictly HTML or some other format. A PDF would be useful for a larger or more complicated explanation, but there is nothing stopping one from linking to a PDF within the POD. POD has its own styles for markup, but HTML can be used within POD if specified. One may get an idea of how a module will be shown on CPAN via this POD renderer: https://metacpan.org/pod2html I found it to be close, but not perfect; in my case requiring some later adjustments to manipulate the final formatting of the displayed POD. The formatting codes, including illustrations for how to embed HTML, are available here: https://perldoc.perl.org/perlpod Blessings, ~Polyglot~	[reply]
Re^4: Where to place POD by mr_ron (Deacon) on Jan 15, 2024 at 14:48 UTC
Maybe helpful documentation on embedding HTML or other mark(up\|down) ... "Perl::Examples::POD::HTML - Embedding HTML in POD - metacpan.org" Perl::Examples::POD::HTML Ron	[reply]
Re^4: Where to place POD by harangzsolt33 (Deacon) on Jan 16, 2024 at 01:35 UTC
Thank you, Polyglot and Bod. This is very useful information here. I am going to try to bookmark it somehow.	[reply]