59137 - README files are wrong

Status: VERIFIED FIXED

(Documentation Graveyard :: Help Viewer, defect)

Description

[James "Kovu" Russell]

The README file for the Linux versions are wrong, and for Windows they're nearly
useless. I have no idea about Mac.

Linux: There is no "package" directory created. Various other errors abound, as
mentioned in bug 45863.

Windows: far too vague, and I don't recall ever having seen a "MozillaSetup.exe"
file. I can't fix this one until I know what this particular README file is
targeted at. Is this for every version of Mozilla period? If so it should
include instructions for every method possible, including Internet installation,
CD installation, binary installation, and binary installer installation.
Otherwise, there should be different READMEs for all, but I think that would be
a nightmare. I'm attaching a quick fix for the Linux installation. Can we get
this reviewed and into the tree?

Also please comment as to what we should do about the READMEs in the long-term.
One for all versions or separate ones for each? If this issue is not cut and
dried already (i.e. if there's no simple answer), maybe it's best dealt with
first in the n.p.m.doc newsgroup before turning this bug into a SPAM-fest. If
so, please comment to that affect and I'll start a post there.

James Russell

Comment 1

[James "Kovu" Russell]

Attachment: README with working Linux installation instructions

Comment 2

[James "Kovu" Russell]

and Steve, please forgive my grammatical blunders above (affect instead of
effect, etc.), I was in a hurry. :)

James

Comment 3

[James "Kovu" Russell]

cc:'ing Asa, as this is both Mozilla- and Netscape-related.

The following is from the Netscape PR3 docs, which are correct. In fact, the
Netscape docs are far superior to the corresponding Mozilla docs. They describe
the process step-by-step, shortening commands with wildcards, etc. and making
the installation process very quick and easy. The corresponding Mozilla docs are
set up completely different, and are often-times either wrong (Linux) or way too
vague (Windows).

To use the Linux Installer:
Create a directory named N6PR3 (mkdir N6PR3), and change to that directory (cd
N6PR3).
Download the Installer file into N6PR3
(netscape-1686-pc-linux-gnu-installer.tar.gz).
Gunzip the Installer file (gunzip net*.gz).
Tar the Installer file (tar -xvf net*.tar).
The Installer is now located in a subdirectory of N6PR3 named
netscape-installer. Change to that directory (cd netscape-installer).
Run the Installer (./netscape-installer).
Follow the instructions in the Install Wizard for installing the Linux Netscape
6 application. Choose a type of installation (Recommended, Full, or Custom), and
choose a default directory or change to a directory of your choice.

