Copy editing guideline for this issue

Paths, File names, URLs, and directories should be in italics.
For URLs within the reader’s site, use base URL example.com

Task Instructions

  1. To claim this task, assign this issue to yourself (see instructions below). Only claim a task if you can complete it in about two weeks.
  2. See the instructions below to "clone" the guide, edit the entire user guide so that it follows the above copy editing guideline, and make a patch file. Do not make other edits at this time -- other edits will be taken care of in other issues. If you find that you cannot complete the whole task, but have made some progress, make a patch file for the part you've done.
  3. Upload the patch file to this issue, in the Files section.
  4. Set the Issue Status to Needs Review, in the Issue Metadata section.
  5. Write a comment stating what you've done.
  6. In this comment, add "Attribution" information 
    https://www.drupal.org/u/msmith[Mary Smith]
or
https://www.drupal.org/u/jsmith[Joe Smith] of https://example.com[Example Company]
  7. Someone will review your work, and either accept it, or set it back to Needs Work for more attention.
  8. If the status is set to Needs Work, make the requested changes, make a new patch file, and upload it. Iterate until it is fixed.

Detailed Instructions for Assigning Issues and Patching

Assigning an issue to yourself

  1. Scroll to the bottom of the issue to Add new comment.
  2. Open the "Issue metadata" section if it is collapsed.
  3. Put your user name in the "Assigned" field, add a short comment stating that you are claiming the task, and Save.

Editing and making a patch file

  1. In order to make a patch file, you will need to use the Git version control software. There are generic instructions on Git at: https://www.drupal.org/documentation/git/ -- if you have never used Git, you will probably want to read the introductory material, and you'll need to install Git.
  2. Specific Git instructions for the User Guide project can be found at https://www.drupal.org/project/user_guide/git-instructions . Follow the instructions to "clone" the repository (see the "One-time only" instructions).
  3. Make the edits for this issue, using a plain-text editor. The source files are located in the source/en subdirectory, and have extension .txt, and are in AsciiDoc format (see below).
  4. Go back to the specific Git instructions page and follow the instructions there to make a patch file. There are also more detailed git patch instructions in the Git documentation section linked above.

AsciiDoc formatting

The documentation in this project is formatted using AsciiDoc. The Formatting page in the User Guide guidelines (login: drupal / drupal ) has links and details for how to format text properly, make cross-links between topics, etc.

CommentFileSizeAuthor
#19 2699061-final-19.patch34.98 KBcleverington
#13 2688061-user_guide-files-urls-directories-13_without-drupalorg.patch10.96 KBcleverington
#13 2688061-user_guide-Drupalorg_only-13.patch42.87 KBcleverington
#9 2699061-user_guide-files_names_urls_and_folders-9.patch10.73 KBcleverington
Support from Acquia helps fund testing for Drupal Acquia logo

Comments

ifrik created an issue. See original summary.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

I've now centralized instructions for the editing tasks. I'll go ahead and leave the instructions on these issues, but you can also go to
https://userguide_new-drupal.dev.devdrupal.org/guidelines/instructions.h...
(log in with drupal / drupal)
and follow the instructions there (probably more complete).

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

Note: While reviewing for another issue, I noticed a page using farmersmarket.com instead of example.com. This is in file: content-paths.txt (and it appears several times in that page).

cleverington’s picture

cleverington CreditAttribution: cleverington as a volunteer commented

I saw it too and planned to ask once I finished my other issues.

https://userguide_new-drupal.dev.devdrupal.org/d8guide/en/planning-chapt...

If you look, the "fake site" used in walking through a typical Drupal Installation for "Anytown Farmers Market" in the 'Planning Your Site' chapter.

I think you might want to specifically include the farmersmarket.com reference in the issue or create a separate issue altogether if changing the project from 'farmersmarket.com' to 'example.com', just because it is part of the 'farmers market example site' referenced a few times on different pages.

As a side-note, I finally re-enabled that new-fangled "IRC" thingy, so if you ever see me in the doc channel, I'm generally around.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

Well. So we have a "guiding scenario" that is referred to everywhere, which is to build a web site for a farmers market. There is a description in the Scenario section of the Preface. We want to keep that, as well as the specifics of it being called "Anytown Farmers Market", etc. This is used to make the steps concrete, when describing how to do tasks.

But separate from that, we have a standard (in drupal.org and drupal docs in general), to use "example.com" for the base URL if you need a "generic URL". This standard is already mentioned as being part of the copy editing standard for this issue, although we could split it out to a different task/issue if we need to.... But anyway, we have mostly done this correctly throughout the guide, even when referring to the web site for the farmer's market that we are building.

Except in this one topic, where the author used farmersmarket.com instead. We just need to change that URL to example.com. Putting it into the patch for this issue would be lovely. Or we can create a separate one, but anyway it is limited to just this one topic file.

cleverington’s picture

cleverington CreditAttribution: cleverington as a volunteer commented
Assigned: Unassigned » cleverington

Works for me!

As two of the other issues have moved to 'Fixed', I'll go ahead and take on this one as well.

*chuckle-snort* the Upload issue would be resolved as well if I hadn't accidentally deleted the wrong Git branch..... *shrug* Live and learn....

Just to clarify, this directive applies to any scenario where the site is written out 'in full', but is not an internal/external link, or any/all scenario where xxx.com / xxx.org appears?

For example, the farmersmarket.com referenced above would be italicized, but https://groups.drupal.org[groups.drupal.org] would not be italicized?

