On Aug 20, 2013, at 5:15 AM, "Dr. Trigon" dr.trigon@surfeu.ch wrote:
What about a README file instead of an URL? Was there a final decision made whether to docu things locally in the repo (REDAME, doxygen, ...) vs. online www.mediawiki.org ?
The README file for pywikipedia IS A BLOODY JOKE!!!!
It provides ZERO information.
I've been building code on the net since it was the ARPAnet and the overall structure of pywikipedia simply flies in the face of conventions.
Were it not for the CONTENTS file, anyone downloading the code for the first time would be utterly lost.
The "docs" directory is a similar joke. If the instructions contained within it are so straight forward, why doesn't the "Installation script" do it automatically? ... oh, that's right, there IS NO installation script!!!
I first started trying to use pywikipedia on a private MediaWiki ... where "private" according to your definitions means NOT part of wikipedia.com. I downloaded it from the SVN at the end of June, just before you began converting to GIT.
Being used to things like Perl and MacPorts, getting pywikipedia working has been a painful experience.
I am a retired Unix SysAdmin, however, when I retired in 2003, Python was not yet a widely used language (and git had not yet been invented).
Your installation instructions still do not acknowledge the fact that "generate_family_file.py" is BROKEN.... that you CANNOT have a "user-config.py" file if you want to run it. "... Before you attempt to create one using the instructions below execute python generate_family_file.py. If it succeeds, ..." It CAN NOT succeed if you have followed the instructions up to that point, especially the step immediately before it where you are instructed to build "user-config.py" http://www.mediawiki.org/wiki/Manual:Pywikipediabot/Use_on_third-party_wikis
The page: http://www.mediawiki.org/wiki/Manual:Pywikipediabot/Installation is simply an instruction on using GIT. I've already updated the page: http://www.mediawiki.org/wiki/Manual:Pywikipediabot/Mac to reflect "Mountain Lion," and to reflect this problem with the instructions.
I realize that I'm in a severe minority here, being both a Unix and OSX (i.e. Mac) person in a Windows based world, but I can live with the Windows distortions as I have been doing for the past 30 years. That is one reason why I have not had anything to say perviously... that plus the fact that I just barely have pywikipedia working for the MediaWiki I'm working on -- LOTRO-wiki.com.
But if you are going to package this software to look like a "correct" (i.e. conventional) Internet download, you need to fix things like the README file!
I realize also that from a developers point of view, maintaining a WIKI is a PAIN !!!! it is much easier to stay inside one's text editor (or whatever tool is being used to write and modify the code with) and to update things like the "CONTENTS" and "README" files. But that is a choice you have made... transferring your documentation from "standard" internet style to Wiki style. However, that choice implies much more work is necessary to keep the two in sync.
One last point -- since you have these assorted "configure" scripts which MUST be run before one can begin using the product -- why not have an "install" script, which automatically runs them as needed. ... of course to do that, you will first need to fix "generate_family_file.py".
(I'll update the OSX instructions once I figure out how to use GIT. Fortunately, Apple includes the GIT client as part of OSX. )
T.T.F.N. William H. Magill # iMac11,3 Core i7 [2.93GHz - 8 GB 1067MHz] OS X 10.8.4 # MacBook Pro4.1 Core 2 Duo [2.5GHz - 4GB 667] OS X 10.6.8 # Macmini6,1 Intel Core i5 [2.5 Ghz - 4GB 1600MHz] OS X 10.8.3
magill@icloud.com magill@mac.com whmagill@gmail.com