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 <jfe...@redhat.com>
Software Engineer
Engineering Operations
Red Hat, Inc
Freedom ... courage ... Commitment ... ACCOUNTABILITY
_______________________________________________
publican-list mailing list
publican-list@redhat.com
https://www.redhat.com/mailman/listinfo/publican-list
Wiki: https://fedorahosted.org/publican