Or, in contrast, the Events Calendar link would be something like:
https://groups.drupal.org/events/["Event Calendar" on _groups.drupal.org_]

Thoughts / Clarification?

cleverington’s picture

cleverington CreditAttribution: cleverington as a volunteer commented
Status: Active » Postponed (maintainer needs more info)
jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Status: Postponed (maintainer needs more info) » Active

Ah. Hm. I guess we should just always have URLs in italics, whether they are example.com, groups.drupal.org (in any context), or whatever. Exceptions to rules are always difficult to figure out.

I guess we should have thought of that before we finished up the External URLs issue... hm. Well, this patch will be large, but at least you'll be familiar with the files...

cleverington’s picture

cleverington CreditAttribution: cleverington as a volunteer commented
Status: Active » Needs review
FileSize
2699061-user_guide-files_names_urls_and_folders-9.patch10.73 KB

I asked in IRC, but I'll follow up here too.

Drupal.org instances within external URLs?

https://www.drupal.org/examples/[_Drupal.org_ community documentation on "Examples"]

Didn't see too many changes. I'll probably review another time tomorrow, just in case.

grep suggestion for directories?

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Status: Needs review » Needs work

Regarding directories and files (finding mention of them), I can suggest grepping for:
- a / (good indication of a file path) in a line without an http (because URLs also have them), so grep "/" *.txt | grep -v http
- the words "file" or "director" (could be directory or directories or file or files)

Regarding the patch, it is mostly great! A few small things to fix:

  1. +++ b/source/en/config-theme.txt
@@ -19,7 +19,7 @@ will be using the visual guidelines for our farmers market site.
-(/admin/appearance).
+(admin/appearance).

    good catch! Not technically in scope for this issue as stated, but within reason. :) 

  2. +++ b/source/en/content-paths.txt
@@ -13,7 +13,7 @@
+the example "Check us out at example.com." the part _example.com_ is

    I think we should probably put the first example.com in italics too? 

  3. +++ b/source/en/extend-module-find.txt
@@ -11,7 +11,7 @@
+Find and evaluate modules on Drupal.org or _Drupalmodules.com_.

    Drupal.org should also be in italics? 

  4. +++ b/source/en/prevent-status.txt
@@ -23,7 +23,7 @@ this information into support requests filed on drupal.org's support forums and
-_Reports_ (/admin/reports/status).
+_Reports_ (_https://example.com/admin/reports/status_).

    Well, in all the other navigation instructions, we are just saying (admin/reports/status) and not giving the full URL. I think we should do that here.

    The wording of this paragraph should be changed to:

    To find the status report, in the _Manage_ administrative menu, navigate to _Reports_, _Status report_ (admin/reports/status).

cleverington’s picture

cleverington CreditAttribution: cleverington as a volunteer commented

I think I may want to create two separate patches. One for just Drupal.org and one for everything else.

Is there any issue with that?

(Also, on #4, I thought I deleted all of those.... lol)

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

Not a problem to have two separate patches. Thanks!

cleverington’s picture

cleverington CreditAttribution: cleverington as a volunteer commented
Status: Needs work » Needs review
FileSize
2688061-user_guide-Drupalorg_only-13.patch42.87 KB
2688061-user_guide-files-urls-directories-13_without-drupalorg.patch10.96 KB

Wow!

That is certainly a few number of edits!

The drupalorg_only patch is just that, Drupal.org only. There were a couple of instances where it was spelled 'drupal.org' that I went ahead and fixed as well, but I don't THINK there will be any issues.

Cheers!

  • jhodgdon committed 22e9468 on 8.x-0.x authored by cleverington 
    Issue #2699061 by cleverington: Copy edit: File names, directories, and...
jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Status: Needs review » Active

Thanks! Both patches look good. I had a little trouble applying them together, because the context had changed, but I took care of it.

So... I used grep to look for other places that still might need to be fixed for this guideline ( I searched for "/" but excluded // which are comments and/or URLs -- I think you probably got all the URLs).

I think we need to fix:

a) content-paths.txt:

* node/7
* taxonomy/term/6
* admin/content/comment
* user/login
* user/3

(this is a list of paths, which are part of URLs so probably we should italicize them?)

b) Sigh, the standard navigation... we have a few places where we've put the ending path in italics, like this in extend-config-versions.txt:

. In the source site, in the _Manage_ administrative menu, navigate to
_Configuration_ > _Development_ > _Configuration synchronization_ > _Export_
(_admin/config/development/configuration/full/export_).

But most topics would not have the admin/config/whatever/whatever in italics... and really, to be consistent, we should have them all in italics. Interested? You can also move on to another issue and we can leave this one for someone else... should be easy to find anyway (look for "admin/" ... oh, there are also two that start with "node/add".

cleverington’s picture

cleverington CreditAttribution: cleverington as a volunteer commented
Issue summary: View changes

I'll work on it, no probs.

I actually left the (admin/yada/yada) without italics because it was a path, but not a URL, file name, or directory.

If you want to include it with this issue, no probs.

I updated the Issue text. See text?

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

Good update, thanks! I updated the guidelines on our web site too (for the next book, if there ever is one).

cleverington’s picture

cleverington CreditAttribution: cleverington as a volunteer commented
Status: Active » Needs review
FileSize
2699061-final-19.patch34.98 KB

You should see how optimistically I named this patch.

^-^

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Status: Needs review » Fixed

I like the optimism... and I also concur! The patch looks good, and after applying it, I do not see anything else that needs to be changed.
THANK YOU.

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.