Re: Octave coding standards

[Jordi Gutiérrez Hermoso]

On 5 November 2010 17:40, Rik <address@hidden> wrote:

> 6) According to the documentation guidelines, the first paragraph is
> written in the active voice, present tense.  Later paragraphs usually sound
> better in the passive voice.  What this means is that the first sentence
> "Generates orbit of a ..." becomes "Generate orbit of a ...".  I know the
> difference is only a single 's', but it makes a large difference to native
> English speakers.

It doesn't make much of a difference to me. I also don't get why you
call that active and passive voice. I thought perhaps I'd find a clue
in Wikipedia, but I don't:

     
http://en.wikipedia.org/wiki/English_passive_voice#Misapplication_of_the_term

Thing is that in the first instance, with the s, it's simply a
slightly more idiomatic form where the subject is implied. This is
normally a fragment in formal English, because the subject isn't
explicitly mentioned, but it's very common to drop the subject in
constructions such as this one. Without the s, it sounds like
imperative to me, as if you were ordering someone (Octave, I guess) to
do what the function does. It doesn't seem like passive and active to
me, and it doesn't make a huge difference to me.

But whatever, it's not as if there weren't plenty of other reasons to
rebuild most of the Octave source tree on regular occasion even when
you're not changing a single character in docstrings. ;-)

- Jordi G. H.