Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Polish English Tutorial #37

Open
wants to merge 2 commits into
base: master
Choose a base branch
from

Conversation

tajmone
Copy link

@tajmone tajmone commented Mar 13, 2021

Polish the English text of every tutorial chapter, and Improve markdown source docs:

  • Add Level 1 title to docs ("Preface", "1. Skeleton", etc.).
  • Replaces smiles with markdown emojis.
  • Fix titles casing using Chicago Manual of Style capitalization rules:
    https://capitalizemytitle.com/style/chicago#
  • Convert inline-link to reference-style links (DRY!).
  • Add a few links to external references.
  • Add .editorconfig and .gitattributes settings to enforce code styles consistency across different editors and IDEs.

Add `.editorconfig` and `.gitattributes` settings to enforce
code styles consistency across different editors and IDEs.
@tajmone
Copy link
Author

tajmone commented Mar 13, 2021

@lotabout, here's my contribution to your great project, by polishing up the English text.

Before going ahead with the remaining tutorial chapters, let me first know if my contribution plays out well with you. If you do confirm, I'll go ahead and polish the other chapters too.

You wrote:

Finally, this series is written in Chinese in the first place, feel free to correct me if you are confused by my English.

Not being able to read the original text in Chinese, I've done my best to adapt the text to its general context, trying to polish it and flesh it out so that it would be smoother to read.

And I would like it very much if you could teach me some "native" English :)

Feel free to drop some questions in this PR thread, e.g. asking why I changed a sentence in a given way, etc. I'll be happy to reply to the best of my knowledge and ability.

@tajmone
Copy link
Author

tajmone commented Mar 13, 2021

Question About an Ambiguous Sentence

@lotabout, I have a question about th paragraph in the Before you go section:

Before you go

Implementing a compiler could be boring and it is hard to debug. So I hope you can spare enough time studying, as well as type the code. I am sure that you will feel a great sense of accomplishment just like I do.

I wasn't sure whether you meant:

  1. Implementing a compiler can be boring and hard to debug, therefore you chose to go for an interpreter instead, and that you hope this will spear the reader some time (because it's easier to study) and having to type code (because you provide the source files with the tutorial).
  2. Implementing a compiler can be boring and hard to debug, therefore you hope that the reader will find enough time to study the subject and type out the required code.

Not being sure, I took the safe approach and stuck to (2), which is closer to the current text; but somehow, I have the gut feeling that you really meant (1) — if that's the case, I can rephrase that sentence and force-push the commit, before merging (or rebasing) the PR (rebasing seems a better option, since there are two commits in this PR, for it would keep history linear).

@lotabout
Copy link
Owner

@tajmone Thanks for the careful proofreading.

I have a question about the paragraph in the Before you go section:

What I want to say is: Though building a compiler/interpreter could be fun and self-accomplishment, it's a hard process because:

  1. There are quite a lot of boilerplate to work with. e.g. we may be satisfied with knowing how + operator works but still need to write code for -, *, / and other operators.
  2. The compiler/interpreter's code is hard to debug, make it work would cost much time.

So, I hope readers not to be too optimistic and aware the obstacles ahead the road. But of cause it's worth the effort.

@tajmone
Copy link
Author

tajmone commented Mar 14, 2021

Then that sentence is good as it is. Feel free to merge/rebase the PR:

@tajmone tajmone force-pushed the polish-EN-tutorial branch 2 times, most recently from 94b1c11 to eed9483 Compare March 14, 2021 10:44
@tajmone tajmone changed the title Polish Preface Polish "Preface" & "Skeleton" Mar 14, 2021
@tajmone
Copy link
Author

tajmone commented Mar 14, 2021

I've combined the fixes to "1. Skeleton" with the last commit and forced pushed, so we can reduce the number of commits (but I've kept the EditorConfig commit separate, for it deals with different changes).

@tajmone tajmone changed the title Polish "Preface" & "Skeleton" Polish English Tutorial Mar 14, 2021
@tajmone tajmone force-pushed the polish-EN-tutorial branch 7 times, most recently from 21b3b34 to 839dd2f Compare March 14, 2021 16:01
Polish the English text of every tutorial chapter, and Improve markdown
source docs:

* Add Level 1 title to docs ("Preface", "1. Skeleton", etc.).
* Replaces smiles with markdown emojis.
* Fix titles casing using Chicago Manual of Style capitalization rules:
  https://capitalizemytitle.com/style/chicago#
* Convert inline-link to reference-style links (DRY!).
* Add a few links to external references.
@tajmone
Copy link
Author

tajmone commented Mar 14, 2021

OK, I've finished polishing all the chapters.

Feel free to merge if there's no more reviewing needed.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

2 participants