On Aug 20, 2013, at 5:15 AM, "Dr. Trigon" <dr.trigon(a)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(a)icloud.com
magill(a)mac.com
whmagill(a)gmail.com