docutils-develop

[Docutils-develop] Project Policies

[David G. <go...@us...>]

I've added a "Project Policies" section to the notes:

    http://docutils.sf.net/spec/notes.html#project-policies

Please take a look; I'd like to hear opinions.  Is it reasonable?  Anything
objectionable?  Thanks.

-- 
David Goodger  <go...@us...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

Re: [Docutils-develop] Project Policies

[Richard J. <rj...@ek...>]

On Thu, 9 May 2002 14:26, David Goodger wrote:
> I've added a "Project Policies" section to the notes:
>
>     http://docutils.sf.net/spec/notes.html#project-policies
>
> Please take a look; I'd like to hear opinions.  Is it reasonable?  Anything
> objectionable?  Thanks.

Looks good to me. Might want to mention the line-continuation indentation 
policy.


   Richard

Re: [Docutils-develop] Project Policies

[David G. <go...@us...>]

Richard Jones wrote:
> Looks good to me. Might want to mention the line-continuation
> indentation policy.

You noticed my fiddling :-).  I just use the Python standard, as
implemented in the Emacs python-mode.  Should I spell out the details,
or is that too anal-retentive?

-- 
David Goodger  <go...@us...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

RE: [Docutils-develop] Project Policies

[Tony J I. (Tibs) <to...@ls...>]

David Goodger wrote:
> I've added a "Project Policies" section to the notes:
>
>     http://docutils.sf.net/spec/notes.html#project-policies
>
> Please take a look; I'd like to hear opinions.  Is it
> reasonable?  Anything objectionable?  Thanks.

Looking at Coding Conventions...

Well, pysource is a big offender on the naming conventions for
non-classes, but I am aware of that and have intended to fix it
(camelCase method names for the visitor methods used to wander over the
Python are indicated by the visitor mechanism [you'll need to add an
allowable exception for cases like this, I'm afraid], and that rather
propagated, even though it is not normally the convention I use). As I
said, something I intend strongly to fix at some point.

The "single quote for string literals" is a problem to me - I have never
been aware of this preference - indeed, I thought the "standard" Python
preference was the other way round (for no reason I can think of).

I have a lot of existing code that would need changing to match that,
and *personally* am not very motivated, since I find 'string' harder to
see than "string" (unless colour coded). On the other hand, following a
consistent set of rules is a good thing. On the other other hand, I am
actually surprised there *is* a policy on this, since Python itself
doesn't care...

Hmm - not sure where I stand on that - obviously I'd prefer not to
change my ways, but also I prefer to code to standards if they exist.

Can you point to where this is documented outwith your text? (fighting
whilst not sure he should!)

The CVS part looks good, and I like the explanation of how to use the
sandbox.

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
Give a pedant an inch and they'll take 25.4mm
(once they've established you're talking a post-1959 inch, of course)
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)

Re: [Docutils-develop] Project Policies

[David G. <go...@us...>]

Tony J Ibbs (Tibs) wrote:
> Looking at Coding Conventions...

Sorry, I didn't mean them to sound so draconian.  I've modified them a
bit and added a preface paragraph:

    These are the conventions I use in my own code.  Contributed code
    will not be refused merely because it does not strictly adhere to
    these conditions; as long as it's internally consistent, clean,
    and correct, it probably will be accepted.  But don't be surprised
    if the "offending" code gets fiddled over time to conform to these
    conventions.

> The "single quote for string literals" is a problem to me
...
> Can you point to where this is documented outwith your text?

It's not.  Purely my preference.  I find it cleaner, and ' doesn't
require shifting.  I was using both for a while, but found it looked
cluttered, so standardized on one.

-- 
David Goodger  <go...@us...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

RE: [Docutils-develop] Project Policies

[Tony J I. (Tibs) <to...@ls...>]

On single quotes for strings...

David Goodger wrote:
> Purely my preference.

s'OK

> I find it cleaner, and ' doesn't require shifting.

Hmm. Since I started touch typing (about eight years into professional
programming - I'm told it looks odd only using the fingers I do to type
with) I'm fairly "blind" to what requires shifting and what doesn't - it
just happens...

Continued usage of C (and latterly Java as well) has constrained me to
use `"` as the string quote character - it's what I'm used to. That's
*not* an argument for me to try and force it onto other people (gods
forbid!), but it's (probably) the selfish reason I don't want to change
old habits in Python (and heck, I've been doing it that way in Python as
well now since 1.0, back when I still occasionally worked on Fortran77
code).

I think it *is* reasonable to ask that people working on an existing
body of code follow the conventions for that code - so if I were to edit
DPS/reST code (using the old term for that part of Docutils) it is
*polite* [1]_ to follow the internal conventions. And for that reason it
*is* worth spelling out the conventions you have used and prefer.

.. [1] Trying to be polite, in a reasonable manner, is
   a Good Thing, I think. (look - I remembered the space
   after the dots!)

> I was using both for a while, but found it looked
> cluttered, so standardized on one.

Interesting. I suspect that the visual impact of two quotes is what I'm
attached to...

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
A single element tuple needs a trailing comma, and an empty tuple needs
brackets to distinguish it from a coffee stain. - Duncan Booth, in his
intro to Python for the ACCU Spring 2002 conference
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)