Beefy Boxes and Bandwidth Generously Provided by pair Networks
XP is just a number

Re^7: RFC: Proofread the POD for my HTML elements module

by Lady_Aleena (Deacon)
on Apr 24, 2013 at 04:21 UTC ( #1030270=note: print w/replies, xml ) Need Help??

in reply to Re^6: RFC: Proofread the POD for my HTML elements module
in thread RFC: Proofread the POD for my HTML elements module

I have made changes since my original post and more are forthcoming when I get inspired. So I do not make this thread any longer than it already is, I created a gist on GitHub. Now onto some comments.

  1. Did you know by mixing the POD in with the code, you added two pages worth of scrolling? With each =cut and the blank line after it, you added that much more scrolling. The code with the POD at the end is already 854 lines long. Adding another 70+ lines and 25% of a kb makes getting around the file more work. (If you have read my home node, file size still matters.)
  2. You have =head3 Setting up the list items before =head2 C<list>. The =head3 would be viewed as part of the =head2 C<paragraph> above it. My head levels were not arbitrary, they are written for (PO)document structure.
  3. Any element not exported does not get a POD heading for it.
    • title - set with the title parameter in head.
    • item - used in the list function.
    • term - used in the definition_list function.
    • definition - used in the definition_list function.
    • cell - set with the rows parameter in table.
    • row - set with the rows parameter in table.
    • col - set with the cols parameter in table.
    • cols - written but unused.
    • legend - set by the legend parameter in fieldset.
    • label - set by the label parameter in selection, textarea, and input functions.
    • option - used in the selection function.
  4. $tab and a tabindex are mutually exclusive. tabindex would be an optional parameter in anchor, input, selection, and textarea.
  5. Comments are supposed to be little things, so one # and a space are enough. I think most text editors these days have syntax highlighting, so long strings of # are not needed.

Reading the POD in POD Checker would show you why I set up the POD as I did. You will see my document structure in all its glory. Any time I write a POD, I always check it with the POD checker.

I am not getting how your tabbed lines work. I have not tried it yet, since it is a major paradigm shift.

Have a cookie and a very nice day!
Lady Aleena

Replies are listed 'Best First'.
Re^8: RFC: Proofread the POD for my HTML elements module
by Don Coyote (Pilgrim) on Apr 26, 2013 at 13:03 UTC

    I agree with your module need criteria. Being faced with 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, 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.

      I tried mixing @EXPORT and @EXPORT_OK. I had to call the default function anyway in the qw(), so it is one or the other, not both.

      1. You figured right, it was an oversight. legend and label should have been removed from the @EXPORT_OK list. I had not gotten to it. Also, definition_list is exportable, however I have not rewritten it to be like the others. It has data gathering in it which is very specific to my site. I need to make it more generally useable.
      2. tabindex has been added to the appropriate elements. :)
      3. I will save bytes where ever I can, so if it means my comments are little, I am okay with it.

      If you think this has the goods to ever be uploaded to CPAN and get users, then by all means play around with making default tabbing at your leisure. anchor and pre are the only elements which do not get tabbed. The former is an inline element, and the latter is special (any tabs before the end tag are part of the output, which is not good). Please remember to hunt down every $tab. Also, if you do it, please add the tabbing code here with maybe an example of one element, but also fork the gist. :)

      PS. I am still trying to figure out how to get rid of the use of &$code. I am not really happy with it in the five elements it is used in.

      Have a cookie and a very nice day!
      Lady Aleena

        i have removed the tabs, and on test running discovered a bigger problem

        using the synopsis example provided, You can clearly see that html passes a tab value, and then a CODEREF. However the html function itself expects two values. And proceeds to behave as if no coderef was even passed to it.

        As this is a major obstacle, going beyond the implementation of tab indentation, I think it would be a good idea to get your take on this. Did your synopsis run through the module ok for you?

        short while passes...

        Ok I just saw your thread on coderefs, so you are aware of this. The solutions provided are fairly robust. I have also been thinking about alternate approaches.

        What though is the problem? At this stage I see the 'problem' to be twofold.

        1. HTML is being programmatically produced
        2. What are you doing differently to existing modules?

        The first point is something that I keep getting told is the most relevantissue, so should be borne in mind throughout the process. Is this module necessary, does HTML require to be programmatically produced etc..

        The second point underlies what i think is the main source of bafflement in this task. Why? are you passing coderefs?

        And how would the module provide an advantage to a user over staticly writing HTML? Or more appropriately, using an existing module?

        I think the issue to confront is, what does the user want to do, and what does the module provide. I have some thoughts inspired by hacking on your module, and from experience of HTML production. I think they could tie in easily at this stage, to produce something simpler.

        To start with, every module i see so far seems to treat the HEAD's elements as only needing one function. Yet BODY's children all get their own functions.

        And so on, HTML as a function, recieving HEAD and BODY as its arguments. Each, recursing into each childs elements function or parameters intil a swamp of refs consume all. If this is to be a functional module why not keep it functional?

Log In?

What's my password?
Create A New User
Node Status?
node history
Node Type: note [id://1030270]
and all is quiet...

How do I use this? | Other CB clients
Other Users?
Others scrutinizing the Monastery: (5)
As of 2017-02-24 10:59 GMT
Find Nodes?
    Voting Booth?
    Before electricity was invented, what was the Electric Eel called?

    Results (354 votes). Check out past polls.