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

Comment on

( #3333=superdoc: print w/ replies, xml ) Need Help??

If you think that was confusing, see below...

Sticking to the op, a lot of Pod I read is interwoven with the code within which it documents. Have you tried placing the function descriptions pods above each of the relevant functions? This may help you to keep clarity with which art of the pod is document which part of the module

I thought you may have been told not to include default exports. Which is fine. However in terms of the pod, your synopsis is an example in how to import routines, rather than how to use your module. So you need to show an example of how to use the module, something like the $tab example you did earlier in this thread. The import example is also the only place where all of the user functions are listed. I think these things need to be listed in a place which says, these are the modules routines. Not as at present, being a side effect of the synopsis.

Heading away from the op and back to tabs...

Looking at the $tabs implementation. There are a couple of issues I see with this.

  • Indirectly conflicts with accessibility elements such as tabindex
  • Currently user implemented due to module author being unable to determine and implement user requirement.

In the case of accessibilty, I would propose you choose a different name for this variable.

Further to the above, consideration of accessibilty attributes and elements to be included with the first release would be advantageous. The element <noscript> I notice does not appear. Also along with [qw(id class style)] consider including [qw(role)] as a default attribute.

Tab implementation. You say you do not know what level the user requires, however, if you did know how would you approach that. To keep this as short as I can, I will just say what I think, rather than explain my thinking.

keeping use base Exporter allows you to customise the import routine. By overriding and extending the routine, you can keep all the functionality of import, and provide a layout indentation pragma to determine the user requirement.

The problem now becomes one of detecting where the indentations are required. Starting with say, wherever a sub{} argument is provided a child element is produced and therefore an indentation would be required, you could effectively determine when the indentation should be increased. Returning from the sub{} argument would indicate a return to the parent element and therefore a reduction in the indentation variable. There is what I think the strategy for indentation implementation in your module should be thinking about.

An alternative may be to apply the indentation after the HTML has been produced, if the indentation pragma has been set. Like using CGI::Pretty, or Perl::Tidy, but as a setting rather than a module. By storing the html then running it throuhgh an indent parser after.

Customising the import routine to overide and extend would go something like this:

Disclaimer: untested code, probably broken, purely figurative. In a rush gotta go..

use HTML::LadyAleenaStyle qw(:all -in1); # end -in with single digit for 'level'.
Package HTML::LadyAleenaStyle; use strict; use warnings; #use Carp; use deparse; #see corrupt code further down use base Exporter; use Base::Nifty qw(line sline); our @EXPORT = qw(html body script noscript etc); our @EXPORT_OK = qw(table form nonessential etc); my $inflag; # indentation flag for checking. my $in; # indentation depth variable. # Expect indentation flag may need to be a constant for checking. # Need to review how to set the constant correctly. sub import{ # strip out the indentation pragma from the argument list; $inflag = ($1) = grep s/^-in(\d){1}$//, @_; # untested $in = 0 if $inflag; # start indentation depth at 0 if flag set >= 1; # pass arg list to Exporter for usual behaviour; SUPER::import(@_); } # now if flag set, determine if child element and alter depth. # this code is a suggestive starting point. # the depth decrement requirements would also need to be determined. # this sub code is gibberish. sub element{ if($inflag){ if(my $indent = map ref(CODE), @_){ $in++ if( grep deparse(&{CODE}) =~ /CHILD ELEMENT SUB/ ); } } # rest of sub ... #return line($in, $open,); }

hope these comments are helpful. I tried to stick to commenting on pod aspects, but somehow diverged into the implementation. I think you wanted a little input on both though.


In reply to Re^5: 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!
  • 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, 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, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • Outside of code tags, you may need to use entities for some characters:
            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.
  • Log In?
    Username:
    Password:

    What's my password?
    Create A New User
    Chatterbox?
    and the web crawler heard nothing...

    How do I use this? | Other CB clients
    Other Users?
    Others chanting in the Monastery: (7)
    As of 2014-08-22 04:49 GMT
    Sections?
    Information?
    Find Nodes?
    Leftovers?
      Voting Booth?

      The best computer themed movie is:











      Results (147 votes), past polls