[freeside-devel] Documentation

[Systems Administrator]

On Sun, 19 Oct 2003 ivan at 420.am wrote:

> On Mon, Oct 20, 2003 at 10:29:47AM +1000, Systems Administrator wrote:
> > On Sat, 18 Oct 2003 ivan at 420.am wrote:
> > > On Fri, Oct 17, 2003 at 10:46:27AM +1000, Systems Administrator wrote:
> > > > 
> > > > 	Has any work on this auto-generation been done?
> > > 
> > > Nope.
> > 
> > 	Ok, I'm intending to start on it, assuming my boss doesn't give me 
> > something else to do.  
> > 
> > > > If not, what format were you planning to embed the documentation in?  
> > > 
> > > Hadn't given it a whole lot of though yet.  Perhaps a data structure in
> > > each individual tablename.pm so we can autogenerate what freeside-setup
> > > needs too.
> > 
> > 	Good idea.  The simplest way I can think of is:
> > 
> > # BEGIN tabledef
> > #    'agent' => {	# Table Descriptions
> > #      'columns' => [
> > #        'agentnum', 'serial',            '',     '',		# The primary key of the table
> > #        'agent',    'varchar',           '',     $char_d,	# The name of the agent
> > #        'typenum',  'int',            '',     '',
> > #        'freq',     'int',       'NULL', '',
> > #        'prog',     @perl_type,
> > #        'disabled',     'char', 'NULL', 1,
> > #        'username', 'varchar',       'NULL',     $char_d,
> > #        '_password','varchar',       'NULL',     $char_d,
> > #      ],
> > #      'primary_key' => 'agentnum',
> > #      'unique' => [],
> > #      'index' => [ ['typenum'] ],
> > #    },
> > # END tabledef
> > 
> > 	Hopefully it doesn't get word-wrapped on me.  The basic idea is 
> > that we could suck this text from the file, s/^# //, and use it to 
> > generate fs_setup.
> 
> Hmm, no, I don't think so.  There's nothing special about the giant data
> structure in freeside-setup, and there's no reason to continue using it.
> tablename.pm modules can declare their schema information somehow and
> freeside-setup can read it, as would some sort of auto-generator for
> httemplate/docs/schema.html.
> 
> (bin/fs-setup from 1.4 is replaced bin FS/bin/freeside-setup in 1.5.)
> 
> > 	Or did you have something entirely different in mind?  
> 
> Sounds like it...

	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.  

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?  

	Anyway, some feedback on those ideas should hopefully enable me to 
generate something more to your taste :).  


-- 
Tim Nelson
Systems Administrator
Sunet Internet
Tel: +61 3 5241 1155
Fax: +61 3 5241 6187
Web: http://www.sunet.com.au/
Email: sysadmin at sunet.com.au