Beefy Boxes and Bandwidth Generously Provided by pair Networks
Your skill will accomplish
what the force of many cannot
 
PerlMonks  

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

by Don Coyote (Monk)
on Apr 19, 2013 at 19:20 UTC ( #1029567=note: print w/ replies, xml ) Need Help??


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

I'm not going to go into the major aspects as I have not yet written up POD myself, just a couple of minor points.

  • I'd like to teach the world to sing...
  • Before you go any further, if you plan on using a table for layout, STOP! Tables are for tabular data, use div elements to lay out your webpage.
    • While it is undeniably gutting to see incorrect usage, the focus of Pod is to inform the user how to implement the module. Refrain from entering ad-hoc didactions about non-related topics.

  • I'd like to teach the perlers a THING...
  • code is an anonymous sub.
    • If I don't know what that funny argument sub {} is, I could always risk asking someone on a forum, or perhaps rtfm. The presentation of the usage should make the argument requirements apparent. If you are going to describe the arguments, consider how consistently you describe them across all the method descriptions. I actually began to look for a hash key 'code' to see what value I would have to provide as an a argument before I realsied you just meant, the first argument is code - how does File::find handle that in Pod?

  • I'd like to teach the italians about drawing...
  • paragraphs, sparagraphs, spaghetti giraffes?
    • Introducing a whole new way to do something as second nature as write a paragraph element, could really do with it has it has own description. You may just be reinventing the wheel in a way that people have not considered previously, and it would be a shame to hide this away by muddling it up with the straight forward paragaraph element method. Or it may be a really bad idea, in which case it can be easily ignored or redifined, either way the paragraph separator routine, dare i say it.... needs separating

On another point more along the coding itself, why ask the user to provide the $tab argument for every method? Could you not implement this as default module behaviour, and then describe this in the Pod?

I hope these comments are helpful in your redraftings.


Comment on Re: RFC: Proofread the POD for my HTML elements module
Select or Download Code
Re^2: RFC: Proofread the POD for my HTML elements module
by Lady_Aleena (Deacon) on Apr 19, 2013 at 22:03 UTC

    Don Coyote, thank you for taking time to read it over.

    • I feel very very strongly about not using tables for layout, so I am not too sorry for my prosthelytizing. I will not go into how frames are evil however. (I will not include frames in the module.)
    • Yes, I was inconsistent when it came to the code block description, so the inconsistency has been removed.
    • With the paragraph and sparagraph descriptions, I was hoping to avoid repetition so I put them together. Separating the separator now would lead to many headaches since I have already implemented it throughout my many many pages.

    I am not sure how to determine what tab level the user is at when using the functions, or if the user wants tabs at all. A user could set my $tab = 0; and not have any tabs with any function used as follows.

    # Unwritten elements used in this example, however they will be soon. my $tab = 0; my @list = ( ['red, { style => 'color:#ff0000' }], ['green', { style => 'color:#00ff00' }], ['blue', { style => 'color:#0000ff' }] ); html($tab, sub { head($tab, sub { title($tab, 'My page title'); }); body($tab, sub { div($tab, sub { heading($tab, 1, 'My sample heading', { id => 'sample_heading' +, style => 'color:#666666' }); paragraph($tab, 'A sample paragraph so you can see how this wo +rks.'); list($tab, \@list, { id => 'colors' }); # list items will get +tabbed. paragraph($tab, 'Another paragraph for you'); heading($tab, 1, 'A second sample heading'); }, { class => 'div_class' }); paragraph($tab, 'Some end remarks.', { id => 'end_remarks', clas +s => 'remarks' }); }); });

    A user could set up the tabs like the following.

    my $tab = 0; html($tab, sub { $tab++; head($tab, sub { $tab++; title($tab, 'My page title'); $tab--; }); body($tab, sub { $tab++; div($tab, sub { $tab++; heading($tab, 1, 'My sample heading', { id => 'sample_heading' +, style => 'color:#666666' }); $tab++; paragraph($tab, 'A sample paragraph so you can see how this wo +rks.'); list($tab, \@list, { id => 'colors' }); paragraph($tab, 'Another paragraph for you'); $tab--; heading($tab, 1, 'A second sample heading'); $tab--; }, { class => 'div_class' }); paragraph($tab, 'Some end remarks.', { id => 'end_remarks', clas +s => 'remarks' }); $tab--; }); $tab--; });

    I will not force too many unwanted tabs onto a user. Make sense?

    Have a cookie and a very nice day!
    Lady Aleena

      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.

        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

Log In?
Username:
Password:

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

How do I use this? | Other CB clients
Other Users?
Others contemplating the Monastery: (6)
As of 2014-12-28 17:21 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    Is guessing a good strategy for surviving in the IT business?





    Results (182 votes), past polls