[Catalog-sig] More documentation for setup meta-data

[Richard Jones]

On Thu, 27 Feb 2003 1:51 pm, Stuart Bishop wrote:
> On Thursday, February 27, 2003, at 12:18  PM, Richard Jones wrote:
> > I'm trying to better document the meta-data for the distutils (and
> > hence
> > PyPI). I've added words to the section in the dev doc about meta-data,
> > and
> > would like some feedback before I post the patch to be applied. Sorry,
> > it's
> > in LaTeX form (until someone writes the ReST->python doc converter ;)
>
> A patch was applied yesterday to dist.tex btw:
> 	https://sourceforge.net/tracker/
> ?func=detail&atid=105470&aid=693474&group_id=5470

Note that python.org has an auto-forwarder set up to make sf references 
easier:

    http://www.python.org/sf/<aid>


> In particular, 'home_page' should be 'url'

Huh. News to me :)


> I think a definition of 'short string' and 'long string' are required:
> 	- Are Unicode strings allowed?
> 	- What formatting is allowed (eg. none whatsoever for short string,
>        and ReST for long string)? I think either ReST or an HTML subset
> 	  is required for the long description. It would suck if long
> description
> 	  ended up in a <pre> section on pypi, although this would be usable if
> 	  lines were shoved through textwrap.wrap()

The current layout of the metadata on the release display page is ... well, 
it's a slightly refined version of a quick hack. It's the result of competing 
interests of getting something out there, and making it look pretty :)

Unicode hadn't occurred to me. Any thoughts? I don't believe sqlite can store 
unicode, but we could probably work around that...

I think that ReST might be an option, but it's going to involve a bit of work 
hooking the parser/formatter into PyPI. Regardless, most long-description 
text will take to being ReST'ed just fine, since they're mostly all just 
paras.


> It would be benefitial to mandate certain trove classifiers, to make
> browsing
> usable on pypi (at the moment, about 75% of projects are implemented in
> no
> language whatsoever!)

+1 (there should be at least one of each top-level group specified)

Note that in my modified documentation, the "platforms", "license" and 
"keywords" distutils meta-data are removed. I suspect that "license" must 
remain (to cope with oddities like the "Don't Bug Me Later License"). I don't 
believe we should promote the other two though. I realise that there will 
probably be disagreements about keywords ;)


> (does this mean the language the docstrings are
> written
>                             in, or programs dealing with language
> processing?)

It's been pointed out (after I went live) that "Native Language" makes more 
sense. It's probably early enough days to make the change now. People who 
have already set up classifiers in their setup files will be annoyed though 
:(


    Richard