-
Notifications
You must be signed in to change notification settings - Fork 20
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Some updates concerning punctuation #545
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Added some notes and suggested edits.
en-US/Grammar.xml
Outdated
@@ -215,6 +215,25 @@ | |||
</tgroup> | |||
|
|||
</table> | |||
|
|||
<para> | |||
You can use the possessive form with the "Red Hat" company name, to refer only to the company itself, without identifying any products or services. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
You can use the possessive form with the "Red Hat" company name, to refer only to the company itself, without identifying any products or services. | |
You can use the possessive form with the "Red Hat" company name to refer only to the company itself, without identifying any products or services. |
en-US/Punctuation.xml
Outdated
</para> | ||
<para> | ||
. , : ; ' " ( ) [ ] { } ! ? | ||
</para> | ||
<para> | ||
For all other characters, use the character name followed by the symbol in parentheses. | ||
For all other characters, use the character name followed by the symbol in parentheses. | ||
When referring to a symbol in parentheses, the symbol name comes after any noun that describes the symbol. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm not quite understanding this line. What does "any noun" refer to, words like "symbol" or "sign"? Is it describing a use case like this: the greater than (<
) symbol.
One issue here is that not all symbol names include a noun like symbol or sign, so then the guidance around this might be unclear. And personally, I don't think we need to add extra words describing a symbol if we don't need to.
How about something like this: For special character names that include nouns such as "sign" or "symbol", provide the character name, the symbol in parentheses, and then the noun that describes the symbol: the greater than (<
) symbol. For special character names that do not include such nouns, provide the character name and the symbol in parentheses: a forward slash (/
). In such cases, it is permissible to end a sentence with an encoded symbol.
en-US/Punctuation.xml
Outdated
<example><title>Referring to Special Characters</title> | ||
|
||
<para> | ||
When a regular user starts a shell, the prompt includes an ending dollar character ($). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I would use backticks on the dollar sign in the parentheses, since it's part of a command prompt.
en-US/Punctuation.xml
Outdated
Use the pipe character (|) to send the output of one program to the input of another program. | ||
</para> | ||
<para> | ||
The hyphen after the greater-than sign (>) indicates that a newline character (\n) is not added to the end of the variable. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
According to the table on special character names, the "greater than symbol" does not use a hyphen (even though that would be grammatically correct!).
en-US/Translation.xml
Outdated
</listitem> | ||
</itemizedlist> | ||
<para> | ||
Sometimes, list items might include some form of a verb, but without a subject and not capable of standing on their own. Such items count as sentence fragments, and are not ended with any punctuation. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Sometimes, list items might include some form of a verb, but without a subject and not capable of standing on their own. Such items count as sentence fragments, and are not ended with any punctuation. | |
Sometimes, list items might include some form of a verb, but if they don't also include a subject, then they are not capable of standing on their own. Such items count as sentence fragments, and are not ended with any punctuation. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Just one fix!
en-US/Punctuation.xml
Outdated
@@ -754,7 +754,9 @@ PLAY [Gather and display facts for managed nodes] ****************************</ | |||
</para> | |||
<para> | |||
For all other characters, use the character name followed by the symbol in parentheses. | |||
When referring to a symbol in parentheses, the symbol name comes after any noun that describes the symbol. | |||
For special character names that include a noun such as "sign", "symbol", or "character", provide the character name, the symbol in parentheses, and then the noun that describes the symbol, for example "the greater than symbol (>)". |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Based on the description, I think the example needs to be updated to: "the greater than (>) symbol"
* Working on #450. * Run Vale over Design.xml. This is the end of part 1/4 of "Run Vale over the style guide." Too big a job to try to handle in one issue and PR. * Ongoing updates for #456 * Closes #456 Part 2 of running Vale over the style guide. I also addressed a few other issues along the way, such as one sentence per line and removing old comments. Language.xml in particular contains lots of examples of what not to do, so it produces lots of noise in Vale. * s/may/might/ per Julian's review. * Working on #457 Run Vale of the style guide part 3. * Closes #457 Run Vale over the style guide, part 3. * Remove spurious space. * Closes #458 Run Vale over style guide part 4. * Closes #365 Remove DocBook references. * Closes #78 Update entry for "virtualized". Basically copy/paste from corp guide. * Closes #355. Improve a bit of formatting. * feat: Add advice on naming the default branch in an inclusive way. (#493) * feat: Add advice on naming the default branch in an inclusive way. * Update en-US/Language.xml Co-authored-by: julian-cable <79939933+julian-cable@users.noreply.github.com> * Update en-US/Language.xml Co-authored-by: julian-cable <79939933+julian-cable@users.noreply.github.com> * Update en-US/Language.xml Co-authored-by: julian-cable <79939933+julian-cable@users.noreply.github.com> --------- Co-authored-by: julian-cable <79939933+julian-cable@users.noreply.github.com> * Updated section about writing titles (#492) * Updated section about writing titles * Reverted title ID * Further edits * Updated guidance on continuation prompts (#494) * Various fixes for 6.1 release (#495) * Various fixes for 6.1 release * XML fix * Updated IBM Style access info (#496) * Updated term entries (#497) * Added guidance on omitting part of an output (#500) * Added guidance on omitting part of an output * Updated wording * Typo fix * Updated sample names and other small fixes (#502) * Various fixes (#512) * Implementing various feedback suggestions from Rachel (#513) * Implementing various feedback suggestions from Rachel * Addressed review comments * Addressed further review comment * Added more punctuation guidance (#515) * Added more punctuation guidance * Implemented review feedback * Updated audience description (#518) * Updated audience description * Further updated audience wording * Adding information about posessives (#519) * feat: added section about posessives * feat: here's the actual section * fix: made some revisions * Content and formatting updates * Update en-US/Punctuation.xml Co-authored-by: Rachel Lee <131199744+rclee33@users.noreply.github.com> * fix: made some revisions * fix: made another revision * Removed company name and restructured section * added link in section 3.6 * Final XML fix --------- Co-authored-by: Julian Cable <jcable@redhat.com> Co-authored-by: Rachel Lee <131199744+rclee33@users.noreply.github.com> * Updated view and edit files section * Added release notes for 6.1 and updated version information (#522) * updating homepage (#525) * 6.2 quick fixes (#544) * Some updates concerning punctuation (#545) * Updated guidance for punctuation and special characters * Enhanced guidance about punctuation in lists * Minor formatting * Content and formatting * Applied feedback * Minor fixes * Word usage updates: screenshot, lookup, see/refer to (#546) * Word usage updates: screenshot, lookup, see/refer to * Addresses one comment * Updates to see/refer to entries * Minor fix * Line continuation for multiple operating systems (#548) * Line continuation for multiple operating systems * Minor edit * Add 64-bit architecture guidance (#547) * Add 64-bit architecture guidance * Implementing edits from review * Updated Boolean guidance and a bug fix (#551) * Updated Boolean guidance and a bug fix * Update to Boolean entry * Reworked entries for tar, tarball, untar, unzip, zip (#552) * Clarify capitalization for table titles (#553) * Updates on referring to object names and using realistic usernames (#554) * Updates on referring to object names and using realistic usernames * Apply review comments * Updates for apostrophes and quotation marks (#557) * Updates for apostrophes and quotation marks * Updated list of punctuation marks * Updated guidance about titles (#559) * Updated guidance about titles * Change 'book' to 'publication' * Footnote update (#560) * adding ulink tag to a url * Replace an invalid URL --------- Co-authored-by: Julian Cable <jcable@redhat.com> * fix(docs): add some build instructions (#562) * fix(docs): add some build instructions * feat: add build shortcut * Added small comment --------- Co-authored-by: julian-cable <jcable@redhat.com> * Corrected some titles to use title case (#563) * Add release notes and update version info (#564) * Add release notes and update version info * Minor wording fix --------- Co-authored-by: daobrien <noreply@solaris.milky.way> Co-authored-by: David O'Brien <daobrien@users.noreply.github.com> Co-authored-by: mweetman-redhat <mweetman@redhat.com> Co-authored-by: Christine Belzie <105683440+CBID2@users.noreply.github.com> Co-authored-by: Rachel Lee <131199744+rclee33@users.noreply.github.com> Co-authored-by: Harpal Singh <52556240+harpasin@users.noreply.github.com> Co-authored-by: Alex Corcoles <alex@pdp7.net>
No description provided.