Re: New draft of manual style
André Malo wrote: http://test.perlig.de/apdoc/manual I am personally +1 on committing this or something very close to it. There are many things about it that I don't find optimal, but they are mostly issues of personal taste. The ones that I find most important can be fixed after we commit. The only problem is that I'm really quite short on time right now. If there are any other committers who can do a final review of this and then commit it, please speak up. Otherwise, I will do my very best to get to it soon. Joshua. - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: New draft of manual style
Joshua Slive wrote: André Malo wrote: http://test.perlig.de/apdoc/manual I am personally +1 on committing this or something very close to it. There are many things about it that I don't find optimal, but they are mostly issues of personal taste. The ones that I find most important can be fixed after we commit. As I said before, great work! I haven't had the time to go really deep but the visual aspects are very usable (apart from some personal dislikes). +1 on committing this in the next days; we will have enough time to fix the details when we have a solid basis to work on. The only problem is that I'm really quite short on time right now. If there are any other committers who can do a final review of this and then commit it, please speak up. Otherwise, I will do my very best to get to it soon. I will try to get deeper into the code tonite, but I'm not sure if I'll have enough time too. Perhaps I will get to the whole stuff tomorrow evening. I'll do my best. Any help is appreciated... Erik - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: New draft of manual style
* Michael Schröpl wrote: +1 on this, although I personally never define link colors in HTML pages, because I trust the user to be familiar with the colors configured (maybe even by installation default) in _his_ browser. hmm, if you define any color (background or text) you SHOULD (in the meaning of RFC 2119) define any other color like link colors etc. Otherwise it will cause undefined results. What I would suggest to do is make hovering _only_ change the background color and then only by some minor change, like white to light grey. Hey, I like this idea very much. IMHO it's more clear and simpler than underlining or foreground hovering. Just built it in :) So I would prefer even the code and module links to be underlined, for consistency's sake. generally +1 sometimes links accumulate. General underlining may lead to less readabality then. Nevertheless: +1 from me for consistency. nd -- print Just Another Perl Hacker; # André Malo, http://www.perlig.de/ # - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: New draft of manual style
* Michael Schröpl wrote: http://test.perlig.de/apdoc/manual/ I would like the div class=directive-section to have some other background color than white, so that it would look more like a bar, separating the directive sections. Light grey would do nicely, and help the eye scanning the document. yes. I readded the bar, a bit brighter than normal sections headings, thus there's a visible difference between them. And I miss a lot of hovering effects. Many links now don't hover at all. But then, most of them are now underlined, although still not all. You only tried the default CSS? :) however. I reverted all my previous trials. bg-color-hovering is applied generally now. nd -- Treat your password like your toothbrush. Don't let anybody else use it, and get a new one every six months. -- Clifford Stoll (found in ssl_engine_pphrase.c) - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: New draft of manual style
* Michael Schröpl wrote: How do we solve this problem? Well, one possibility is to eliminate the use of code entirely and use CSS to get that effect. But I would prefer not to do that because then non-css browsers would see the example in a proportional font. what is the general strategy? example in proportional font is far better than unusable. Sure, non-CSS browsers would also lose the background color if not being set in HTML code, but we are talking about Netscape 3 here, or about Netscape 4 with CSS explicitly switched off. NN4 gets nothing of the current CSS... If I have much time, perhaps I will setup a JSSS for NN4. Maybe ;-) So +1 from me for omitting code here, rather than generating different code for different situations, No. code has also a semantic meaning. Examples are in nearly cases paragraphs containing code. I set up a loop for example. To make it work, a list of blockelements has to be defined in the head of common.xsl (just did it in http://test.perlig.de/apdoc/manual/style/xsl/common.xsl). If it's maintainable enough I'd propose this as a solution. nd -- s;.*;aoaaaoaaoaaaom:a:alataa:aaoat:a:a:a maoaa:a:laoata:a:oia:a:o:a:m:a:o:alaoooat:aaool:aaoaa matooololaaatoto:aaa:o:a:o:m;;s:\s:\::g;y;mailto:; \40\51/\134\137|ndparker [EMAIL PROTECTED];;print; - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: New draft of manual style
* Joshua Slive wrote: First a general comment (not to you specifically): Careful on the use of -1. In Apache terms, this doesn't mean I disagree or I vote against. Rather, it means I VETO this change. [...] oh, thanks for the enlightenment. Now on to the content: Wouldn't you agree that anyone who finds text unreadable with font-size:small (or small or font size=-1) would have a very hard time browsing the web. The majority of major websites use that setting. hmm. I know much sites, that use fix font sizes. If I really cannot read such pages, I'm turning off CSS (NN4 gives the ability, I'm really missing that in mozilla...). But turning off CSS is not the desired way to handle the docs in general, I think :) Even google, that bastion of Usability enhanced web design, uses font size=-1 for most of its text. The same thing goes for side menus (or in google's case, side advertisements). :-(, font size is BAD (broken as designed). because there's no way to :turn off the effect in most browsers. In real strong cases I take Lynx :or simply go away. http://test.perlig.de/apdoc/manual/ I think I might take a few more days off of the style issue before I come back to it. If any of the other committers wants to follow up, please feel free. Otherwise, I'll look at it in a few days. ok, time goes by :) I made a lot of detail changes and some more major ones since my last post. But take a look at it yourself :) During my work at the examples a realized another serious cache bug in ant. While creating the directive index it sometimes (!) forgets some modules. This behaviour is triggered by a little bit more complex xslt transformation, that applies on files which will be transformed before directives.xml. i.e. I applied some xsl to a module file (e.g. core.xml) and ant forgot all core directives... (?!?) In result of this I modified the build.xml to handle directive.xml.* separately. (Took me several days to find out that it was a problem of ant :-( ) In order to find out the problem I rebuilt the complete xsl and splitted the common.xsl into several parts, so the common.xsl only contains common template scraps. (so done in http://test.perlig.de/apdoc/manual/style/) I think it becomes more clear this way. nd -- die (eval q-qq:Just Another Perl Hacker :-) # André Malo, http://www.perlig.de/ # - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: New draft of manual style
* Joshua Slive wrote:
I'm not sure whos argument it supports, but I thought I would point
out that, coincidentally, Jakob Neilson's latest usability Alertbox
is on font-size:
http://www.useit.com/alertbox/20020819.html
hehe, I agree: I'm not sure, too ;-)
however, I don't recommend it, but I could live with the 90% style.
nd
--
$_=q?tvc!uif)%*|#Bopuifs!A`#~tvc!Xibu)%*|qsjou#Kvtu!A`#~tvc!KBQI!)*|~
tvc!ifmm)%*|#Qfsm!A`#~tvc!jt)%*|(Ibdlfs(~ # What the hell is JAPH? ;
@_=split/\s\s+#/;$_=(join''=map{chr(ord( # André Malo ;
$_)-1)}split//=$_[0]).$_[1];s s.*s$_see; # http://www.perlig.de/ ;
-
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
Re: New draft of manual style
* Joshua Slive wrote: I suppose we could use some tricky XSLT to insert code only if the contents of example are bare text. As said in a posting before, I set up a loop, that does do exactly this. Only requirement: a list of blockelements in the head of common.xsl. http://test.perlig.de/apdoc/manual/style/xsl/common.xsl (I probably should add some explaining comments to the template match=example, or?) nd -- Gefunden auf einer Webdesigner-Seite: Programmierung in HTML, XML, WML, CGI, FLASH # André Malo # http://www.perlig.de/ # - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Antwort: Re: New draft of manual style
Hi Andy, Now on to the content: Wouldn't you agree that anyone who finds text unreadable with font-size:small (or small or font size=-1) would have a very hard time browsing the web. The majority of major websites use that setting. hmm. I know much sites, that use fix font sizes. If I really cannot read such pages, I'm turning off CSS (NN4 gives the ability, I'm really missing that in mozilla...). Preferences - Appearance - Fonts - Minimum Font Size (overrules everything). You set it once and never bother about small fonts again. Regards, Michael - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: New draft of manual style
Joshua Slive [EMAIL PROTECTED] writes: 1. There was one main reason I stopped developing the wacky style: complexity. If felt it was over-complex both visually and particularly the css and html code. The css code had the advantage that it was externally developed and maintained at style.tigris.org, but I still didn't like using something that seemed difficult to maintain. Oh, I didn't know that. My comment was solely on look and feel, so I completely agree with your suggestion #2 below. 2. Let's try to determine exactly what about the original style people like better. Perhaps we can combine the two in a way that will work. Some suggestions: b) Side-menu listing important stuff seperate from text rather than having the menu integrated from the text. I like this, but I'm not sure how much it is about the cool factor. It also leads to the obvious disadvantage of having to put the whole darn page in a table, which is annoying but very common for modern sites. As Michael pointed out, it can be done with only css. If implementing it doesn't end up in complex html and css, I'd like to see it done. Module docs looks much better if directives is listed on side-menu. c) Smaller font. As I mentioned in the original discussion, smaller fonts tend to look more modern and professional, since almost all major websites now use a less-than-default font size. Of course, it is silly to contradict what the user set as their default font, but since almost all sites do it, small can almost be considered the default. I don't have strong opinion about this. Either one is fine with me. -- Yoshiki Hayashi - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: New draft of manual style
* Joshua Slive wrote: with the help of google I took a crash course in XSLT and tried to complete your work. Fun, isn't it? ;-) oh, yes ;-) I spent several hours to find out that the things I wanted, don't work with xslt... however, I've learned much by doing that :) * reverted the link colors to the proposed :) the green and the red, weren't a good choice, imho. there was too less contrast between them. (e.g. I have problems with red green, like about 20% of men) But now you've chosen red for the module entries. I really like to restrict the use of red to things that we want to be important (like security warnings). It is too jarring to see in ordinary text. hmm, my red and green were much more different in contrast, but ok. I set the module color now to blue (like in the current version) * but, you're right, I removed the underlines of code and module links for better reading My problem is that there is too many different link colors and actions. I prefer that hover trigger only a single, consistent change. In your versions, sometimes hovering adds an underline, and sometimes it removes it. Sometimes it triggers a color change, and sometimes it doesn't. In addition, colors tend to get less forceful when you hover. This seems backwards to me. Hovering should make the link stronger, because it gets you closer to the action. modified the link styles as follows: * a:link color = a:hover = a:active * a:hover and a:active are always underlined * a:visited is less forceful everywhere this results in: - no change, if the link is underlined and not visited - color change, if the link is underlined and not visited - underline change if the link is not underlined and not visited - color underline change if the link is not underlined and visited better? See my previous email question re the semantics of th. the table /head/ is defined by thead, table /header cell/ by th. They may appear everywhere a table header cell is needed. * a lot of small issues, thus the xsl produces proper HTML (e.g. exampletable..., used in howto/htaccess.xml) I don't like the way you handled example in the xslt. Your code essentially says if it is pre or table, then leave it, otherwise wrap it in p class=example. nope. I always put the example into div class=example. Your previous version didn't validate, because you set up: div class=examplecode [ example content ] /code/div if example content is a pre or a table, you get a problem. code is an inline element and cannot contain blocklevel elements like pre or table. So my code produces three variants: div class=example pcode [ simple text ] /code/p /div !-- or -- div class=example pre [ preformatted text ] /pre /div !-- or -- div class=example table [ table ] table /div This is meant as: an example that contains a paragraph containing code or an example that contains preformatted text or an example that contains a table. Maybe we could say: an example that contains preformatted text containing code. IMHO, that behavior is correct. (If that doesn't make sense, think of example as an element like blockquote or li. These elements can take pretty much any contents in xhtml. They may contain complete paragraphs in p, or they may contain just some simple bare text It would not make any sense (semantically or otherwise) to wrap the entire contents of a blockquote in p.) ;-) Blockquote is not a good example. It is intended to contain block level elements. http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd In transitional DTD it may contain %flow;, but I'd never recommend the transitional DTD - especially in our case there's no need for that. Probably we also need some modifications to the DTDs: Let's address that as a seperate issue. If you want to look at changing that right now, please start a new thread. ok :) later nd -- s s^saoaaaoaaoaaaom a alataa aaoat a a a maoaa a laoata a oia a o a m a o alaoooat aaool aaoaa matooololaaatoto aaa o a o ms;s;\s;s;g;y;s;:;s;y#mailto: # \51/\134\137| http://www.perlig.de #;print;# [EMAIL PROTECTED] - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: New draft of manual style
* Joshua Slive wrote:
1. There was one main reason I stopped developing the wacky style:
complexity. If felt it was over-complex both visually and
particularly the css and html code. The css code had the advantage
that it was externally developed and maintained at style.tigris.org,
but I still didn't like using something that seemed difficult to
maintain.
probably nice to hear :)
I revised the css completey and hope that the ruleset is now more
simple.
2. Let's try to determine exactly what about the original style people
like better. Perhaps we can combine the two in a way that will work.
Some suggestions:
a) Black-on-white. I tend to agree that this is preferred.
hmm, really: black on white is too much contrast. After a while it hurts
my eyes. But I can imagine, that for example japanese characters
(symbols? could someone lead me to the right term, please? ;-) are
better to read then, because they are much more complex.
Of course, with xslt we are able to include a different style sheet for
such case. But that's probably not a good idea.
b) Side-menu listing important stuff seperate from text rather than
having the menu integrated from the text. I like this, but I'm not
sure how much it is about the cool factor. It also leads to the
obvious disadvantage of having to put the whole darn page in a table,
which is annoying but very common for modern sites.
I don't like the sidebar, because it wastes so much space. On the other
hand on large pages, like mod/core.html it's useful and makes the page
more clear.
c) Smaller font. As I mentioned in the original discussion, smaller
fonts tend to look more modern and professional, since almost all
major websites now use a less-than-default font size. Of course, it
is silly to contradict what the user set as their default font, but
since almost all sites do it, small can almost be considered the
default.
-1 for font-size: small.
If we want a small(er) font, I'd propose using px instead, because if
someone set up his browser to use a smaller font by default, a
font-size:small will lead to a non-readable document.
d) Other things ??? (I think the header and footer from the new
version are nicer, and I also prefer how the section titles are now
handled...)
I've added a Modules breadcrumb on modulesynopsis pages.
And, more technical: added xml:lang and lang attribute to html.
Also sourced out the menu items to the $lang.xml files.
This results in the following changes (in $lang.xml)
messages lang=en
!-- attribute containing the language token. --
!-- breadcrumb links --
message name=apacheApache/message
message name=http-serverHTTP Server/message
message name=documentationDocumentation/message
message name=versionVersion 2.0/message
!-- super menu --
message name=modulesModules/message
message name=faqFAQ/message
message name=glossaryGlossary/message
message name=sitemapSitemap/message
!-- footer line --
message name=maintainedbyMaintained by the /message
I'm a bit unsure about the term Apache HTTP Server Documentation
Project in the footer line. It's yet hardcoded in the common.xsl,
because I think, it's the proper noun of the project and should not be
translated. (?)
you'll find my current work at:
http://test.perlig.de/apdoc/manual/
I set up several alternate style sheets (loose style, sidebar, color
schemes), which you may try out using a browser that can handle them
(e.g. mozilla).
The whole stuff is rolled in:
http://test.perlig.de/apdoc/manual.zip
(1.3 MB, windows \n) and
http://test.perlig.de/apdoc/manual.tar.gz
(0.98 MB, unix \n)
nd
--
my @japh = (sub{q~Just~},sub{q~Another~},sub{q~Perl~},sub{q~Hacker~});
my $japh = q[sub japh { }]; print join #
[ $japh =~ /{(.)}/] - [0] = map $_ - () #André Malo #
= @japh;# http://www.perlig.de/ #
-
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
Antwort: Re: New draft of manual style
Hi Joshua, I'm not sure whos argument it supports, but I thought I would point out that, coincidentally, Jakob Neilson's latest usability Alertbox is on font-size: http://www.useit.com/alertbox/20020819.html - At least let users override whatever default font size you have, i. e. don't use px as M$IE cannot override it (Opera and Mozilla can). - Select a default so that as few as possible users need to know how to override it (i. e., 10+ pt). Capable users will override it anyway, so care about those who know less about their browser configuration. - Kess' suggested alternate style sheet is explicitly approved by Nielsen. :-) - Nielsen votes for maximum color contrast and doesn't like grey ... just as his own pages look like. ;-( Regards, Michael - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: New draft of manual style
Finally caught up on this list after coming back from vacation... Joshua Slive [EMAIL PROTECTED] writes: http://cvs.apache.org/~slive/manual/ Contains a new draft of the proposed new manual style. This one is fully generated using xslt, so all the xml files should be converted. Sorry to say this now but I prefer previous wacky one. That one had more information compactly layed out in first screen with navigation bar on left side. This is probably just a matter of taste but I don't like bluish characters on white background. To me, black on white is easier to read. -- Yoshiki Hayashi - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: New draft of manual style
On 27 Aug 2002, Yoshiki Hayashi wrote: http://cvs.apache.org/~slive/manual/ Contains a new draft of the proposed new manual style. This one is fully generated using xslt, so all the xml files should be converted. Sorry to say this now but I prefer previous wacky one. FWIW from the peanut gallery, I kinda did too. :-( - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Antwort: Re: New draft of manual style
Hi Joshua and Andy, But now you've chosen red for the module entries. I really like to restrict the use of red to things that we want to be important (like security warnings). +1 on this, although I personally never define link colors in HTML pages, because I trust the user to be familiar with the colors configured (maybe even by installation default) in _his_ browser. And I myself override link colors with my browser settings, because I am very used to my personal colors that visualize unvisited and visited links (which are red and blue, if anyone cares - the Netscape installation defaults were too similar for my weak eyes). * but, you're right, I removed the underlines of code and module links for better reading My problem is that there is too many different link colors and actions. I prefer that hover trigger only a single, consistent change. In your versions, sometimes hovering adds an underline, and sometimes it removes it. Sometimes it triggers a color change, and sometimes it doesn't. In addition, colors tend to get less forceful when you hover. This seems backwards to me. Hovering should make the link stronger, because it gets you closer to the action. Basically, I support all of that. What I would suggest to do is make hovering _only_ change the background color and then only by some minor change, like white to light grey. The message for the user should be this is some active element, if you weren't aware of this before - it should not be a color signal of any kind. So maybe the solution that would look best in my eyes would require to define colors for a depending on each and every context tag, which might well boost the CSS definition a lot more. So I would suggest to use some neutral greyish background color for all hover effects, as to make the user understand that they are all the same, semantically. On the other hand, I would consistently display underlines for every link even in non-hover mode. I like to know where the sensitive areas are, even before I have to play the 'guessing game' to locate them with my mouse. So I would prefer even the code and module links to be underlined, for consistency's sake. Make it easy for the reader to learn the concept of highlighting, or else he/she will not be able to understand and use and profit from it: Underlined is a link, hovering is a link, all else is semantic concepts of the Apache manual. (Last week I just got bashed for my own method of highlighing way too much, and it was very justified to bash me there. ;-) The color issue I can live with, but the underlining must be consistent. If underline means link, then a:hover should ALWAYS be underlined, regardless of the original state. I would like links to be always underlined, no matter whether they are hovering or not, and make hover only change the background color, not the font color. Beyond that, I like nearly every selection of colors as I will easily get used to it when I frequently read the Apache manual. The correct wrapping of this type of content in xhtml is div, not p. +1 Thanks for all your hard work on this. +2 :-) Regards, Michael - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Antwort: Re: New draft of manual style
Hi Joshua, a) Black-on-white. I tend to agree that this is preferred. at least a minimum of contrast is helpful. I personally would be quite happy with dark blue on white, or with black on light grey. But black and white will likely be most easy to accept for all users. There is no need to be different without a purpose. b) Side-menu listing important stuff seperate from text rather than having the menu integrated from the text. I like this, but I'm not sure how much it is about the cool factor. It also leads to the obvious disadvantage of having to put the whole darn page in a table, which is annoying but very common for modern sites. I strongly encourage you to visit http://www.schroepl.net/projekte/mod_gzip/browser.htm with a _modern_ browser (i. e. Mozilla or Opera 6) and scroll down the page. Even with M$IE and Netscape 4 it will look like it were a table. But it is no table ... and no frames either, although it will feel like frames in Mozilla. It is just CSS, and even good old Netscape 4 under- stands enough of it to support this effect well enough. The CSS code is inside the file (I use SSI for this), and no, it was _not_ me who created it, but it is not really difficult to understand once you know what you want to get. This is what I would consider to be cool. (Thus I asked for it, and some CSS freaks explained me how to do it. ;-) c) Smaller font. As I mentioned in the original discussion, smaller fonts tend to look more modern and professional, since almost all major websites now use a less-than-default font size. Of course, it is silly to contradict what the user set as their default font, but since almost all sites do it, small can almost be considered the default. Just because of this, competent users will tend to use Mozilla or Opera, which both allow you to override font sizes by zooming with a single keystroke. Only M$IE cannot zoom, and only if px font sizes are being used. If you use relative sizes (anything but px), even M$IE will allow five zoom levels from a menu selection. So choose a font as you like, I will do the same. ;-) Regards, Michael - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Antwort: Re: New draft of manual style
Hi Joshua, - I agree with Patrik to use th for table header cells. Question: th stands for Table Header. Can Row titles really be considered headers (they aren't at the head of the table)? This is purely a symantic issue. If I had to create some header of a whole table, I would use caption for this purpose. There are situations where I use th for other things but column headers (maybe row headers ;-), but I am aware of that to be trickery (like code volume saving if all you need is two types of td and you don't want to have hundreds of td class=... - I am quite used to have tables with a thousand cells and more ...), not good style. So I am +1 on using th for column headers. Regards, Michael - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re[2]: New draft of manual style
It's a bit different from André's suggestion and sometimes ... unbalanced. Can you be more specific. I'm not sure what you mean. sorry, for my late answer. Now after a closer look, I have to excuse. The unbalanced feeling came from the german pages. They still have the old header image, which looks strange with the new layout. But I want to suggest some other small points: - The generated documents schould have a doctype. I would prefer XHTML. And if no one else does I'm willing to do the neccessary changes. - Some line break in the generated output would make the code much easier to read. This is only interesting for us during generation development. - I agree with Patrik to use th for table header cells. - The table columns (e.g. in http://cvs.apache.org/~slive/manual/install.html under overview for the impatient, or at the module pages) should have a little bit more horizontal distance. I miss the additional styles, You mean the alternate style-sheets? Those can certainly be put back, but I'm not sure I understand the point of them. Ordinary users will never find them, I'm sure. This is a doom loop. If nobody sets such links, no one will use them. If no one use them, nobody sets them. I think, we should set them, because it is just a small sentence. And personally: I will use them. I do not like the fixed width of nds stylesheet. The alternate styles were created based on an discussion between him an me. They are a possibility to support views for every liking. the harmonized link colors All the link colors look the same to me, except for directives and modules which are deliberately different. I changed everything to turn red on hover, and I removed the underlining on modules and directives, because I think it makes paragraphs with many references difficult to read. I don't like the big red hover color. It is to eye-catching for me. I often move the mouse over the document, while reading. The red color distracts me. The missing difference between module link colors and directive link colors is a pity. But other links shouldn't be red, whil using the red hoover color. I would prefer the colors suggested from nd, bu I can live with yours too, espacially, if we use alternate styles ;-) Kess - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: New draft of manual style
[ml manager doesn't want a big mail, so look at the next mail, too...]
* Joshua Slive wrote:
http://cvs.apache.org/~slive/manual/
Contains a new draft of the proposed new manual style. This one is
fully generated using xslt, so all the xml files should be converted.
[...]
I'm a little uncomfortable with the complexity of the css, but I'll live
with it as long as the docs still work fine with all css turned off.
ok. at first: I merged the css files and excluded NN4 completely.
(manual-nonn.css). It's not really shorter but probably a little bit
clearer.
here's the long rest ;-):
with the help of google I took a crash course in XSLT and tried to
complete your work.
I modified the common.xsl and the manual.en.xsl to work with all current
(en-) xml documents correctly and produce valid xhtml (strict).
As a result of this I patched several things in the xmls which were not
correct (see xml-current.en.patch).
CSS/HTML issues, modified by me:
* reverted the link colors to the proposed :)
the green and the red, weren't a good choice, imho.
there was too less contrast between them.
(e.g. I have problems with red green, like about 20% of men)
* but, you're right, I removed the underlines of code and module links
for better reading
* (re?)added proposed semantics (th instead of td, ul in module
list etc.)
* renamed #header to #page-header, because #header clashes with the
Header directive... ;-)
* a lot of small issues, thus the xsl produces proper HTML
(e.g. exampletable..., used in howto/htaccess.xml)
* added doctype and xhtml namespace to xsl:output (manual.en.xsl)
Probably we also need some modifications to the DTDs:
- a var element
- a dfn element
- a blockquote element (?) (mod_rewrite.xml)
- proposal: a figure element, which works as below:
figuretitle.../title
img src= width= height= alt= /
/figure
(mod_rewrite.xml uses figures, for example)
- I believe I forgot something ;-)
The changes are a suggestion, if you don't like them, please speak
now...
nd
--
die (eval q-qq:Just Another Perl Hacker
:-)
# André Malo, http://www.perlig.de/ #
/* == */
/* manual.css*/
/* == */
/* general*/
/* == */
body {
background-color: #fff;
color: #036;
padding: 0 1em 0 0;
max-width: 55em; /* ??? */
margin: 0;
}
p, td, th, li, ul {
line-height: 1.3em;
}
div.example p {
line-height: 1em;
}
/* normal links */
a:link {
color: #0073c7;
background-color: inherit;
}
a:visited, a:active, a:hover {
color: #54acc4;
background-color: inherit;
}
a:link,
a:visited {
text-decoration: underline;
}
a:active, a:hover {
text-decoration: none;
}
/* module links */
code.module, code.module a:link {
color: #bc0f00;
background-color: inherit;
}
code.module a:link,
code.module a:visited,
code.directive a:link,
code.directive a:visited {
text-decoration: none;
}
code.module a:hover,
code.module a:active,
code.directive a:hover,
code.directive a:active {
text-decoration: underline;
}
code.module a:visited,
code.module a:active,
code.module a:hover {
color: #a06b66;
background-color: inherit;
}
/* directive [links] */
code.directive,
code.directive a:link {
color: #35a500;
background-color: inherit;
}
code.directive a:visited,
code.directive a:active,
code.directive a:hover {
color: #99af76;
background-color: inherit;
}
div.example {
background-color: #e5ecf3;
color: #000;
padding: 0.5em;
margin: 1em 2em 1em 1em;
}
div.note div.example {
border: 1px solid #000;
background-color: inherit;
color: #000;
}
div.example p,
div.note p,
div.example pre,
div.example table {
padding: 0;
margin: 0;
}
.section p {
margin: 0 0 1em 0;
padding: 0;
}
div.note, div.warning {
background-color: #eee;
color: #036;
padding: 0.5em;
margin: 1em 2em 1em 1em;
}
div.warning h3, div.warning p {
background-color: #eee;
color: #036;
padding: 0 !important;
}
div.warning p {
margin: 0 !important;
}
div.warning h3 {
text-align: center;
margin: 0 0 0.5em 0 !important;
}
table div.example, table div.note {
margin-right: 1em;
}
td, th {
empty-cells: show;
}
p.indent {
margin-left: 2em;
margin-top: 1em;
}
blockquote p {
font-style: italic;
margin: 0;
}
blockquote p.cite {
font-style: normal;
margin-top: 0;
margin-left: 2em;
}
blockquote p.cite cite {
font-style: normal;
}
p.figure {
margin-left: 2em;
font-style: italic;
}
p.figure img {
border: 1px solid #aaa;
}
p.figure dfn {
font-weight: bold;
}
/* headings */
/* == */
h1 {
padding: 0.2em;
}
h1, .directive-section h2 {
border: 1px solid #405871;
}
h1, .directive-section h2, .directive-section h2 a,
.directive-section h2 a:hover, .directive-section h2 a:active {
text-decoration: none;
Re: New draft of manual style
Astrid Keßler wrote: - Some line break in the generated output would make the code much easier to read. This is only interesting for us during generation development. This is because indent is turned off in the xslt. With indent on, some very funny things happen with spacing which can have bad effects on the resulting display. I sugest a quick run through htmltidy (with the non-indent features turned off) if you want to actually read the stuff. - I agree with Patrik to use th for table header cells. Question: th stands for Table Header. Can Row titles really be considered headers (they aren't at the head of the table)? This is purely a symantic issue. - The table columns (e.g. in http://cvs.apache.org/~slive/manual/install.html under overview for the impatient, or at the module pages) should have a little bit more horizontal distance. Sure. I don't mind using CSS to increase the default cellpadding a little. I'd also like to slightly increase the vertical space before dt entires, because we use that quite a bit to seperate sub-headings. This is a doom loop. If nobody sets such links, no one will use them. If no one use them, nobody sets them. I think, we should set them, because it is just a small sentence. And personally: I will use them. I do not like the fixed width of nds stylesheet. The alternate styles were created based on an discussion between him an me. They are a possibility to support views for every liking. OK. But lets get a primary version done first, and then we can play as much as we want with alternate stylesheets. I don't like the big red hover color. It is to eye-catching for me. I often move the mouse over the document, while reading. The red color distracts me. The missing difference between module link colors and directive link colors is a pity. But other links shouldn't be red, whil using the red hoover color. I would prefer the colors suggested from nd, bu I can live with yours too, espacially, if we use alternate styles ;-) I believe there needs to be a single characteristic that says this is a clickable link for mouse-hovers. The point of red is to catch the eye so people know that they can get further info. Andre's latest version uses underline for the hover. Personally, I find that this breaks my concentration more than the color change, but I can live with it if it is consistent. Thanks again for the feedback. Joshua. - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: New draft of manual style
André Malo wrote: with the help of google I took a crash course in XSLT and tried to complete your work. Fun, isn't it? ;-) * reverted the link colors to the proposed :) the green and the red, weren't a good choice, imho. there was too less contrast between them. (e.g. I have problems with red green, like about 20% of men) But now you've chosen red for the module entries. I really like to restrict the use of red to things that we want to be important (like security warnings). It is too jarring to see in ordinary text. I stuck with green because module and directive are highly related concepts. If we can find a color that integrates well, it is fine to make module a different color. But I don't like red. * but, you're right, I removed the underlines of code and module links for better reading My problem is that there is too many different link colors and actions. I prefer that hover trigger only a single, consistent change. In your versions, sometimes hovering adds an underline, and sometimes it removes it. Sometimes it triggers a color change, and sometimes it doesn't. In addition, colors tend to get less forceful when you hover. This seems backwards to me. Hovering should make the link stronger, because it gets you closer to the action. The color issue I can live with, but the underlining must be consistent. If underline means link, then a:hover should ALWAYS be underlined, regardless of the original state. * (re?)added proposed semantics (th instead of td, ul in module list etc.) See my previous email question re the semantics of th. * a lot of small issues, thus the xsl produces proper HTML (e.g. exampletable..., used in howto/htaccess.xml) I don't like the way you handled example in the xslt. Your code essentially says if it is pre or table, then leave it, otherwise wrap it in p class=example. But example is a block level element that can take block, inline, or CDATA contents. In the parlance of the XHTML dtd, example contains Flow contents. That is, it is perfectly acceptable to have a p in example, or it is perfectly acceptable to have bare text. The correct wrapping of this type of content in xhtml is div, not p. (If that doesn't make sense, think of example as an element like blockquote or li. These elements can take pretty much any contents in xhtml. They may contain complete paragraphs in p, or they may contain just some simple bare text It would not make any sense (semantically or otherwise) to wrap the entire contents of a blockquote in p.) * added doctype and xhtml namespace to xsl:output (manual.en.xsl) This is good. Probably we also need some modifications to the DTDs: Let's address that as a seperate issue. If you want to look at changing that right now, please start a new thread. Thanks for all your hard work on this. I'd also like to hear more from people about the overall look and feel. Joshua. - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: New draft of manual style
This is because indent is turned off in the xslt. With indent on, some very funny things happen with spacing which can have bad effects on the resulting display. I sugest a quick run through htmltidy (with the non-indent features turned off) if you want to actually read the stuff. Ugh, you are right. Nice code isn't worth such problems. Question: th stands for Table Header. Can Row titles really be considered headers (they aren't at the head of the table)? This is purely a symantic issue. I think so. The HTML 4 specification does not say, they could not. And the table row element is defined as !ELEMENT TR - O (TH|TD)+ So one row may have both TH and TD cells. TH is described to be a cell that contains header information. I ever thought of header information as a title, not as a position. For example, cross tables uses two headers for each cell: top and left. There is an example at http://www.w3.org/TR/html401/struct/tables.html#h-11.4.2 showing such a cross table with table header cells on top as well as at left site together with data cells in the same line. Thanks again for the feedback. Of cource :-) Kess - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
New draft of manual style
http://cvs.apache.org/~slive/manual/ Contains a new draft of the proposed new manual style. This one is fully generated using xslt, so all the xml files should be converted. I made a bunch of changes from Andre's version; some of the them were necessary to work with the xslt (ie replacing p class=note with div class=note) and others I made because I think they work better. There are still a ton of little things wrong, but I think it is getting close to the stage where it will be ready to commit. Therefore, I think we have reached the speak now or forever hold your peace stage. If you don't like the direction this is going, please speak up! I'm a little uncomfortable with the complexity of the css, but I'll live with it as long as the docs still work fine with all css turned off. Joshua. - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: New draft of manual style
On Saturday 24 August 2002 05.15, Joshua Slive wrote: As for the new look, I'm a big -1 to it! The wacky design that Joshua did was so much better. It looked much more modern. This new look is plain ugly (not very constructive criticism, I know.) I'll take some time to criticize it in detail later on today... :-) I've only had time to look through the index.html page so far. Here are some problems I see with it... Contains a new draft of the proposed new manual style. This one is fully generated using xslt, so all the xml files should be converted. Then the meta tag for generator is wrong. The html source wasn't generated by Tidy - so they shouldn't be blamed :-) Don't lock the main table's width to 600. If you have a big font things begin to wrap much too early. I'd suggest that you don't use any width at all. The alt value for pixel.gif should be , not .. Actually, for this page I would remove the pixel.gif part completely. Use th for table headers! A) that's what they're for :-) B) It's much easier to make changes to their styles later on C) Some screen readers handle the semantics of the page much better if you use correct table tags. That's what I found after a quick perusal, I'll try to spend some more time on this later on... -- .-. | Patrik Grip-Jansson | | Ringen 4B |.. | 78444 Borlänge .--'' http://gnulix.com/ `-. | Sweden | All views and opinions are my own, | `--| PH:+46(0)24382823 PW:+46(0)707354360 | `--' - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: New draft of manual style
Patrik Grip-Jansson wrote: On Saturday 24 August 2002 05.15, Joshua Slive wrote: As for the new look, I'm a big -1 to it! The wacky design that Joshua did was so much better. It looked much more modern. This new look is plain ugly (not very constructive criticism, I know.) I'll take some time to criticize it in detail later on today... :-) I've only had time to look through the index.html page so far. Here are some problems I see with it... Hmmm... The index.html page has not been changed because it is not in xml. You need to look at some of the pages that have xml source in order to see the new format. Joshua. - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: New draft of manual style
On Saturday 24 August 2002 15.30, Joshua Slive wrote: Hmmm... The index.html page has not been changed because it is not in xml. You need to look at some of the pages that have xml source in order to see the new format. Actually, I was making two seperate statements :-) Yes, I've looked at several pages in the docs hierarchy. And No, I don't like the new layout - I even prefer the original look. But I thought I might as well begin my scrutinization from the first page - even though it doesn't have that much to do with the rest of the layout. The whole site should look good and be useful! Sorry if I my reply was a bit muddled :-) -- .-. | Patrik Grip-Jansson | | Ringen 4B |.. | 78444 Borlänge .--'' http://gnulix.com/ `-. | Sweden | All views and opinions are my own, | `--| PH:+46(0)24382823 PW:+46(0)707354360 | `--' - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: New draft of manual style
Patrik Grip-Jansson wrote: On Saturday 24 August 2002 15.30, Joshua Slive wrote: Hmmm... The index.html page has not been changed because it is not in xml. You need to look at some of the pages that have xml source in order to see the new format. Actually, I was making two seperate statements :-) Yes, I've looked at several pages in the docs hierarchy. And No, I don't like the new layout - I even prefer the original look. You need to be specific. And I don't mean you need to debug the html source. That is an irrelevant implimentation detail if you say you don't like the look. You need to say exactly what you don't like about the look and how it can be improved. The original index.html is completely irrelevant. It will be changed to match whatever new layout is chosen. Joshua. - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: New draft of manual style
http://cvs.apache.org/~slive/manual/ Contains a new draft of the proposed new manual style. This one is fully generated using xslt, so all the xml files should be converted. Fine, so we have now a first draft to work with the whole documentation. It is actually a draft, isn't it? It's a bit different from André's suggestion and sometimes ... unbalanced. I miss the additional styles, the harmonized link colors, and the german documents seem to need some code correction (maybe only an updated xsl, this should be no problem). I haven't looked behind the code, what you have changed. So I don't know which is aim and which is oversight. I'm a little uncomfortable with the complexity of the css, but I'll live with it as long as the docs still work fine with all css turned off. I would suggest to exclude Netscape 4 completely from css. This will simplify the css a lot. Kess - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: New draft of manual style
Astrid Keßler wrote: http://cvs.apache.org/~slive/manual/ Contains a new draft of the proposed new manual style. This one is fully generated using xslt, so all the xml files should be converted. Fine, so we have now a first draft to work with the whole documentation. It is actually a draft, isn't it? Certainly. It's a bit different from André's suggestion and sometimes ... unbalanced. Can you be more specific. I'm not sure what you mean. I miss the additional styles, You mean the alternate style-sheets? Those can certainly be put back, but I'm not sure I understand the point of them. Ordinary users will never find them, I'm sure. the harmonized link colors All the link colors look the same to me, except for directives and modules which are deliberately different. I changed everything to turn red on hover, and I removed the underlining on modules and directives, because I think it makes paragraphs with many references difficult to read. , and the german documents seem to need some code correction (maybe only an updated xsl, this should be no problem). I haven't looked at the translations, but they should be relatively easy to fix. I would suggest to exclude Netscape 4 completely from css. This will simplify the css a lot. That's always been my opinion, but others disagree. Joshua. - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
