RELEASED: pynits 040615

[François Pinard]

Hi, my Python and Vim friends.

Here is the initial release of `pynits', and the beginning of its
documentation file.  I hope some courageous souls will help me at
eradicating packaging and other blunt bugs! :-)



*pynits.txt*	Tidying up Python files

                        TIDYING PYTHON CODE WITHIN VIM

                               François Pinard
                           pinard at iro.umontreal.ca

Pynits is a tool which I find useful while editing Python source code
with Vim, for tidying up individual sources lines, and some auxiliary
tasks.  It is particularly helpful when formatting lines holding long
or complex expressions.  This tool requires a Python-enabled Vim.

1. Introduction                         |pynits-introduction|
2. Finding nits                         |pynits-finding-nits|
3. Reformatting lines                   |pynits-reformatting|
4. Other commands                       |pynits-other-commands|

The Pynits tool may be downloaded from:
    http://fp-etc.progiciels-bpi.ca/showfile.html?mode=archives
while installation directives may be found at:
    http://fp-etc.progiciels-bpi.ca/showfile.html?name=pynits/README
This file you are reading is also available on the Web as:
    http://fp-etc.progiciels-bpi.ca/showfile.html?name=pynits/pynits.txt

WARNING: This tool is in alpha state, its specifications may change.
Write to the author for corrections, suggestions or bug reports.

==============================================================================
1. Introduction					*pynits-introduction*

I once had to take over the maintenance of a set of big Python modules,
written by someone without much concern about source line length limits,
and also a bit lacking in the area of sound coding standards.  The
sources were hard to read on an usual terminal screen, hard to print
without stunts on a printer, hard to edit: in a word, hard to maintain.

When it comes to source coding standards, people develop religious
feelings.  My personal coding practices, which are somehow reflected in
this tool, are surely debatable and questionable, yet I dare to think
they are quite reasonable.  I use an eclectic choice of good ideas from
various sources: the Python mode as written for GNU Emacs, the standard
Python plugin for Vim, Guido's own style as he documented it, some
relevant parts of GNU and Gnits standards, good horse sense, but also,
my own programming experience, accumulated for a good while by now.

Source code lines are often carefully crafted by programmers, and a
reformatting tool may defeat local art work.  This is why I think
reformatting is best done from with a scalpel, like Vim may be, than
operated in bulk or in batch.  The programmer may choose to accept or
refuse, on a line basis, suggestions made by a tool like this one.

There are three sets of commands in this tool.  The first set is meant
to discover and report various formatting nits.  The programmer may then
ask the tool for correcting them, when a correction recipe is known.
The second set takes a whole Python source line, possibly continued, and
fully rebuilds a surface representation from its syntax tree.  The third
set contains a few random commands for simple tasks.

[...]

-- 
François Pinard   http://www.iro.umontreal.ca/~pinard