mthom
Documentation for built-in predicates
Continued from #2020.
Predicates such as (<)/2, (@<)/2, copy_term/2, sort/2 and is/2 are built-in in the interpreter. The Scryer Prolog documentation currently doesn't document them because it only documents libraries with source code as far as I know.
- [ ] Add a section for built-in predicates in the documentation site
- [ ]
(@>)/2 - [ ]
(@<)/2 - [ ]
(@>=)/2 - [ ]
(@=<)/2 - [ ]
(==)/2 - [ ]
(\==)/2 - [ ]
(>)/2 - [ ]
(<)/2 - [ ]
(>=)/2 - [ ]
(=<)/2 - [ ]
(=:=)/2 - [ ]
(=\=)/2 - [ ]
(is)/2 - [ ]
acyclic_term/1 - [ ]
arg/3 - [ ]
compare/3 - [ ]
copy_term/2 - [ ]
functor/3 - [ ]
ground/1 - [ ]
keysort/2 - [ ]
read/1 - [ ]
sort/2 - [ ]
atom/1 - [ ]
atomic/1 - [ ]
compound/1 - [ ]
integer/1 - [ ]
number/1 - [ ]
rational/1 - [ ]
float/1 - [ ]
nonvar/1 - [ ]
var/1
- [ ]
is is also a standard operator, so let's write the predicate indicator also as a valid Prolog term, as (is)/2.
Another thing I noticed: Github seems to cause issues with \, affected are (\==)/2 and (=\=)/2.
Doing this in the current Scryer site will be kind of hard because, if I understand correctly, Doclog would need some extra features to be able to document predicates not on any source. I think a good way to improve the situation here is to link to a documentation of the ISO predicates (I only know of the SWI documentation for that, which isn't ideal, and the standard itself, which is not freely available so also not ideal) for the not documented predicates in the module documentation of library(builtins). This could be done with a list in the module documentation where each predicate links to the SWI documentation page for that predicate. For example, (@>)/2 would link to here.
Is anyone against this? It would already improve the user experience of the documentation a lot for people new to Prolog while we think of a better way to do this. Also, is there any site that would be more fitting than the SWI documentation? Pointing to the documentation of a "competitor" implementation seems kind of wrong.
An idea I just had that is better than linking to SWI is just documenting these predicates inline in the module documentation. This has the added benefit that you don't have to go to another site to read the documentation of them. They still wouldn't appear in the search bar, but they would at least be there.
We could also document the predicates from #2020 and #2031 in library(builtins) that way, because they are effectively global and I can't think of any other appropriate place to document them, but say very explicitly that those are implementation defined and not ISO like all the other predicates there.
Although I haven't done it yet, my idea was to support the parsing of extra files. Then we can supply an extra file that is not under the same directory as others (so it doesn't get included in the binary) but contains documented definitions for all those predicates.
Although I haven't done it yet, my idea was to support the parsing of extra files.
Yes, this would be the obvious solution. But this opens a lot of design space. What should be the scope of this functionality? For this case it would be good to have a kind of "mixin" functionality that you could make another file add predicates to an already generated page. For #2020, where we kind of don't have the file in the same place, it would be good to be able to make an entire page out of those extra files. A cool functionality would be to also do non-documentation pages (imagine a "good practices" page for example).
Some of those ideas conflict with one another if the design is not well though out, so it would be necessary to decide the scope of what is intended to be implemented before implementing this. I assume this would take quite some time to do right, and that is why I'm looking for a temporary solution while this hasn't landed yet.
I already tried to implement this in Doclog but stopped precisely because the design space is so large.