Addendum: I was working on a program where i needed to split a path into dirname, corename, and suffix.
I came to this page and took me a while to understand what split() is about. There are other path related functions splitext(), splitdrive(), basename(), dirname(). User has to scan the whole page and read painfully each one to fully understand how to choose and use them for the task at hand. As i have explained before (see references at bottom), documentation should be organized oriented towards programer's tasks, not alphabetically, compiler view, or computer sciency scheme. On this os.path module, split(), splittext(), dirname(), basename() should all be under one section. This way, their usefulness and each's fitness becomes clearer, and also easier to document as a collective. Other functions that test files or get info about files should be together. Don't be afraid that there are functions that doesn't fit into some “classification”. For exapmle, the walk() and supports_unicode_filenames() can be lumped at the bottom as Other. The need to present materials in some aloof, computer sciency, academic, precision pretensions way is a major usability problem in the Python doc. (the OpenSourcers's need to present materials that way is a backlash of the willful juvenile sloppiness of unix/perl community. However, they being the same crowd without significant critical thinking and writing skills, cannot do better by hiding in formality.) Also, at the top we see: Warning: On Windows, many of these functions do not properly support UNC pathnames. splitunc() and ismount() do handle them correctly. As indicated before, this is a exhibition of tech geeking and jargonizing. If this warning is necessary, place it at the bottom of the page as a footnote. Also, spell out UNC, and provide a link to its proper spec. Tech geekers are very pretentious of tech matters. They are afraid, as if spelling out UNC would make them unprofessional, that their peers would deem them inferior. There are a myriad of techincal standards that any programer could only be familiar with a fraction, confined to his area of expertise. Standards and its acronyms come and go , and each with varying degree of precision, actual revelance, and they are intermingled with de facto “standards” in the commercial world that may not even have official names. The tech geekers are clouded by their narrow knowledge. The purpose of documentation is not some cold academic presentation. Vast majority who came to use os.path wouldn't know what UNC is. Spell things out when in doubt. UNC here, isn't really a significant “standard”. This warning should be left out. ----------- This post is archived at: http://xahlee.org/perl-python/python_doc_os_path_split.html Xah [EMAIL PROTECTED] ∑ http://xahlee.org/ Xah Lee wrote: > Python Doc Problem Example > > Quote from: > http://docs.python.org/lib/module-os.path.html > ---------- > split( path) > Split the pathname path into a pair, (head, tail) where tail is the > last pathname component and head is everything leading up to that. The > tail part will never contain a slash; if path ends in a slash, tail > will be empty. If there is no slash in path, head will be empty. If > path is empty, both head and tail are empty. Trailing slashes are > stripped from head unless it is the root (one or more slashes only). In > nearly all cases, join(head, tail) equals path (the only exception > being when there were multiple slashes separating head from tail). > ---------- > > Can anyone tell me what this verbiage is trying to fucking say? > > what the fuck is with the head and tail thing? > > is the doc writer, trying to write the doc with some austereness, but > is confused about the behavior of split, or confused about expressing > it? Did his pretension fucked him up? > > i was working on a program where i needed to split a path into dirname, > corename, and suffix. But this fucking python doc diverted my work and > wasted my time. It normally isn't a problem to find imperfections in > the world except the fucking OpenSourcers fuck with their fucking > moronicity and moronitude and propagate haughtily their fucking lies > and stupidity. Die. > > Suggested rewrite: > > split(path) > returns a pair (dirname,filename), where dirname is the part of path > up to the last slash, and filename is the rest of the string after the > last slash. > > Exceptional cases are: > • if path is a single slash (or repeated), then path == dirname and > filename is empty. > • If the “last” slash is repeated, they are treated as one single > slash. > > ------------ > Fuck the motherfucking liers of OpenSourcing fuckheads. > (Note: my use of OpenSource here does not include people of GNU > community.) > > For more about Python Doc problems, see > http://xahlee.org/Periodic_dosage_dir/t2/xlali_skami_cukta.html > > Xah > [EMAIL PROTECTED] > ∑ http://xahlee.org/ -- http://mail.python.org/mailman/listinfo/python-list