72037 - README files need updating / os localizing

Status: VERIFIED DUPLICATE of bug 59885

(Documentation Graveyard :: Help Viewer, defect)

Description

[James "Kovu" Russell]

Linux comes with a ReadMe file, Win32 does not. Can we get the new Read Me
bundled with Windows? (I have no idea whether Mac comes with a ReadMe file...
anyone?)

James

Comment 1

[James Cox]

accepting QA for mozilla developer docs.

some of these bugs have been around for a _long_ time. Reporters, would you
please review the bugs, see if the issues have been resolved, and close bugs
appropriately.

I will do a full review of all bugs not touched in one week (8th April). 

Thanks.

</spam>

Comment 2

[Curt Patrick (gone)]

A placeholder README.txt is check in right under the mozilla directory.

Comment 3

[James "Kovu" Russell]

The placeholder is absolutely useless as a README. Leaving as New.

Comment 4

[Curt Patrick (gone)]

Which is why it was refered to as "a placeholder".  My point is that that is
where the real readme needs to be put if you want the installer to pick it up.

Comment 5

[James "Kovu" Russell]

I figured that much out. I don't understand why it, and not the actual ReadMe,
is there. I personally rewrote that ReadMe and it's good for Windows, Linux, and
Mac, so why it's taken over a year to get just a placeholder there is why I'm
confused.

Comment 6

[Curt Patrick (gone)]

When I was reworking the installer I was not able to find a readme for Windows
which is why I dropped this placeholder in.  Where does the linux readme live? 
Is that what we should be using?

Comment 7

[James "Kovu" Russell]

We made a one-size-fits-all README for the three major platforms. See the last
attachment to Bug 59137 for the latest version.

James

Comment 8

[Daniel Veditz [:dveditz]]

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

Comment 9

[Curt Patrick (gone)]

Okay, I'll check in that readme from 59137 so that it gets into the windows
install.  For the record, I found a readme under
mozilla/xpinstall/wizard/unix/src2 that looks like it might the one for unix,
but it isn't identical to this one.  If we have a one-size-fits-all readme for
all platforms we should open another bug to set up our builds such that we only
have to check it in one place and avoid double (triple) maintenance prospects.

Comment 10

[Curt Patrick (gone)]

reassigning to myself

Comment 11

[Curt Patrick (gone)]

Attachment: Real readme.

need an r= and an sr= on this

Comment 12

[James Cox]

Comment on attachment 77547 [details] [diff] [review]
Real readme.

some comments:

> files mentioned in the instructions in this file at the
> Mozilla.org FTP site at

should be :

> files mentioned in the instructions in this file from the
> Mozilla.org FTP site at

--------

you don't state where to get proper releases (a'la 0.9.9 , 1.0 , etc)

and about here:

>     To install Mozilla by downloading the Mozilla installer,
>     follow these steps:
> 	
> 	1. Click the the mozilla-win32-installer.exe link to
> 	download the file to your machine.

it isn't clear as to what link you are downloading

and here:

> 
> 	1. Click the mozilla-win32-talkback.zip link or the
> 	mozilla-win32.zip link to download the .zip file to
> 	your machine.

perhaps, btw, it's worth making mention of the differences between talkback
enabled builds and not?

again, with the mac/linux links.

> 
>     To install Mozilla by downloading the .zip file and
>     installing manually, follow these steps:
> 
> 	1. Click the mozilla-mac-*.sea.bin link to download
> 	the Mozilla binary to your machine. By default, the
> 	download file is downloaded to your desktop
> 	compressed in .sit.bin format.

copy and paste error? :)

not sure what you're doing here:

> 	  gunzip -dc moz*.tar.gz	| tar -xvf -

but isn't tar zxvf <file> better?

sorry for the nits, but it's important to get this right.

good work, though :)

James

Comment 13

[James Cox]

for some reason i can't give review/needs work or anything on the patch, so i'll
say it here..

it has r=imajes but with the caveats of the work already mentioned. :)

Comment 14

[Daniel Veditz [:dveditz]]

Comment on attachment 77547 [details] [diff] [review]
Real readme.

Last updated 11.21.00 ?

Still, better than what we've got. sr=dveditz (can someone else check the box
for me? Can't see it using today's build).

Comment 15

[James "Kovu" Russell]

