+++ This bug was initially created as a clone of Bug #1027229 +++ Description of problem: Overarching bug to cover a few identified issues in publican-redhat brand. Need to be picked up by other Red Hat brands as well. Some of these are based on inconsistencies, some on diversions from accepted standards, and others identified by STC as part of book review. Version-Release number of selected component (if applicable): publican-redhat-3.1-1.el6eng.noarch is my local version. Brewed docs may use a different version. How reproducible: Always? Possibly depends on brand version. Legal Notice is outdated. Not sure if this can make it into 4.0. 1. Document Conventions "Note: Red Hat Enterprise Linux 5 and later includes the Liberation Fonts set by default." Subject is plural and doesn't agree with verb. 1.1. Typographic Conventions "Four typographic conventions are used to call attention to specific words and phrases." Only three conventions are described. "This denotes words or phrases encountered on a system, including application names; dialog box text; labeled buttons; check-box and radio button labels; menu titles and sub-menu titles." Treatment of compound adjectives is inconsistent. s/sub-menu/submenu/ "Note the words in bold italics above — username, domain.name, file-system, package, version and release. Each word is a placeholder, either for text you enter when issuing a command or for text displayed by the system." IBM recommends not using em dashes in tech pubs. 1.2. Pull-quote Conventions "Output sent to a terminal is set in mono-spaced roman and presented thus:" Use of "thus" sounds... toffy. Maybe "as follows" or similar, as in the next example? 1.3. Notes and Warnings Recommend changing heading to "Admonitions." Also standardize text around (e.g.), "<admonition_type> admonitions are..." "Ignoring a box labeled 'Important' will not cause data loss but may cause irritation and frustration." Use double quotes for "Important." 2. Getting Help and Giving Feedback 2.1. Do You Need Help? One of RH doc's general guidelines (and not just RH) is to not use two consecutive headings without intervening text. If such a structure occurs it might mean that the layout needs revising, or that one of the headings is not required. "Click on the name of any mailing list to subscribe to that list or to access the list archives." s/click on/click/ 2.2. We Need Feedback! "If you find a typographical error in this manual, or if you have thought of a way to make this manual better, we would love to hear from you!" Remove exclamation points. Additional info: This BZ is a WIP. Julie and I are both reviewing for potential updates, errors, and improvements. See also BZ993519
(In reply to Ruediger Landmann from comment #0) > +++ This bug was initially created as a clone of Bug #1027229 +++ Thanks for the review, David and Julie: > 1. Document Conventions > "Note: Red Hat Enterprise Linux 5 and later includes the Liberation Fonts > set by default." > > Subject is plural and doesn't agree with verb. Already fixed in source for bug 952490 -- will be released with 4.0 > 1.1. Typographic Conventions > "Four typographic conventions are used to call attention to specific words > and phrases." > > Only three conventions are described. Four are described: * Mono-spaced bold * Proportional bold * Mono-spaced Bold Italic * Proportional Bold Italic even though the usage of the latter two is not differentiated. > "This denotes words or phrases encountered on a system, including > application names; dialog box text; labeled buttons; check-box and radio > button labels; menu titles and sub-menu titles." > > Treatment of compound adjectives is inconsistent. > s/sub-menu/submenu/ Will fix for 4.0 > "Note the words in bold italics above — username, domain.name, file-system, > package, version and release. Each word is a placeholder, either for text > you enter when issuing a command or for text displayed by the system." > > IBM recommends not using em dashes in tech pubs. I'll check their recommendation and get back on this (I don't have my copy of IBM with me), > 1.2. Pull-quote Conventions > "Output sent to a terminal is set in mono-spaced roman and presented thus:" > > Use of "thus" sounds... toffy. Maybe "as follows" or similar, as in the next > example? "Thus" is fine there; certainly not worth the translation overhead to change anyway. > 1.3. Notes and Warnings > Recommend changing heading to "Admonitions." "Admonitions" is the technical DocBook term for these structures, but I think it reduces clarity for people not thinking in DocBook. I suspect this would also be an interesting problem for translation, since most languages probably have a word meaning something close to "admonition" but probably zero have a word for the DocBook structure. > Also standardize text around > (e.g.), "<admonition_type> admonitions are..." See above for my thoughts on "admonitions". Moreover, I think that "Note admonitions are tips, shortcuts or alternative approaches" and "Warning admonitions should not be ignored" are considerably clunkier than what we have now and gain us nothing but conformity for its own sake. However, I'm certainly open to suggestions, but they would need to be really significant improvements on the existing text to justify the cost to translate. > "Ignoring a box labeled 'Important' will not cause data loss but may cause > irritation and frustration." > > Use double quotes for "Important." Will fix for 4.0
(In reply to Ruediger Landmann from comment #2) > (In reply to Ruediger Landmann from comment #0) > > +++ This bug was initially created as a clone of Bug #1027229 +++ > > Thanks for the review, David and Julie: > <snip> > > > 1.1. Typographic Conventions > > "Four typographic conventions are used to call attention to specific words > > and phrases." > > > > Only three conventions are described. > > Four are described: > > * Mono-spaced bold > * Proportional bold > * Mono-spaced Bold Italic > * Proportional Bold Italic > > even though the usage of the latter two is not differentiated. We did wonder about that. This "three vs four" comment came back from STC review of the book. > > > "This denotes words or phrases encountered on a system, including > > application names; dialog box text; labeled buttons; check-box and radio > > button labels; menu titles and sub-menu titles." > > > > Treatment of compound adjectives is inconsistent. > > s/sub-menu/submenu/ > > Will fix for 4.0 Great. > > > "Note the words in bold italics above — username, domain.name, file-system, > > package, version and release. Each word is a placeholder, either for text > > you enter when issuing a command or for text displayed by the system." > > > > IBM recommends not using em dashes in tech pubs. > > I'll check their recommendation and get back on this (I don't have my copy > of IBM with me), IBM p. 48: "Do not use en dashes or em dashes in technical information." > > > 1.2. Pull-quote Conventions > > "Output sent to a terminal is set in mono-spaced roman and presented thus:" > > > > Use of "thus" sounds... toffy. Maybe "as follows" or similar, as in the next > > example? > > "Thus" is fine there; certainly not worth the translation overhead to change > anyway. Good point. > > > 1.3. Notes and Warnings > > Recommend changing heading to "Admonitions." > > "Admonitions" is the technical DocBook term for these structures, but I > think it reduces clarity for people not thinking in DocBook. I suspect this > would also be an interesting problem for translation, since most languages > probably have a word meaning something close to "admonition" but probably > zero have a word for the DocBook structure. > > > Also standardize text around > > (e.g.), "<admonition_type> admonitions are..." > > See above for my thoughts on "admonitions". Moreover, I think that > > "Note admonitions are tips, shortcuts or alternative approaches" > > and > > "Warning admonitions should not be ignored" > > are considerably clunkier than what we have now and gain us nothing but > conformity for its own sake. > > However, I'm certainly open to suggestions, but they would need to be really > significant improvements on the existing text to justify the cost to > translate. Yes, can wear that. > > > "Ignoring a box labeled 'Important' will not cause data loss but may cause > > irritation and frustration." > > > > Use double quotes for "Important." > > Will fix for 4.0 Thanks. Not sure if there's much else that we would really like to get in, especially given that some are already fixed upstream.
6dfa968..007f85f devel -> devel