Beefy Boxes and Bandwidth Generously Provided by pair Networks
No such thing as a small change
 
PerlMonks  

comment on

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

These are fine ideas, and I like them quite a bit.

Currently, there is an option to use a config file - it's just a file of Perl that's then eval() in. In the future, I don't think I want to use straight Perl.

I also say that it's an option since there's also a ProgramName::Config module, that holds all the default global configurations. What's funny, is that people do edit this directly - having them make a config file is a little beyond them - even when I give an example of one, and even, if you can believe me, have the program automatically make them one, on behalf of them, so I give two sets of directions - one that says "do edit the ProgramName::Config" file and one that says don't. Sigh.

Anyways, the people who don't, go through the ProgramName::Config file and they come to inline documentation, written in pod, something like this:

=pod =head1 $WIDGET To turn Program into a Camel, Set, C<$WIDGET> to, B<hump>: $WIDGET = 'hump'; =cut $WIDGET = 'no hump'; =cut

I will get people who will turn the variable part to this:

$WIDGET = B<hump>;

And then not understand what they did wrong. Or they'll see the example in the pod and say, "Well, it's already set to, "hump". These are the type of problems I'm having :)

It may behoove me to just simple make a doc up about editing perl files for the uninitiated, it's just has to be very smart about how you're to word these things.

I know these aren't huge problems when $Geek talks to other $Geek, no matter what $Geek->type returns. These are problems that happen when $Geek interfaces with, say, a receptionist, or a beginning website designer, or just someone that bakes cookies, in a small town, that needs the program you've created. It's almost an old world vs. new world problem. And in that case, it's time to listen to the Modern Lovers ;)


In reply to Re^2: Documentation for non-Geeks by skazat
in thread Documentation for non-Geeks by skazat

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post; it's "PerlMonks-approved HTML":



  • Are you posting in the right place? Check out Where do I post X? to know for sure.
  • Posts may use any of the Perl Monks Approved HTML tags. Currently these include the following:
    <code> <a> <b> <big> <blockquote> <br /> <dd> <dl> <dt> <em> <font> <h1> <h2> <h3> <h4> <h5> <h6> <hr /> <i> <li> <nbsp> <ol> <p> <small> <strike> <strong> <sub> <sup> <table> <td> <th> <tr> <tt> <u> <ul>
  • Snippets of code should be wrapped in <code> tags not <pre> tags. In fact, <pre> tags should generally be avoided. If they must be used, extreme care should be taken to ensure that their contents do not have long lines (<70 chars), in order to prevent horizontal scrolling (and possible janitor intervention).
  • Want more info? How to link or or How to display code and escape characters are good places to start.
Log In?
Username:
Password:

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

How do I use this? | Other CB clients
Other Users?
Others lurking in the Monastery: (1)
As of 2022-08-15 22:02 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found

    Notices?