Re: [MacPerl] subs, pod, package & sectioning

[Matthias Ulrich Neeracher <neeri@iis.ee.ethz.ch>]

Tom Fetherston <ranch1@earthlink.net> writes:
>By pieces, this part helps me eliminate sections of text that shouls not be
>scanned for any indexing:
>=head1|=pod|__END__|__DATA__)
>
>[Q] Can I count on these starting in the first column? (same for "=cut").

Yes, the Perl parser requires this.

>I need to know if I'm in a package so:
>package
>
>for this an index is created that notes the name and the fact that it is a
>package. Now any subsequent subroutine will be considered a part of the
>package and will appear indented and prefixed with '::'.
>
>[Q] Can I count on this starting in the first column?

Technically no.

>[Q] Other than another package, is there some way of 'unpackaging' that I
>      need to be aware of?

Not that I know.

>Once in a package, BEGIN and END act as special subroutines, so I create
>indexes for them:
>BEGIN|END
>
>[Q] Can I count on these starting in the first column?

Technically no.

>[Q] Are there other such?

I don't think so.

>Wether or not any of the above occurs, we always want to form index entries
>for subroutines. The above will only catch a sub if the keyword 'sub'
>starts in column 1.
>
>[Q] Is this reasonable?

Technically no, but pragmatically yes. The only "sub" I have not starting in
column 1 in my style are anonymous closures.

>I've seen code where a sub defines a sub inside its code, if I allow
>whitespace before 'sub', I'll index these also, Such indexes don't reflect
>that they are defined in a sub, and are confusing. So I want to leave them
>out.
>
>[Q] Will this cause trouble?

Probably not.

>Are their any other keyword/constructs that would be useful to index?
>
>Here is an example of how a file might index:
>
> SDF_USER *pkg
>*Constants
>*Variables
>*Initalization
>  ::InitMacros
>*Support Routines
>  ::_PageNF
>... etc.
>
>The indexes that start with a '*', are sectioning enteries, they are formed
>from comments with this format:
>#### Constant ####
>
>(actually, three sharp's on each side is enough to trigger this)
>
>[Q] Is this going to cause any problems with the way people do comments?

Well, from the POV of the Mac Toolbox modules, it would be cool if you could
recognize =head2 as such a sectioning comment. Your convention is not bad 
as such, but it would be good to encourage pod documentation as well, which
would be done by tying into the pod system.

Matthias

-----
Matthias Neeracher   <neeri@iis.ee.ethz.ch>   http://www.iis.ee.ethz.ch/~neeri
   "I'm set free to find a new illusion" -- Velvet Underground

***** Want to unsubscribe from this list?
***** Send mail with body "unsubscribe" to mac-perl-request@iis.ee.ethz.ch