[pmwiki-users] Wiki SSI to include a Program File

Benjamin Wilson ameen at dausha.net
Sun Jul 31 18:46:12 CDT 2005


Sivakatirswami wrote:
> Aloha Ben: (we live in Hawaii)
> 
> Thank you for sharing your solution. If I may pursue one part of your  
> implementation a bit further... Ben wrote:
> 
> ------
> I required that every method used in my team's developing accompany a  
> POD-annotated description that included the method's interface. If  you 
> are using any language that allows multi-line comments (e.g.  PHP), then 
> you can use POD. This allowed me to create a searchable  web site where 
> each program file had its own page.
> ----
> The above seems to be the cornerstone of your approach. Exactly how  did 
> the team generate the "POD-annotated description"
> 
> ??
> 
> I infer, perhaps wrongly, that the reference to "POD is a very brief  
> form of text markup that can be included in the body of your code  that 
> can later be converted into HTML, RTF, or even PDF." means that

By brief, I mean it was similar to wiki markup, but not exact. There is 
B<bold>, I<italic>, and =head1, =head2, =item.

If I were to do something like POD from scratch, I would pick a wiki 
markup style (e.g. pmwiki), put it into the multiline comment, and have 
an automatic application scrape that markup. I would probably convert 
the markup into HTML and dump it, since it is automatically generated 
when its viewed on the web. However, that's a personal thing.

POD encapsulated comments between a =pod and an =cut tag (both starting 
a line). Everything between was expected to be POD marked. However, you 
might prefer to have everything that is multi-lined commentary be parsed 
out (so a single-line comment would be ignored, which allows for 
in-program comments that are more appropriate in the code). That is:

/*
This would be wiki marked up commentary for a web page
and this is too.
*/
# But this is only relevant in the internals of the program
# so I would mark it this way.

> a) you asked everyone to copiously comment his program copiously  (yes, 
> we use Revolution-xTalk and it allows multi- line comments and  yes, 
> would be easily parseable and output to HTML-web formatted page)

The core requirement was that all functions and methods be well 
described. That would include what was expected on input and the 
expected output, as well as what went on internally. The "Internals" was 
  meant to be general as the code should be able to speak for itself. 
However, if one did not know the function they should be able to figure 
out if they needed it, and know where to go to find out more.

Programs likewise were meant to have documentation. CLI programs had to 
have good help documentation, as well as POD notation. When we had 
groups of functions (e.g. DBI), then there was documentation that 
explained how it all worked.

> b) then you simply ran another program that dumped this into a second  
> POD (web page) file? i.e. you kept the DRY principle (our goal too)  
> even though you had two instances of the data i.e. the POD file being  
> simply a kind of mirror or window on the root file which was the code  
> itself and its copious comments.

Yes. Perl has its own batch of POD-to-format modules. However, it is 
possible to have any langauge do so. However, the "lazy-by-efficiency" 
approach left me to use what Perl already had.

The POD-to-HTML program originally ran via cron every so often. It 
simply recursed the software's directories and built the HTML files in 
the web area and built an index.

It was DRY in that the author maintained the documentation in one place, 
and that place was well established as the cron-app told you where the 
source of the POD notation came from (and told you it was an automated 
method). We also had POD files explaining this.

> c) Then "above" all that like  metadata for the entire project, you  had 
> other project documentation... well, working backwards I already  have 
> this (c) on our collaboration wiki, what's missing is a) and b)

Yeah, we didn't start using a wiki until I left--and that was limited to 
user-specific documentation. We would explain in layman's terms what was 
going on, since most of the system was supposed to be automated.

> But, I'm not sure if I understood you correctly.

I think you did--which is a miracle because I'm typically hard to 
follow. Just ask my wife, who routinely has to translate what I say into 
English--and I'm a native born English speaker. :-)

> Thanks for taking the time to examine this.  Overcoming the  resistance 
> to actually writing the documentation  is a challenge know  what will 
> happen "sorry, if we all die before lunch, tough luck, you  can all 
> start from scratch..."

Documentation is always hard to enforce. I was lucky in that when the 
project started I was solo. I was allowed to set things up as I 
needed--so I could easily enforce my own system. As I got to interview 
prospective new-hires, I was able to ensure I had team players. When 
they started working, they saw what was there and just accepted it 
needed to happen. It's always harder after the project has begun.

However, a good way to start it is to have people document each new 
class/method/function or to document those that were previously 
undocumented that they are using. So, for example, if you have an 
established DBI class that is undocumented, as a person uses a method he 
goes in and documents it. It adds a little time, but it allows for 
gradually documenting those methods/functions that are more frequently used.

Although, I think we're straying off topic for wiki. I'm more than happy 
to carry this off-forum if you want to discuss this further.

Ben

