[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