145965 - Amendment to the Windows installation guide

Status: RESOLVED FIXED

(Bugzilla :: Documentation, defect, P4)

Description

[Jean-Sebastien Guay]

I have written a small guide on Windows installation of version 2.16 rc1, with 
the help of Toms Baugis <[e-mail]>. I believe it would be a 
good addition to the Bugzilla guide, since parts of the Windows installation 
notes in the guide are outdated, imprecise, or not as concise as they could be. 
Also, we have included tips that would be useful to first-time Bugzilla 
installers.

Since the guide focuses on the quirks of installing on Windows, and is so 
specific to version 2.16 rc1, it may also become obsolete very quickly. I will 
try to update it when that happens.

Any comments are welcome.

Comment 1

[Jean-Sebastien Guay]

Attachment: Official version of the guide

The guide in its present form has already gone through a couple versions.

Comment 2

[Jean-Sebastien Guay]

Targeting at 2.16, at the request of Gervase Markham.

Comment 3

[Toms Baugis]

i hope, that the patch will be included in 2.16
if not, then the line
"Apply patch v3 from this Bugzilla bug" must be replace with 
"Apply latest patch from this Bugzilla bug" 
because now bug 124174 has patch V4 (attachment 84192 [details] [diff] [review])

Comment 4

[Toms Baugis]

One question to GERV - what would be the best way to append our guide into
existing, complete guide? I tried to do it with HTML text editor, but the
existing guide is formatted really funny.

Is there any way we can help you or will you solve this by yourself?

Comment 5

[Gervase Markham [:gerv]]

The reason for the ugliness in the HTML is that the original of the guide is in
SGML :-|

What would be really good, though, is if you ran the current page through HTML
Tidy (so you can read the HTML), and then edited that into another HTML page
which represented the true Windows installation instructions, in the style of
the rest of the guide. Then, I could convert that back into SGML.

That would be a massive help.

http://www.bugzilla.org/docs216/html/ is where the current docs are.

Gerv

Comment 6

[Matthew Barnson]

Yes, the Guide is maintained in XML (No longer SGML, Gerv) so HTML simply sucks.

Plain text is actually easiest to import into the Guide.  I'll run what he has
through an HTML stripper and see if I can clean up the Windows install portion
of the Guide.

Comment 7

[Jouni Heikniemi]

I promised to take a look at this pre-2.16. Latter half of next week, probably.

Reassigning to myself at least temporarily, so I won't forget it. :-)

Comment 8

[Gervase Markham [:gerv]]

I've linked to the attachment from the Bugzilla Guide - no-one has both the
expertise and time to rewrite the Win32 docs in time for 2.16. Pushing out to
2.18 for proper integration.

Gerv

Comment 9

[Jean-Sebastien Guay]

If anyone is interested, I will probably be putting up a new version of this 
guide soon, but the current state of the various patches needed for Win32 
install makes it more difficult than it was. I offered my help to test the 
patches for bug 124174 and bug 84876, which are the major ones for e-mail 
support on Windows. Once these two are ironed out, Windows support will just be 
a matter of changing shebang lines and switching "./" for "perl " (more or less)

I will still keep updating my guide since I still feel it's got more to-the-
point instructions for installing Apache, ActiveState Perl and MySQL. So even 
if the many other code changes are no longer needed, it will still have its 
place. Maybe later I can check into making my instructions a "Summary" section 
to the more detailed instructions that are in the guide, so that it will 
integrate together nicely. We'll see.

Comment 10

[Jouni Heikniemi]

Oh drat, so this was mine. I had all forgotten. That's what you get when you've
got too long bug lists in several Bugzillas. Damn. Sorry, everybody.

