[PATCH 3 of 5] extensions: improve the consistency of synopses

[Martin Geisler]

Dirkjan Ochtman <dirkjan at ochtman.nl> writes:

> Okay, so I have some comments here... Sorry for the bikeshedding.
>
> First, why are we wrapping everything at 70 chars? It makes comments
> require more lines in the code, and it looks stupid in a
> defaulting-to-80 terminal. For example, this means the description
> line for share and zeroconf wrap to the next line when they really
> don't need to, which looks ugly and feels stupid.

We discussed this briefly on IRC -- it is obviously needed in order to
handle translations which require more space. But you're right that it
could be better to use 78-80 chars for the short description strings.

The main texts are wrapped at 70 chars, partly because it is the default
in Emacs and partly because it gives a nice indent on both sides (though
it's 4 chars on left and 10 on right). We could increase this to 76
chars to get a symmetric indent?

By the way, at some distant point in the future I hope we're using reST
to format the strings and that we can let the help system process the
strings and reflow them dynamically to match the terminal width...

> Summarizing comments below:
>
> - Providing hooks to do something does not equal doing that
> - Providing commands to do something does not equal doing that, either

I'm reading the short descriptions as

  "extension X let's me [short description]"

and so the new short descriptions make good sense to me.

> - Making non-obvious dependencies explicit is a good thing

I agree, let's add Pygments back to the short description.

-- 
Martin Geisler

VIFF (Virtual Ideal Functionality Framework) brings easy and efficient
SMPC (Secure Multiparty Computation) to Python. See: http://viff.dk/.