[freeside-devel] Documentation

[ivan at 420.am]

On Mon, Oct 20, 2003 at 01:22:04PM +1000, Systems Administrator wrote:
> 	Ok, let me try this in pieces, then:
>
> 1.	How are you with the idea of information that is read as a comment 
> 	by Perl (ie. lines start with a hash), delimited by things like 
> 	the begin and end tabledef?  I'm happy to junk the idea as soon as 
> 	someone thinks of a better one.  If someone knows how to declare a 
> 	POD section, but not use it to generate POD, that might be an 
> 	idea.  Or we could even try to come up with some format that would 
> 	work in POD too.  Or I suppose we could even use something strange 
> 	from perldata: Text after __DATA__ but may be read via the 
> 	filehandle "PACKNAME::DATA", where "PACKNAME" is the package that 
> 	was current when the __DATA__ token was encountered.  

Barking up the wrong tree completely.  Trying to hide the data is not
the objective here.

tablename.pm modules can declare their schema information in a variable,
like their "table" subroutine, or as a (package) global.

> 2.	Aside from how we encapsulate it (ie. 1 above), what would you 
> 	prefer here?  Perl data structures?  SQL?  Something that works 
> 	with POD?  Or some non-standard entirely new thing?  Or something 
> 	else that I'm unaware of?  HTML?  XML?  

"Perl data structures".  Take a look at DBIx::DBSchema.  pretty_print
and pretty_read are close, but probably need to use a hashref for each
column instead of throwing six elements for each column into a giant
array, and also need to be factored down into DBSchema/Table.pm so we
can work with a structure for an individual table, not just for the
whole schema.

-- 
_ivan