> Sivakatirswami
> 
> 
> 
> 
> On Jul 30, 2005, at 9:51 AM, Benjamin Wilson wrote:
> 
>> I believe I have dealt with your exact problem. I managed a small  
>> development team and we needed web-accessible documentation.  However, 
>> we wanted to ensure the documentation kept current with  the code. 
>> There's a thing called the DRY principle (Don't Repeat  Yourself).
>>
>> The first thing is it would be great _if_ you could write self- 
>> documenting code. That is, code that intuitively tells the reader  
>> what is happening. However, that is not always effective.
>>
>> Perl uses a type of markup called POD (Plain Old Documentation).  POD 
>> is a very brief form of text markup that can be included in the  body 
>> of your code that can later be converted into HTML, RTF, or  even PDF.
>>
>> I required that every method used in my team's developing accompany  a 
>> POD-annotated description that included the method's interface.  If 
>> you are using any language that allows multi-line comments (e.g.  
>> PHP), then you can use POD. This allowed me to create a searchable  
>> web site where each program file had its own page.
>>
>> However, we did not implement a way of presenting the code inline  
>> with the POD.
>>
>> We also included project level documentation in POD as well. So,  for 
>> example, we had a DBI interface that was fairly intricate. We  never 
>> wrote a stitch of SQL in our program, sending it to the DBI  interface 
>> that would turn the data structures into SQL. (Okay, some  of the more 
>> complex WHERE clauses had to be spelled out.) To keep  it organized 
>> and modular, we kept the DBI calls in a half-dozen  different 
>> files--one for user interface, another for a different  interface. 
>> These files were in their own directory (named 'dbi',  naturally). In 
>> that directory, we had an overview POD file that  explained how the 
>> DBI worked, how to call it, design concepts  (i.e., why we did it in 
>> such a crazy way). The goal was that if the  entire team died on the 
>> way to lunch, a new team could go and read  the HTML documentation and 
>> pick up quickly.
>>
>> This way, developers who were changing code in that directory had  the 
>> documentation there, too, and could quickly update it. All this  was 
>> stored in CVS as well.
>>
>> So, I don't know if you need a wiki for this.
>>
>> Ben
>>
>>
>>
>> Sivakatirswami wrote:
>>
>>> I would like to use PMWiki for documentation, but not duplicated   
>>> program code, which could change.
>>> I'm sure this is an ancient "problem" and solutions have already  
>>> been  worked out -- a philosophical search for the best way to  
>>> manage  software development and documentation:
>>> OK, a concrete scenario envisioned...  has
>>> Page A on PMwiki details a series of processes. Or a completed   
>>> functional specification where some body of the code that  
>>> implements  that plan has already been written and is in use.
>>> _among them are references to a CGI (s and other "live" programs  on 
>>> a  web server) in the ./cgi-bin which is one level up from the  
>>> docroot  where pmwiki lives and is being served.
>>> -- I would like to be able to make some kind of link that would   
>>> dynamically pull in that code from that CGI for viewing the wiki,
>>> Page B we see the code but
>>>   a) the code cannot be tampered with directly.
>>> b) if the person in charge of that CGI (or any program for that   
>>> matter) makes a change, the next time you go to the wiki and click  
>>> on  the above link you will see the same CGI but with its'  
>>> updates...  this is kind of like an SSI inside a non-editable wiki  
>>> page or  section of a page.
>>> I think you get the idea... responses to this could also suggest   
>>> other strategies for the achieving the same goal. I find RCS a  good  
>>> model, for programmers who are actually modifying the code,  
>>> checkin,  checkout, checkin with comment.... But it requires cmd  
>>> line check  savvy and a terminal session if you want to review  
>>> comments.
>>> The bigger issue is: the program code is completely disconnected  
>>> from  the larger body of documentation surrounding the project, of  
>>> which a  small program or CGI is only a part.  Sometimes  
>>> "documentation" is  more properly placed as comments in the code  
>>> itself, duplicating this  documentation in another context means  two 
>>> instances of the same data  = headache...
>>> if I go in and work on a major upgrade to the CGI, where comments  
>>> are  critical for all to understand what it does...I would then  have 
>>> to  duplicate this explanation outside in the documentation.  But 
>>> then it  become unintelligible without the code itself forcing  you 
>>> copy the  entire CGI to the wiki... but then if you edit the  CGI...  
>>> go back  and update the docs...  you get the picture.  There's got to 
>>> be an  easier way.
>>> Thanks
>>> Sivakatirswami
>>> _______________________________________________
>>> pmwiki-users mailing list
>>> pmwiki-users at pmichaud.com
>>> http://host.pmichaud.com/mailman/listinfo/pmwiki-users
>>>
>>
>>
> 
> 
> 
> 
> 





More information about the pmwiki-users mailing list