Okay, try this revision on for size. It addresses the concerns listed above. I
also tweaked here and there. Attaching.

Comment 16

[James "Kovu" Russell]

Attachment: Readme revision

Updated Read Me

Comment 17

[James "Kovu" Russell]

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

Comment 18

[Tuukka Tolvanen (sp3000)]

Attachment: diff of attachment 77599

Comment 19

[James Cox]

yes, i'm pretty happy with this.

can you add somewhere a few lines or two about where to get versions from? 

so the "link where you downloaded it from" means something .:)

thanks.

Comment 20

[James Cox]

Comment on attachment 77602 [details] [diff] [review]
diff of attachment 77599 [details]

a few notes on this patch:

+
+	To view and use the new streamlined "Modern" theme,
+	your display monitor should be set to display
+	thousands of colors. For users who cannot set their
+	displays to use more than 256 colors, Mozilla.org
+	recommends using the "Classic" theme for Mozilla.
+
+	To select the Classic theme after you have installed 
+	Mozilla, from the navigator browser, open the View
+	menu, and then open then open the Apply Theme submenu
+	and choose Classic.

classic gets switched on by default.. lets flip this around.

+Note: For Windows NT/2000 systems, you must have Administrator
+privileges to install Mozilla. If you see an "Error 5" message
+during installation, log on with Administrator privileges and
+try installing again.

use the "run as" thing, where you can run an installation as an administrator,
without having to log off.

thanks,

james

Comment 21

[James "Kovu" Russell]

Okay, did another revision to address James' concerns above. This time I moved
info on downloading Mozilla to a central "Getting Mozilla" section. I also made
a few formatting tweaks to make it look more professional.

Comment 22

[James "Kovu" Russell]

Attachment: latest readme revision

Comment 23

[Curt Patrick (gone)]

I presume that we want this updated readme to get checked in for linux also? 
I'll check in for both win and linux when I get a=.

Comment 24

[James "Kovu" Russell]

Yeah, Curt, please check in for Linux, too. Can you check it in for Mac as well?

Comment 25

[James Cox]

there is still a reference to :

  gunzip -dc moz*.tar.gz	| tar -xvf -

if we could update that, I would think it is good to go.

curt, have you emailed drivers for this ?

Comment 26

[James "Kovu" Russell]

Attachment: New Readme revision

Fixed the tar command I had missed.

Comment 27

[Asa Dotzler [:asa]]

Comment on attachment 77702 [details]
New Readme revision

a=asa (on behalf of drivers) for checkin to the 1.0 trunk

Comment 28

[Curt Patrick (gone)]

Checked into mozilla\README.txt for windows.
Checked into mozilla/xpinstall/wizard/unix/src2/README for linux

Still figure out what the story is for Mac.  JJ, do you if Mac installs a readme
for mozilla and, if so, where it is checked in?

Comment 29

[Peter Henderson]

It's minor, but

> 3. Extract the .zip file to a directory such as
> C:/Program Files/ Mozilla.

should be

> 3. Extract the .zip file to a directory such as
> C:\Program Files\Mozilla.

or even C:\Program Files\mozilla.org\Mozilla to be consistent with the
installer. Also, Windows XP should be in the list (aren't Windows versions
annoying?! 95/98/Me/NT/2000/XP)

Comment 30

[James "Kovu" Russell]

Attachment: Latest revision

This revision addresses Peter's comments above (good catches!).

Comment 31

[James Cox]

yes, very good catches, I'm ashamed I missed them.

anyhow,

	-Windows 9x/ME, or Windows NT 4/2000/XP

should be

	-Windows 9x/ME/XP, or Windows NT 4/2000

nitpick, but the product family is arranged that way, as XP is an upgrade to Me.

Comment 32

[James Cox]

r=imajes (again) with those updates.

Comment 33

[James "Kovu" Russell]

Well, XP is based on NT, and XP Pro is an upgrade to Windows 2000. XP Home is
the upgrade to ME. Is this really necessary to change? If so, I will, but I've
always classed XP alongside NT because "It's an NT after all..."

Comment 34

[James Cox]

I'm easy, XP fits into both. 

also,

<jesup> imajes: Go ahead, a=[e-mail].  This is the equivalent of a
bustage checkin for a typo.

Comment 35

[Peter Henderson]

Oops, one more:
Under the heading "Windows Installation Instructions" it should say

