Better examples, man page

README.rst

@@ -5,25 +5,44 @@ One should use the right tool for the right task. But Learning 300 tools is coun
 
 Enters **py1**, it aims at being a "Python AWK". It can be used in two modes.
 
-In both modes indents and dedents can be replaced with “``{{``” and “``}}``”.
+In both modes indents and dedents can be replaced with “``{{``” and “``}}``”, line feeds can be replaced with “``;``”.
 
 Minimalist
 ----------
 
-You simply provide as a single argument the program with curly brackets.
+To use this mode:
 
-.. code:: bash
+.. code-block:: bash
+
+   py1 "python_one_liner"
+
+"{{" and "}}" can be used instead of indent/dedent, and ";" instead of line feed eg:
+
+.. code-block:: bash
+
+   py1 "import sys ; if True: {{ print(sys.version) }}"
 
-    py1 "for x in range(4): {{ print x; print x*2 }}"
 
 AWK-like
 --------
 
-You provide ``--begin``/``-b``, ``--each-line``/``-l``, ``--end``/``-e``. py1 generates a python script wrapping them and defining a convenient set of 1&2-letters variables and functions.
+In this mode, py1 generates a python script wrapping your code and defining a convenient set of 1&2-letters variables and functions.
+
+To use this mode, pass any of ``--begin``/``-b``, ``--each-line``/``-l``, ``--end``/``-e``.
+
+For example, to count lines matching ``'$a*^'``:
+
+.. code-block:: bash
 
-.. code:: bash
+    py1 --begin "count=0" --each-line "if M('$a*^'): count += 1"
+        --end "P(count)"
+
+To learn more you can read the
+`list of one letter functions and variables <http://py1.vleu.net/page/variables.html>`_
+or just look at
+`examples <http://py1.vleu.net/page/examples.html>`_
+and figure out the rest.
 
-    py1 --begin "count=0" --each-line "if 'cow' in L: count += 1" --end "P(count)"
 
 Sustainable hacking
 -------------------
@@ -43,6 +62,7 @@ or just look at
 `examples <http://py1.vleu.net/page/examples.html>`_
 and figure out the rest.
 
+
 How to contribute?
 ------------------
 

docs/conf.py

@@ -243,8 +243,8 @@
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    ('index', 'py1', 'py1 Documentation',
-     ['Brice Arnould'], 1)
+    ('man', 'py1', 'sensible Python one-liners',
+    ['Brice Arnould'], 1)
 ]
 
 # If true, show URL addresses after external links.

docs/examples.rst

@@ -1,3 +1,6 @@
+.. highlight:: bash
+
+
 Examples
 ========
 
@@ -32,7 +35,7 @@ Show lines matching the regexp '$a+^'.
 
 .. code:: bash
 
-    py1 -l 'if M('$a+^', L): P(L)'
+    py1 -l 'if M("$a+^", L): P(L)'
 
 Here we use the M matching function to match the regexp.
 
@@ -54,5 +57,5 @@ Given a file of '$name $value', with name being repeated, sum the values for eac
 
 .. code:: bash
 
-    py1 -b 'd=defaultdict(int)' -l 'd[L[0]] += int(L[1])'  \
+    py1 -b 'd=defaultdict(int)' -l 'd[L[0]] += int(L[1])'
         -e 'for n, v in d: P(n, v)'

docs/man.rst

@@ -0,0 +1,56 @@
+:orphan:
+
+py1 manual page
+===============
+
+Synopsis
+--------
+
+**py1** < [-b *BEGIN*] [-e *END*] [-l *EACH_LINE*] | *python_one_liner* >
+
+Description
+-----------
+Enables one to write Python one-liners. It is meant to be used in interactive shell sesssions and provide a slightly augmented Python language where {{ }} can be used instead of indent/dedent.
+
+Minimalist mode
+---------------
+
+To use this mode:
+
+   **py1** *python_one_liner*
+
+"{{" and "}}" can be used instead of indent/dedent, and ";" instead of line feed eg:
+
+   **py1** "import sys ; if True: {{ print(sys.version) }}"
+
+
+Awk-like mode
+-------------
+
+In this mode, py1 generates a python script wrapping your code and defining a convenient set of 1&2-letters variables and functions.
+
+To use this mode, pass any of **-b**/**--begin**, **-l**/**q--each-line**, **-e**/**--end**.
+
+For example, to count lines matching '$a*^':
+
+.. code:: bash
+
+   py1 --begin "count=0" --each-line "if M('$a*^'): count += 1"
+       --end "P(count)"
+
+For more examples, please see `http://py1.vleu.net/examples.html`, for the definition of all 1-letter varibles, please refer to `http://py1.vleu.net/variables.html`. 
+
+Options
+-------
+
+  -h, --help            show an help message and exit
+
+  -c, --dump-code       show the code that would have been run
+
+  -V, --version         show program's version number and exit
+
+  -b BEGIN, --begin BEGIN   as per "Awk-like mode" above
+
+  -e END, --end END   as per "Awk-like mode" above
+
+  -l EACH_LINE, --each-line EACH_LINE   as per "Awk-like mode" above