|
in reply to Re^2: RFC: Proofread the POD for my HTML elements module
in thread RFC: Proofread the POD for my HTML elements module
Hi Aleena, I have had another look now, and I think the key word in review is consistency.
The $tab is a code impelmentation, and as such does not really fall within the scope of the op. The importance lays with the expected usage being documented in an easy to understand way.
In respect of paragraphs functions, I was not suggesting to split the code. Consistency would confer that all exported (default or optional) functions recieve a description in the Pod. So describe the paragraph function, then describe the sparagraph function, even if that description is 'see #paragraph function'. This is fairly common in Pod. However the important point is that now I can navigate to each function description from the index, or anywhere else I happen to be. I would also like to know how to pass sparagraph to other functions, from the current description I think sparagrah is essentially an array of paragraph function. What is sparagraph, how is it different from paragraph, what do I need to do to implement it? Should I implement it?
Scanning through the headings, the 'setting the ...' headings under table suddenly switch from =head3 to =head4 and then the =head4 setting remains for what were previously =head3> headings.
The export of routines, is an implementation consideration, I am unsure you have achieved what you intended. Unless you have intended there are no functions exported by default? The main difference is that exporting no functions is an OO (Object Orientated) approach, whereas the module you have created is functional, so would be expected to export a default list of functions. This also helps by allowing the user to know which functions make up the interface, and which are used by the module itself. For example, if the module tracked a variable value through the use of internal functions. Which then altered the behaviour of the interface functions in a documented way. The user would not expect their program to break if they only use the documented (exported) functions, but if they tried to access the variable value themselves and their program broke after a module update. They get downvotes.
|
Re^4: RFC: Proofread the POD for my HTML elements module
by Lady_Aleena (Priest) on Apr 20, 2013 at 21:17 UTC
|
Don Coyote, I will add a section for sparagraph. I only go to =head4 in three places because they go with the preceding =head3.
I have been told by some not to export functions by default. Most of the time I export default functions only when there is one function in the module. The list of functions exported upon request is in the synopsis.
I am sorry to say, the last paragraph about tracked variables is confusing.
Have a cookie and a very nice day!
Lady Aleena
| [reply]
[d/l]
[select] |
|
|
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.
| [reply]
[d/l]
[select] |
|
|
Pod. I put pod =head2 headings above each of the exportable routines in the code. I am not sure this is any easier to read, but you can see which pod relates to which part of code. I then cut and paste your pod over into the relevant spaces, and where there were conflicts just pasted your pod as is. This may help to show where the function descriptions and general module implementation descriptions and examples need to be refined.
changed use base 'Exporter'; to use Exporter qw(import); not extending import so no need to become an Exporter.
Tabs. extending the import routine may have been overkill. using deparse to get at teh child elements may not be overkill, rather it may be necessary, but in reality highlights ineffective code.
I quite like the idea of extending the import and using a pragma to set a module variable. But for simplicity, I have converted this into a settable variable.
The idea is that whenever you would call $tab in the module code to open a tag you now call the tab ascenscion routine, $ref to (CODE) to return the increased level, and the the same for descenscion, but a different $ref to (CODE)
Now the user only has to set the $HTML::LadyAleenaStyle::inlvl variable to a suitable number. Because in the Module you replace the $tab variables throughought the element subs with calls to &$ina for ascending tab depth, and &$ind for descending tab depth. And remove $tab assignement from special array.
This still does not work perfectly, as it now only indents the parent element itself rather than the child elements. This is probably far simpler than trying to deparse code during sub calls to see what the user may have in store for us, which we probably should not be doing anyway. And, I'm just getting my head round inheritance and callbacks right now. I have also thus far refrained from viewing CGI.pm source, lest the old copy and paste button inexplicably resembles free beer.
again code untested, figurative...
package HTML::LadyAleenaStyle;
use strict;
use warnings;
use Exporter qw(import);
our @EXPORT_OK = qw(title script heading anchor paragraph sparagraph l
+ist definition_list table form fieldset legend
label selection input textarea div pre);
use HTML::Entities qw(encode_entities);
use Base::Data qw(data_file get_hash);
use Base::Nifty qw(sline line);
=head1 NAME
B<HTML::Element> generates HTML tags for most of the HTML elements.
=head1 SYNOPSIS
To use B<Element> to print HTML tags, use the following.
use Base::HTML::Element qw(
title heading script anchor paragraph sparagraph list definition_l
+ist table
form fieldset selection input textarea div pre
);
## Module Vars
=head3 C<indentation>
To print readable html, set the indentation to the level. Can be 0 - 9
+. Each level constitutes a tab space multiplier
applied to child elements (according to dominterpretation?). Default i
+s no indentation in output or 0 level.
$HTML::LadyAleenaStyle::inlvl = 7;
Each child element will be indented seven tab stops from the relevant
+parent element
=cut
$HTML::LadyAleenaStyle::inlvl = 0 unless $HTML::LadyAleenaStyle::inlvl
+; # default indentation none;
### set module variables if required in calling script.
sub in_depth {
state $level = 0; # requires Perl version 5.10
return (
sub { $level += $HTML::LadyAleenaStyle::inlvl },
sub { $level -= $HTML::LadyAleenaStyle::inlvl },
);
}
my ($ina,$ind) = in_depth;
# now replace the $tab variables throughought the element subs with ca
+lls to
# &$ina for ascending tab depth,
# &$ind for descending tab depth,
# and remove $tab assignement from secial array.
# for example in sub div:
#
# sub div{
#
# my ($code,$opt) = @_; # no $tab
# my $tag = 'div';
# my $open = open_tag($tag,$opt,[@ics,@java]);
#
# line(&$ina,qq(<$open>)); # indent depth increase
# &$code;
# line(&$ind,qq(</$tag>)); # indent depth decrease
# }
#
all the code here
| [reply]
[d/l]
[select] |
|
|
|
|
|
|
|
