some edits to the (new) manual

[ko56]

I attach shop3-manual.tex.gz.

You can see the changes in Emacs' ediff, but here is a short summary also:

0. Many changes of \code or \emph to \var and other such, throughout.
1. Comment at line 391 of the original.
2. Added some lines at line 1029 of the original.
3. I reorganized the text a little bit after line 1088 of the original, up to line 1110.
4. Added a footnote at line 1237
5. Comment at 1269
6. Added some text at 1606

7. shop3-manual.texinfo.gz

[rpgoldman]

Quick question: at what point did this get branched?

From the filename, I take it that it was done after f9dc9fba737a721d54fa2ef6bb312bee6dd64470 which is great.

[ko56]

I cloned the SHOP3 repo on Jan. 31. I don't know how to find the rev number in the git info, maybe you could tell me.

[rpgoldman]

Checking the history list (https://github.com/shop-planner/shop3/commits/master) it looks like the manual was last updated on the 25th, which means merging should be easy.

[rpgoldman]

Here's an interesting note: you extended the discussion of list-terms, but I cannot find any code in input.lisp that seems to handle list terms with the optional list prefix described in the manual.

Probably we need to test this and fix the manual if it's inaccurate.

[rpgoldman]

Another thing I should fix: the manual uses the term "conjunct" incorrectly. We use the term "conjunct" (disjunct) where we should use "conjunction" (disjunction).

[ko56]

OK, I've never tried the optional list prefix either. So please fix. I somehow missed the use of "conjuct" in the section title ...

While you're at it, would you also add something other than "experimental and unstable" about mcts in sec. 3.2.1, since you've done work on it?

[rpgoldman]

The MCTS code is still not folded into the SHOP repository proper, so it isn't available yet. I hope to make it available later, but right now I would have to get agreement from my funding agency.

[ko56]

There still seems to be an issue with @include include/fun-shop-find-plans-stack.texinfo. The file still ends with

Return values: There are two possible return types, selected by the keyword argument unpack-returns:

1. Default/compatible with `find-plans`:
@itemize
@item  List of plans
@item  List of plan trees (if computed)
@item  List of plan tree lookup tables
@item  List of final world states
@item  List of analogical replay tables (if computed)
@end itemize
To comply with SHOP3,
though, always returns a list of plans.
  If the @code{plan-tree} keyword argument is non-NIL, will return an enhanced plan
tree, with causal links, unless @code{no-dependencies} is non-NIL.
  Returns the values returned by @code{seek-plans-stack}, qv.
@end deffn

So the "1. Default ..." at the top is still hanging without a "2.". Unless the "2." is meant to be attached to "To comply with SHOP3, ..."

[rpgoldman]

I think the problem is that SB-Texinfo does not handle enumerated lists, so that it gets confused. When I look at that, I see that the 1. and 2. are not translated into @enumerate.

I'll have to extend SB-Texinfo to find and translate enumerations.

[ko56]

When I look at the file shop3/shop3/explicit-stack-search/explicit-search.lisp, it ends exactly as I posted above. So it seems to me that the problem is not with SB-Texinfo, but with the file itself.

[rpgoldman]

You are right: I have been working with an uncommitted modification to this file. In my file, the documentation string is:

 "Top level search function for explicit-state search in SHOP3.
Does not support the full range of options supported by SHOP3's
`find-plans-stack`.

Keyword arguments:
* domain : either a domain name (symbol) or a `shop:domain` object.
* verbose : 0, 1, 2, 3; default 0
* plan-tree : build and return a plan tree? (`plan-tree:top-node`),
        defaults to `nil`.
* gc : If possible, perform a full GC before starting to plan.  Default:
        current value of `shop:*gc*`.
* no-dependencies : if building a plan tree, build it *without* causal
        dependencies.  Default: `nil`.
* repairable : return plans that can be repaired.  Default: `nil`.
* rationale : build a plan tree with rationale information.  Default: `nil`.
* state-type : what state type should be used for representing world states?
        (Note: world-state/SHOP state, *not* search-state). Default: `:mixed`.
* out-stream : where should output be printed.  Default: `t` (standard output).
* which : What/how many plans should be returned?  Supports only `:first` (the
        default) and `:all`.
* analogical-replay : Do search informed by the contents of the
        `*analogical-replay-table*`. Default: `nil`.
* make-analogy-table : Populate `*analogical-replay-table*` while planning.
        Only works with `:which` = `:first`.  Default: `nil`.
* unpack-returns : If true, return values in a way compatible with `find-plans`.
        If false, return a list of `plan-return` objects instead.  See discussion
        of return values, below.  Default: `t`.

Return values:
    There are two possible return types, selected by the keyword argument
`unpack-returns`:

1. Default/compatible with `find-plans`:
    * List of plans
    * List of plan trees (if computed)
    * List of plan tree lookup tables
    * List of final world states
    * List of analogical replay tables (if computed)
To comply with SHOP3, always returns a list of plans.
  If the PLAN-TREE keyword argument is non-NIL, will return an enhanced plan
tree, with causal links, unless NO-DEPENDENCIES is true.
  Returns the values returned by SEEK-PLANS-STACK, qv.

2. If UNPACK-RETURNS is NIL, then return one or more appropriate PLAN-RETURN
objects."

This does not get formatted correctly still because SB-TEXINFO does not understand enumerations.

I am considering supporting markdown-style section headers, something like this (see keyword arguments and return values). But I'm busy and it's hard to find time to mess with SB-TEXINFO.

I like the library's support for texinfo, but I also wish that I had just figured out how to extract the docstrings and pipe them to some kind of Markdown preprocessor. Maintaining a text formatting library is not the best use of my time.

 "Top level search function for explicit-state search in SHOP3.
Does not support the full range of options supported by SHOP3's
`find-plans-stack`.

# Keyword arguments:
* domain : either a domain name (symbol) or a `shop:domain` object.
* verbose : 0, 1, 2, 3; default 0
* plan-tree : build and return a plan tree? (`plan-tree:top-node`),
        defaults to `nil`.
* gc : If possible, perform a full GC before starting to plan.  Default:
        current value of `shop:*gc*`.
* no-dependencies : if building a plan tree, build it *without* causal
        dependencies.  Default: `nil`.
* repairable : return plans that can be repaired.  Default: `nil`.
* rationale : build a plan tree with rationale information.  Default: `nil`.
* state-type : what state type should be used for representing world states?
        (Note: world-state/SHOP state, *not* search-state). Default: `:mixed`.
* out-stream : where should output be printed.  Default: `t` (standard output).
* which : What/how many plans should be returned?  Supports only `:first` (the
        default) and `:all`.
* analogical-replay : Do search informed by the contents of the
        `*analogical-replay-table*`. Default: `nil`.
* make-analogy-table : Populate `*analogical-replay-table*` while planning.
        Only works with `:which` = `:first`.  Default: `nil`.
* unpack-returns : If true, return values in a way compatible with `find-plans`.
        If false, return a list of `plan-return` objects instead.  See discussion
        of return values, below.  Default: `t`.

# Return values:
    There are two possible return types, selected by the keyword argument
`unpack-returns`:

1. Default/compatible with `find-plans`:
    * List of plans
    * List of plan trees (if computed)
    * List of plan tree lookup tables
    * List of final world states
    * List of analogical replay tables (if computed)
To comply with SHOP3, always returns a list of plans.
  If the PLAN-TREE keyword argument is non-NIL, will return an enhanced plan
tree, with causal links, unless NO-DEPENDENCIES is true.
  Returns the values returned by SEEK-PLANS-STACK, qv.

2. If UNPACK-RETURNS is NIL, then return one or more appropriate PLAN-RETURN
objects."

[rpgoldman]

Looks like I could use SB-TEXINFO to collect up all of the docstrings and then pipe them through pandoc instead of trying to manage a text formatter....

[ko56]

So pandoc would translate from markdown to texinfo?

By the way, one more issue with this text is right at its beginning:

"Top level search function for explicit-state search in SHOP3.
Does not support the full range of options supported by SHOP3's
`find-plans-stack`.

This is the docstring for find-plans-stack, and it says that find-plans-stack does not support the full range of options supported by SHOP3's find-plans-stack!

[rpgoldman]

Good catch! That's probably an auto-complete error. I have fixed it on the branch and will get it merged.

[rpgoldman]

So pandoc would translate from markdown to texinfo?

Well it claims to be able to do this. Before jumping in, it would be nice to think how to distinguish parameters, types, etc., and how to do this without turning the docstrings into an unreadable mess.

My model here would be something like Python's numpy documentation style (readable on screen as well as when formatted) versus RST documentation (so clotted with ugly markup that you can't read it with the help function).

I want docstrings in source code to continue to be readable when editing the code. But I'd also like to enable some reasonable linking.

[rpgoldman]

If we could collect declare and declaim forms, those might help.

[ko56]

I just did a little experiment: pandoc -o doc.html doc.md where doc.md is the file you posted above https://github.com/shop-planner/shop3/issues/125#issuecomment-1443852311, with no modification at all. The html result looks decent to me.
I also did a .texinfo test, that looks decent as well (I didn't run it through latex).

[rpgoldman]

I think it's probably better to go from Texinfo to the other formats: Texinfo has semantic markup (e.g., "this is a function") that isn't available in HTML or Markdown...

I think I should close this and then make better documentation strings a different topic...