Hi,
On Thu, Sep 24, 2009 at 2:03 PM, Kingsley Idehen <kide...@openlinksw.com> wrote:
> Aldo Bucchi wrote:
>>
>> Ivan, Hugh,
>>
>> Thank you for the pointers.
>>
>> I have read the docs and in particular found some nice code in ( parts
>> of ) the Virtuoso Opensource project which I will aim to use as guide.
>> In general, I find that the language is so powerful ( PL + SPASQL )
>> that not having a coding style is dangerous.
>> But peer refactorings can help here.
>>
>> Some points
>>
>> * I really miss the shorthand addition in place i.e. myVar :=+ 5
>> ** Lots of string concatenations are flying around in the codebase,
>> and they look like this
>> myVar := myVar || 'postfix'
>>
>> * What's the criteria to use DB.DBA.procedureName or procedureName?
>> Does the latter resolve to the former qualified name or does it depend
>> on the user? I see a lot of code writen in the DB.DBA.* catalog, then
>> I see lots of procedures with no qualification and I also see some
>> places where they are qualified.
>> The obsessive compulsive side of me can't get my mind around this ;)
>>
>> This is a nice one:
>> * Most procedures have an extensive list of parameters that need to be
>> documented ( in my code at least ). Since there is no current doc
>> parser, generator, etc, what if we use a modified inline TTL dialect
>> to declare metadata for procedures? Comments, links to documentation,
>> author metadata, etc.
>> Since the source text is stored on the database itself, then it can be
>> easy to extract this using a sponger and saving it onto a graph, etc.
>>
>> Building on the latter suggestion, here's an example.
>> The idea is that each line in the code becomes a potential subject (
>> for an SPO;PO;PO,O, etc. statement ).
>>
>> create procedure foo(
>> in name varchar, -->> "Name of the person"; rdfs:seeAlso foaf:name .
>> in lastname varchar -->> rdfs:label "Last Name"; rdfs:seeAlso
>> foaf:lastName .
>> ) returns varchar
>> {
>>
>> }
>>
>> Common cases can be abbreviated: L stands for rdfs:label
>>
>> in name varchar, -->> L Name of the person
>>
>> And this can be put anywhere in the code, the subject will always be
>> the latter statement.
>>
>> http( 'I am calling this function with stupid args', 5, 6 );
>> -->> virt:todo "Fix this!"; foaf:maker ols:johhny ; moat:
>>
>> This can be useful in the eventuality of creating an IDE. Procedure
>> documentation gets parsed and stored along with the code and ( some
>> form of the ) parse tree into an RDF graph ;)
>> >From there, generating docs can be a piece of cake.
>>
>> This is just a top of the head proposal. Take it with a grain of salt.
>> ( But I DO want it very badly! )
>>
>> One more thing.
>> Since procedures live as isolated enities in the database, we have an
>> advantage over traditional IDEs. Depending on the granularity of the
>> parse tree and the metadata ( these comments ), you can achieve pretty
>> incredible usability feats.
>> You start the coding experience with a faceted browser over your
>> procedures. You can type and search a la spotlight, or filter by
>> author, or look for tags, etc.
>>
>> And then we fall into full integration with SVN if you want to
>> roundtrip... but, wait! Virtuoso is WebDAV server! LOL.
>>
>> Regards,
>> A
>>
>
> Quick FYI.
>
> You know our entire docbook based docs exist in a Linked Data Graph?
> Basically RDF Views over the Docs.
Coming from you, it can't be any other way... ;)
>
> All being well, you should be able to dereference structured descriptions of
> every document section, ditto tutorials.
>
> The docs can be beautified via code driven automation if anyone is
> interested. We are strict dog-fooders at every level :-)
But what about the previous step. Generating the docs?
You do this by hand?
The Function Reference section, for example?
I find my codebase growing and growing, and since there is no Classes
( save for UDT and modules ) to organize code, things become complex
quickly.
If you could also bring the parse tree plus annotations to the RDF
world, then the game can get really interesting.
Phased implementation N1:
* Give each procedure a URI ( based on its name, and URIQA of the
server or general URIQA if they are built in )
* Start with the parameter level annotations ( not more than what
Javadoc gives you )
* Create a simple built-in webapp that provides a UI for this.
That's already a killer feature. I see lots of linking happening.
Regards,
A
>
> Kingsley
>>
>> On Thu, Sep 24, 2009 at 12:54 PM, Ivan Mikhailov
>> <imikhai...@openlinksw.com> wrote:
>>
>>>
>>> Hello Aldo,
>>>
>>> On Thu, 2009-09-24 at 01:18 -0400, Aldo Bucchi wrote:
>>>
>>>>
>>>> Hi,
>>>>
>>>> 1.
>>>> I'm looking for Virtuoso programming best practices. Looking at a
>>>> codebase like ODS I can see several intermixed styles. Any particular
>>>> corpus that you would say is "worth following"?
>>>> ( other than your own code :P )
>>>>
>>>
>>> My own code is definitely bad example. Every time I write really
>>> interesting and compact and useful procedure I get a request to rewrite
>>> it as C code for better speed and to place into the executable.
>>>
>>>
>>>>
>>>> 2.
>>>> Any documentation pattern for procedures? Any tool to generate docs?
>>>>
>>>
>>> I use Doxygen ( http://www.stack.nl/~dimitri/doxygen/ ) notation for
>>> some parts of the C code. It's quite similar to javadoc (it can even
>>> parse javadoc comments). No specific tools or notations are used for
>>> SQL, and there are no strict plans, but I guess I'll extend Doxygen
>>> sooner or later to support SQL sources. ("later" is more probable: I
>>> intend to do that at least twice a year since 2001, still no progress)
>>>
>>> Best Regards,
>>>
>>> Ivan Mikhailov
>>> OpenLink software
>>> http://virtuoso.openlinksw.com
>>>
>>>
>>>
>>>
>>
>>
>>
>>
>
>
> --
>
>
> Regards,
>
> Kingsley Idehen Weblog: http://www.openlinksw.com/blog/~kidehen
> President & CEO OpenLink Software Web: http://www.openlinksw.com
>
>
>
>
>
--
Aldo Bucchi
skype:aldo.bucchi
http://www.univrz.com/
http://aldobucchi.com/
PRIVILEGED AND CONFIDENTIAL INFORMATION
This message is only for the use of the individual or entity to which it is
addressed and may contain information that is privileged and confidential. If
you are not the intended recipient, please do not distribute or copy this
communication, by e-mail or otherwise. Instead, please notify us immediately by
return e-mail.
