Beefy Boxes and Bandwidth Generously Provided by pair Networks
Problems? Is your data what you think it is?
 
PerlMonks  

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

by Don Coyote (Monk)
on Apr 26, 2013 at 13:03 UTC ( #1030825=note: print w/ replies, xml ) Need Help??


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

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.


Comment on Re^8: RFC: Proofread the POD for my HTML elements module
Select or Download Code
Re^9: RFC: Proofread the POD for my HTML elements module
by Lady_Aleena (Chaplain) on Apr 27, 2013 at 06:30 UTC

    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 Element.pm 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?

        OOPS! I did not update the example code in the synopsis. It has been updated now.

        For the other issues, here goes.

        1. You are basically asking for the history of how all of this began about six years ago. You might want to read my home node for the history.
        2. Most other HTML modules use OO. I am a function oriented person and wrote this so I could have easier to use (for me) functions.

        Do you know how big my files would be if I statically produced HTML? My site menu alone is 41.2 kb. Keeping it updated across approximately 300 pages would cripple me. When I first started, without being able to produce my site menu with programming, I would have had to quit after only a few pages (since at the time I had a space cap of 10 Mb). Perl has allowed me to keep my file sizes extremely small in some places.

        Another bit of history, some did not like seeing me printing HTML directly in my code, and others loathe my line subroutine. So a few months ago, I decided to see if I could start hiding both. One serendipitous side effect of writing this was I was separating my logic from my display, which many here have been telling me to do all along, I just had not seen how to do it. (One script I wrote was three screens long, with this module I was able to reduce it to less than one.)

        I can not speak for the other authors, so I will only speak of my own work with head and body.

        • The head of an HTML document is not printed to the screen, so the order of the elements inside it do not have to be in any particular order, so I came up with an arbitrary order for them to appear and was able to have their values assigned in a hashref.
        • The body of an HTML document is printed to the screen, so the order of the elements inside it does matter, so I could not make any arbitrary order for them to appear meaning I have to use coderefs so the elements appear on the order I (or the user) wish them to appear. body and other structural elements can have almost anything inside them. An aside could contain a ramble which includes several paragraphs and a table. A section could include several paragraphs with a list between the third and fourth paragraphs.

        Here is the template I wrote for my pages using the module...

        sub my_html_template { my (%opt) = @_; my $heading = textify(basename($0)) !~ /index/ ? textify(basename($0 +)) : 'My '.lc((split(/\//,cwd))[-1]); my $title = textify(join(' - ',($root_name,map(ucfirst,split(/\//,$r +elative_path))))); $title .= textify(" - $opt{heading}") if $opt{heading}; my $page_heading = $opt{heading} ? $opt{heading} : $heading; my $page_heading_id = idify($page_heading); $page_heading =~ s/_/ /g; html(0, { head => { title => $title, links => [map {{ rel => 'stylesheet', type => 'text/css', href = +> $_ }} get_styles($root_path.'/files/css')], scripts => [{ type => 'text/javascript', src => "$root_link/file +s/javascript/list.js" }] }, body => [ sub { nav(2, sub { heading(3,1,'Site menu', { id => 'Site_menu' }); list(4,'u',get_menu( directory => $root_path, tab => 2, color +=> 0, full => 0 ), { onclick => 'list_onclick(event)' }); link_list(3,qq($root_user off-site),%other_sites); link_list(3,qq(Reciprocated links),%reciprocated_links); }); article(2, sub { heading(3,1,$page_heading, { id => $page_heading_id }); &{$opt{code}}; paragraph(4,"Contact $link{mail}!", { class => 'address' }); # + I should use the address tag here. paragraph(4,'I am against the Internet Blacklist Legislation . +..', { class => 'address' }); }); }], }); }

        I went one step further for a lot of my pages with this...

        sub story { my ($source) = @_; my $tab = 3; while (my $line = <$source>) { chomp($line); if ($line =~ m/^</) { line($tab,$line); } elsif ($line =~ /^[1-6]\s/) { my ($heading,$text) = split(/ /,$line,2); heading($tab,$heading,$text); } elsif ($line =~ /^[bh]r$/) { line($tab,"<$line>"); } else { paragraph($tab,$line); } } }

        So, when I go to display the page, I can do this...

        my_html_template( code => sub { story(*DATA) });

        Did that cover everything?

        Have a cookie and a very nice day!
        Lady Aleena

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: note [id://1030825]
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others cooling their heels in the Monastery: (13)
As of 2014-08-01 12:43 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    Who would be the most fun to work for?















    Results (16 votes), past polls