[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 against 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 behavior. 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 bobs@sagehill.net
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]