Convert 10 PEPs to reSt

[Mariatta]

PEP 212
PEP 216
PEP 219
PEP 228
PEP 235

PEP 269
PEP 288
PEP 312
PEP 315
PEP 3102

#4

[berkerpeksag]

I suggest using ``...`` formatting consistently (or don't use it at all) CONSTANTs and function()s aren't the only things that can be wrapped by ``...``. If you change irange() to ``irange()``, I'd expect the following sentence to be formatted too:

This solution adds two built-in functions 'indices' and 'irange'.

I guess you have a script that converts these PEPs to reST format, but It would be nice to do some proofreading before sending a PR.

[brettcannon]

Yep, @Mariatta has written a script to do the conversion.

[gvanrossum]

While I think a moderate amount of proofreading and manual fix-up is warranted, I don't think the formatting needs to be perfect. We're mostly trying to improve the rendering of old historical documents, and if occasionally something isn't using a code font that is code, that's fine with me. Someone else can do some proofreading. The most important thing is that we don't accidentally break the meaning of a PEP.

[Mariatta]

Thanks for the review, @berkerpeksag @brettcannon and @gvanrossum :)

I've gone through these again, and made these changes:

• PEP 212:
  replace the single quotes (') with backticks (``) for:
  'range', 'zip', 'indices', 'irange'

  Fix typo: dicitionaries -> dictionaries

• PEP 216:
  poplib module -> poplib module

• PEP 228:
  math module -> math module
  cmath module -> cmath module

• PEP 312:
  Inline "if" -> Inline if

  Add reference url to a python-dev discussion about PEP 308.

Please let me know if you notice anything else that needs adjustment.

[brettcannon]

Since you already address the backtick request from @berkerpeksag and I'm with Guido that as long as the content's meaning doesn't shift I'm not too worried about minor formatting, I'm merging this. Thanks @Mariatta !

[Mariatta]

Thanks :)

[berkerpeksag]

Here are some additional comments:

• `something` is not a valid markup for making something italic. We have a rule for this in the linter we use for CPython documentation

• In PEP 235, the paragraph starts with

  then if Python finds ``FiLe.py`` first [...]
  

  is part of the first item of the list.

• docutils will convert the following bullet points to numbered ones:

  a. foo
  b. bar
  
  A. spam
  B. eggs
  

  will be rendered as:

  1. foo
  2. bar
  
  1. spam
  2. eggs
  

  This might look harmless most of the time, but for example, in PEP 235,
  the following sentences refer to them as #A and #B:

  #B is the same rule as is used on Unix, so this will improve cross-
  platform portability.
  

  and

  #A is needed to cater to case-destroying filesystems mounted on Windows,
  and *may* also be used by people so enamored of "natural" Windows
  behavior that they're willing to set an environment variable to
  get it.
  

  See https://www.python.org/dev/peps/pep-0235/#proposed-semantics

d558317 and e511fb5 should address some of these comments, but the last one still needs to be fixed.

[Mariatta]

Sorry that I did not notice these mistakes before, and thanks for fixing them @berkerpeksag

but the last one still needs to be fixed.

Any suggestion on how to fix this?
My initial thought is to replace #A and #B with #1 and #2. But then the proceeding paragraph is making a reference to a different #2.

i.e.

The potential damage is here: #2 (matching on ALLCAPS.PY ) is proposed to be dropped.

[brettcannon]

I don't think keeping the references for pointing to specific bullet points is critical. If you would use an explanatory shorthand that does the same thing, e.g. "The second rule is the same rule ..."