Re: GNU Prolog documentation

[Daniel Diaz]

Hello Sean,

thanks again for your contribution.

Le 02/07/2013 17:30, emacstheviking a écrit :

Thanks Daniel,

I have now written a second script that produces individual text files for every functor name within a predicate element which, at the expense of excessive files containing the same descriptive content, I can now type:

    help(some_predicate).

and I get the contents dumped to my console. It's not perfect though; the filenames may not play well with windows so I would need to translate things like "==" to "equalsequals" or something but then that means having a mapping function defined in the PHP code and the prolog code that reads it back and for now I just wanted to keep it simple. On Linux and OSX it works fine.

BTW, an alternative to all these files would be to have a Prolog file with one fact per built-in predicate.

doc(Pred, Arity, DocText).

(we could imagine a more complex structure for DocText, separating templates, description, errors, portability...). Then help/1 is obvious.

The pros are: only one file, can be searched easily from Prolog code (eg., by help/1), less file manipulation
The cons: more memory consuming (all docs are present in memory under the top-level even if never consulted).

In case anybody can make it cleaner or slicker, I paste the code I have written which when consulted, does the job so far. It allows for two environment variables, one which MUST be set and one which MAY be set:

    GP_HELP_ROOT  => folder containing the processed help text files
    GP_HELP_CMD    => external command to produce output to stdout, $1 is predicate name

Here's the code, I have only been learning Prolog for a few weeks at most, so be kind, I did what I needed to get the job done! :)

help(Pred) :-
    environ('GP_HELP_CMD', Helper)
    -> (
        open_output_atom_stream(Cmd),
        format(Cmd, "~a ~a", [Helper, Pred]),
        close_output_atom_stream(Cmd, SystemCmd),
        system(SystemCmd)
    )
    ; (
        help_filename(Pred, HF),
        open(HF, read, H),
        help_show(H),
        close(H)
    ).

help_filename(Pred, AbsFile) :-
    environ('GP_HELP_ROOT', Root),
    open_output_atom_stream(S),
    format(S, "~a/pred_~a.txt", [Root, Pred]),
    close_output_atom_stream(S, AbsFile).

help_show(H) :-
    at_end_of_stream(H) -> true
    ;
    get_char(H,C),
    put_char(C),
    help_show(H).

BTW, you can simplify your code using format_to_atom/3 (http://gprolog.univ-paris1.fr/manual/html_node/gprolog039.html#sec178).
You can also test EOF (get_char returns the atom end_of_file at EOF).

in the meantime I shall continue to spend time cleaning up the LaTeX markup from the description sections.

I think I may change it so that it doesn't balk if there is not GP_HELP_ROOT because the external command may be capable of using the XML file instead. All up in the air right now as you can guess!

I am also planning a "C" extension as well but I am not sure that is the best way to do it... unless it becomes a core predicate it might be cleaner to leave it as a bunch of processed files OR of you don't want the process files you can run some kind ox external command that can get what it wants from the XML file I produced. That is why I tried to make it flexible.

Thanks,
Sean.


PS: If there is enough interest I guess I can github this and you can have a play. It uses PHP as the scripting language and that's the only dependency.

It is a good idea. Please do it !

For the moment I'm studying the best way to implement the doc system (the help/1 will be a part of the whole system). I keep you informed.

On 1 July 2013 20:40, Daniel Diaz <address@hidden> wrote:

Hi Sean,

Congratulations for your work on the doc (NB there are also built-ins docs in the fd-cstr.tex file). This will be very useful. For gprolog we need a documentation system similar to :

• lpdoc for SWI-prolog (http://www.swi-prolog.org/pldoc/package/pldoc.html)
• PLdoc for Ciao Prolog (http://ciao-lang.org/legacy/files/ciao/lpdoc.pdf) 

These tools (in the spirit of javadoc) extracts the doc part from the sources to inject them in the final documentation. In our case we will also add code for the help/1 predicate.

I'm discussing with prolog commons member to try to know what has been finally decided as documentation systems for the commons (I'd like to use the same syntax for the doc). I keep you informed.

Thank you again

Daniel

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 été vérifié par MailScanner pour des virus ou des polluriels et rien de suspect n'a été trouvé.