Bug 1033830

Summary: Can we have a visual style for a providing tips to users?
Product: [Community] Publican Reporter: nilakshi <nilakshihandique>
Component: publicanAssignee: Jeff Fearn 🐞 <jfearn>
Status: CLOSED CURRENTRELEASE QA Contact: Don Domingo <ddomingo>
Severity: low Docs Contact:
Priority: unspecified    
Version: 3.2CC: aigao, ddomingo, jfearn, rlandman, sgordon, topic-tool-list
Target Milestone: 4.2Keywords: Reopened
Target Release: ---   
Hardware: Unspecified   
OS: Unspecified   
Whiteboard:
Fixed In Version: 4.2.0 Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of: Environment:
Last Closed: 2014-09-01 03:40:29 UTC Type: Bug
Regression: --- Mount Type: ---
Documentation: --- CRM:
Verified Versions: Category: ---
oVirt Team: --- RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: --- Target Upstream Version:
Embargoed:
Attachments:
Description Flags
Attachment for reference. none

Description nilakshi 2013-11-23 14:37:34 UTC
We can have a visual style for providing tip just like we have for Note, Warning, and Important (screenshot attached for reference).
The Tip element is important to provide information that helps users apply the techniques and the procedures that are described in the text in a better way. The element might contain information such as keyboard shortcuts,alternate ways to perform the same procedure etc.

Comment 1 nilakshi 2013-11-23 14:39:18 UTC
Created attachment 828094 [details]
Attachment for reference.

Comment 2 Stephen Gordon 2013-11-23 16:27:35 UTC
The publishing toolchain (specifically Publican) actually explicitly disallows the use of "tip" and "caution".

From http://jfearn.fedorapeople.org/en-US/Publican/3.2/html/Users_Guide/appe-Users_Guide-Disallowed_elements_and_attributes.html#sect-Users_Guide-Disallowed_elements_and_attributes-Disallowed_elements :

"DocBook XML supports five admonitions of varying severity: <tip>, <note>, <important>, <caution>, and <warning>. Taken together, these represent a very fine-grained set of distinctions. It is unlikely that these fine distinctions can be applied consistently within a document, especially when more than one person writes or maintains the document. Moreover, this level of granularity is meaningless to readers. By design, Publican disallows the <tip> and <caution> elements, these elements being the two most redundant in the set.

Use <note> instead of <tip>, and use either <important> or <warning> instead of <caution>. Some criteria by which you might select a suitable level of severity are presented in the β€˜Document Conventions’ section of the preface of books produced with Publican's default brand."

Comment 3 Jeff Fearn 🐞 2013-11-24 22:27:42 UTC
Changed to PUG component as the PUG is out of date on this. Publican does not disallow any element, it recommends against them and may not provide any style for them, but it does not prevent you from using them or stop brands from styling them.

The PUG should be updated to match this.

Comment 5 Jeff Fearn 🐞 2014-05-15 06:08:22 UTC
Going to add tip formatting to HTML5 output.

Comment 6 Jeff Fearn 🐞 2014-05-15 22:38:15 UTC
http://jfearn.fedorapeople.org/HTML5_Test/html/pref-Publican-Users_Guide-Preface.html#idm210053778208

Text for tip and caution required.

Rudi, please set a docs contact for above.

Comment 7 Don Domingo 2014-08-25 03:57:07 UTC
Verified that this works; when using <tip> and <caution> with the common-db5 branch, the resulting HTML style looks exactly as laid out in the link provided by Jeff.

(In reply to Jeff Fearn from comment #6)
> http://jfearn.fedorapeople.org/HTML5_Test/html/pref-Publican-Users_Guide-
> Preface.html#idm210053778208
> 
> Text for tip and caution required.
> 
> Rudi, please set a docs contact for above.

Comment 8 Don Domingo 2014-08-25 03:57:44 UTC
Sorry, I meant common-db5 *brand*

(In reply to Don Domingo from comment #7)
> Verified that this works; when using <tip> and <caution> with the common-db5
> branch, the resulting HTML style looks exactly as laid out in the link
> provided by Jeff.

Comment 9 Jeff Fearn 🐞 2014-09-01 03:40:29 UTC
A fix for this shipped in Publican 4.2.0.