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

[Sivakatirswami]

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

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)

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.

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)

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

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..."

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
>>
>
>