Topic extend-manual-install -- would be better to suggest uploading archive and unpacking on server

I agree, although you can only do the unpacking on the server if you have server terminal access, which some people may not have on some hosting situations. So, we might need to think a bit more about exactly how to write this.

Oh, that's a good point!

So... would you like to propose new text for those two steps? I think the "edit source" link is still broken (I assume so, the issue hasn't been touched), but if you want to just type in the text you propose in the issue here, I can apply it to the txt file.

Thanks!

Great! Much appreciated.

And if I didn't say so already, thanks for reading through the guide carefully over the past few days, noticing problems, and best yet making all those issues! We cannot improve the Guide unless people point out problems they notice.

We did subject the Guide to some testing with novice users, which was good for pointing out where things were unclear, and catching some of the "you didn't talk about this yet" types of problems (and you caught a few more, great!). But it's also very useful to have someone like yourself, with experience, to look it over for accuracy. Joe and I tried to make sure it was accurate, but ... again, sometimes a fresh perspective is useful.

AsciiDoc source editing should be working again!

Thanks, this looks pretty good!

A few small suggestions:

1. +++ b/source/en/extend-manual-install.txt
   @@ -48,7 +48,7 @@ If you are installing a module or theme from _Drupal.org_, follow the
    downloading and unpacking instructions, and then the uploading instructions. If
   

   This line also needs a small adjustment (follow the downloading, then the uploading/unpacking...)

2. +++ b/source/en/extend-manual-install.txt
   @@ -90,9 +88,23 @@ or theme. Modules are normally located in directories under the top-level
   +(if adding a new module or theme). If you have access via a terminal,
   +you may use FTP, SFTP or scp. If you are using an interface like cPanel,
   +you will find some type of File Manager utility.
   

   I am not sure we need these sentences about how to upload the files to the site. Probably we don't. We don't tell people how to upload the Drupal Core download in the Installation chapter, so we probably don't need to do it here either.

   Come to think of it, that installation chapter should also be revised to suggest uploading the archive and then unpacking....

3. +++ b/source/en/extend-manual-install.txt
   @@ -90,9 +88,23 @@ or theme. Modules are normally located in directories under the top-level
   +. Extract the files into a directory on the server. If you have access via
   

   This is vague "a directory". Let's be more specific.

4. You should also add yourself to the Attributions section at the end. Should say "Written and edited by..." and you can add your name to the list.

--- a/source/en/extend-manual-install.txt
+++ b/source/en/extend-manual-install.txt
@@ -48,7 +48,7 @@ If you are installing a module or theme from _Drupal.org_, follow the
 downloading and unpacking instructions, and then the uploading instructions. If
 you created the module or theme, skip the downloading and unpacking steps.
 
-===== Downloading and unpacking the files
+===== Downloading and the files

An unnecessary "and" has been left in the last line.

That's better, thanks! I think maybe it needs one more pass...

1. +++ b/source/en/extend-manual-install.txt
   @@ -62,10 +62,8 @@ image:images/extend-manual-install-download.png["Downloading module files"]
    . Click _tar.gz_ or _zip_ to download the file to your computer.
   

   Later on in this topic (with your edits), you've called this "compressed file"... in other topics we've just called it "tar.gz or zip file"... maybe we should do that here, or else in this line, add the word "compressed" just to be clear?

2. +++ b/source/en/extend-manual-install.txt
   @@ -62,10 +62,8 @@ image:images/extend-manual-install-download.png["Downloading module files"]
   -===== Uploading the files to your site
    
   +===== Uploading the files to your site and unpacking them
    . If you are adding a new module or theme, create subdirectories in your
   

   There should be a blank line before the header, and another between the header and the first step. Sorry, missed that in the last review.

3. +++ b/source/en/extend-manual-install.txt
   @@ -90,9 +88,21 @@ or theme. Modules are normally located in directories under the top-level
   +. Upload the compressed file to your site. Place it in either the same
   +location as the one you deleted (if replacing an existing module or theme)
   

   You deleted a whole directory, and you're uploading one file, so "the one" is a bit confusing, because you didn't delete a compressed file.

   How about:

   ... same location as the directory you deleted...

4. +++ b/source/en/extend-manual-install.txt
   @@ -90,9 +88,21 @@ or theme. Modules are normally located in directories under the top-level
   +. Extract the files on the server. If you have access via
   +a terminal, you can use a command like
   ++
   +----
   +tar -xzf admin_toolbar-8.x-1.17.tar.gz
   +----
   

   If we're going to explicitly suggest this command, maybe we should also suggest they download the .tar.gz file above? Either that or also provide the unzip command.

   Also, what if they are hosting on IIS?

   Hmmm....

   So. Maybe what the text before the command should say is:

   Extract the files from the archive, making a subdirectory in the same location as the archive file. For example, if you have terminal access to your hosting server running Linux, and you downloaded the _.tar.gz_ file, you can use a command like this:

5. +++ b/source/en/extend-manual-install.txt
   @@ -90,9 +88,21 @@ or theme. Modules are normally located in directories under the top-level
   +If you are using an interface like the File Manager in cPanel, you
   +will find an option to Extract files.
   

   How about something like:

   If you do not have terminal access, your hosting control panel's file manager should provide a way to extract the files.

   Note: I don't think "Extract" should be capitalized here.

Sorry, I was out of town a few days and just got back last night... catching up with issues... Let's see.

Regarding #15, how about if we just tell them to download the .tar.gz file, so that we just have one set of instructions?

Setting status back to needs work...

This looks great -- very clear. Thanks!

My only concern now is this sentence near the top:

+++ b/source/en/extend-manual-install.txt
@@ -45,10 +45,10 @@ Skip this topic if none of the above applies to you.
+downloading instructions, and then the uploading/unpacking instructions. If
 you created the module or theme, skip the downloading and unpacking steps.

This case (you created the module or theme) now doesn't really have instructions, because in this case, you would have a directory of files on your local server that you'd need to upload, not a .tar.gz file to upload/unpack. The previous instructions covered that case because they said to extract the .tar.gz archive locally and then upload the directory of files, but since we're not suggesting that any more, this part at the top doesn't quite make sense now in the context of the rest of the page.

So, can we put in a step that explains what to do in this case, and revise this sentence?

Hm. I'm not sure if people who don't run Linux as their desktop would know how to compress their own directory into a .tar.gz file?

Fair point... I think we still need to say something, because we have pointed to this page as instructions when you're installing a custom module/theme that you or someone else created... so OK, let's just say to zip it up into an archive and then follow the upload/unpack instructions.

Looks good... a couple of very small things and I think we're done:

1. +++ b/source/en/extend-manual-install.txt
   @@ -45,10 +45,13 @@ Skip this topic if none of the above applies to you.
   +downloading instructions, and then the uploading/unpacking instructions. If
    you created the module or theme, skip the downloading and unpacking steps.
   +Instead, create an archive file (that you know how to extract on the server)
   +and proceed with the steps in uploading/unpacking, using whatever method
   +is appropriate for the way you initially created the archive file.
   

   So this should say just to skip the downloading instructions, right?

   Otherwise, this looks good.

2. +++ b/source/en/extend-manual-install.txt
   @@ -90,9 +91,27 @@ or theme. Modules are normally located in directories under the top-level
   +(running Linux), you can use a command like:
   ++
   +----
   +tar -xzf admin_toolbar-8.x-1.17.tar.gz
   +----
   +If you do not have terminal access, or your hosting server is not running
   

   nitpick: I'm not sure why there is a blank line before this command but not after. It seems like there should either be two blank lines or no blank lines?

3. +++ b/source/en/extend-manual-install.txt
   @@ -90,9 +91,27 @@ or theme. Modules are normally located in directories under the top-level
   +. Delete the compressed file from the server. (Your archive format may
   +convert the compressed file directly into the extracted format without
   +leaving a compressed file on the server.)
   

   How about here saying just:

   Delete the compressed file from the server, unless your unpacking method already deleted it.

OK, this is now perfect! Or at least wonderful. Thanks for all the iterations. :) I'll get it committed shortly (in the middle of something else at the moment). We'll need to update now 5 translations as well, and add notes to several issues for them, so I don't want to do it when my mind is elsewhere.

Committed. Adding notes to
#2830965: [ES] Traducir este archivo fuente: extend-manual-install.txt
#2806465: [CA] Tradueix aquest fitxer extend-manual-install.txt
#2803559: [HU] extend-manual-install.txt lefordítása

One other note. The "Preparing to install" topic already has similar instructions to unzip on the server, phew:
https://www.drupal.org/docs/user_guide/en/install-prepare.html

Thanks VERY MUCH for that analysis!

I think we should open up another issue to address install-prepare, which should add some specifics similar to what this page now has.

And then another one to fix security-update-core so it actually makes sense and/or has instructions that work. That would be a good thing. ;)

Want to create them? Or I can...

Thanks very much!