[pypy-commit] extradoc extradoc: some tweaks and comments

[cfbolz]

Author: Carl Friedrich Bolz <cfbolz at gmx.de>
Branch: extradoc
Changeset: r5660:7c07538c059b
Date: 2016-08-01 17:44 +0200
http://bitbucket.org/pypy/extradoc/changeset/7c07538c059b/

Log:	some tweaks and comments

diff --git a/blog/draft/new-jit-log.rst b/blog/draft/new-jit-log.rst
--- a/blog/draft/new-jit-log.rst
+++ b/blog/draft/new-jit-log.rst
@@ -1,12 +1,18 @@
 PyPy's Toolbox got a new Hammer &#x1f528;
 =======
 
+.. : XXX the title is very generic
+
+.. : XXX I don't actually like the first paragraph, I think it should be more
+    to the point. eg that things happened at the Leysin sprint doesn't matter much.
+    I would also add links to all the existing tools
+
 Tools, tools, tools! It seems that PyPy cannot get enough of them!
-In the last winter sprint (Leysin) covered the current tool for observing interals of the JIT compiler (JitViewer). VMProf at that time already proved that it is a good tool for CPU profiles. We are happy to release a new version of VMProf incooperating a rewritten version of JitViewer.
+In the last winter sprint (Leysin) covered the current tool for observing internals of the JIT compiler (JitViewer). VMProf at that time already proved that it is a good tool for CPU profiles. We are happy to release a new version of VMProf incorporating a rewritten version of JitViewer.
 
-The old logging format, is a hard to maintain plain text logging facility. Frequent changes often broke internal tools most notably the JITViewer. A second bad taste is that the logging output of a long running program takes a lot of space.
+The old logging format was a hard to maintain plain text logging facility. Frequent changes often broke internal tools, most notably the JITViewer. Another problem was that the logging output of a long running program took a lot of disk space.
 
-Our new binary format encodes data densly, makes use of some compression (gzip) and tries to remove repetition where possible. On top of that protocol supports versioning and can be extended easily. And! *durms* you do not need to install JitViewer yourself anymore. The whole system moved to vmprof.com and you can use it any time free of charge.
+Our new binary format encodes data densly, makes use of some compression (gzip) and tries to remove repetition where possible. On top of that protocol supports versioning and can be extended easily. And *drumroll* you do not need to install JitViewer yourself anymore! The whole system moved to vmprof.com and you can use it any time.
 
 Sounds great. But what can you do with it? Here are two examples useful for a PyPy user:
 
@@ -15,7 +21,7 @@
 
 For some hard to find bugs it is often necessary to look at the compiled code. The old procedure often required to upload a plain text file which was hard to parse and to look through. 
 
-The new way to share a crash report is to install vmprof and execute either of the two commands:
+The new way to share a crash report is to install the ``vmprof`` module from PyPi and execute either of the two commands:
 
 ```
 # this program does not crash, but has some weird behaviour
@@ -42,13 +48,13 @@
 
 We hope that the new release will help both PyPy developers and PyPy users resolve potential issues and easily point them out.
 
-Here are a few ideas what might come in the next few releases ().
+Here are a few ideas what might come in the next few releases:
+
+* Combination of CPU profiles and the JITLOG (Sadly did not make it into the current release)
 
 * Extend vmprof.com to be able to query vmprof/jitlog. Some times it is interesting to search for specific patterns the compiler produced. An example for vmprof: 'methods.callsites() > 5' and for the jitlog would be 'traces.contains('call_assembler').hasbridge('*my_func_name*')'
 
-* Combination of CPU profiles and the JITLOG (Sadly did not make it into the current release)
-
 * Extend the jitlog to capture the information of the optimization stage
 
-plan_rich and the PyPy team
+Richard Plangger (plan_rich) and the PyPy team