Note: For Windows NT/2000/XP systems

instead of

Note: For Windows NT/2000 systems

since both XPs (Home and Pro) are based on the NT/2000 kernel (with the notion
of administrator privileges, etc), even if Home is marketed and positioned as an
upgrade to Me.

I feel like I'm being extremely picky, but it's Windows Me not ME, according to
my System control panel. Also, my recent nightly builds have been closer to 20
MB than 26 MB, and the ZIP file has been about 10MB, so I'd suggest saying the
system requirements are either 20MB after install, or about 30MB during
install/unzipping. Or whatever...either way this README is so much better than a
placeholder!

Yet another nitpick (I think this is the last one...):
At the top, under "Getting Mozilla":

"You can download nightly builds of Mozilla from the Mozilla.org FTP site at
ftp://ftp.mozilla.org/pub/mozilla/nightly/  For the very latest builds, see the
/latest directory at this site."

Doesn't that imply ftp://ftp.mozilla.org/latest (because of the leading slash)?

I hope these aren't too picky. Again, thanks for getting this Readme in!

Comment 36

[James "Kovu" Russell]

Attachment: YARR (yet another readme revision)

Argh, Peter, you should be a technical editor for computer books (let me know,
I can probably hook you up :)). Fixed again.

Comment 37

[James "Kovu" Russell]

From imajes in IRC:

<imajes> kovu: r=[e-mail]

I think he's getting tired of visiting this bug today. ;)

Comment 38

[James "Kovu" Russell]

Attachment: and another...

argh, changed Windows ME to Windows Me

Comment 39

[James "Kovu" Russell]

Around and around and around we go...

From James Cox in IRC, again, post "ME/Me" change

<imajes> kovu: cool, r=imajes , again

Comment 40

[Peter Henderson]

As long as it hadn't been checked in, I figured I was good. :o)
Sorry for all the nits, but hey, it's Mozilla 1.0 we're talking about. :o)
Thanks for going through all the changes and r= and everything. Finally looks
good^H^H^H^Hdone (and I doubt anyone will ever notice the tabs on blank lines ;o)).

Comment 41

[Curt Patrick (gone)]

Under the assumption that the sr= and a= continues to apply for updates to the
readme, I just checked in the latest update updated readme to windows and linux
again.

Comment 42

[Simon Fraser [no longer active]]

The readme needs to include Mac OS X info. I also think that readme files should
be platform specific. Why should someone who downloaded a build for Windows care
about Linux or Mac info, and have to wade through stuff for other platforms in
the Readme?

Comment 43

[timeless]

this readme is really inappropriate for an installer package. Installation 
instructions are more than 50% of that document, and if your target audience is 
using the installer, then you're only giving them the file *after* they've 
followed those directions.  Similarly, system requirements are useless as 
something that you'd get after running the installation, because ideally you 
only download something if you think it'll work, and if it won't work, the 
installer has already told you and pretty much refused to run.

Comment 44

[James "Kovu" Russell]

It's come to my attention that Mac doesn't in fact come with a README.

Comment 45

[timeless]

here is the url for nai (mcafee)'s virex datfiles update for mac readme:
http://download.nai.com/products/datfiles/mac/virex/ReadMe.txt

Note that the readme is titled
Release Notes for the Virex Virus Update for April 1, 2002

And it includes:
WHAT'S IN THIS FILE?

- What Is a Virus Update File?
- New Features
- Documentation
- New Features
- Installation
- Additional Information
- New Viruses Detected and Removed
- Understanding Virus Names
- Contacting Network Associates
- Copyright and Trademark Attributions

Obviously the last 7 and 8 are specific to Virex (and would have to be 
replaced for mozilla). 9 can be replaced with something about support 
(contact some other vendor, or read our newsgroups). and 10 can be replaced 
with something about how Mozilla was developed.  1 could be replaced with What is Mozilla (if anyone could answer that).

This is Quake III Arena (1.25)'s readme:
http://www.quake3arena.com/news/readme125.html

notice that it's an html file. Their target audience is Windows, however 
MacOS users are acustomed to readmes not being plaintext, so I think we 
should seriously consider using a file format other than text/plain. -- After 
all, our product is a ... web browser.

smfr's right, readmes should be os specific.

Comment 46

[James "Kovu" Russell]

