Download & Extend
Issues

INSTALL Documentation Update

Posted by pcwick on September 3, 2006 at 10:35pm
Project:Drupal core
Version:x.y.z
Component:other
Category:task
Priority:critical
Assigned:Unassigned
Status:closed (fixed)

Issue Summary

Today, I installed and tried out what will be Drupal 5.0. Wow!! An install script! An option to select an admin theme! Block visibility by role! The reorganization of the administration section is fabulous!

I noticed the install docs have not been updated to reflect the changes in the installation procedeure. As a gesture of appreciation to the developers and to give back to the community, I offer what I hope will be accepted as a first draft of an update of the install documentation.

AttachmentSizeStatusTest resultOperations
INSTALL_5.txt9.28 KBIgnored: Check issue status.NoneNone
Login or register to post comments

Comments

#1

Posted by pcwick on September 3, 2006 at 10:37pm

Here's an updated INSTALL.mysql.txt.

AttachmentSizeStatusTest resultOperations
INSTALL.mysql.txt1.4 KBIgnored: Check issue status.NoneNone

#2

Posted by pcwick on September 3, 2006 at 10:37pm

And an update INSTALL.pgsql.txt.

AttachmentSizeStatusTest resultOperations
INSTALL.pgsql.txt1009 bytesIgnored: Check issue status.NoneNone

#3

Posted by webchick on September 3, 2006 at 11:04pm
Priority:normal» critical
Status:active» needs work

I'm bumping status to 'critical' because "How can I install this when there is no database directory?" has already come up at least 3 times on the forums, and it's impeding would-be testers from trying it out since they think it's broken.

This patch is a good start, however needs a bit of work...

  1. It's not in patch format, but probably not that big of a deal as this is documentation and we don't want to create additional barriers, blah blah. If possible though, it would be great if you could submit updates in the form of a patch. This will show the differences between the text you wrote and what the original text said, so we can more easily compare.
  2. The text in these files needs to wrap at 80 characters.
  3. Use single spaces between sentences, not double. There are also some weird spacing issues at other places (e.g. mod_rewrite and   the ability)
  4. Drupal's audience tends to consist of either people who host with a company that provides PHPMyAdmin or something, or who know MySQL/PostgreSQL commands by the back of their hands. I'd therefore maybe consolidate the "CREATE DRUPAL DATABASE" section to essentially say, "Drupal requires access to a database in order to be installed. Take note of the user/pass/dbname/hostname. If you have questions on how to create a database, please talk with your hosting provider."
  5. On that note, Is it any longer in scope for us to have separate INSTALL files for MySQL/PostgreSQL? Should we instead inform them in INSTALL.txt of the UTF-8 requirement (is this a requirement?) and tell them what permissions Drupal requires?

#4

Posted by pcwick on September 4, 2006 at 2:53am

1. Its too late in the day for me to figure out how to convert this to a patch, but that skill is on my todo list. :-)

2. Text is now wrapped to 80 characters.

3. I believe I corrected all the double spaces and wierd spacings.

4 & 5.
I did consolidate the CREATE THE DRUPAL DATABASE section somewhat. For now, I left in the references to INSTALL.mysql.txt and INSTALL.pgsql.txt though I do agree it seems cleaner to incorporate these into the INSTALL.txt. On the other hand, including all of the text of INSTALL.mysql.txt and INSTALL.pgsql.txt into INSTALL.txt seems unwieldy. I wonder if a better option is to refer users who need instruction on creating a database to page(s) in the handbook?

Upon review I see it is only the original "INSTALL.pgsql.txt" that states "Note that the database must be created with UTF-8 (Unicode) encoding." I have changed the new INSTALL.txt to read "A PostgreSQL database must be created with UTF-8 (Unicode) encoding. UTF-8 (Unicode) encoding is recommended for MySQL databases." I don't know if this statement is true (and I am beginning to see why using patch would be helpful :-)

