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@postgis.refractions.net
http://postgis.refractions.net/mailman/listinfo/postgis-users
_______________________________________________
postgis-users mailing list
postgis-users@postgis.refractions.net
http://postgis.refractions.net/mailman/listinfo/postgis-users