Timeless, what's to prevent this README from coming up before install in the
installation? Admittedly, it can't be too hard to cut this into three README
files, one for each platform. 

The one-size-fits-all README may be no more than a quickfix for now, but as
noted in bug 135351, right when we're pushing to get Mozilla 1.0 RC1 out there
is not the time to goof around with the build system. 

As noted by dveditz in Comment #14, it's better than what we've got, which until
quite recently was absolutely nothing on both Windows and Mac, and downright
wrong for Linux. Timeless, I agree that this is not the best way to do this, but
we can file a "This README system sucks bug" for 2.0, no?

Can we get this checked into Mac? A good place would be the README folder under
/mozilla. Mac could be the first build to point to it there, and Windows and
Linux could both point there later.

As for Mac OS X instructions, yes, this README needs them. It also needs someone
to write them, because I don't have a Mac, nor do I have access to one at this
time. Anyone on Mac OS X or with access who wants to add those instructions
could  maybe file a bug on this README with a patch?

Anyhow, this bug is about Windows not having a README, and so as soon as I
verify that Windows does, in fact, come with a README then I will close this bug.

James

Comment 47

[James "Kovu" Russell]

Marking this bug FIXED, since Windows now comes with a README.

Comment 48

[James Cox]

Given that there are already interested people cc'ed, plus this discussion is
already going towards a more centralised approach, I'm going to reopen this so
we can use it to get the next generation of README in for RC1, if possible.

As dveditz said, we now have some files which are a bit more than placeholders.
now we can work on getting them more complete.

sfraser, timeless: 

would you guys be opposed to an about:readme style url? we can then make it
text/html , (depending on how the about: system works, we could also put it on
www.mozilla.org, so we can always update it) , and then put a link in the help
menu. mpt: would a readme link in the help menu be inappropriate? 

as for contents of such a readme, we should focus on post-install stuff, (as
timeless said),

so: (in no particular order) 

 - getting support
 - what is mozilla 
 - getting involved
 - documentation (where to find it, etc)
 - something about skins? - xulplanet.com ?
 - features

also see comment #45 for more.

Comment 49

