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.
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).
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.
On 1 July 2013 20:40, Daniel Diaz <[email protected]> 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 <[email protected]> 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 <[email protected]> wrote:
>
>
> Le 25 juin 2013 à 11:56, emacstheviking <[email protected]> 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
> [email protected]
> https://lists.gnu.org/mailman/listinfo/users-prolog
>
>
>
> --
> Ce message a été vérifié par MailScanner <http://www.mailscanner.info/>pour
> des virus ou des polluriels et rien de suspect n'a été trouvé.
>
_______________________________________________
Users-prolog mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/users-prolog
