some suggested small changes to manual.texinfo

[ko56]

I've made some small tweaks, mainly some additional cross-references useful to the beginner, and fixed a typo and a typesetting problem. I don't know how to deal with git. How can I show you what I've done?

[rpgoldman]

If you have committed these into your git repository, you can send me a patch using git format-patch. Here's a tutorial explaining how to do that:

https://www.git-tower.com/learn/git/faq/create-and-apply-patch/

That would be the best way, as in the easiest for me to apply.

Otherwise, if you haven't used git at all and haven't committed any of your changes, you could use

git diff master -- doc/manual.texinfo > manual.patch

That would give you a patch file that you could send to me, and that I could apply to the manual. (Note that I didn't check that command to make sure it has the right pathname to the manual.)

[rpgoldman]

I have moved your changes to Merge Request #66

Let's discuss anything further about these changes on that Merge Request.

[ko56]

If you are OK with these changes, they are fine with me.

[rpgoldman]

Preparing this for merging led me to another round of typographical improvements (replace some misuses of @emph with @var, insert uses of @noindent and @dots, etc.).

This could go on forever, so I will merge this as long as it passes. Please contact me off-list, so I can credit you in the Colophon for your doc improvements.

[ko56]

[I also noticed many indentation issues (needing @noindent), but I wonder if they have to do with the @lisp macro.]
Anyhow, thank you, my changes were minor. How do I contact you off-list?

[rpgoldman]

I thought that this could be done by messaging through GitHub, but ... I can't figure out how to do that. I don't want to put my email here to be scraped so....

Would you please go to the documentation at github.io (the manual) -- or just look at the source file for the manual, and at the first page you can click on the link to my SHOP3 paper at the European Lisp Symposium. From there you will see the title page, which will give you my full name and email address. OK? It is roundabout, but it should get you what you need.

[ko56]

One more question/comment, maybe relevant to the manual.
"Eval terms" allow general Lisp expressions, and such an expression can use arbitrary code, for example Lisp functions defined by the user, correct? (And this is a very powerful feature of SHOP3.) "call terms" also allow arbitrary functions.
Now in the definition of a domain in sec. 4.12, it says that at a minimum it will include definitions of the operators and methods. Then in sec. 4.12.1 it says that each i_i is an operator, method, or axiom.
I think it would be good to say something here about the user-defined Lisp functions, they are a rather unique feature.

[rpgoldman]

I'm not sure what we could say there, since the domain does not -- at least not in terms of syntax -- include the user-defined functions. Those functions are parts of the lisp image that SHOP is loaded into. The domain can refer to arbitrary lisp code, but that the arbitrary lisp code is part of the domain....

[ko56]

Well, you could insert somewhere, wherever you think is the right place, just what you wrote above.
(Perhaps something like this is obvious to someone familiar with Lisp, I don't know.)
Further, it seems to me that the issue of user-defined Lisp code arises also in sec. 3.7. Am I right?

A separate comment: splitting sec. 4.10 is nice. The only thing left unclear is what (forall V E L) does.

[ko56]

It seems that the (forall V E L) can be used to implement PDDL's conditional effects.

[ko56]

I am attaching another suggested set of tweaks to the manual. Revised multiple times ...
manual.patch.gz