Forum OpenACS Improvement Proposals (TIPs): Re: TIP #54 (Proposed) Add an adp tag to handle documenting and commenting adp files.

4: Re: TIP #54 (Proposed) Add an adp tag to handle documenting and commenting adp files. (response to 1)

Posted by Tom Jackson on 03/13/04 06:15 PM

ns_register_adptag comment /comment my_comment 

proc my_comment {string tagset} {}


#or 

template_tag comment {} {}

Using <%, etc. isn't a good idea, because AOLserver will still have to read and interpret every line of the comment.

6: Re: TIP #54 (Proposed) Add an adp tag to handle documenting and commenting adp files. (response to 4)

Posted by Bart Teeuwisse on 03/13/04 08:26 PM

Tom,

I don't think that ns_register_adptag fits the bill. For one it documents a tag not a page. Secondly, the comments are not included in the ADP page it self and thus not available to editors like Dreamweaver.

Randy, naming the documentation tag allows us to extract the documentation and include it in the API browser. While TCL/ADP pages are currently not included it could be usefull to list their properties too. aD indended to create a .dat mechanism whereby one could call page 'my_page' as 'my_page.dat' and one would get the aspects of a TCL/ADP pair pertinent to a designer. AFAIK, this was never implemented. Lars' proposal to make the presentation of an OpenACS site more independent from the backend heads in the same direction. (https://openacs.org/forums/message-view?message_id=160479)

Using <doc> would allow us to improve the documentation of the ADP component, use that documentation in the OpenACS API browser or an .dat mechanism. While at the same time make the documentation available in editors like Dreamweaver. Using Dreamweaver templates one can protect the <doc> tag from modification.

/Bart

7: Re: TIP #54 (Proposed) Add an adp tag to handle documenting and commenting adp files. (response to 6)

Posted by Benjamin Bytheway on 03/13/04 09:07 PM

Actually, Bart, the way I was planning to implement this is by using template_tag, which is (among other things) a quick interface to ns_register_adptag. The parser sees the tag, and passes its contents to a proc, which in this case will ignore them.

The mechanism for grabbing the documentation out of the page and presenting it to the browser is another discussion, but one to definitely keep in mind.

8: Re: TIP #54 (Proposed) Add an adp tag to handle documenting and commenting adp files. (response to 6)

Posted by Tom Jackson on 03/13/04 11:55 PM

Bart: you might refer to the docs on ns_register_adptag first, my examples are how to define a comment tag (or doc tag), in other words it is easy. After defining (registering) the tag, just use it:

<comment>
@author tom 
@cvs-id $Id$
</comment>

template_tag does a few more nice things on top of ns_register_adptag, but eventually it calls that proc.

9: Re: TIP #54 (Proposed) Add an adp tag to handle documenting and commenting adp files. (response to 8)

Posted by Bart Teeuwisse on 03/14/04 12:05 AM

Tom, sure that is how you define and include a custom tag in ADP. And yes, I should have read up on ns_registeradp_tag. I misread you post. :)

Ben, my point is that we shouldn't ignore the content of the tag -all the time-. Instead we should make the documentation available to developers/designers. I think that we should at least outline how the ADP documentation can be used. So that when this TIP gets approved we've decided on format that we can later expand upon with ways to display the documentation.

/Bart

10: Re: TIP #54 (Proposed) Add an adp tag to handle documenting and commenting adp files. (response to 6)

Posted by Lars Pind on 03/15/04 06:26 PM

Benjamin,

I agree very much we need this.

Do we need any info besides author, date, cvs-id?

Like which CSS classes are being used? Cumbersome, probably not necessary, easier to read the code to find out.

Or which properties from the Tcl file are used? Probably not, we (will) have that in the Tcl file's contract already.

Maybe which Tcl file the template was designed for, if the tcl and adp files are not named and located the same.

/Lars

11: Re: TIP #54 (Proposed) Add an adp tag to handle documenting and commenting adp files. (response to 10)

Posted by Jeff Davis on 03/15/04 06:47 PM

I think we need two tags, one for comments and one for the "page definition". Also great would be if the page definition tag worked with developer support so that you could tell which .adp files were actually used in constructing the page. Of course we could add that to templating instead I guess but I like having cvs info as well.

As we use more .vuh files, nested masters, and includes it can become quite difficult to tell which .adp/.tcl pairs are being used.

I think the proposal should be a little more concrete but I would approve in any case.

12: Re: TIP #54 (Proposed) Add an adp tag to handle documenting and commenting adp files. (response to 11)

Posted by Benjamin Bytheway on 03/18/04 06:52 PM

Jeff, you make a good point. Soon after I posted this TIP I realized breaking things up into two seperate tags would be the better way to do things.

**TIP MODIFICATION**

I propose that we add two adp tags to the toolkit, one to handle a kind of ad_page_contract for adp files, and another to enable inline code comments.

This tag will be combine some functionalities from ad_page_contract and ad_proc. There should only be one contract tag per adp file. It should include a short description explaining what the adp is used for. It should also contain attribute identifiers, including the following:

@author -- name and email address of the author.
@creation-date -- date of creation.
@cvs-id -- the expanding $Id$.
@arch-tag -- the unique arch identifier, for those using gnu-arch (tla).

@param -- used for each variable the adp expects, with the variable name and a description (see ad_proc documenation).

@css-class -- the name of the css class and a short description of how it is used. This will make it easier for those modifying style sheets to know what classes they need to modify to obtain the look they want.

This tag will be used for inline code comments in the adp. No special form is required for using this tag.

Both <contract> and <comment> tags and all of their contents will be removed as the adp is parsed and sent to the broswer.

21: Re: TIP #54 (Proposed) Add an adp tag to handle documenting and commenting adp files. (response to 12)

Posted by Randy O'Meara on 03/19/04 07:07 AM

Benjamin,

I don't know how far you're willing to go with this, but...

If we're going to have a "contract" tag it would be good to make it "functional". Right now, there is no enforcement of tcl variable access from the adp. As in, you can declare a variable to be available from the tcl side, but the adp is not limited to the declared vars.

Of course, there should be some indication (switch) that the programmer/designer wants to apply this enforcement, otherwise many things would break.