[Christian :Biesinger (don't email me, ping me on IRC)]

>(depending on how the about: system works, we could also put it on
>www.mozilla.org, so we can always update it)

Easily possible. You can either create an about: url whose content is generated
by C++ code, or you can make that URL be a redirector to another resource: or
chrome: or whatever URL.

Comment 50

[James Cox]

Attachment: enables about:readme

Comment 51

[James Cox]

curt, do you mind if i accept this bug?

Comment 52

[Matthew T (active 1999-2002)]

It's probably most helpful to answer these questions in reverse order ...

> so: (in no particular order)

Every one of those things listed would make more sense, and be easier to read, 
in the online help than in the readme. The readme should only contain 
information for situations where the help browser is not available: installing 
Mozilla, and troubleshooting when either Mozilla or the installer won't run.

In a readme you get points for how short it is, not for how long it is.

> mpt: would a readme link in the help menu be inappropriate?

Completely. Help navigation belongs in the help browser, not the Help menu.

> would you guys be opposed to an about:readme style url?

Yes. There would be very little point in it, because the only time you would be 
able to see it would be when you didn't need it.

> depending on how the about: system works, we could also put it on
> www.mozilla.org, so we can always update it

Please do NOT do that. It is a grievous bug with <about:credits> that in ten 
years, if Mozilla development is at <http://mozilla.sourceforge.net/> and the 
mozilla.org domain has been snatched by a porn site (hypothetical, obviously, 
but entirely possible), someone looking back at Mozilla 1.0 will have no record 
of the people who contributed to it, because the `contributors' link in the 
About page is a 404 (or worse). That bug should NOT be repeated anywhere else.

Comment 53

[James Cox]

Ok, 

after discussion with mpt and timeless, I would like to propose the following:

a: we create README files for each different OS, specifically for PRE INSTALL info.
This is especially relevant to *nix style systems, win32 only with zip files,
and i am not sure about macs. This should contain how to install, requirements, etc.

b: we maintain an OS independent post install general readme. ie: how to get
more help, usefull links, how to contribute, how to report bugs, etc. This could
be the first url on launch, ie, incorporating www.mozilla.org/start (but keeping
that as the default url). I don't know what [e-mail] will think of
that, however.

I agree with mpt's comments about not having it on the site (btw mpt, the Help >
Releases link also goes to www.m...) so a chrome:// page would workforme.

I generally disagree that we should depreciate README's, users have come to
expect them to be available, so much so that i know a number of people who
religiously find the readme file first. we would look stupid if we didn't have one.

As far as user discovery of an about:readme - I would still like it to be
available somewhere -- even if only a link in the start menu folder? [many other
products include documentation links this way].

Comment 54

[Curt Patrick (gone)]

Somewhat randomly reassigning this since it has moved out of the installer realm.

Comment 55

[rudman]

Reassigning to James Cox.

The read me should definitely include pre-install info. That's why it was
created in text in the first place---so it could be read prior to the browser
coming up.

Platform-specific read me's are fine, but I don't see any evidence that they're
essential. In fact, having one read me with clearly marked info for the
different platforms is a reminder that Mozilla is indeed cross-platform.
Similarly, we don't have platform-specific help per se---but when there are
platform differences, they're indicated in the help itself (the same html files
are used across all platforms, with a note here and there about platform
idiosyncrasies). There is no reported impact to usability with only one read me
for all platforms.

Comment 56

[Matthias Versen [:Matti]]

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

Comment 57

[James "Kovu" Russell]

I don't think each platform needs its own README, and that being the case I'd
just rather not haggle with that. In any case, having platform-specific READMEs
with an additional general OS-independent README would involve having not one
but two README files for each platform, which doesn't make sense at all.

If someone wants to break this README into various and sundry different READMEs,
and then maintain those themselves, cool. I personally would be happy with a
single README and a single Release Notes that includes all three major
platforms, as we have now.

By the way, in my view post-install README files are the same thing as Release
Notes and as such are not README files (which are IMHO by definition text-only). 

If no one has any further specific issues with the content of this particular
README (i.e., anything they think should be cut or added - besides Mac OS X
stuff, which I can't do), I personally will be happy with the status quo:
Windows and Linux at least now come with decent README files.

Comment 58

[James "Kovu" Russell]

Attachment: reformatted "final" 1.0 readme

The bug that this bug depends on (Bug 136258) has been fixed. I reformatted the
readme file so that it was narrower, so that it can now fit in the installer
window. Can we get this checked in to at least Windows and Linux?

Comment 59

[timeless]

afaik there is mozilla.org and Mozilla, no Mozilla.org

Comment 60

[James "Kovu" Russell]

Attachment: final final (?) Mozilla 1.0 readme

Oops, I Did It Again... Changed "Mozilla.org" to "mozilla.org". Good catch,
Timeless. :)

Comment 61

[James "Kovu" Russell]

Attachment: newest readme rev

Argh. I changed "Milestone" to "milestone", sorry for the spam all.

Comment 62

[Peter Henderson]

I apologize in advance for the length of this comment...but I have to say it
because I *sentimental sniff* want Mozilla 1.0 to be perfect. :o)

(1)
> You can download nightly builds of Mozilla from the
> mozilla.org FTP site at
>
>   ftp://ftp.mozilla.org/pub/mozilla/nightly/
 --------------------------------------------^
> For the very latest builds, see
>
>   ftp://ftp.mozilla.org/pub/mozilla/nightly/latest
 ---------------------------------------------------^


(2)
> To select the Modern theme after you have
> installed Mozilla from the Navigator browser,
> open the View menu, open the Apply Theme submenu,
> and then choose Modern.

Sounds sort of like you have to install Mozilla from Navigator. Maybe something
like, "To select the Modern theme after you have installed Mozilla, open the
View menu in the Navigator browser, open the Apply Theme submenu, and then
choose Modern. You will see the Modern theme the next time you start Mozilla."


(3)
> -Red Hat Linux 6.x or 7 with X11 R6
 ------------------------^ how about 7.x?


(4)
> *Windows
>         -Intel Pentium-class 233 MHz (or faster) processor
...
> *Linux
>         -Intel Pentium 233 MHz (or faster) processor

Linux needs a Pentium, but Windows needs Pentium-class?


(5)
> Windows Installation Instructions
> ---------------------------------
...
>     To install Mozilla by downloading the Mozilla
>     installer, follow these steps:

> Mac OS Installation Instructions
> --------------------------------
...
>     To install Mozilla by downloading the Mozilla
>     installer (recommended), follow these steps:

Isn't the installer recommended for Windows also?


(6)
> Note: This step assumes you already have a
> recent version of WinZip installed, and that
> you know how to use it. If not, you can get
> information about WinZip at www.winzip.com.

> Expander ships with all new
> Macs and comes with the default system install

All new versions of Windows (I believe) come with some type of Zip capability.
Also, maybe say "a recent version of WinZip or a similar {Zip|.zip} program"?


(7)
> To install Mozilla by downloading the .bin file
> and installing manually, follow these steps:
>
>        1. Click the mozilla-mac-*.sea.bin link on
 ---------------------------------------^
>        the site you're downloading Mozilla from to
>        download the Mozilla binary.
>
>        A mozilla-mac-*.sea.sit.bin icon appears on
 ----------------------------^^^
>        your Mac's desktop.

The last release that had a .sea.bin binary (AFAICT) was 0.9.5. Nightlies now
only have an installer (again, unless I'm missing something). Nightlies seem to
have MacMozillaFullInstall.sea.bin and MacMozillaInstaller.sea.bin. 0.9.9 had
mozilla-mac-099-full-instal.bin. Mac OS X also has a .smi.bin binary.
Since releases and nightlies seem to vary, we should make sure we refer to the
filenames the RC1 binaries will be saved under. No use telling the nightly
filename in an RC1 release README, if the filenames will continue to be different.


(8)
>    To install Mozilla by downloading the Mozilla
>    installer, follow these steps:
...
>    To install Mozilla from the tar.gz file:
 -------------------------------^ (.zip .bin tar.gz)

I suppose Linux users know what their own needs enough, so they don't need to
have the installer/.tar.gz/RPM recommended? The option besides the installer is
the tar.gz file. But the installer is a .tar.gz file too. And shouldn't there be
a period before tar? Also, since Red Hat Linux is listed under the system
requirements, shouldn't there be installation instructions for the RPM? Yes, I
know it's quite simple, but isn't downloading mozilla-win32-installer.exe and
double-clicking on it obvious enough too?


(9)
> 2. Right-click the icon for Mozilla on the
> Panel and enter the following command:
>
>   directory_name./mozilla
 -----------------^
> where directory_name is the name of the
> directory you downloaded mozilla to.

Downloaded Mozilla to, or installed Mozilla to?


(10)
>   directory_name/icons/mozicon50.xpm
 ------------^
> where directory name is the directory
 ----------------^ (should be "_" not " ")
> where you installed Mozilla.

See #9. I think this is correct (where you installed Mozilla) rather than #9's
where you downloaded Mozilla.


Sorry for the long comment. I hope it helps. One more thing:

http://tuxedo.org/jargon/html/entry/README-file.html
Hacker's-eye introduction traditionally included in the top-level directory of a
Unix source distribution, containing a pointer to more detailed documentation,
credits, miscellaneous revision history, notes, etc. (The file may be named
README, or READ.ME, or rarely ReadMe or readme.txt or some other variant.) In
the Mac and PC worlds, software is not usually distributed in source form, and
the README is more likely to contain user-oriented material like last-minute
documentation changes, error workarounds, and restrictions.

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwue/html/ch01f.asp
> Checklist for a Good Interface
>   3. Users do not have to read a Readme file before using your application. 
(If you read the page, you'll notice that very few Microsoft programs follow
their own checklist, but that is beside the point...I consider something like
this to be approximately equivalent to the various published Human Interface
Guidelines.)

Included with Windows Me is a Readme.htm file, which has frames, one of which
frames says, "Readme files contain late-breaking information that's not included
in printed documentation or online Help. This topic describes and displays the
major Readme files included with Microsoft® Windows® Millennium Edition."
Microsoft tends to include multiple Readmes on various topics (pcmcia.txt,
drivers.txt, network.txt, printers.txt, etc), and this is the first time I've
seen one not in plain text format. I'm sure this is one "innovation" we don't
want to follow (unless we want to build Gecko into the installer), but what I'm
getting at is the part "Readme files contain late-breaking information that's
not included in printed documentation or online Help" as opposed to the
Unix/Linux tendency to include an package overview and directions to compile.
Microsoft seems to want to provide a lot of information, but make it unnecessary
to read (even though the file is called README!).

I don't want to make this any longer, but one last comment is that (to respond
to the comment that a README is only available after installation and thus
should not contain download/install instructions [which, btw, I always find
weird, since if I'm reading it I obviously know how to download and install it])
Internet Explorer's README also includes system requiremetns and installation
instructions, even though it comes PREINSTALLED. I'm basically trying to
describe not what is good practice, but what is the "accepted" practice for
READMEs on Windows platforms. Every Windows program handles READMEs differently,
depending on the author's preferences, but I would consider these two Microsoft
examples to be pretty common models. I can't check on "standard practice" on
Macintosh, but I'm sure someone else can.

There...I think I'm done. Treat all this as being my comments before r=p4peter,
if I were privileged enough to be able to give an r=.

Comment 63

[James "Kovu" Russell]

Attachment: README rev 12

Fixed all of Peter's comments (I think) except for his #7, which I can't do
until I know what, in fact, the Mac RC1 files will be called. I thought about
just saying "the mozilla*.bin file", but that seems a bit cheap.

Comment 64

[James "Kovu" Russell]

Seems no Win32 builds, RC1 or trunk, come with a README at all now, not even a
placeholder. What gives?

Comment 65

[James "Kovu" Russell]

Forgive me, RC1 DOES come with a README, but it's the wrong one. Can we get rev
12 (the latest) in RC2?

Also, should /latest builds come with the README? Currently, they don't.

Comment 66

[Peter Henderson]

1.
mozilla-mac-10rc1-full-ins.bin
mozilla-mac-10rc1-stub-ins.bin
mozilla-macosX-1.0rc1.smi.bin

...too bad we didn't know that _before_ the builds were uploaded. Maybe the same
names s/rc1/rc2/ will be used for RC2.


2.
On Linux, is /user/local/mozilla/./mozilla the same as /user/local/mozilla/mozilla?


3.
http://www.mozilla.org/releases should be http://www.mozilla.org/releases/
because releases is a folder (one fewer redirect for the server). Same for
http://bugzilla.mozilla.org.


4.
www.aladdinsys.com/expander/expander_mac_login.html redirects me to
http://www.stuffit.com/expander/macindex.html.


5.
> To install Mozilla by downloading the Mozilla
> RPM files for Red Hat Linux (and other versions
          ^
> of Linux that support RPM, such as Mandrake),
> follow these steps:
>
>    1. Click the the mozilla*.rpm link on the site
                                       ^
>    you're downloading Mozilla from to download
>    the RPM file to your machine.
                 ^
>
>    2. Navigate to where you downloaded the file
                                                 ^ 
>    and double-click the RPM program icon on
                                          ^
>    your machine to begin the Setup program.
>    Or, from the command line, use the rpm
>    command (see the rpm man page for more info
>    on the rpm command).

There are multiple RPM files, so there sould be multiple links to click. Maybe
it should also say which RPM to click on. Does installing the first RPM (i.e.
the one without another component in the name) automatically install the others,
or run a setup program that does so, or will each RPM need to be installed
individually? (I've never used an RPM install in Linux.)


6.
Why do we say how to add a GNOME panel icon, but not a Start Menu icon, or Dock
icon (is that the rignt name?)?


7.
Also, why are there LEGAL, LICENSE, and README.txt?

Comment 67

[James "Kovu" Russell]

Attachment: tweaked Mac

I can't currently answer the Linux questions, due to not having it installed,
but I will get Linux on here real soon. Attaching rev 14 of the README. If you
missed rev 13, well so did I, I suppose I'm a bit of a superstitous fellow. It
has slightly modified Mac instructions.

Comment 68

[James "Kovu" Russell]

Attachment: tweaked Mac again

Shortened Mac version. Longer comment to follow. I want to get this in ASAP.

Comment 69

[James "Kovu" Russell]

1. fixed
2-5 willfix
6. Because the Start Menu icons and Dock icons pretty much add themselves. On
Gnome it's like pulling teeth.
7. License is monstrous and would:

Combining the License, etc. with the README would 

A) Make the README itself massive, because the MPL is huge
B) Lessen the visibility of the License itself
C) Make the License, etc. less easy to update
D) Make the README less easy to update

Still, there can be a good argument for having one single text file instead of
multiple ones. However, mucking with the build files would nnecessarily
complicate 1.0; any effort to combine these should probably be post-1.0.

Comment 70

[Henrik Gemal]

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

Comment 71

[timeless]

it doesn't make any sense but could you make it clear that Macintosh requires a 
PCI PowerMac or that Mozilla will not work on NuBus powermacs? (see release 
notes)

Comment 72

[Peter Henderson]

Thanks Kovu for making all the changes. Sorry for not saying it properly. What I
was getting at in #7 was that there are LICENSE and LEGAL files with no
extension, but README.txt not README. I think in general, Linux uses all upper
case (README), Mac uses title case (Readme), and Windows uses title case with
extension (Readme.txt) or just extension (readme.txt). That's just my
observations though, and I see no reason why they can't all be README with no
extension. Maybe that's a separate bug though, now that I think about it. If
making the LICENSE, LEGAL, and README.txt files share common naming is not part
of "os localizing", then let me know and I'll file it separately.

And about #6, I was thinking that it would make all three platforms consistent
to have directions to add an icon to each of their application-launcher
facilities. I haven't ever added an icon to a GNOME panel, but from the outlined
steps, it seems like it's about the same process as adding one to Windows' Start
menu. Also, the directions seemed to be for a "complete install"--either use the
installer, or the .tar.gz and add an icon. (Does the Linux installer add a GNOME
icon like the Windows installer adds a Start menu icon?) So if that's the case
it would make sense to have instructions for the Windows installer, and also for
.zip packages and adding an icon. That's just for the sake of consistency, as
perceived by Peter... Don't get me wrong, I'm happy with the current file (after
2-5 go in, of course)...but I'm a perfectionist, and as long as it's being
worked on I think we might as well get it as perfect as possible. Thanks again
for all the work.

PS: Would it help if I either attached an updated version (with 2-5) or else
sent a diff? I'd be happy to do either.

Comment 73

[Leston Buell]

What is the status on this bug? I filed bug 136258 back in April and we found a
solution. My bug was marked fixed because it blocked this bug. But now it's
September and i see that the text formatting of the installation is still bad in
Mozilla 1.2a. I would like to reopen my bug. Please advise.

Comment 74

[James "Kovu" Russell]

Can we PLEASE get the latest version of this README checked in? I (and others)
went to a lot of hard work on this, and it appears that an old version is still
part of the builds.

Comment 75

[Mike Kaply [:mkaply]]

If I want to add OS/2 to the readme, what is the best way to do it, attach it here?

Comment 76

[Leston Buell]

The fact that this is not checked in yet is amazing. The issue raised in bug
136258 has to do with incorrect formatting in the *very first window* a Linux
user sees when opening the installer program. (See screenshot at that bug.) The
fact that this is something seen by the user during installation suggests that
the component for this bug should be "user" and not "Mozilla developer". You
decide that one. And the platform should be "all" rather than "Windows 98".

Comment 77

[James "Kovu" Russell]

The major README for Mozilla, IMO, shouldn't include anything other than
top-tier platforms (there are three: Unix/Linux, Mac, and Windows) just for the
sake of brevity. I would rather an OS/2 README come with only those builds, if
possible, but I'm not sure what the logistics of this are. Anyone know?

-JR

Comment 78

[David Baron :dbaron: (⌚️UTC-4, no longer working on Mozilla)]

Comment on attachment 83675 [details] [diff] [review]
tweaked Mac again

>    Tip: To hook up Mozilla complete with icon to
>    the GNOME Panel, follow these steps:
[...]
>        2. Right-click the icon for Mozilla on the
>        Panel and enter the following command:
>
>          directory_path/./mozilla
>
>        where directory_path is the name of the
>        directory you installed mozilla to. For
>        example, the default directory that Mozilla
>        suggests is /usr/local/mozilla. In that
>        case, the command you would type in would
>        be as follows:
>
>          /user/local/mozilla/./mozilla

This seems like something that could be described in fewer than 10 lines. 
(This applies to point (4) as well.)  But if you're giving istructions this
detailed, it might be worth mentioning that after right-clicking, the user
should choose "Properties".  Also, the last line says "user" rather than "usr",
and the extra "./" is unnecessary.

Comment 79

[Daniel Wang]

*** This bug has been marked as a duplicate of 59885 ***

Comment 80

[Brant Gurganus]

v