[postgis-users] Postigis self documenting code?

[Dane Springmeyer]

Kevin and Regina,

Thanks for the feedback. It sounds like there is a lot of room for  
improvement and expansion of the core docbook xml before we worry  
about exactly how to parse it.

While I am not at all familiar with Docbook logic I have looked  
closely at the postgis.xml and will begin to file tickets on the
bug tracker with ideas to improve it.

As a start their is a missing tag in postgis.xml in trunk that I've  
provided a patch for here:
http://code.google.com/p/postgis/issues/detail?id=39

I'm also curious about the '&long_xact;' insert on 5267. I had to  
remove it to avoid parsing errors in the python script. I'm pretty  
sure that it works to pull text from a linked file, so perhaps I  
should be working on the product of that file and postgis.xml rather  
than postgis.xml itself?

I really like Kevin's idea of linked examples for each function, but  
it makes me wonder whether XML is the right format to try to  
incorporate code examples. What about a relational database? :)

It seems like it would almost be easier to build a wiki page that  
would allow users to upload examples that are tied, by Foreignkey to  
each function. Then the postgis dev's could pick the best examples and  
join them to the docs in-database. Django would be a great tool for  
this.

Either way, I have posted the python script I mentioned and some  
preliminary output here: http://code.google.com/p/postgis/issues/detail?id=35

All it does right now is pull the first paragraph of documentation for  
each function and sticks that in the comments. I have an additional  
script that that loops through all the <para> and <note> tags, but it  
sounds like there may be reason to reorganize these tags differently  
so I'll hold off on any improvements for now.

Cheers,

Dane


On Jun 21, 2008, at 4:01 PM, Paragon Corporation wrote:

> Dane,
>
> In response to your comments
>
>> Well, maybe this is the best place to start....
>
>> And another benefit is that auxiliary meta could be added at the  
>> same time
> in a separate table (see below).
>
> I think its more maintainable as a separate file as the way you  
> suggested
> and a separate more informative table would be helpful.  If we can  
> agree on
> specific tags to use, I think it would make the parsing easier and  
> less up
> to the whims of the postgis doc book.  The additional tables can be  
> used for
> a building a help system ala the R-help as it looks like you have  
> already
> started.  I think large comments with examples may be more desirable  
> in a
> separate table.
>
>
>> I had not given thought to the issue of how long the comments might  
>> be.
> I've only viewed comments in a psql terminal, > > so long comment  
> strings
> simply wrap. But I can see that PgAdmin must enforce some max length  
> (looks
> like around >  > 140 char) to maintain the readability within the
> 'properties view'. Do you know if PostgreSQL enforces a max length  
> on the >
> comments field?
>
> Technically PgAdmin doesn't place constraints per say.  It just will  
> only
> show the first 140 char in the comment pane and if you double click  
> on the
> function, you will see a scrollable field where you can see all the
> comments.  I just think it would be a bit distracting to have a huge
> definition in there.  If I needed to read that much, I would go to  
> the docs.
> That's more a personal preference though.
>
>
> My guess is that Postgres does not place constraints on length of  
> comments.
> I pasted a fairly huge paragraph in it and it took it.  Strangely  
> Postgres
> is I think the only database I have run into where from an efficiency
> standpoint it may actually be better to not put constraints on your  
> field
> lengths and there is no real penalty of not doing so as with other  
> databases
> (aside from users going crazy stuffing the kitchen sink in there).
>
> Thanks,
> Regina
>
>
> _______________________________________________
> postgis-users mailing list
> postgis-users at postgis.refractions.net
> http://postgis.refractions.net/mailman/listinfo/postgis-users