Support for Drupal 7 is ending on 5 January 2025—it’s time to migrate to Drupal 10! Learn about the many benefits of Drupal 10 and find migration tools in our resource center.Problem/Motivation
In many User Guide pages, there are tables of fields, explanations, and values that tell how to fill in administration forms.
In the block-create-custom topic, the table is missing the explanation column. Here's a link to the topic page:
https://www.drupal.org/docs/user_guide/en/block-create-custom.html
The source file is source/en/block-create-custom.txt.
Also the next topic has the same problem:
https://www.drupal.org/docs/user_guide/en/block-place.html
source file: block-place.txt
Proposed resolution
Add the Explanation column to the tables in these two topics.
Here are the guidelines for how these tables should be constructed:
https://www.drupal.org/docs/user_guide_guidelines/good-writing.html#good...
Remaining tasks
Make a patch that adds an Explanation column to the tables.
| Comment | File | Size | Author |
|---|---|---|---|
| #6 | 2864484.patch | 1.69 KB | jhodgdon |
Comments
Comment #2
jhodgdonThe Description field is also missing from the next topic, so adding this to the issue.
Comment #3
jhodgdonWhoops. that should be "Explanation" not "Description".
Comment #4
ashishdalviWe will work on it at DCM2017
Comment #5
jhodgdonI guess the work at DCM didn't happen... I will make a patch.
Comment #6
jhodgdonI used grep and found one more topic with no explanations in the tables -- structure-image-style-create. But I looked at the tables there:
https://www.drupal.org/docs/user_guide/en/structure-image-style-create.html
and I think the explanations are probably OK to be omitted. For instance, explaining what "width" and "height" fields are doesn't seem very useful.
This is in contrast to the ones in the Block topics that were part of this issue, which seem to be a good thing to add, because the title/description fields in blocks are a bit confusing. Anyway, here is a patch.
Comment #7
jhodgdonAnyone want to review this patch please?
Comment #8
Balu ErtlPatch downloaded, applies smoothly on 8.x-3.x branch, the two Blocks-related files (source/en/block-create-custom.txt and block-place.txt) opened in Atom's AsciiDoc Preview mode, and indeed now the tables has the "Explanation" column in between of Field name and Example values columns. I agree with Jennifer in #6 on that table in structure-image-style-create.txt is quite simple, so no real need to stick to our general rule in this case. Here are the issues of translating these two sections:
block-create-custom.txt
block-place.txt
All of them are in Active status, except HU, which I can take for.
Comment #9
jhodgdonThanks for the review! I am no longer adding notes to every translation issue when we make changes to English -- instead I am just putting out a notice on the email list with a suggested action for the translation team managers.
Anyway, I went ahead and committed the change to English, 3.x branch, and am sending out a message to the email list now too.
Comment #11
Balu ErtlOf course I didn't meant to go through on all issues and leave comments on them. This is exactly why we changed the update procedure :) I just collected to have a visual overview on how many locales are affected or not.
Meanwhile HU translation is updated as well.
Comment #12
Balu ErtlOne observation turns out during the first commit in this new system: in HU we already pre-processed our source files in favor of being able to feed the Translation Memory (TM). Now when I simply copy-paste from /source/en folder into /source/hu folder, this benefit will lost.
At the moment I believe it's an acceptable level of discomfort for us, but good to know about this issue if other translation teams (eg. German) also wants to utilize TM software in the future.
As a kind of workaround these updates in English source are good motivation to get that section already translated soon instead of postponing them into far future :)
Comment #13
jhodgdonSorry for your discomfort!
In this case, only a few lines of the source file were changed, so you would have been better off just copying these few lines. That is why I always include a link to the commit in the email messages, because you can look and see if the change is small (so copying just the new lines might be sensible) or large (easier to copy the whole file and fix the newlines).
Also I thought maybe after you did that change, you figured out how to tell the TM to ignore line breaks maybe? Or maybe I am remembering incorrectly... We should really get the TM guide into the Contributor Guide by the way! :) #2828137: Add section about using Translation Memory to contributor guide Hint hint. :) I will gladly review/proofread any patches you submit there!