6. I don't use PostgreSQL and I don't know if there are any options specific to PostgreSQL that need to be included in the RUN THE INSTALL SCRIPT section.

7. I changed the DRUPAL ADMINISTRATION section because it is no longer accurate given the improvements to Drupal Administration. The improvements also necessitated a change in the CONFIGURE DRUPAL section.

8. I tightended up the phrasing in several places where it seemed I could do so without losing any meaning.

9. I moved multisite instructions near the end of the file because I recall when I set up my first basic Drupal site I spent some time figuring out that those instructions were not relevant to me. Although the multisite instructions are the best instructions available on the topic, I do wonder if these instructions are really INSTALL.txt. material, and if instead those interested in a multisite setup should consult the handbook. I'm not sure on this one and wondering about other opinions.

AttachmentSizeStatusTest resultOperations
INSTALL_6.txt9.17 KBIgnored: Check issue status.NoneNone

#5

Posted by pcwick on September 4, 2006 at 6:08pm

1. I tried to make a patch, but haven't got the hang of it yet.

4 & 5
If I understood correctly a discussion at dupal-support, napkin suggests it is
not technically required that UTF-8 be used, but is strongly recommended.
Also, because MySQL 4.1 and greater uses UTF-8 by default, it is not
necessary to instruct that a MySQL database be created with UTF-8. Instead,
it may be better to recommend that users of MySQL use MySQL 4.1 or greater to
assure that the database can be transferred safely. I made a change to this
effect in the REQUIREMENTS section.

Questions that remain:

Should INSTALL.mysql.txt and INSTALL.pgsql.txt be left as seperate files,
incorporated into INSTALL.txt, or made into handbook pages referenced by
INSTALL.txt.

I'm still not clear whether or not this phrase in INSTALL.pgsql.txt is
accurate: "Note that the database must be created with UTF-8 (Unicode)
encoding."

6. Heine stated "the settings page code for install doesn't contain any logic
to display extra options for pgsql" so I'm considering item 6 to be closed.

AttachmentSizeStatusTest resultOperations
INSTALL_7.txt9.09 KBIgnored: Check issue status.NoneNone

#6

Posted by gopherspidey on September 5, 2006 at 1:35am
Status:needs work» needs review

1. I have attached a patch that contains the mysql, pgsql and just the plain INSTAL.txt files.

AttachmentSizeStatusTest resultOperations
INSTALL.patch.txt24.02 KBIgnored: Check issue status.NoneNone

#7

Posted by Dries on September 5, 2006 at 11:03am

Good. :)

Small nit: I don't think we should explain the basic and advanced options. That needs to be explained by the installer itself.

#8

Posted by pcwick on September 5, 2006 at 3:25pm

Basic and advanced option explanations removed.

AttachmentSizeStatusTest resultOperations
INSTALL.patch_0.txt24.02 KBIgnored: Check issue status.NoneNone

#9

Posted by pcwick on September 5, 2006 at 3:37pm

It may be my ignorance of working with patches, but it looks like when the patch was created much of the content of INSTALL.pgsql.txt was deleted and replaced with "@@ -41,13 +24,4 @@"

#10

Posted by gopherspidey on September 6, 2006 at 12:16am

Most likely it is due to the text not changing for the old file.

A patch is just the changes from one version of a file to the other. Only changes

#11

Posted by Dries on September 6, 2006 at 7:43am

The wordwrapping seems to be inconsistent? Different lengths...

#12

Posted by pcwick on September 6, 2006 at 5:54pm

Yes, the original INSTALL docs were wrapped to 70. While it seemed to me unclear that INSTALL.mysql.txt and INSTALL.pgsql.txt would continue to be independent documents, I had not taken the time to update them to width 80.

I tried to make changes by modifying the patch file but am afraid I was making a mess.

Attached are the three install docs in txt format. Each is wrapped to 80. I made a couple of minor changes to INSTALL.txt as well.

