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

Thanks to all for the helpful feedback.  Based on that, here is my new
proposal for DocBook-generated CSS.   I'm trying to balance flexibility 
too much complexity.  I've got it down to just four new params.

1.  Add a new param 'make.clean.html', which when set to 1 will cause the
HTML stylesheet to output HTML that requires CSS for default styling. The
default value of this param will initially be zero to preserve current

2.  Add a new param 'docbook.css.source', which specifies the CSS source
filename (with <style> root element) for generating the default CSS output
file.  This will be set by default to a file named 'docbook.css.xml' that is
included in the distribution.  The output filename is the same except the
'.xml' extension is removed.  For chunked output, this file is placed in the
directory specified by the 'base.dir'  param.  For non-chunked output, it is
written to the current directory.  In each HTML output file's head element,
a <link> element is added that references this generated CSS filename.  If
this param is set to blank by the user, then no default CSS output file will
be generated (and no <link>).  If set to some other filename, the stylesheet
will use that instead of the default source file in the distro (again,
stripping the .xml suffix to get the output filename).  None of this happens
if  'make.clean.html' is set to 0.

3.  Add a new param 'custom.css.source', which specifies a separate
user-created CCS source filename (with <style> root element).  This param is
empty by default.  If non-empty, then the stylesheet will generate a CSS
output file from it (again, stripping the .xml suffix to get the output
filename).  When this param is set, then the <link> element in each HTML
head element will reference this file instead of the default 'docbook.css'
file.  This feature works regardless of the value of  'make.clean.html'.
That will support users who just want to automatically add their own
existing CSS file to each build, regardless of whether they are generating
'clean' HTML or not.

 4. Add a new param 'generate.css.header', which when set to non-zero will
generate the CSS (docbook and/or custom) in the HTML head element instead of
a separate file and the <link> element in head.

I think this combination of params covers most of the scenarios that I've
heard described.  Here are a few.

a.  If you do nothing, you get the current behavior, which is the existing
HTML output and no generated CSS file or header. If you use the existing
'html.stylesheet' parameter, a <link> is still generated in each head
element, and the CSS file it references must be manually copied to your
output, as you do now.

b.  If you want clean HTML, then you just set the 'make.clean.html' param to
1.  You will get the docbook.css file included in the output, and a <link>
element referencing it in each head element.  If you also set
'html.stylesheet', then its <link> element will appear second in the head
elements (so it can override the default), but you still  have to manually
copy that custom CSS file.

c.  If you want to add a CSS customization layer that modifies only certain
styles, then set 'make.clean.html' to 1 and set 'custom.css.source' to
something like 'sagehill.css.xml'.  That file should include a line for
@import url("docbook.css"), and any overrides of the default styles in
docbook.css. If both 'docbook.css.source' and 'custom.css.source' are
nonempty, then a single <link> element referencing the custom.css file is
output. This makes it essential that the @import line is included.

d.  If you want to entirely replace the default docbook.css with a single
complete custom.css file, then set 'docbook.css.source' to blank, set
'custom.css.source' to your input filename, and omit the @import line from
your custom file.

e.  If you have an existing custom CSS file that you want to automatically
be added to the output, but don't  want to turn on 'make.clean.html', then
wrap the CSS in <style> and set 'custom.css.source' to that filename.  And
set 'html.stylesheet' to empty. Now you will get a <link> to custom.css and
the file will automatically appear in the output. No more manually copying
the CSS file.

Scenario (c)  is the one that I have the most concern about.  Requiring the
custom CSS to include @import seems awkward.  The alternative
is to put two <link> elements in head, with the docbook.css
first and custom.css second.  I believe that the CSS cascade in existing
browsers will treat the sequence the same as if the second were importing
the first.  Or the stylesheet could scan the CSS from custom.css.source and
warn the user if @import is not present.

Let me know if any of this is unclear and needs further explanation.

Bob Stayton
Sagehill Enterprises

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