[Pythonmac-SIG] Fixing the documentation...

[Ronald Oussoren]

On 20-apr-2006, at 11:50, has wrote:

> Ronald Oussoren wrote:
>
>>>>       2.1 macpath -- MacOS path manipulation functions
>>>
>>> Deprecate. Also note that the 2.4.3 documentation now says "It  
>>> can be used to manipulate old-style Macintosh pathnames on Mac OS  
>>> X (or any other platform)." which is incorrect (it uses POSIX- 
>>> style paths), so delete that sentence.
>>
>> I'm not a native english speaker, but I read this as "you can use  
>> this to manipulate OS9 style paths on any platform".
>
> Note that the above sentence was only added in the 2.4 docs. If you  
> can find a way to make it do HFS paths then let me know, otherwise  
> the sentence needs to be deleted and the module itself should be  
> deprecated (i.e. folk should be using os.path anyway).

It does do HFS paths right now, you can import it using 'import  
macpath'. Any mention of it being os.path on macos should be removed,  
that was true in os9 but not in osx.


>
>
>> As I mentioned in another message this module might be useful to  
>> work with OS9-style paths as used by some Carbon API's.
>>>
>>>>       2.4 MacOS -- Access to Mac OS interpreter features
>>>
>>> Get/SetCreatorAndType should really be fixed or deprecated as  
>>> they don't appear to work for bundle-based files.
>>
>> They should be fixed. Why does everyone want to remove what they  
>> don't quite understand?
>
> Fix or deprecate; doesn't bother me which as long as it's done.
>
> Bear in mind, however, that file typing has gotten a lot more  
> complicated since OS 9 days, so this API has been grossly  
> inadequate for the job for a long time now. Deprecating it would  
> just be an honest admission of that fact; heck, might even  
> encourage folks to come up with a modern replacement.
>
> And deprecation doesn't stop anyone using it in the meantime, of  
> course, but considering it's been in this state for the last five  
> years I doubt many are. :)

Could you please file a bug at SF about this, I'll surely forget to  
fix it if you don't.
>
>
>>>>       4.2 Carbon.AH -- Apple Help
>>>
>>> Do nothing.
>>
>> Documentation would be nice :-)
>
> Yeah, but let's finish cleaning up the existing material first,  
> since that can be done in time for 2.5's release. If we wait for  
> comprehensive new documentation to be completed first then  
> nothing'll get done for 2.5 and we'll be back having this same  
> discussion come 2.6. ;)

I want any documentation that I can, there's no need to write up  
comprehensive documention. If you (or anyone else for that matter)  
has knowledge about some part of the mac specific libaries and wishes  
to contribute documentation that would be greatly appreciated.

>
>
>>>>       4.10 Carbon.Evt -- Event Manager
>>>
>>> Deprecate, or at least add note to use modern alternative.  
>>> Superceded by CarbonEvt.
>>
>> Don't deprecate but not that you should CarbonEvt and that Apple  
>> has deprecated the Event Manager API.
>
> If Apple have deprecated the original Carbon API then I think it  
> makes very good sense to deprecate the Python wrapper for that API  
> as well. That way, no surprises if/when Apple decide to break it/ 
> drop it. We're just following their lead.
>
> The only exception might be where we don't have a wrapper for the  
> new API that supercedes it, in which case we should leave it  
> undeprecated but add a warning note. In the case of Carbon.Evt, we  
> have Carbon.CarbonEvt, so I don't think deprecation is too strong a  
> statement to make. It says nothing about if/when a module will be  
> removed (if ever); only that sensible folks should avoid its use in  
> any future projects, and may want (or need) to update any existing  
> dependent code at some point.

Yeah, you're right.

Ronald