If someone could please convert these to patch format, I think they are just about ready. gopherspidey, you around?

AttachmentSizeStatusTest resultOperations
INSTALL_8.txt8.5 KBIgnored: Check issue status.NoneNone

#13

Posted by pcwick on September 6, 2006 at 5:56pm

INSTALL.mysql.txt

AttachmentSizeStatusTest resultOperations
INSTALL.mysql_0.txt1.33 KBIgnored: Check issue status.NoneNone

#14

Posted by pcwick on September 6, 2006 at 5:57pm

INSTALL.pgsql.txt

AttachmentSizeStatusTest resultOperations
INSTALL.pgsql_0.txt1007 bytesIgnored: Check issue status.NoneNone

#15

Posted by gopherspidey on September 7, 2006 at 12:32am

I will make you a patch when I get home tonight. Give me a couple hours!

#16

Posted by gopherspidey on September 7, 2006 at 1:35am
Status:needs review» reviewed & tested by the community

Here is the patch rolled from cvs mins ago.

AttachmentSizeStatusTest resultOperations
INSTALL.patch_1.txt25.25 KBIgnored: Check issue status.NoneNone

#17

Posted by Dries on September 7, 2006 at 7:36am
Status:reviewed & tested by the community» needs work

Patch does not apply?

#18

Posted by Ralf on September 7, 2006 at 7:52am

@ gopherspidey

Why do you want to delete the CVS ID tags?

Why 'mysql://root:drupal@localhost/drupal'? Please make consistent.

#19

Posted by gopherspidey on September 7, 2006 at 2:37pm
Status:needs work» reviewed & tested by the community

Sorry Sorry Sorry.

That was a dumb mistake. I have also added back the CVS id lines to the files.

I have tested and it applies cleaning to head and only modifies the INSTAL*.txt files

AttachmentSizeStatusTest resultOperations
INSTALL.patch_2.txt24.4 KBIgnored: Check issue status.NoneNone

#20

Posted by Ralf on September 7, 2006 at 3:14pm
Status:reviewed & tested by the community» needs work

Hi gopherspidey,

Sorry if I sounded rough.

There is still 1 www.example.org instead www.example.com.

dba_user and username not consistent.

#21

Posted by webchick on September 7, 2006 at 3:27pm
Status:needs work» reviewed & tested by the community

Off-topic:

Gopherspidey: Not sure if you knew this or not, but you can move your settings.php file into a folder called:

sites/localhost

(alongside sites/default)

And the do cvs update -dPC (C = Clean) form the sites directory to place the original settings.php file back in.

This way your test site will still work, but you'll no longer accidentally roll patches with your $db_url in them.

Just remember that each time you run the installer, it will always write to sites/default/settings.php, so you'll have to do the process again. :)

#22

Posted by gopherspidey on September 7, 2006 at 6:29pm

Thanks. For giving me some tips. I will rearrange my test site.

#23

Posted by sepeck on September 7, 2006 at 6:48pm

I'd also like to see if we can do away with the seperate install MYSQL and install PostGRE documents. With the web installer hadling most of the heavy lifting, having to refer to a sperate document for a step BEFORE you run the installer seems odd and interupts the workflow.

#24

Posted by gopherspidey on September 7, 2006 at 6:50pm

@Ralf Stamm: Thanks for the pointers. Since I did not write or update the documentation, I did not read is carefully. I started out just making for pcwick.

I have updated both the dba_user to username and example.org to example.com

AttachmentSizeStatusTest resultOperations
INSTALL.patch_3.txt24.41 KBIgnored: Check issue status.NoneNone

#25

Posted by Dries on September 8, 2006 at 4:29pm
Status:reviewed & tested by the community» fixed

Committed to CVS HEAD. Thanks.

#26

Posted by Anonymous on September 22, 2006 at 4:30pm
Status:fixed» closed (fixed)