Re: GNU Prolog documentation

[Sean Charles]

Hi,

I have spent some time over the last few days writing some PHP code to convert 
the contents of the file "pl-bips.tex" into an XML file for subsequent reuse.

I am pleased to attached my efforts so far, the XML file is created from the 
contents of the Tex file and when loaded into emacs in "nXML" mode reports 
itself as "valid". If nXML mode is happy, so am I!

Each "section" heading results in a <predicate> element, this has child 
elements of <functor>, <templates>, <description>, <errors> and <portability>. 
The <functor> element is a repeating group that contains as many <functor> 
elements as are required, each having two attributes, "name" and "arity", 
allowing the search that my help system will need.

The description is in a CDATA section and contains a lot of the original LaTeX 
for now, I will gradually remove it as I have time.

The errors are captured in one <error> element containing child elements <cond> 
and <term> which would allow searching predicates by the errors they raise, in 
theory at least, a regex on the contents of the elements would be required to 
do that. 

I am sure there is more to say but reading the attached XML says it all.

I would like now for comments and suggestions on what is the best way for this 
to be of use to GNU Prolog i.e. while it is fresh in my mind and I am motivated 
to do it, how best can I proceed to make this XML file be as good as it can be ?

I have attempted to replace LaTeX markup with Markdown syntax where it makes 
sense to do so but the description (currently) contains as yet un-removed code.


I also have an option (currently disabled) to include a <tex> element which 
contains the raw original sliced tex content for each description in case that 
is necessary but *if* we did move this part of the documentation to XML then it 
might not be required.

So, time for bed, it's 11:50 PM in the UK right now, good night hackers 
everywhere!

:)

Sean

bipdoc.xml
Description: application/xml

PS: If the attachment gets stripped I will put it somewhere on the net and post 
the link.


On 25 Jun 2013, at 21:47, Daniel Diaz <address@hidden> wrote:

> 
> Le 25 juin 2013 à 11:56, emacstheviking <address@hidden> a écrit :
> 
>> Hi,
>> 
>> Does anybody know what would be the *best* way to slice and dice the 
>> documentation source files to produce "nuggets" per predicate?
>> 
>> As far as I can see, the gprolog runtime doesn't have apropos or help 
>> predicates like some other implementations so I have decided that as an aid 
>> to learning more I am going to try to implement them but of course they need 
>> access to the underlying documentation for the meat of the output.
>> 
>> I can see from the source distribution that the documentation is written 
>> using .tex files (I have used LaTeX for many many years) BUT would it be 
>> *easier* to pick apart the large single HTML file instead. The H4 tags carry 
>> the predicate name which is useful as a starting point.
>> 
>> I would like to have something like this:
>> 
>>    help(predicate).
>> 
>> Dump the relevant part of the help file to the console.
>> 
>> 
> 
> Hi
> 
> Thank you for your interest for GNU Prolog and for your proposal to 
> contribute to the doc. Contributions are always welcome :-)
> 
> As explained by Lindsay in another mail, the doc is written in LaTeX. PDF is 
> obtained with pdflatex, HTML with HeVeA. The solution proposed by Lindsay, 
> ie. extracting doc from pl-bips.tex (BTW, FD constraint predicates are in 
> fd-cstr.tex) is doable and should work for most predicates. However, when 
> several predicates are grouped in a same subsubsection you will obtain the 
> help for all involved predicates (eg. var, nonvar, atom,…).
> 
> A preferable solution would consist in extracting once for all the doc from 
> the tex file and to put once for all in the corresponding source files (ala 
> Javadoc or pldoc). I never had enough time for this… Recently the Prolog 
> Commons group discussed a syntax for the literate doc of the commons 
> predicates (the syntax is close to markdown): it would be a good idea to 
> use/extend this syntax for the gprolog built-ins too. Let me know if you are 
> interested in participating to this.
> 
> 
>> I have written a "C" extension that wraps the dynamic link library calls 
>> (dlopen,dlcose etc) and so far that seems to show promise.
> 
> BTW: I'm interested on your experience. We have also done this for ix86/linux 
> (easy architecture). For x86_64/linux I thing it is needed to produce PIC 
> code so I have recently added this option to compiler (gplc and the ma2asm 
> sub-compiler). But it is not yet really used (the idea with the module 
> support is to load/unload a module with dlopen/dlclose). On which 
> architecture do you use libld (dlopen,…) ?
> 
>> I was toying with writing the actual implementation in C using libxml or 
>> something to scour the HTML file, on demand. My other approach would be to 
>> produce a "database" (bunch of files called predicatename.txt) and then just 
>> interpolate the filename from the help argument and do it that way. 
>> Whatever, with all programs it comes down to defining the data first!
>> 
>> I really like GNU Prolog, I started with SWIPL but it's too big a dung-ball 
>> for me right now. Ciao seems "ok" but again, too big a dung-ball. I like the 
>> lean and mean approach with GNU Prolog plus the opportunity to make it 
>> better with my own extensions.
> 
> Thank you for those kind words !
> 
> Daniel
> 
> 
> -- 
> Ce message a ete verifie par MailScanner
> pour des virus ou des polluriels et rien de
> suspect n'a ete trouve.
>