This document is a very good example of one that would be easy to repurpose for
Mozilla, and should be. The current system has Mozilla developers creating
redundant documentation, which is unnecessary when Netscape has fine
documentation that could just be chopped up (I'd do it) a bit, with a search and
replace for Netscape/Mozilla, and so on, and save Mozilla the trouble of
constantly reinventing the wheel.

Is this then a licensing bug? Does Netscape mind if Mozilla.org ravage Netscape
documentation so that Mozilla can have up-to-date docs, especially while their
engineers are too strapped to update it?

Attaching Mozilla original README for comparison with the preceding Netscape
Linux installation text (I fixed the Linux text in the README I attached earlier).

Note that that the page I took the Netscape text from
(http://home.netscape.com/eng/mozilla/ns6/relnotes/pv6-3.html#install) seems to
be missing Windows installation notes.

JR

Comment 4

[James "Kovu" Russell]

Attachment: This is the current README (11/6/00 builds), warts 'n all

Comment 5

[rudman]

James,

Thanks much for your efforts here. I never wrote a read me for mozilla, so I
don't know what it's doing in the build (well, I know now how it got there, but
it shouldn't have gotten there...but that's another story).

I'll create an attachment with the most recent Netscape read me, and you can
base the Mozilla one on that. There's a bunch of info you might need to confirm
for Mozilla, but we can talk later about that...or it may be that we decide that
there really isn't THAT much to change.

As far as distributions: Mozilla can only be downloaded, so the instructions
should stick to that. There should be one read me, for all platforms (with
appropriate info for each), but there seems to be no need for CD installation.
instructions, for instance. The read me should only deal with currently known
details of installation for the most recent build, as downloaded from mozilla.org.

If you want to attach the updated read me, I'll review it and check it in. Sound
OK? Any remaining questions?

Comment 6

[rudman]

Attachment: rtm read me for netscape 6

Comment 7

[James "Kovu" Russell]

Okay, I see what happened now. As noted in bug 45863, aside from errors in the
copy, only the binary instructions were included in the README before for Linux.
Conversely, only the installer instructions are included for Windows and Mac,
ignoring the binary instructions altogether. Worse, the Windows binary
installation doesn't come with a README at all! I'm not sure about the Windows
installer.

I'm attaching a new README, including both binary and installer instructions for
Windows and Linux (both of which I use and could double check) but only the
installer instructions for Mac. I also cannot verify that Mac's instructions are
correct because I'm not on the platform. I have tried to make Mac's instructions
style-wise consistent with Linux and Windows.

see my comments preceded by ### in the file to see things I changed that I
thought were important enough to call out. Note that I don't know Netscape
conventions, I only know IDG Books conventions, so if I've ruined any Netscape
conventions I'm sorry. Let me know and I'll fix it. Granted, these should be
considered Mozilla conventions, but I'd like to keep them close to Netscape
style conventions for the obvious reason that docs will require less porting
this way.

I've also removed CD instructions per Steve's permission, as users of any
Mozilla CDs will presumably have an accompanying readme for the CD specifically.

Steve or Asa: Please verify that the Bugzilla language and licensing language at
the top is okay as added/altered.

Note that with the Linux installation instructions I took the original, modified
it with changes I made to the original attachment to this bug, and then combined
good qualities of the Netscape 6 Release Notes instructions that I quoted
earlier in the bug wiht the Netscape 6 readme that Steve posted. Then I tried to
make the rest of the README consistent with these qualities/styles (for example,
I tried to shorten Linux commands with wildcards when possible as do the
Netscape Release Notes.

I'd like one more edit of this, but right now with all the work/rearranging,
etc. that I've done I can barely look at it without seeing through it. Steve, if
you review it I'll make any changes you need me to make, even just reverting
back to the original styles. It will be good practice so that I good a good
grasp of what Netscape guidelines are and how I broke them (if I did).

JR

Comment 8

[James "Kovu" Russell]

Attachment: Attaching new README with some comments on what I did and why.

Comment 9

[Alex]

RH6.0, 6.1, and 7.0 are listed but not 6.2
runs fine on P2

Comment 10

[Zach Lipton [:zach]]

I'm taking mac here.

Comment 11

[Zach Lipton [:zach]]

Attachment: New README with changes to the mac section. My comments are marked with ### (zach) ...

Comment 12

[James "Kovu" Russell]

Editing submission one last time, w/ Zach's Mac additions. I will attach a final
version for review shortly.

JR

Comment 13

[Alex]

when i said P2 earlier i meant P200 and for Linux I'd recomend saying "RedHat
6.x or 7.x" instaed of listing them all out

Comment 14

[James "Kovu" Russell]

Attachment: Re-edited, revised ReadMe including Zach's Mac comments

Comment 15

[James "Kovu" Russell]

Okay, I've attached my final revision of the new Mozilla ReadMe. This version is
sans comments, if you want to see comments from Zach or myself, they're in our
previous attachments.

Important: I think the Mac instructions are missing steps, but I can't do
anything without owning a Mac myself. Also, there are some very good notes in
the Netscape 6 Release Notes at
http://home.netscape.com/eng/mozilla/ns6/relnotes/pv6-3.html that aren't in
here, and that concerns me because they seem like important notes. I'm not sure
if they're relevant for Mozilla or not, though, so I can't just drop them in.
For example, is QuickTime required for Mozilla as it is for Netscape? I think
these notes should, if they're also true for Mozilla, be dropped in at the
beginning of the Mac installation instructions if they're relevant to both sets
of instructions, or within one of the steps of the two sets of instructions
where they're relevant. (This is how I set up the Windows and Linux
instructions). Here's the text I'm referring to:

You may experience a crash during the first attempt to install Netscape 6.
Subsequent installs will be successful.

QuickTime is required before installing Netscape 6.

If you have previously installed Netscape 6 or mozilla, and experienced an
incomplete, canceled, or crashed install, you must clean out your "Temporary
Items" folder before installing PR3. If you have Mac OS 9.0.4, Mac OS 8.6, or
Mac OS 8.5, rebooting your computer should clean out your "Temporary Items"
folder. If you have Mac OS 9.0, rebooting will not flush out the "Temporary
Items" folder due to an operating system bug. You will need to install PR3 using
the installer available at:
ftp://ftp.netscape.com/pub/netscape6/english/6_PR3/mac/macos8.5/sea/MacNS6FullInstaller.sea.bin

If you have version 5.5 (or earlier) of Suffit Expander may see an error message
stating that the archive is corrupted. You can ignore the message and continue
with the installation. Users that need a newer version of Suffit Expander (in
order to extract the installer) can download it from
http://www.aladdinsys.com/expander/expander_mac_login.html

If you attempt to run Netscape 6 using the Japanese Language Pack, a
non-Japanese version of the Mac OS, and the Japanese Language Kit, all menu bar
items will be incorrectly displayed. To resolve this problem, register Netscape
6 as a ja application using the Language Register.

Steve, would you like to review this now and see what you can do about the Mac
version yourself or should I hunt down Jason Kersey for his promised comments first?

JR

Comment 16

[James "Kovu" Russell]

Oh, also these are still missing a service pack req. for Win NT. Look in the
reqs and you'll see a (SP#?) which can be either filled in or deleted if there
isn't an SP requirement.

Finally, the last list (hooking up the icon in Linux) starts a little funky, I
meant to say "To hook up a Mozilla launcher to the GNOME Panel (along with the
Mozilla icon), follow these steps:"

JR

Comment 17

[Andreas Franke (gone)]

For a list of open installer readme bugs, see
http://bugzilla.mozilla.org/buglist.cgi?bug_id=33182&bug_id=45863&bug_id=58859&bug_id=59137&bug_id=42233

Comment 18

[rudman]

Attachment: Comments on James's read me.

Comment 19

[rudman]

Samir, where is the read me file checked in? Can we hook it up to a button in
Mac and Linux builds?

Copying ssu. Can we hook the read me up to a button as in the commercial Windows
build?

James, the read me on windows is accessible via the button only---it doesn't
exist as a flat file in some post-download directory that a user can access. We
may end up posting the read me at the site, so one can view it pre-download and
pre-install. In any case, take a look at my comments, and you can attach a final
version here once you incorporate any edits.

Comment 20

[James "Kovu" Russell]

Attachment: Finalized Mozilla Read Me, ready for final review and checkin

Comment 21

[James "Kovu" Russell]

Attached finalized Read Me, based on Steve's comments.

Notes: I added back the http:// to all sites on the off chance someone
opens this in a viewer with an automatic links feature that only recognizes
http:// as the beginning of a URL.

Also increased indent/offset of URLs and commands from the left border to two
spaces, just so they'd stand out better visually. Did a final edit, with just
minor tweaks.

JR

Comment 22

[James "Kovu" Russell]

bah, one thing I missed: When I rewrote Step 1 in the last list I broke 62
characters width. Attaching a new final where I fixed this. (arghh, sorry for
the spam and double attachment, I'm a perfectionist when I have the time).

Comment 23

[James "Kovu" Russell]

Attachment: Final Finalized Read Me

Comment 24

[[e-mail] (gone - use [e-mail] instead)]

I want to keep track...

Comment 25

[James "Kovu" Russell]

Having worked on the new Mozilla release notes, I think we should take the
"Uninstalling Mozilla" section from those notes and add them into this Read Me
on its next update.

Comment 26

[James "Kovu" Russell]

Damn, sorry forgot to X-ref the release notes bug: bug 61182 (sorry for the spam
all)

JR

Comment 27

[Samir Gehani]

In response to rudman's 2000-11-21 00:39 comment:

Mac:
====
There is no mozilla readme being packaged with the installer currently.  If a
new readme is to be added please do the following:
1> Check in the new readme file to: mozilla/xpinstall/wizard/mac/macbuild
2> Email [e-mail] so build packaging changes can be made.
3> Email [e-mail] so that config.ini changes can be made.

Linux:
======
The readme is currently picked up from the following location:
mozilla/xpinstall/wizard/unix/src2/README
Replace the contents of this file and it will automatically be packaged with the
installer.

Comment 28

[Zach Lipton [:zach]]

What about windows? Also, we should put the readme up on gila 
(www.mozilla.org) so that it can be read from there. It should be linked 
from several places. Once there is a final version that is checked in with 
the source, we can put this up (we shouldn't make 5,000 changes to this 
on the website after it is already up)

Comment 29

[rudman]

Apologies for letting this languish.

Reassigning to Asa for review and checkin.

Comment 30

[Asa Dotzler [:asa]]

A couple of things have changed.  Release notes now located at
www.mozilla.org/releases/ and the linux zipped builds create a "mozilla"
directory instead og a "package" directory. This change from package to mozilla
makes for a somewhat confusing insruction: 

    To install Mozilla by downloading the tar.gz file:

	1. Create a directory named "mozilla" (mkdir mozilla)
	and change to that directory (cd mozilla).

	2. Click the link to download the non-installer
	mozilla*.tar.gz file into the mozilla directory.

	3. Change to the mozilla directory (cd mozilla) and
	decompress the file with the following command:

	  gunzip -dc moz*.tar.gz	| tar -xvf -
 	
	This creates a "mozilla" directory under your mozilla
	directory. 

	4. Change to the mozilla directory (cd mozilla). 

	5. Run Mozilla with the following run script: 

	  ./mozilla

I'll attach a patch with the changes but we should probably change the name of
the install directory to something other than mozilla to make things a little
less unclear.  Any other thoughts?

Comment 31

[Asa Dotzler [:asa]]

Attachment: asa's updates to fix relnotes page and linux install dir change

Comment 32

[James "Kovu" Russell]

Anyone who was interested in the discussion earlier in this bug regarding a
Mozilla style guide (whether to uppercase "Web" and such), I've started the
official Mozilla.org style bug (unless there's an earlier one I'm missing): Bug
71919

James R.

Comment 33

[Zach Lipton [:zach]]

Kovu--You did miss it. Look at http://www.mozilla.org/README-style.html 
which contains some style gudlines. Somewhere in the mozilla.org 
component there is a bug to do more work on these, including a patch to 
make it less rude. Try doing a url search for that string and see if it pops 
up.

Comment 34

[James "Kovu" Russell]

Thanks, Zach. I'll review that and then post comments to Bug 71919.

James

Comment 35

[André Dahlqvist]

Why haven't the obviously correct changes been checked in ages ago? The Mozilla
installer README is still missing info such as how much disk space is needed,
and that has already been fixed in the patches attached to this bug.

I could do some work on this if I knew the changes had a chance to get checked in.

Comment 36

[Asa Dotzler [:asa]]

Andre, that would be great. I'm not really the fixer of this bug, just the
shephard. If you all can come up with a patch that makes things better I'll try
to find someone to check it in.

Comment 37

[James "Kovu" Russell]

*** Bug 42233 has been marked as a duplicate of this bug. ***

Comment 38

[Brant Gurganus]

The current readme.txt in the 2002123108 includes has some of the mentioned
issues fixed and looks almost identical to Final Finalized Read Me.

Comment 39

[Brant Gurganus]

v