[publican-list] RFE for Publican Brands

[Jeffrey Fearn]

Lana Brindley wrote:
> On 10/01/2010 08:23 AM, Jeffrey Fearn wrote:
>> A real example where you couldn't write around it would carry much more
>> weight and prevent such responses.
>>
> 
> OK.
> 
> file:///usr/share/doc/publican-doc-2.1/en-US/index.html#sect-Users_Guide-Building_a_document 
> 
> 
> "Note -- Customizing output"

I think this is an example of poor use of admonitions.

Option A:

1: Starting a section with an admonition is bad form.

2: The information in the admonition should be and optional step 5 in 
the 'To build a document' procedure.

3: There is now no need for the admonition to exist.

Option B:

1: Make the note a formal para and move it after the procedure, there is 
no reason for it to be marked up for special attentions, it is just 
another command line option.


The proceeding section, 3.5. Preparing a document for translation, has 
an example of poor use of important.

1: The information in the important 'set Project-Id-Version for 
packaging' should be inserted as step 5, with the current 5 becoming 6, 
in the procedure it references.

2: The important should actually be a warning that failing to follow 
step 5 will result in invalid packages or your build failing.

3: The new warning should be moved to after the procedure.


Regardless of having no example of where this kind of layout isn't bad 
form, I still think it's a good idea not to break the output.

Having said that "lighter, brighter, darker, less/more colourific" don't 
mean anything to me, so unless someone supplies some real input, like 
actual colors or something, this won't be fixed in a hurry.

Cheers, Jeff.

-- 
Jeff Fearn <jfearn at redhat.com>
Software Engineer
Engineering Operations
Red Hat, Inc
Freedom ... courage ... Commitment ... ACCOUNTABILITY