Lady_Aleena has asked for the
wisdom of the Perl Monks concerning the following question:

I have just finished writing the preliminary POD for my HTML elements module to get my thoughts in order about how I wrote the functions. I have already found two functions I need to rewrite and several more which need to be written. I can use and understand the module and POD, however I am not sure others will be able to use it with what I wrote. I have checked to make sure the POD is well formed with CPAN's POD checker which is the best place to read it. I have not figured out how to get tidy output from pod2man yet.

If you have some time to spare, would you please give it a read through and let me know if I need to rewrite it to make it more understandable? Also, if I took a wrong turn anywhere in my code, I would appreciate a note.

PS. I see there is already an HTML::Element module on CPAN, so if I do ever upload this, I will have to come up with a new name.

Good morning, Lady_Aleena. I had some extra time, so let's get the ball rolling.

When I finish a module, I try to edit it as many times as possible. I usually start by running it through Deparse and perltidy, then I edit it some more and repeat the process until I'm sure that it's ready for production. Go through the script and look for obvious errors like barewords, etc.. Once the script is tidied, then run perltidy again.
Looking at the first 13 lines or so, perltidy output this:

The SYNOPSIS should give at least one example of how an end user can make use of the module.

It's also conventional to have a DESCRIPTION section that gives an overview of what the module does. There are manyexamples on CPAN that can serve as a guide.

Those who read the documentation you provide may also wonder what the rationale behind this module is? And what it does that others don't (or does better) ? Also, do you realise that templating systems have long since become the preferred way of generating HTML; e.g. see Using HTML::Template

Arunbear, thank you for taking time to read it over. I will expand the synopsis and try to come up with a description, though I thought the opening paragraph in ELEMENTS covered it.

Every time I see HTML::Template mentioned, I want to scream. It will not work for my site. I spent several frustrated hours trying to make it work. It made me so mad, I gave up trying and made my own template which is in a nice neat function.

For what it's worth, I'm entirely in agreement with you about HTML templating.

Any sufficiently mature templating language starts to exhibit signs of following Greenspun's tenth rule. It acquires bits of syntax for conditionals, looping and so on. They become Turing complete. And if I want to generate my HTML using a Turing-complete language, I've already got one right in front of me: Perl.

I do use templates occasionally. And when I do, I tend to use Text::Template which allows me to embed Perl in the templates thank-you-very-much and not some poorly designed ersatz scripting language.

But that's only occasionally; and not usually for outputting HTML, but for outputting other formats. Why? Because of the other thing I dislike about templating...

The other thing I dislike about templating is that it composes HTML using a linear, string-like paradigm, whereas an HTML document is really a tree-like structure that just happens to have been serialized down to a string.

Then I have no confidence that the end </div> tag will end up closing the initial start <div> tag. The stuff within the [% ... %] may well do something like </div><div>. It's simply a flaky way to compose a tree. If I do this:

The module really needs a revisit. The problem is that many HTML elements have names that conflict with Perl's built-ins (tr, map, etc). Right now, HTML::HTML5::Builder exports some of these as capitalized functions to deal with that issue, but I'm not especially happy with the current solution.

The fact that there's already a module with the name you chose on CPAN suggests that yours isn't the first attempt to solve this problem. It would be friendly to include a "SEE ALSO" section listing related modules, and explaining how yours is different or better.

I'm not going to go into the major aspects as I have not yet written up POD myself, just a couple of minor points.

I'd like to teach the world to sing...

Before you go any further, if you plan on using a table for layout, STOP! Tables are for tabular data, use div elements to lay out your webpage.

While it is undeniably gutting to see incorrect usage, the focus of Pod is to inform the user how to implement the module. Refrain from entering ad-hoc didactions about non-related topics.

I'd like to teach the perlers a THING...

codeis an anonymous sub.

If I don't know what that funny argument sub {} is, I could always risk asking someone on a forum, or perhaps rtfm. The presentation of the usage should make the argument requirements apparent. If you are going to describe the arguments, consider how consistently you describe them across all the method descriptions. I actually began to look for a hash key 'code' to see what value I would have to provide as an a argument before I realsied you just meant, the first argument is code - how does File::find handle that in Pod?

I'd like to teach the italians about drawing...

paragraphs, sparagraphs, spaghetti giraffes?

Introducing a whole new way to do something as second nature as write a paragraph element, could really do with it has it has own description. You may just be reinventing the wheel in a way that people have not considered previously, and it would be a shame to hide this away by muddling it up with the straight forward paragaraph element method. Or it may be a really bad idea, in which case it can be easily ignored or redifined, either way the paragraph separator routine, dare i say it.... needs separating

On another point more along the coding itself, why ask the user to provide the $tab argument for every method? Could you not implement this as default module behaviour, and then describe this in the Pod?

I feel very very strongly about not using tables for layout, so I am not too sorry for my prosthelytizing. I will not go into how frames are evil however. (I will not include frames in the module.)

Yes, I was inconsistent when it came to the code block description, so the inconsistency has been removed.

With the paragraph and sparagraph descriptions, I was hoping to avoid repetition so I put them together. Separating the separator now would lead to many headaches since I have already implemented it throughout my many many pages.

I am not sure how to determine what tab level the user is at when using the functions, or if the user wants tabs at all. A user could set my $tab = 0; and not have any tabs with any function used as follows.

Hi Aleena, I have had another look now, and I think the key word in review is consistency.

The $tab is a code impelmentation, and as such does not really fall within the scope of the op. The importance lays with the expected usage being documented in an easy to understand way.

In respect of paragraphs functions, I was not suggesting to split the code. Consistency would confer that all exported (default or optional) functions recieve a description in the Pod. So describe the paragraph function, then describe the sparagraph function, even if that description is 'see #paragraph function'. This is fairly common in Pod. However the important point is that now I can navigate to each function description from the index, or anywhere else I happen to be. I would also like to know how to pass sparagraph to other functions, from the current description I think sparagrah is essentially an array of paragraph function. What is sparagraph, how is it different from paragraph, what do I need to do to implement it? Should I implement it?

Scanning through the headings, the 'setting the ...' headings under table suddenly switch from =head3 to =head4 and then the =head4 setting remains for what were previously =head3> headings.

The export of routines, is an implementation consideration, I am unsure you have achieved what you intended. Unless you have intended there are no functions exported by default? The main difference is that exporting no functions is an OO (Object Orientated) approach, whereas the module you have created is functional, so would be expected to export a default list of functions. This also helps by allowing the user to know which functions make up the interface, and which are used by the module itself.

For example, if the module tracked a variable value through the use of internal functions. Which then altered the behaviour of the interface functions in a documented way. The user would not expect their program to break if they only use the documented (exported) functions, but if they tried to access the variable value themselves and their program broke after a module update. They get downvotes.

When putting a smiley right before a closing parenthesis, do you:

Use two parentheses: (Like this: :) )
Use one parenthesis: (Like this: :)
Reverse direction of the smiley: (Like this: (: )
Use angle/square brackets instead of parentheses
Use C-style commenting to set the smiley off from the closing parenthesis
Make the smiley a dunce: (:>
I disapprove of emoticons
Other