Re: pengines extension to html_requires

On 02/09/2014 10:18 PM, Anne Ogborn wrote:
> The real issue isn't options vs no options.
> 
> As Jan says-
> 
> Note that a small interface has advantages in itself: documentation, 
> understanding and reducing the risk of forgetting arguments.
> 
> The real issue is that there's no clue which of these are rarely used
> by the end user, or how the commonly used ones fit together. The
> documentation assumes knowledge of concepts that aren't explained.
> The overview doesn't seem connected to actual use.

Yes.  Some of that is due to the nature of PlDoc (by default), where
you get a story about the module and a list of predicates without a
possibility to group these (easily) into sections.  That is clearly
what should happen here because the predicates fall into several
groups that have little to do with each other.  If you are a web
user, all you need are pengine_debug/1, pengine_output/1 and
pengine_input/1.  Often you also do not need these, and all you
need to do is make the application API accessible to the
pengine_sandbox module.

If you are a Prolog programmer, you want pengine_rpc/2,3.

Only if you want to manage a more complex orchestra from Prolog
you'll need the others.  For example if you want to collect
answers from several pengine servers concurrently.

PlDoc does allow for sections, but it is a bit clumsy :-(

	Cheers --- Jan

> After struggling with this apparently more than any other outsider,
> I'm still stuck with a single 'happy path' of slavishly imitating the
> examples, and not really understanding how to go off and fly on my
> own.