[SciPy-dev] usage of "scipy", "Scipy", "SciPy"
jh@physics.uc...
jh@physics.uc...
Tue Dec 16 09:53:50 CST 2008
Damian Eads wrote in a thread on scipy-user (ANN: SciKits Portal):
> 2. Replace "Scipy" and "scipy" with "SciPy" when referring to the
> SciPy tool suite. Use "scipy" (all lowercase) in a fixed-width font
> when referring to the Python package name "scipy".
David Cournapeau <david@ar.media.kyoto-u.ac.jp> responded:
> I think it would be nice to have this noted somewhere for everything
> around scipy, actually.
+1, mostly.
I don't think the fixed-width font is crucial; we don't consistently
do this for "numpy" except in actual code examples and I for one find
it jarring to read prose in manuals where you know perfectly well what
is being discussed but fonts are changing all the time as though
you're an idiot and can't remember. I do find it helpful to change
fonts in syntax usages, etc., just not in paragraphs of prose when the
context is clear (e.g., you're just talking about one item). Others
will differ. So, I'd make the suggestion and leave it to the writer
to decide on fonts appropriate to the document.
Also, what about numpy/Numpy/NumPy? See below.
We have a set of doc guidelines. I don't think we (yet) have a set of
style guidelines for web sites, but we should. This could be its
first point.
----------------------------------------------------------------------
Use "SciPy" when referring to the SciPy tool suite. When referring to
the single Python package named "scipy", use "scipy" (all lowercase),
preferably in a fixed-width font when using fonts to distinguish
syntactic elements. At or very near first use, and in titles, etc.,
say "SciPy platform" when referring to the tool suite and "scipy
package" when referring to the package alone, to ensure that readers
not familiar with the distinction are not confused. When
capitalization is required, "scipy" becomes "Scipy" and should be
followed by "package" unless the context is already well established.
Use "NumPy" when referring in general to the syntax, mechanics, and
coding approach of the numpy package and/or the ndarray class, as used
in other packages. When referring to the single Python package named
"numpy", use "numpy" (all lowercase), preferably in a fixed-width font
when using fonts to distinguish syntactic elements. Writers should
clarify the context if there is ambiguity. When capitalization is
required, "numpy" becomes "Numpy".
Examples:
The SciPy platform includes the numpy, scipy, and matplotlib packages.
The SciPy universe is extended by the stand-alone packages called
SciKits, and many other packages distributed separately from the
SciKits.
The fnord package's routines follow NumPy style. They use ndarrays
and many accept "axis=" and other NumPy keywords.
The fnord package is based on numpy. It also uses matplotlib, but it
does not import the scipy package.
(Title) The SciPy Platform User Manual
(Title) The Scipy Package User Manual
Incorrect:
(Title) The SciPy User Manual (requires new reader to know our nuances)
(Title) Implementation of the SciPy "axis=" Keyword (should be NumPy)
In the NumPy package,... (should be numpy)
In numpy/scipy, this IDL expression shortens to... (should be NumPy
for generic expression syntax, SciPy if specific routines outside
of numpy are involved, or numpy or scipy if routines from those
packages are involved)
-----------------------------------------------------------------------
Thoughts? I'm open to calling the syntactic elements "SciPy" rather
than "NumPy", and never allowing "NumPy" or allowing it optionally as
a synonym for "numpy" the package, but I think there is a place for
"NumPy" as described above.
If people like the idea, Stefan, can you put this guideline in our doc
standards and examples? I'll hang it off of Developer_Zone as the
start of our web style guidelines, once it's had some discussion here
(and pending the outcome).
--jh--
More information about the Scipy-dev
mailing list