write-a-C-interpreter icon indicating copy to clipboard operation
write-a-C-interpreter copied to clipboard

Polish English Tutorial

Open tajmone opened this issue 3 years ago • 6 comments

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.

tajmone avatar Mar 13 '21 16:03 tajmone

@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 avatar Mar 13 '21 16:03 tajmone

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).

tajmone avatar Mar 13 '21 16:03 tajmone

@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.

lotabout avatar Mar 14 '21 01:03 lotabout

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

tajmone avatar Mar 14 '21 09:03 tajmone

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 avatar Mar 14 '21 10:03 tajmone

OK, I've finished polishing all the chapters.

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

tajmone avatar Mar 14 '21 16:03 tajmone