OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook-apps message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: Re: [docbook-apps] improve DocBook's HTML output

I agree that the default should be a separate CSS file, not CSS in the head 

FYI, I was planning to implement this feature as follows.

1.  Create and check in a new file 'docbook-css.xml'  in the distro that 
looks like:

<?xml version="1.0"?>
<style type="text/css">
[CSS styles go here]

This checked-in file would be updated by the DocBook XSL developers as 
changes are made to the HTML stylesheet that require CSS styling.  This file 
serves as the input for generating the CSS in the output.

2.  The path to this file is a new stylesheet parameter, perhaps named 

3.  During HTML processing, this file is read into a variable by the 
stylesheet using the document() function.  That's why it needs a root 
element <style> so that it is well-formed XML and can be read by document().

4.  If the output is to be a separate CSS file, then the DocBook 
'write.text.chunk' utility template is called to write the content of 
<style> to the CSS filename specified by the 'html.stylesheet' parameter 
(without the <style> wrapper), in the directory specified by the 'base.dir' 
parameter if chunking is used.  If instead the CSS is for the HTML head, 
then the whole <style> element is copied to <head> element of each output 

5.  You can customize the CSS input file beyond the minimal CSS styles that 
ship with distro.  If so, then put your file with your customization layer 
and change the 'docbook.css.file' parameter to point to your customized 
version.  You just need to keep the <style> root element wrapper.

The nice thing about this design is that you would no longer have to copy 
your CSS file to the output directory as a separate step.  It would be 
included each time you build the HTML output.

Bob Stayton
Sagehill Enterprises

----- Original Message ----- 
From: <jdickey@seven-sigma.com>
To: "Chris Maloney" <voldrani@gmail.com>
Cc: "DocBook Apps" <docbook-apps@lists.oasis-open.org>
Sent: Monday, November 30, 2009 5:59 AM
Subject: Re: [docbook-apps] improve DocBook's HTML output

Hi, guys,

(Jumping in a bit - as somebody who uses DocBook regularly but has a day
job doing bare-metal HTML/CSS coding)

As I understand the discussion thus far, what's wanted is an easy way for
new folks to generate/deploy DocBook-generated HTML that, as they progress
up the learning curve, they can customize/reuse the CSS for as well. If
this is the case - that the feature is to appeal to/be usable by both new
and experienced users, then I'd like to make one suggestion:

Please, please, *please* don't use inline-generated CSS. Have sensible,
overrideable defaults for where the CSS file(s) go, but *do not* put CSS
inline in the document header. Doing so will:
* cause grief for folks whose shop HTML standards call for unobtrusive,
progressive enhancement of HTML;
* make it more difficult to reuse customizations in the CSS used for a
* increase bandwidth required to serve the document, since the CSS won't be
cacheable across multiple HTML pages;
* etc., etc., etc.

Or if you absolutely *must* support the 'generate.header.css' configuration
as described, then make the default value '0'. But then, turning it on
would require a certain, very minimal, knowledge of How Things Work - and,
since the feature was proposed in the context of "how do we make it easier
for the new folks?", we've just given ourselves even more rope with which
to shoot ourselves in the foot. Yes?

My two cents, adjusted for inflation,

Jeff Dickey

On Sun, 29 Nov 2009 12:15:08 -0500, Chris Maloney <voldrani@gmail.com>
> Well, if that's the goal, then I'd like to add another option for
> consideration: maybe called 'generate.header.css', or something, that
> cause the generated css to appear in the HTML header rather than in a
> separate file.
> 2009/11/29 Jirka Kosek <jirka@kosek.cz>
>> Chris Maloney wrote:
>> >> 2.  A new param named 'generate.css', which when set to 1
>> >
>> > Why would this be necessary?  Presumably one, or possibly a set of
>> > static
>> > CSS files could be supplied that provide all the basic styling based
>> > classes used in the generated output.  Or, are you suggesting that the
>> XSL
>> > generate a per-output CSS with just the subset of the "master CSS"
>> styles?
>> Generating CSS file on the fly simplifies deployment -- user doesn't
>> have to copy CSS into target directory. This is easy, but for newcomers
>> it is much more handy if there are no additional steps required to
>> generate working output.
>>                                Jirka
>> --
>> ------------------------------------------------------------------
>>   Jirka Kosek      e-mail: jirka@kosek.cz      http://xmlguru.cz
>> ------------------------------------------------------------------
>>       Professional XML consulting and training services
>>  DocBook customization, custom XSLT/XSL-FO document processing
>> ------------------------------------------------------------------
>>  OASIS DocBook TC member, W3C Invited Expert, ISO JTC1/SC34 member
>> ------------------------------------------------------------------

To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: docbook-apps-help@lists.oasis-open.org

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]