Add description of elision with apostrophe

[thoni56]

This PR contains a couple of things which probably should have been separated for cleanliness, but the major contribution is a description of the new elision/contraction feature.

It tries to explain that if the author defines l´ as a definite article and aqua as a noun then the player will be able to type l´aqua and it will do the right thing.

---

Live Preview links

These links are branch based, and will work even after force-pushing to the PR:

• HTML Manual
• PDF Manual

[tajmone]

Since the commit is in conflict with the master branch, I've checked out the whole branch locallly, and created another temporary branch from it so I can rebase it on master and solve the conflicts without affecting your PR branch.

It might take a while, then I'll merge my conflict resolution changes into this branch. But when merging this PR into master we should definitely squash this into single commits (eg., keep the bash build scripts together, and then the doc chages plus the new HTML and PDF docs in another).

I'll have to manually revise some of your changes, because by changing the letter casing of cross reference you've actually broken them (Asciidoctor xrefs are case sensitive). This is why is taking so long, I have to do a three-way diff-merge going through the text in detail (plus, my new Git GUI has a conflict resolution interface which I'm still not acquainted with, but setting the whole thing up to use BeyondCompare for that would take too long right now).

[tajmone]

Arrrrrrrrrrrrggggggggggg!

The xrefs in your commit were right, somehow the titles casing had been changed but when rebasing on master the diff tool show them capitalized.

I have no idea why is that. Probably because your branch was based on a very old point in master history. This also means that I'll need to check how it compares to the latest version of the same doc.

Ok, now I'll:

• remove my last commit and force push.
• checkout the edited chapter 5 in a separate up-to-date branch from master and see how it diffs.

Sorry for the inconvenience.

[tajmone]

Ok, sorry for the inconvenient above, but the conflicts warning and the whole attempt to rebase lead me into confusion. Hopefully, no harm done. (still not sure what went wrong, probably during the rebase operation the diff tool was showing me some old version of the same doc on master, which still had the xrefs in all caps, mea culpa!).

I've just fixed a typo and slightly edited a sentence:

A player might occasionally regret AN command already input,

Beside fixing the AN I've also changed it a little:

A player might occasionally regret a typed command,

It's shorter and IMO more readable.

Personally, I think that the original was far better:

A player might occasionally regret an imparted command,

for imparted is le mot juste in relation to commands (as they say ... you can make a cake 🍰, but baking one is always better). You can type all sort of things on the keyboard, including a command, but imparting is more specific (you can't impart a question, you can only type it or ask it).

Why drop impart in favour of input in the first place? (there are not output commands anyhow — at least as of today we don't have IF works ordering us to do stuff 😜 — so commands are flowing in one direction only).

[tajmone]

@thoni56, I couple of questions regarding merging these new contents...

Beta7 Branch?

Since the apostrophe elision is a new feature, currently only available in dev snapshots, and the Manual currently refers to Alan beta6, should the Alan version mentioned in the Manual be already changed to beta7?

Or should we maybe create a new beta7 branch and merge there the contents in the meantime, so that we then merge them into master once the next Beta is out?

I've also noticed that some command line options have changed too, some probably when beta7 is released the section on command line switches might need revising before merging into master, and possibly some other parts of the document to. This last argument might confirm that having a dedicated beta7 branch to temporary host the contens changes for the upcoming release might be a better choice, to avoid having a Manual which is partly relating to beta6 and partly to beta7.

What to you think?

Extra Note

Also, in this point of the text:

This makes it possible to use natural words as nouns and create “ l’ ” as a synonym for the definite article.

I would add a further clarification:

This makes it possible to use natural words as nouns and create “ l’ ” as a synonym for the definite article (or for a noise word, if articles in player input can be disregarded in the language, as it usually is).

It's not a fundamental point (nor stricly realted to the topic) but it could be a good remainder of how all the different elements fall together in the larger picture.

[thoni56]

I actually tried to rebase locally before pushing but somehow git didn't show anything, so I was quite surprised when I saw the conflict. Had I seen that earlier I probably would have tried other approaches to get in line with master. Sorry about that.

I'm not sure about the "beta7" question. Maybe just let this PR live until beta 7 is another option? Although that would probably increase the number of conflicts going forward. I'm not so fond of branches either since the have the same drawback. But I agree (as I interpret you) that master should be in sync with the latest release.

Perhaps scheduling this PR for an upcoming, yet un-created, milestone would be sufficient. (Milestones are like labels, but you probably new that...)

[tajmone]

Perhaps scheduling this PR for an upcoming, yet un-created, milestone would be sufficient.

Done!

Maybe just let this PR live until beta 7 is another option? Although that would probably increase the number of conflicts going forward.

We can just avoid editing Manual contents in master branch and start working on individual topics on branches, then merge them all into a temporary beta7 branch until we are satisfied that all contents reflect the new release before merging into master. After all, the original Manual has been fully ported to AsciiDoc, and we had somewhow already planned that contents changes should pass through branches and PRs so that they could be discussed and revised before merging.

Hopefully then, the bump to the next Alan Beta could also mark the first official release of the new Manual.

I'm not so fond of branches either since the have the same drawback. But I agree (as I interpret you) that master should be in sync with the latest release.

As long as they are not long-standig branches it should be fine. Also, currently the ported Manual is still referring to Beta 5 anywhow.

I actually tried to rebase locally before pushing but somehow git didn't show anything, so I was quite surprised when I saw the conflict.

I don't understand that either, and I start to think that since the MS acquisition the GitHub default for Continuous Integration might have changed, and that message might actually be something to do with CI.

Still can't work out why when I was locally rebasing it picked an older version of that same chapter, with the old Section titles convention instead of picking the latest one in master (could be an issue with the Git GUI though).

[tajmone]

@thoni56

Dev Branch for Beta7

In view of the upcoming Alan 3.0 beta7 release, I've created a new beta7-prep branch, and mereged branch handle_elisions into beta7-prep and resolved all conflicts on Chapter 5 source by using "theirs" stategy (See: cd0245b).

I propose that from now on we shall do all changes to the Manual in this beta7-prep development branch, which we'll then squash into master once beta7 is publicly available.

I've found a few small things I'd like to fix in the Manual, but I'd rather fix them now in a dev branch than wait for Beta7 to be out, or to work on master and then have to solve more conflicts when the dev branch needs to be merged in (conflicts resolution with markup languages tends to be harder to deal with than code).

That is, unless we agree to just merge right now the beta7-prep branch, even though your changes regarding apostrophes elision are out of synch with the current beta. Whichever we choose for me is fine, but right now I'll keep working on beta7-prep, and wait for the next Alan Beta before integrating changes.

Delete handle_elisions Branch?

So, if you're happy with the conflicts resolution we could close this issue and delete the branch. Note that in the merge I've solved conflicts by chosing your branch ("theirs") for all the manual checks and fixes were done on this branch already, there were just problems integrating it directly into master.

[thoni56]

I think that sounds like a good plan. I've had a quick look at the elision description and that seems fine. So go ahead a delete that branch.

I'll remember to make any documentation updates in the beta7-prep branch.

OT: I got some warnings from asciidoctor when I ran the html_build.sh on cygwin:

asciidoctor: WARNING: invalid reference: Verbs
asciidoctor: WARNING: invalid reference: Pronouns
asciidoctor: WARNING: invalid reference: Syntax Definitions
asciidoctor: WARNING: invalid reference: Syntax Definitions
asciidoctor: WARNING: invalid reference: Distant & Imaginary Objects
asciidoctor: WARNING: invalid reference: Verbs
asciidoctor: WARNING: invalid reference: Exits
asciidoctor: WARNING: invalid reference: Verb Checks

[tajmone]

OT: I got some warnings from asciidoctor when I ran the html_build.sh on cygwin:

Me too (didn't see them before because my "watch" script suppresses STDERR"). I can't believe it, those errors are back. I thought I had solved them before the conflict resolution. I'll look into that and try to amend the situation.

It's a nightmare solving conflicts with AsciiDoc files, the diff output is barely readable.

I'll have to keep the branch until this is solved.

[tajmone]

Ok, solved. This was actually my fault because I had forgot that your edited document was based on an older version of the Manual which used the old naming convention for Alan keywords in section titles.

During my many local attempts to solve the conflicts I had manually edited them, but then when I finally did the changes on the remote branch I must have forgot to redo them (one of those situations where having done something many times makes you believe you did it also in the last edit, which wasn't the case).

Apart from those cross-references, your edited text seems fine. I've checked a few sample of the current document and compared them to versions in the commit history, and it seems to reflect the latest changes. But if you check it once more I'd feel safer.

Let's keep this branch until we merge everything from Beta7 into master, just to be on the safe side.

[thoni56]

Check.

[tajmone]

No Need to Merge: Was Already Done in The Past!

@thoni56,

I'm manually sifting through the changes of this PR, and the more I look into it the more I think the elision changes were already merged into beta7-prep in the past.

I believe these changes were integrated in commit 60e1a1d.

But since the handle_elisions branch also contained some extra commits, not just the ALAN Manual contents updates, it might be worth double checking, to make sure nothing would go lost by skipping this PR.

My understanding is that the changes affected only the following fies:

• manual_05.asciidoc — Sec. "§5.3 » Contractions", and a few other places in the same file.

I've compared the commits diffs of that branch to the current status of manual_05.asciidoc in beta7-prep HEAD, and I can see every single change, so I have reason to believe that the past merge makes this PR redundant.

[thoni56]

Yes, A draftable.com comparison shows that both the current HEAD of beta7-prep and handle-ellisions contain the passage on ellisions. I haven't checked other details since this was the important part.

So I'm closing this PR.