Jcable/297 Change of standard for punctuation with quotation marks. #315
Conversation
en-US/Punctuation.xml
Outdated
| <!-- Not implementing this change for now. | ||
| <para> | ||
| In technical documentation, punctuation marks, including periods, commas, question marks, exclamation points, dashes, and semicolons go inside the quotation marks if they are part of the quotation; if not, they go outside. | ||
| In technical documentation, punctuation marks, including periods, commas, question marks, exclamation points, dashes, and semicolons go inside the quotation marks if they are part of the quotation or part of a programming element that uses quotation marks; if not, they go outside the quotation marks. If a sentence ends with a quotation, use only one punctuation mark to end the sentence, and place it inside the closing quotation mark if it is part of the quotation, or outside if it is not. |
There was a problem hiding this comment.
Rather than "In technical documentation, punctuation marks,... go inside..." how about "In technical documentation, place punctuation marks,...inside..."
Also remember to continue with the "one sentence per line" guide to make reviews and edits easier. This is relatively new in the SG so you won't see a lot of it yet.
There was a problem hiding this comment.
Agree with moving the verb earlier in the sentence.
Will note about one sentence per line.
| <title>"That" in Clauses</title> | ||
| <para> | ||
| Include the word "that" in clauses unless it results in writing that is too formal or stilted. The use of the conjunction "that" makes the sentence easier to translate and improves clarity for readers whose primary language is not English, | ||
| Include the word "that" in clauses unless it results in writing that is too formal or stilted. The use of the conjunction "that" makes the sentence easier to translate and improves clarity for readers whose primary language is not English. |
There was a problem hiding this comment.
Yes, this commit wasn't intentionally included in this issue.
en-US/Punctuation.xml
Outdated
| Add examples of when to use or not to use quotation marks. | ||
| <example><title>Correct Examples of the Use of Punctuation with Quotation Marks</title> | ||
| <para> | ||
| For bind mounts, add "bind" and set fstype to "none". |
| In the program segment, ensure that the value is X'FF'. | ||
| </para> | ||
| <para> | ||
| If you use the keyword operand PGMID="PAYCOM", you must ... |
There was a problem hiding this comment.
Where did this example come from? I'm not sure how good of an example it is for what we're trying to demonstrate.
There was a problem hiding this comment.
It came from IBM Style. The idea was to show that the comma goes outside the quotation marks. I'll remove it and we have several other examples anyway.
en-US/Punctuation.xml
Outdated
| </para> | ||
| <para> | ||
| Julius Caesar said, “I came. I saw. I conquered.” | ||
| </para> | ||
| </example> | ||
|
|
||
| </section> |
There was a problem hiding this comment.
It's a good idea to stay on top of formatting, indentation, etc., when working in markup languages. It can make a difference to readability, troubleshooting, and in some cases (e.g., YAML) actual results.
There was a problem hiding this comment.
In my VS Code the indentation looks the same regardless of whether a leading tab or spaces are used. That appears not to be the case in this view, so I'm changing those lines to use a tab only.
julian-cable
changed the title
No description provided.