Re: Where to place POD

For me, I have only written POD when I intended to publish the module. As some others have said, it would be an unnecessary interruption to the code which does not give me any useful information. I prefer to comment the code with things I need to remember.

For finding sections of my code, I use a heading, via comments, but one that is large and easy to see when scrolling quickly past it. This can be as simple as something like this for a function...

# -------------------------------------------------------------
#   P R O C E S S    R E P L A C E M E N T S
# -------------------------------------------------------------
[download]

...or with my HTML code to be able to easily find a section there...

<!--
#^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^
# ******* S T A R T   O F   J A V A S C R I P T S   H E R E ! ! ! ****
+***
#_____________________________________________________________________
+____
-->
[download]

...to something more noticeable for a group of functions or a section of HTML, like this:

<!--
#^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
# ******* N E W   A C C O U N T   C R E A T I O N *******
#________________________________________________________

  -----                                                               
+-----
1 | H |                                                               
+|He |
  |---+----                                       --------------------
++---|
2 |Li |Be |                                       | B | C | N | O | F 
+|Ne |
  |---+---|                                       |---+---+---+---+---
++---|
3 |Na |Mg |3B  4B  5B  6B  7B |    8B     |1B  2B |Al |Si | P | S |Cl 
+|Ar |
  |---+---+---------------------------------------+---+---+---+---+---
++---|
4 | K |Ca |Sc |Ti | V |Cr |Mn |Fe |Co |Ni |Cu |Zn |Ga |Ge |As |Se |Br 
+|Kr |
  |---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---
++---|
5 |Rb |Sr | Y |Zr |Nb |Mo |Tc |Ru |Rh |Pd |Ag |Cd |In |Sn |Sb |Te | I 
+|Xe |
  |---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---
++---|
6 |Cs |Ba |LAN|Hf |Ta | W |Re |Os |Ir |Pt |Au |Hg |Tl |Pb |Bi |Po |At 
+|Rn |
  |---+---+---+-------------------------------------------------------
+-----
7 |Fr |Ra |ACT|
  -------------
              --------------------------------------------------------
+-----
   Lanthanide |La |Ce |Pr |Nd |Pm |Sm |Eu |Gd |Tb |Dy |Ho |Er |Tm |Yb 
+|Lu |
              |---+---+---+---+---+---+---+---+---+---+---+---+---+---
++---|
   Actinide   |Ac |Th |Pa | U |Np |Pu |Am |Cm |Bk |Cf |Es |Fm |Md |No 
+|Lw |
              --------------------------------------------------------
+-----


-->
[download]

(Yes, I found that text art online somewhere and copied it...too much work to make it myself!)

Sometimes my header can be removed once active development on that section is complete. It just helps me find it at the time I am working with that section.

These headers have been my way of navigating my code more easily, as each of the 20+ files in the required codebase has over 1,000 lines on average.

Blessings,

~Polyglot~

Comment on Re: Where to place POD Select or Download Code

Replies are listed 'Best First'.
Re^2: Where to place POD by harangzsolt33 (Deacon) on Jan 15, 2024 at 01:54 UTC
I have a related question. Is writing POD necessary when one is publishing a module or is it optional? What if the author's preferred way of writing documentation is HTML format instead of POD? What if he wants to publish the documentation alongside the module in PDF book format?	[reply]
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]