More changes/fixes to manual

[ko56]

I'm attaching the latest manual.patch.gz. Besides the typographical and other minor fixes, I've reorganized sec. 11.

In sec. 11.1, item 1, I think something more may need to be said about satisfiers/unifiers in axioms, concerning variables that don't appear in the head, but I don't know how to say it.

My opinion is that this section should precede the current sec. 10.

manual.patch.gz

[rpgoldman]

Thanks for this. I am working to apply it. But... how did you create it?

When I try applying it with patch, it does not have the expected format:

 $ patch < manual.patch
can't find file to patch at input line 5
Perhaps you should have used the -p or --strip option?
The text leading up to this was:
--------------------------
|diff --git a/shop3/docs/manual.texinfo b/shop3/docs/manual.texinfo
|index 7bf5b2e..5e514a9 100644
|--- a/shop3/docs/manual.texinfo
|+++ b/shop3/docs/manual.texinfo
--------------------------

So I tried

~/lisp/shop $ git am manual.patch
Patch format detection failed.

But that does not work, either.

It looks like you are using git diff in which case, it would be better if you would either:

1. Use ordinary diff so I get a patch I can apply with patch
2. Use git format-patch to give something I can apply with git am or
3. Just use a GitHub pull request.

For now I was able to apply this patch, but only manually. And you don't get credit for it the way you would with method 2 or 3, above (git would remember that you had done the commit: right now it looks like I did, although I try to give you credit textually).

[ko56]

I created the patch following the 2nd method in your old email below. All the other patches I've sent were created the same way.

On Sat, 2021-08-07 at 09:12 -0700, rpgoldman wrote:

Thanks for this. I am working to apply it. But... how did you create it? When I try applying it with patch, it does not have the expected format: $ patch < manual.patch can't find file to patch at input line 5 Perhaps you should have used the -p or --strip option? The text leading up to this was: -------------------------- |diff --git a/shop3/docs/manual.texinfo b/shop3/docs/manual.texinfo |index 7bf5b2e..5e514a9 100644 |--- a/shop3/docs/manual.texinfo |+++ b/shop3/docs/manual.texinfo -------------------------- So I tried ~/lisp/shop $ git am manual.patch Patch format detection failed. But that does not work, either. It looks like you are using git diff in which case, it would be better if you would either:

1. Use ordinary diff so I get a patch I can apply with patch
2. Use git format-patch to give something I can apply with git am or
3. Just use a GitHub pull request. For now I was able to apply this patch, but only manually. And you don't get credit for it the way you would with method 2 or 3, above. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub, or unsubscribe. Triage notifications on the go with GitHub Mobile for iOS or Android.

[ko56]

Sorry, I see I didn't append the right email, somehow. Here is the correct text:

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]

@ko56 Did not mean to seem critical. It's just that if you continue to contribute -- and I hope you do! -- it would be easier if you did it in the standard way.

But if this is what works best for you, I will continue to take patch files.

[rpgoldman]

@ko56

My opinion is that this section should precede the current sec. 10.

So you mean swap sections 11 (General Notes on Shop3) and section 10 (Internal Technical Information) so that what is now 11 becomes 10?

Just want to be sure I understand what you have in mind.

[ko56]

Ok, I will try the github way to submit patches, although I d find github painful. I will submit a test patch, and you'll let me know how it worked.

Concerning sec. 11, my opinion is that additional explanatory notes that mostly concern the usage of the tool should precede Internal Tech Info. So I would say swap the two sections. Unless yoy have another idea.

[rpgoldman]

I am happy to make this change; just wanted to confirm it was what you suggested.

[ko56]

I am still struggling with git. I have a directory "shop3" which contains the master branch:

[ko@wiley ~/build]$ l shop3
img/        jenkins/    README.md   shop3/
[ko@wiley ~/build]$ 

I also have a directory "shop3-manual-fixes":

[ko@wiley ~/build]$ l shop3-manual-fixes
shop3/
[ko@wiley ~/build]$ l shop3-manual-fixes/shop3/
img/        jenkins/    README.md   shop3/
[ko@wiley ~/build]$ 

I created shop3-manual-fixes because git wouldn't let me check out the manual-fixes branch under ~/build. It said that the name "shop3" was already existing.

Anyhow, now I have some new changes in ~/build/shop3-manual-fixes/shop3/shop3/docs. What do I do to create a patch to send you?

[ko56]

I created the branch by

[ko@wiley ~/build]$ cd shop3-manual-fixes
[ko@wiley ~/build/shop3-manual-fixes]$ git clone -b manual-fixes https://github.com/shop-planner/shop3.git
...
[ko@wiley ~/build/shop3-manual-fixes]$ 

Maybe I should have cd'd to ~/build/shop3 and created the branch there? If so, I can easily go back and do this.

[rpgoldman]

I see what you did wrong. To make a branch you should just have done

git checkout -b manual-fixes

You don't re-clone to make a branch.

When you do git checkout it does not matter what directory you are in (well, except you should not be in one of the submodules below jenkins).

You ended up with an entirely new copy of the repository instead of a branch in the repo.

[ko56]

I think I finally have some sucess! Here is what I did:

[ko@wiley ~/build/shop3]$ git checkout -b manual-fixes
Switched to a new branch 'manual-fixes'
<I now edited docs/manual.texinfo. ...>
[ko@wiley ~/build/shop3] git checkout manual-fixes
[ko@wiley ~/build/shop3]$ git add shop3/docs/manual.texinfo
[ko@wiley ~/build/shop3]$ git commit
[ko@wiley ~/build/shop3]$ git checkout master
[ko@wiley ~/build/shop3]$ git diff -p master manual-fixes > man.patch

