On Tue, 9 Sep 2003, Francois Gouget wrote:
documentation/Makefile.in, documentation/default.dsl, documentation/winedoc.css
Don't hardcode the look and feel in default.css. Use a css file
instead.
For that, we should just completely remove documentation/default.dsl and use the site-wide one.
On Tue, 9 Sep 2003, Dimitrie O. Paun wrote:
On Tue, 9 Sep 2003, Francois Gouget wrote:
[...]
Don't hardcode the look and feel in default.css. Use a css file instead.
For that, we should just completely remove documentation/default.dsl and use the site-wide one.
By site-wide one I suppose you mean the one shipped with DocBook? We cannot do that because the DocBook one: 1. does not reference any css file 2. does not use the %use-id-as-filename% option which results in ugly HTML filenames
(it also lacks the systemitem and empty-sosofo hacks. I'm not sure that last point is important since I don't know what these hacks are for anyway)
On Tue, 9 Sep 2003, Francois Gouget wrote:
By site-wide one I suppose you mean the one shipped with DocBook?
yes
We cannot do that because the DocBook one:
- does not reference any css file
So why is that a problem?
- does not use the %use-id-as-filename% option which results in ugly
HTML filenames
that's Their Problem (TM).
(it also lacks the systemitem and empty-sosofo hacks. I'm not sure that last point is important since I don't know what these hacks are for anyway)
So it does seem that people that want to build the stuff themselves can use the default.dsl shipped with DocBook. If they want the docu generated by us, they can just download it.
On Tue, 9 Sep 2003, Dimitrie O. Paun wrote:
On Tue, 9 Sep 2003, Francois Gouget wrote:
By site-wide one I suppose you mean the one shipped with DocBook?
yes
We cannot do that because the DocBook one:
- does not reference any css file
So why is that a problem?
You do not want the HTML docs generated by 'make html' to look good?
- does not use the %use-id-as-filename% option which results in ugly
HTML filenames
that's Their Problem (TM).
You do not want the documentation generated by 'make html' to use sensible names? You want to tell users to do 'make html' and then open 'wine-user/x1483.html' (or maybe that's actually 'wine-devel/x1523.html') in their browser rather than 'wine-user/index.html'?
[...]
So it does seem that people that want to build the stuff themselves can use the default.dsl shipped with DocBook. If they want the docu generated by us, they can just download it.
You want to make like hard for anyone to use 'make html'?
On Tue, 9 Sep 2003, Francois Gouget wrote:
So why is that a problem?
You do not want the HTML docs generated by 'make html' to look good?
I don't care. In fact, the very purpose of using SGML in the first place is so that we shouldn't need to care. The _fundamental_ principle is separating content from presentation. We provide the content, they provide the presentation.
The SGML tools are this way for a reason. If people don't like them, they should change them. Or they should do their custom default.dsl. Most people don't care and are happy with the SGML tools -- this is what they get for all the other stuff. We will not upset those. The users that prefer the WineHQ style better, they can just download the docu from our website. But the big problem is that we screw users that care or they have a requirement to integrate stuff into _their_ website.
Using the standard tools is the better approach, rather then trying to fix them into our tree. If you think the fix deserves a bigger audience, it belongs in the DocBook tree.
So which do you want:
1. keep the old default.dsl file which hard-codes the presentation in all the output files and makes it impossible for an end-user to modify it.
2. use the new default.dsl file which puts all the presentation aspects in the css file so that the html files don't have a hard-coded look and feel.
3. remove the dsl file altogether so that we get filenames of the form p3552.html and the default look and feel.
Apparently you are supporting 3 by saying: * that 1 and 2 make it impossible for end-users to change the look and feel. I would agree for 1 but not for 2 which specifically makes it possible to change the look and feel of the documentation. * that users who don't like the default DocBook html should write their own dsl file. In other words, you are forcing users to learn how to write a dsl file to make any sort of customization of the look and feel. * the previous argument invalidates your argument that 2 makes it impossible for users to customize the look and feel. If option 2 does not provide the means they need to customize the look and feel, all they have to do is to write a custom dsl file and they will get whatever they would be getting in option 3.
But the big problem is that we screw users that care or they have a requirement to integrate stuff into _their_ website.
Obviously we are not screwing them. See above.
Using the standard tools is the better approach, rather then trying to fix them into our tree. If you think the fix deserves a bigger audience, it belongs in the DocBook tree.
We are using the standard tools or else I certainly was not aware that I had rewritten docbook2html. The docbook2html authors specifically provided options to make it possible to customize its output. Now you are saying that we should not be using these options at all. Then I suppose you are against the use of -O2 or -I when invoking gcc too? You're obviously not and that's because the default behavior of gcc does not necessarily meets our needs. Similarly, it makes sense to set a couple of options when generating the html code using docbook2html.
Also you still seem to think that the purpose of the default.dsl file is to decide the background and text color, what should be in italics or bold, etc. IT'S NOT!
The purpose of the DSSSL file is to customize whether one will get a title page, alter section numbering, modify headers and footers, etc. All color and font settings kind of things is left to CSS as is obvious when looking at the HTML generated by the docboo2html: most tags have a CSS class so that one can alter their look by setting the proper CSS attributes:
<BODY
CLASS="BOOK" <--- a CSS hook BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#840084" ALINK="#0000FF"
<DIV
CLASS="BOOK" <--- another
<A
NAME="INDEX"
</A
<DIV
CLASS="TITLEPAGE" <--- another
<H1
CLASS="TITLE" <--- yet another
<A
NAME="AEN2"
Wine Developer's Guide</A
</H1 <HR></DIV <DIV
CLASS="TOC" <--- and another ...
All these hooks are there so that people don't have to mess with the DSSSL to change the look and feel of the pages.
On Wed, 10 Sep 2003, Francois Gouget wrote:
- keep the old default.dsl file which hard-codes the presentation in
all the output files and makes it impossible for an end-user to modify it.
- use the new default.dsl file which puts all the presentation aspects
in the css file so that the html files don't have a hard-coded look and feel.
- remove the dsl file altogether so that we get filenames of the form
p3552.html and the default look and feel.
My apollogy, I must not have been clear enough. I want 4:
4. use the new default.dsl file when building the HTML docu on the WineHQ site. It should _not_ be in the Wine tree, but rather in in the WineHQ tree. I suggest the tools/ module. When a user does 'make html' in the documentation/ directory, that should just use the default.dsl file that is installed on the user's box.
This way we generate the docs our way, and they generate the docs their way.
Peace? :)
-
Dimitrie O. Paun -
Francois Gouget