Talk: Document

Discussion opened by CQ • 08:44, 9 October 2006 (UTC)

Documenting code in MediaWiki[]

OK. I did this page manually. There MUST be a better way. Most modern text editors use XML to text highlighting for selected filetypes once you give them an extention: .html, .pl, .php, .cgi, &....

I'm not sure yet if pod2wiki and other MediaWiki stuff on CPAN can do this or not. I haven't gotten that far yet myself. Anyone else been here?

I did it like this:

 <font color="Brown">if</font> (<font color="Green">$leapyear</font>) {<font color="Green">$MonthDaysFeb</font>=29}
 <font color="Brown">else</font> {<font color="Green">$MonthDaysFeb</font>=28}
 
 <font color="Green">@Months30</font>=(<font color="Tomato">'Apr'</font>,<font color="Tomato">'Jun'</font>,<font color="Tomato">'Sep'</font>,<font color="Tomato">'Nov'</font>);
 <font color="Green">@Months</font>=(<font color="Tomato">'Jan'</font>..<font color="Tomato">'Dec'</font>);
 
 <font color="Brown">foreach</font> <font color="Green">$month</font> (<font color="Green">@Months</font>) {
  <font color="Brown">chomp</font> <font color="Green">$month</font>;
   <font color="Brown">unless</font> (<font color="Green">$month</font>==<font color="Tomato">'Feb'</font>) {
    <font color="Brown">unless</font> (<font color="Green">@Month30</font>) {
     <font color="Green">%MonthDays</font>=(<font color="Green">$month</font>=>(1..31)}
    <font color="Brown">else</font> <font color="Green">%MonthDays</font>=(<font color="Green">$month</font>=>(1..30)}
   <font color="Brown">else</font> <font color="Green">%MonthDays</font>=(<font color="Green">$month</font>=>(1..28)}
  <font color="Green">%Year</font>=(<font color="Green">@Months</font>=><font color="Green">%MonthDays</font>)}

Whew! What a pain in the &...!

Pasting code strait into a wiki editor is fine as long as you put that space at the beginning of each line and don't mind it showing up uncolorized. You can run the code with the spaces in place and perl's compiler don't care, 'cuz it ignores white space with one exception:

=pod

=pod

 This is *plain old documentation*
 which appears to humans reading the
 code but not to the perl compiler.

 That is *if* you obey the rules. 
 See _perlpod_ for the scoop.

=cut

perlpod (documentation on POD for people writing documents in it)
perlpodspec (documentation on POD for people writing parsers for it)
The Perl manpages in raw POD format can be viewed at [1].
The directory [2] contains many modules with embedded POD formatting.

User:nwclark could be here soon to help with all of this. I'll go ahead and welcome him in advance! ;) &... CQ 09:19, 9 October 2006 (UTC)

Brown and the Green Tomato Blues[]

Here's a cool color scheme that mimics gedit, BlueFish, emacs, &...:

statement
$Scaler
@Array
%Hash
"quoted string"
#comment
=pod

 Your documentation here, please.

=cut

The crude syntax:

 <font color="Brown">statement</font>
 <font color="Green">$Scaler</font>
 <font color="Green">@Array</font>
 <font color="Green">%Hash</font>
 <font color="Tomato">"quoted string"</font>
 <font color="Blue">#comment</font>
 <font color="Blue">=pod
 
  Your documentation here, please.
 
 =cut</font>

Just in case you're a glutten for punishment ;) CQ 09:40, 9 October 2006 (UTC)