I attach the file. Let me know if it makes sense, I still don't understand git. (Updated 8/21/2021) man.patch.gz

[rpgoldman]

I just got around to testing this and I am having some trouble. I did patch < man.patch and this is what happened:

$ patch < ~/Downloads/man.patch
can't find file to patch at input line 5
Perhaps you should have used the -p or --strip option?
The text leading up to this was:
--------------------------
|diff --git a/shop3/docs/manual.texinfo b/shop3/docs/manual.texinfo
|index 7bf5b2e..605a4f2 100644
|--- a/shop3/docs/manual.texinfo
|+++ b/shop3/docs/manual.texinfo
--------------------------
File to patch: shop3/docs/manual.texinfo
patching file shop3/docs/manual.texinfo
Reversed (or previously applied) patch detected!  Assume -R? [n] y
Hunk #13 FAILED at 1010.
Hunk #14 FAILED at 1023.
Hunk #18 FAILED at 1185.
Hunk #19 FAILED at 1201.
Hunk #20 FAILED at 1244.
Hunk #21 succeeded at 1270 (offset -4 lines).
Hunk #22 FAILED at 1315.
Hunk #23 succeeded at 1409 (offset -4 lines).
Hunk #24 succeeded at 1472 (offset -4 lines).
Hunk #25 succeeded at 1488 (offset -4 lines).
Hunk #26 succeeded at 1521 (offset -4 lines).
Hunk #27 succeeded at 1549 (offset -4 lines).
Hunk #28 succeeded at 1591 (offset -4 lines).
Hunk #29 succeeded at 1623 (offset -4 lines).
Hunk #30 succeeded at 1971 (offset -4 lines).
Hunk #31 succeeded at 2003 (offset -4 lines).
Hunk #32 succeeded at 2456 (offset -4 lines).
Hunk #33 succeeded at 2537 (offset -4 lines).
Hunk #34 succeeded at 2660 (offset -4 lines).
Hunk #35 succeeded at 2980 (offset -4 lines).
Hunk #36 succeeded at 3609 (offset -4 lines).
Hunk #37 succeeded at 3729 (offset -4 lines).
Hunk #38 succeeded at 3740 (offset -4 lines).
6 out of 38 hunks FAILED -- saving rejects to file shop3/docs/manual.texinfo.rej

I'm not sure why patch printed nothing about Hunks 1-12 before starting to print the above.

But I'm afraid that we are having troubles because you have been working against master, instead of against the manual-fixes branch, which is what resulted from me applying your previous patches.

I will look at this and see if the results make sense and update this issue.

[rpgoldman]

I think you could try

git diff -p origin/manual-fixes manual-fixes > man.patch

That would take the difference between your local manual-fixes, and the one that is at github. That assumes that your origin is the same as mine. If you forked the repository, then you might need to do something different. Keep me posted.

[rpgoldman]

P.S. I may be able to work through your changes and get them committed. I will update here ASAP.

[ko56]

I think you could try

git diff -p origin/manual-fixes manual-fixes > man.patch

That would take the difference between your local manual-fixes, and the one that is at github. That assumes that your origin is the same as mine. If you forked the repository, then you might need to do something different. Keep me posted.

Sorry about the confusion. I'm still not comfortable with git. What I originally did is

git clone --recurse-submodules https://github.com/shop-planner/shop3.git

and updated periodically by

git pull --recurse-submodules origin master)

But I am confused about how branches work. Let me try what you suggest, and repost the patch.

[ko56]

What branch should I be in whenI try your command? If I am in master, I get

[ko@wiley ~/build/shop3]$ git diff -p origin/manual-fixes manual-fixes > man.patch
fatal: ambiguous argument 'origin/manual-fixes': unknown revision or path not in the working tree.
Use '--' to separate paths from revisions, like this:
'git <command> [<revision>...] -- [<file>...]'
[ko@wiley ~/build/shop3]$

If I switch to manual-fixes by git checkout manual-fixes, same error.

[rpgoldman]

Try git fetch origin. That should get you all the contents of my repo (you may just have been getting the master branch).

After that, try the diff again and we can see if that does it.

Git does have a very steep learning curve, I'm afraid.

[ko56]

So try

[ko@wiley ~/build/shop3]$ git fetch origin --recurse-submodules https://github.com/shop-planner/shop3.git

?

[rpgoldman]

I think that's right, but I'm not sure what --recurse-submodules does. Anyway, it shouldn't matter for this case since the documentation is not contained in a submodule.

[ko56]

Am I in the wrong directory when doing this, or is something else wrong?

[ko@wiley ~/build/shop3]$ git fetch origin https://github.com/shop-planner/shop3.git
fatal: invalid refspec 'https://github.com/shop-planner/shop3.git'
[ko@wiley ~/build/shop3]$

[rpgoldman]

What's gone wrong there is that git is interpreting the URL you gave it as the identifier for a thing like a branch that you are trying to fetch, and it can't parse it.

All you need is git fetch origin : that will fetch all the contents of origin, but will not merge origin/manual-fixes into your local copy of manual-fixes. And that's what you want, because after that, you can do git diff origin/manual-fixes manual-fixes and see what changes are only in your local manual-fixes.

Meanwhile, I will see if the diffs I have are enough to make it possible for me to apply your patch.

[ko56]

OK, I did it. Hopefully correctly. See attached. man.diff.gz

[ko56]

I have made some more changes to the manual, hopefully taking into account the latest from your end. But git still confuses me, so I'm simply attaching manual.texinfo.gz and you can easily see the changes with Emacs' ediff mode.