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 :
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
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é.