Beefy Boxes and Bandwidth Generously Provided by pair Networks
Keep It Simple, Stupid
 
PerlMonks  

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

by Arunbear (Parson)
on Apr 19, 2013 at 14:47 UTC ( #1029529=note: print w/ replies, xml ) Need Help??


in reply to RFC: Proofread the POD for my HTML elements module

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 many examples 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


Comment on Re: RFC: Proofread the POD for my HTML elements module
Re^2: RFC: Proofread the POD for my HTML elements module
by Lady_Aleena (Chaplain) on Apr 19, 2013 at 20:38 UTC

    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.

    Have a cookie and a very nice day!
    Lady Aleena
      I mentioned ovid's node on HTML::Template mainly because he describes why templates should be preferred, but the exact templating module to use is less important.

      I also am not a fan of HTML::Template, but I have used Template Toolkit quite a bit and found it very user friendly and versatile. I suggest giving it a try.

        Arunbear, I tried TT too. Like HT, I could not get it to do what I wanted. So I came up with my own template.

        sub html { 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; print "content-type: text/html \n\n"; line(0,q(<!DOCTYPE html>)); line(0,q(<html>)); head(0, sub { links(1, [map {{ rel => 'stylesheet', type => 'text/css', href => +$_ }} get_styles($root_path.'/files/css')]); script(1,{ type => 'text/javascript', src => "$root_link/files/jav +ascript/list.js" }); }, { title => $title }); body(0, sub { div(1, sub { heading(2,1,'Site menu', { id => 'Site_menu' }); list(3,'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); }, { class => 'left' }); div(1, sub { heading(2,1,$page_heading, { id => $page_heading_id }); &{$opt{code}}; # This is where individual page contents goes. paragraph(3,"Contact $link{mail}!", { class => 'address' }); }, { class => 'right' }); }); line(0,q(</html>)); }

        It is so much easier to use then either TT or HT.

        Have a cookie and a very nice day!
        Lady Aleena

      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.

      If I have a template like:

      <div style="color:red">[% ... %]</div>

      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:

      div( ... );

      ... and div() is written to return a DOM node, and all the parameters passed to it are DOM nodes, then I know my resulting document is going to be sane.

      My own attempt to write something along the lines of what Lady_Aleena has done above, is HTML::HTML5::Builder.

      Basic usage is along these lines...

      use HTML::HTML5::Builder qw[:standard]; my @things = ( "raindrops on roses", "whiskers on kittens", "bright copper kettles", "warm woollen mittens", ); print html( -lang => 'en', head( title('Test'), Meta(-charset => 'utf-8'), ), body( h1('Test'), p('Here are a few of my favourite things...'), ul(map li($_), @things), ), );

      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.

      package Cow { use Moo; has name => (is => 'lazy', default => sub { 'Mooington' }) } say Cow->new->name

        .. HTML::HTML5::Builder...

        everybody can't not to resist to reimplement like CGI.pm :)

        I have added a lot since the original post, and since this tread is getting so long, the current code is a gist on GitHub Gist. I have not written for every possible HTML tag, only the ones I use (or got interested in while writing).

        The problem is that many HTML elements have names that conflict with Perl's built-ins (tr, map, etc).

        There are only five HTML elements (six when HTML5 is ready) which have names in conflict with Perl's built-ins, and it is an easy fix. Make the HTML element subroutine names semantic or expand them to do more.

        • link - I wrote a sub called links which gets fed an array of hashes for many link elements within the head sub as an option.
          html(0, { head => { title => 'Section 2', links => [ { rel => 'Index', type => 'text/html', href => 'index.html' }, { rel => 'Prev', type => 'text/html', href => 'Section_1.html' +}, { rel => 'Next', type => 'text/html', href => 'Section_3.html' +} { rel => 'stylesheet', type => 'text/css', href => 'my_style_she +et.css' }, ] }, body => [ sub { heading(2,1,'Section 2'); paragraph(3,'Section 2 is great!'); }] });
        • map - You could name the sub image_map.
        • select - I renamed it selection.
        • sub - Once I get the inline elements worked out, I will be able to do something like SUB<text>, hopefully.
        • tr - I named the sub row, which is more semantic.
        • time - new element for HTML5 which we will have to deal with some day. Since it is an inline element, I may be able to treat it like I would sub like TIME<20 April 2013>

        Note: I treat all inline elements differently than I do block elements, except a which is anchor when I am writing one alone.

        The great thing about writing this in Perl is the HTML element tag names do not hold us hostage. We can name the subroutines whatever we want. So, for h1 through h6 I wrote a sub called heading. For ul and ol, I wrote list (with li being item).

        I added your module to my SEE ALSO. :)

        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://1029529]
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others taking refuge in the Monastery: (7)
As of 2014-08-31 10:16 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    The best computer themed movie is:











    Results (294 votes), past polls