I agree with your module need criteria. Being faced with CGI.pm when you start up in perl does kind of slow down production. A functional base HTML element Module would be a far better introduction to programatically producing html. is this what you are thinking here? However, I believe a functional module is expected to export some routines. For example I am expecting I will not have to declare I want to import html, head, body, div, paragraph at a bare minimum. I can understand you being informed not to create an import list if the module was going to be in any way object orientated, but as a functional module, no import list, does not make sense.

  1. yes you are right here, my bad.
  2. I remained consistent here. I placed a head2 above each exported function, and where your pod matched filled in, otherwise placed the approximate pod nearby in the format existing. I found that the pod was not in the same order as the source, this made finding the related pod and source cumbersome in clarity.
  3. Some of the items in the list are still in your EXPORT_OK list. I'm figuring this is just oversight at the moment. However it would be clearer if when I viewed the source I could distinguish between what a user function and an intrenal module function. I understand the convention is to include an underscore within the function name. Or more explicitly as the first character of the function name. For example, I might currently think &definition_list is an internal module function which I should not use (excepting it being in the export_ok list), but that I can import and use &legend. In this case my headaches increase and my kudos for the author decrease when the author decides to reimplement &legend behaviour. Certainly adds to the folklore...
  4. keyword being 'would'. I do not think any other optional parameter other than the prescribed values can curently be input, being validated, as they are.
  5. Pod is to the user as comments are to the maintainer, no? What I mean is, well written comments complement the source, such as CGI.pm, the comments I included in the source were meant to hint at this kind of using comments to structure the source into sections. You already started doing this with the # start/end comments. My comments are still getting the noobland translation app treatment. I will keep your point in mind.

The main principal of the tabbing is, I do not think the user wants to sit and write out tab increments and decrements. I think the user wants to the module to do that for them. What I am suggesting is that you present the user with a couple of optins how the tabs will be implemented, and they choose which they like, by setting a flag on or off. The major difference is you write an internal function to handle the implementations, based on the flag value, saving the user from having to do this. Would you like me to work on that properly? I have so far just thrown it in as an idea more than anything. I think really just need to clarify the way the variable is set, and add an actual $level return sub. I can see from your functions you have already determined some elements will be untabbed anyway such as pre, and anchor. So you are already making half the decision for the user.

The gist source is really readable and easy to navigate, good stuff.

In reply to Re^8: RFC: Proofread the POD for my HTML elements module by Don Coyote
in thread RFC: Proofread the POD for my HTML elements module by Lady_Aleena

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post, it's "PerlMonks-approved HTML":


  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.