Re: GNU Prolog documentation

Le 29 juin 2013 à 00:50, Sean Charles <address@hidden> a écrit :

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

--
Ce message a ete verifie par MailScanner
pour des virus ou des polluriels et rien de
suspect n'a ete trouve.

<bipdoc.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.

_______________________________________________
Users-prolog mailing list
address@hidden
https://lists.gnu.org/mailman/listinfo/users-prolog

From:	Daniel Diaz
Subject:	Re: GNU Prolog documentation
Date:	Mon, 1 Jul 2013 21:40:14 +0200