Beefy Boxes and Bandwidth Generously Provided by pair Networks
Don't ask to ask, just ask

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

by Arunbear (Prior)
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

Replies are listed 'Best First'.
Re^2: RFC: Proofread the POD for my HTML elements module
by Lady_Aleena (Curate) 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

        I adapted your example for my needs ;-)...

        #!/usr/bin/env perl use strict; use warnings; use HTML::HTML5::Builder qw[:standard]; my @things = ( "Sex", "Drugs", "Rock and Roll", "Charlie Haden", ); print html( -lang => 'en', head( title('My Favorite Things'), Meta( -charset=> 'utf-8' ), ), body( h1('Testomato'), p('My Favorite Things...'), ul( map li($_), @things ), ), ); __END__

        ...and get:

        karls-mac-mini:monks karl$ ./ <!DOCTYPE html> <html lang=en> <title>My Favorite Things</title> <meta charset=utf-8> <h1>Testomato</h1> <p>My Favorite Things... <ul> <li>Sex <li>Drugs <li>Rock and Roll <li>Charlie Haden </ul>

        Ooops! Omitting end tags needs getting used to (was so in HTML 3.2) but the missing body tag is a big surprise as i requested it with body(# stuff).

        And this validator tells me that the generated html is valid.

        I found in a hurry Is it necessary to write HEAD, BODY and HTML tags? Ok, i wasn't aware of this.

        It is like it is. Or is there any chance/way that i can get a body tag?

        It's just because i'm inured to have it ;-) And in my opinion the generated html looks really strange without it.

        Update: Yes sure - DOM Tree view in Safari gives me what i want...

        <!DOCTYPE html> <html lang="en"> <head> <title>My Favorite Things</title> <meta charset="utf-8"> </head> <body> <h1>Testomato</h1> <p>My Favorite Things...</p> <ul> <li>Sex</li> <li>Drugs</li> <li>Rock and Roll</li> <li>Charlie Haden</li> </ul> </body> </html>

        Best regards, Karl

        «The Crux of the Biscuit is the Apostrophe»

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

        everybody can't not to resist to reimplement like :)

        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?

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

How do I use this? | Other CB clients
Other Users?
Others about the Monastery: (5)
As of 2018-03-17 22:38 GMT
Find Nodes?
    Voting Booth?
    When I think of a mole I think of:

    Results (227 votes). Check out past polls.