Documentation revisions from Kostas.

[rpgoldman]

Needs review followed by merge to master.

[rpgoldman]

@ko56 -- would you please add a comment that briefly summarizes the changes you've made? It looks like you have revised the treatment of citations, and moved some introductory material above some more obscure material, but it's hard to get an overall picture from groveling over the Texinfo source. So a bullet list of change descriptions would be helpful.

[ko56]

Almost all my changes w.r.t. the latest in issue 76 are about formatting.
From your comment, it seems to me that whatever your version is now, it is out of sync with the latest in issue #76. E.g. the movement of material was discussed there on August 8 2021, and I submitted a patch on August 12 2021 using the "git way", as far as I could tell. Did you look at that?
The citations were revised/changed by you, in some version I got from git, probably after August 2021, but now I forgot exactly how I did that.
Unfortunately, git is very confusing for me.

[rpgoldman]

Almost all my changes w.r.t. the latest in issue 76 are about formatting. From your comment, it seems to me that whatever your version is now, it is out of sync with the latest in issue #76. E.g. the movement of material was discussed there on August 8 2021, and I submitted a patch on August 12 2021 using the "git way", as far as I could tell. Did you look at that? The citations were revised/changed by you, in some version I got from git, probably after August 2021, but now I forgot exactly how I did that. Unfortunately, git is very confusing for me.

Got it. I am doing a pass over this as a review, and will later make the changes. Going forward, please try to keep your editor from changing whitespace. There are a bunch of blocks in the diff that I have to read carefully to see whether there are textual changes or only that the text has been re-filled.

(FWIW, I made this problem worse by committing a version with trailing whitespace removed because of my git configuration...)

[ko56]

Sorry, I like to have Emacs fill my text, not realizing that it would cause you a problem.

[rpgoldman]

Sorry, I like to have Emacs fill my text, not realizing that it would cause you a problem.

That's OK; I do, too. I have found it is often helpful to do the re-filling once up front, commit that, and then edit from there. That gives one diff to ignore and one to review.

It's not a huge problem, but it makes things easier if we can manage it.

[rpgoldman]

Need to clear these before merging.

[rpgoldman]

Note: should fix the docstring for find-plans in SHOP3, or fix how it is translated to Texinfo: the list is poorly formatted in the documentation.

[ko56]

I agree, I didn't mention this issue because I didn't know what to do about it
#100 (comment)

[rpgoldman]

I agree, I didn't mention this issue because I didn't know what to do about it #100 (comment)

Added new issue #101 -- I can work on that in a different PR

[ko56]

I'm not sure how we can sync up now. How do I get the latest from you?

[rpgoldman]

I'm not sure how we can sync up now. How do I get the latest from you?

I will try to get this all edited together and merged today or tomorrow. Then we can resync, after the merge to main.

[rpgoldman]

I will merge this after tests run. Need to update the online documentation pages, too.

[ko56]

I obtained all your changes by git pull origin master, and I now have two more items:

1. I fixed some occurrences of @code{} which should have been @var{}. Compressed file is here:
   manual.texinfo.gz

2. I suggest removing sec. 3.7 Hook Routines, as I believe we agreed that it is obsolete w.r.t. SHOP3.

And one last thing: did you see my proposal in "Add alternative syntax for methods #72"?