Update README.md #1

ovidr · 2018-07-09T05:40:27Z

Renamed "How?" to "How it Works"
Removed avoidable phrases and commas
Reorganized bullet points under "Caveats" section

Renamed "How?" to "How it Works" Removed avoidable phrases and commas Reorganized bullet points under "Caveats" section

ovidr · 2018-07-09T05:40:48Z

Hello,
I have made some changes to your README file. The reason is that I am tasked by my professor to help github projects be more easy to read and understand. I have not made any changes to your code.

Thank you for your time.

shdown

What sort of classes do you take?

shdown · 2018-07-09T06:10:52Z

README.md

 ===
-There’s nothing new in Lua being flexible: it allows to override all the memory management by passing a custom allocator to [`lua_newstate`](https://www.lua.org/manual/5.3/manual.html#lua_newstate).


The reason I used a colon here is, the second part explains/illustrages the first one. According to http://www.thepunctuationguide.com/colon.html, colon is particulary used

Between independent clauses when the second explains or illustrates the first

The colon is used to separate two independent clauses when the second explains or illustrates the first. In such usage, the colon functions in much the same way as the semicolon. As with the semicolon, do not capitalize the first word after the colon unless the word is ordinarily capitalized.

I have very little time to learn the language: my new job starts in five weeks.

A college degree is still worth something: a recent survey revealed that college graduates earned roughly 60% more than those with only a high school diploma.

All three of their children are involved in the arts: Richard is a sculptor, Diane is a pianist, and Julie is a theatre director.

Are you sure we don’t need this “the”?

The main reasons for all the changes I have made is to make it easier for a reader to understand. It could be grammatically correct, but may still be confusing to read.

Yes, you are correct in using colon to connect two independent clauses together. I changed the colon to a period as they imply the same meaning for me when I had read the sentence for the first time. So using colon or period are both okay, but I chose periods for the sake of avoiding confusion between the two clauses.

"the" is to be used for definite articles and when a noun is specified. Using "all the memory management" is not specific as "all" was used, so "the" was removed. Source: https://owl.english.purdue.edu/owl/resource/540/1/

Definite Article: the
The definite article is used before singular and plural nouns when the noun is specific or particular. The signals that the noun is definite, that it refers to a particular member of a group.

shdown · 2018-07-09T06:41:42Z

README.md

 The only things left are to create a shared memory mapping and implement an allocator working in it.

-This is more or less safe as long as Lua knows nothing about parallelism. Some things in the standard library do know, though; see the “Caveats” section.


Why did you remove “more of less”? This isn’t entirely safe, for example if Lua made some weird use of signals, or something like that.

“though” is there for a reason: the second clause is in contrast with the first one; in these cases, “though” is used.

“please” is usually not used with “see”.

"more or less" does not really help the reader clarify how safe Lua is. It is best to avoid uncertainty by specifically mentioning the conditions in which Lua is not safe. Mentioning parallelism is one condition, and maybe more could have been added? I'll let you decide.

My aim was to remove the semi-colon and comma so "though" was removed as well. Maybe a better sentence would be: "See the 'Caveats' section for what things the standard library does know"?

I agree, "please" is not necessary in this sentence. Sorry about that. My 2nd point suggests a sentence without it.

shdown · 2018-07-09T06:46:57Z

README.md


-On systems other that Linux, shared memory mappings have to be of fixed size; by default, this PoC allocates 16 Mb on these systems.


Why this change? We have two related independent clauses but no conjunction is used; so we need to use a semicolon.

The sentence is too long. I do not think we need to use a semi-colon whenever there are two related independent clauses. Both clauses can be separate sentences, and still give the same message.

shdown · 2018-07-09T06:58:14Z

README.md


 In fact, Linux shared memory mappings also have to be of fixed “size” — of fixed *virtual size*:
 thanks to the [overcommit feature](https://www.kernel.org/doc/Documentation/vm/overcommit-accounting) and the [`MAP_NORESERVE`](http://man7.org/linux/man-pages/man2/mmap.2.html) `mmap` flag,
 which tells Linux to only allocate physical pages on demand (this does *not* depend on which overcommit policy your system is configured to use), we can only pay for what we use,
 and not a page more. And with [`madvise(..., MADV_REMOVE)`](http://man7.org/linux/man-pages/man2/madvise.2.html), we can reclaim the pages we don’t need anymore. Yay!

-On Linux, this PoC goes on to allocate 16 Gb of *virtual* memory. Because this ought to be enough for anybody.


Why did you remove “goes on to”? I’m not sure if this is a correct usage, but I just wonder what your motivation was.

The second sentence is a reference to (supposedly) Bill Gates’ quote (https://quoteinvestigator.com/2011/09/08/640k-enough/) which I beleive you didn’t get. Since it’s a half-joke, it has to be separated from the “serious” part.

"goes on to" is not needed. "allocates" is shorter and still gives the same message.

I had not known that it was a reference. I take back my revision. Separating the sentences is the better option. Thank you for the article.

shdown · 2018-07-09T06:58:59Z

README.md


 In fact, Linux shared memory mappings also have to be of fixed “size” — of fixed *virtual size*:
 thanks to the [overcommit feature](https://www.kernel.org/doc/Documentation/vm/overcommit-accounting) and the [`MAP_NORESERVE`](http://man7.org/linux/man-pages/man2/mmap.2.html) `mmap` flag,
 which tells Linux to only allocate physical pages on demand (this does *not* depend on which overcommit policy your system is configured to use), we can only pay for what we use,
 and not a page more. And with [`madvise(..., MADV_REMOVE)`](http://man7.org/linux/man-pages/man2/madvise.2.html), we can reclaim the pages we don’t need anymore. Yay!

-On Linux, this PoC goes on to allocate 16 Gb of *virtual* memory. Because this ought to be enough for anybody.
-If your virtual memory is, in some reason, limited, run it as `./main -p`, which forces it to fall back to a portable 16 Mb mapping.


These changes just for sake of changes are no good.

"in some reason" is not useful information for the reader so that is why I removed it.
If-then is a common method of writing conditional sentences.
In your original sentence, there are four commas which makes the sentence is too long so I split it into two sentences.

shdown · 2018-07-09T07:02:24Z

README.md

-
-* My memory allocator sucks. Implementing a better one — possibly leveraging the aforementioned Linux features — is left as an exercise for the reader.
-
+* Some functions in Lua’s standard library *really* don’t expect being called with such a setup. These functions are `os.execute`, `io.popen`, `os.exit`, and `os.setlocale`.


The line is too long.

It is long, but I joined them together to be consistent with the bullet-point ordering.

shdown · 2018-07-09T07:03:09Z

README.md

-* My memory allocator sucks. Implementing a better one — possibly leveraging the aforementioned Linux features — is left as an exercise for the reader.
-
+* Some functions in Lua’s standard library *really* don’t expect being called with such a setup. These functions are `os.execute`, `io.popen`, `os.exit`, and `os.setlocale`.
+* All actions on files, including opening and closing, are local to the current process.


It was better that way.

Sure, both ways are correct. Whichever one you choose is fine.

shdown · 2018-07-09T07:05:28Z

README.md

-
+* Some functions in Lua’s standard library *really* don’t expect being called with such a setup. These functions are `os.execute`, `io.popen`, `os.exit`, and `os.setlocale`.
+* All actions on files, including opening and closing, are local to the current process.
+* My memory allocator is not optimal. Implementing a better one — possibly leveraging the aforementioned Linux features — is left as an exercise for the reader.


“not optimal” may create an illusion that it… eh, does not suck. And it does suck. So no.

If you say so. I generally avoid saying "suck" to describe my work.

shdown · 2018-07-09T07:17:58Z

You could also try your luck updating README.md of https://github.com/shdown/luastatus.

ovidr · 2018-07-10T04:47:43Z

The class I take talks about technical communication, but also focuses on judging writing based on the perspective of a reader.
Sorry for not explaining my revisions clearly.
I will try to change your other README.md file.

Thank you for your time.

Update README.md

ba71af2

Renamed "How?" to "How it Works" Removed avoidable phrases and commas Reorganized bullet points under "Caveats" section

shdown reviewed Jul 9, 2018

View reviewed changes

		===
		There’s nothing new in Lua being flexible: it allows to override all the memory management by passing a custom allocator to [`lua_newstate`](https://www.lua.org/manual/5.3/manual.html#lua_newstate).

		The only things left are to create a shared memory mapping and implement an allocator working in it.

		This is more or less safe as long as Lua knows nothing about parallelism. Some things in the standard library do know, though; see the “Caveats” section.


		On systems other that Linux, shared memory mappings have to be of fixed size; by default, this PoC allocates 16 Mb on these systems.


		* My memory allocator sucks. Implementing a better one — possibly leveraging the aforementioned Linux features — is left as an exercise for the reader.

		* Some functions in Lua’s standard library really don’t expect being called with such a setup. These functions are `os.execute`, `io.popen`, `os.exit`, and `os.setlocale`.

Update README.md #1

Are you sure you want to change the base?

Update README.md #1

Uh oh!

Conversation

ovidr commented Jul 9, 2018

Uh oh!

ovidr commented Jul 9, 2018

Uh oh!

shdown left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Between independent clauses when the second explains or illustrates the first

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

shdown commented Jul 9, 2018

Uh oh!

ovidr commented Jul 10, 2018

Uh oh!

Uh oh!