jean_seb, it's great to have you helping with these. If 124174 and 84876 get
fixed, we really are much closer to a working Win32 Bugzilla. Still, I think
we've got quite a lot to do with edit*.cgi taint issues and checksetup, in
particular (at least if we're aiming for IIS compatibility as well). 


If you've got the energy to refresh guide, that's great. However, I think it's
better to wait until the mail patches have landed, because the windows
installation instructions will be _so_ much easier to write (and to follow, of
course) after the processmail crap can be disposed of. 

I really do not have the time to do anything for this right now (my civil law
exam is too close, not to mention being sorely pressed by serious work :-(), so
if you want the bug, just make a grab. I'll try to help with reviews of those
two mail bugs, that probably consumes less time. I have a good history with
124174 already ;-)

Comment 11

[Jean-Sebastien Guay]

jouni, re: update to the guide :

I agree, I'll wait a bit. That's why I want to help with 124174 and 84876 as 
much as I can. It's just that I get e-mails from people pretty often asking why 
the instructions are not up to date (for instance, I mention in there that you 
should apply 124174 patch v3, when it's at v7 now with a v8 supposed to be out 
this week, hopefully :-). So I thought I'd just post a little message here to 
let people know what's going on.

This bug can sit here for a while, can't it? If so, I'll take it and once stuff 
starts landing (especially on the Mail on Win32 issue) I'll start the updating.

I'm starting to find it pathetic that I know two b.m.o bug numbers by heart :). 
I never thought I'd get involved with an open source project (because of time, 
not will), but I think this is a great project and there's no reason it can't 
work on Win32 as well.

Comment 12

[Jouni Heikniemi]

>This bug can sit here for a while, can't it? If so, I'll take it and once stuff 
>starts landing (especially on the Mail on Win32 issue) I'll start the updating.

Why, it certainly can. It's not Win32-bz had the problem of too many cooks doing
too much work. 

Now that you gave me the chance to eliminate yet another weight of my poor
conscience, I'll give you this one with great pleasure. Good luck with it, and
don't hesitate to ask for comments when you've got a new version :-)

Comment 13

[Jean-Sebastien Guay]

Great job on 191034, Jake! The Win32 instructions are more concise and less 
repetitive.

One thing is missing in the Win32 instructions, but you might have omitted it 
because you foresee 124174 being fixed soon... :-) Please see my changes in the 
patch I will attach to this bug. I think that's the only thing missing. And 
once 124174 lands, that can be removed.

I also think that the warning section at the beginning of the Win32 section 
could be shortened. It really isn't that hard anymore, as the very short Win32-
specific section shows. The Perl and MySQL installation is easy, so is the 
Apache config, and getting all the Perl modules is much easier than it was now 
that ActiveState have updated some of the versions in their library (most 
notably CGI and DBD-mysql). I find the current two paragraphs a bit 
melodramatic, to be honest...

With this change to the Win32 side of things, I think we can close this bug as 
soon as this version of the docs goes online. My guide no longer serves any 
purpose, and I will instead help you guys maintain the Win32 side of the 
official docs instead, to prevent duplication of efforts and make sure everyone 
finds the most recent instructions.

Comment 14

[Jean-Sebastien Guay]

Attachment: Section about BugMail.pm added to installation.xml

By the way, is there a way for me to 'recompile' the docs from the XML files?
I'd like to see the results...

Comment 15

[Jean-Sebastien Guay]

Comment on attachment 84430 [details]
Official version of the guide

As noted above, I believe this is obsolete.

Comment 16

[Jacob Steenhagen]

Comment on attachment 123791 [details] [diff] [review]
Section about BugMail.pm added to installation.xml

If you have a docbook environment set up you can generate the html w/the
|./makedocs.pl| script in the docs/ directory. The difficulty of setting up
docbook varies by where you're trying to set it up. I can't say that I've ever
tried on win32.

Comment 17

[Gervase Markham [:gerv]]

Er... bug 124174 is fixed.

Gerv

Comment 18

[Jacob Steenhagen]

I would guess that Jean meant to say bug 84876.

Comment 19

[Jacob Steenhagen]

Checking in installation.xml;
/cvsroot/mozilla/webtools/bugzilla/docs/xml/installation.xml,v  <-- 
installation.xml
new revision: 1.46; previous revision: 1.45
done

Though I didn't checkin a doc recompile yet.

Comment 20

[Jean-Sebastien Guay]

Yep, I meant 84876, sorry Gerv.

Comment 21

[Jean-Sebastien Guay]

Attachment: <old patch> =~ s/124174/84876/;

As stated above, I said 124174 when I meant 84876...

Comment 22

[Jacob Steenhagen]

Well, I jacked up the checking comment, but I fixed the bug number and also made
it a link.

Comment 23

[Jean-Sebastien Guay]

Ok thanks Jake.