httpd-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Michael.Schro...@telekurs.de
Subject Antwort: Wacky new docs style
Date Mon, 05 Aug 2002 07:38:03 GMT

Hi Joshua,


> Since nobody had any better ideas, here's a proposal for a new
> display format for the docs.  It is stolen directly from
> http://style.tigris.org/
> Obviously, there are still tons of details to work out.
> (For example, the top banner is obviously horribly wrong;

all that seems wrong to me is that the logo is transparent,
and thus optimized to a white background. Tell me how it
should look like and I might be able to change that easily.

> But I think it looks pretty good overall.
> What do others think?

It is very close to what I would have suggested, and IMHO
a great step forward. I don't really care about the exact
color values, I can learn their semantics very easily anyway.

I like colors to visualize semantics. Thus I would like to
ask whether the <directive> tag might get a different back-
ground color too, maybe a very light grey (#f0f0f0, to not
dominate the layout too much).

I would like to have a unique style for hovering links.
Currently the hover effect is changing the color and adding
an underlining, but the color change sometimes is suppressed
by more local formatting, like inside a <directive> tag
whose font and color overrule the hover effect.
And I would like the links of the left-sided navigation
section to behave identical to other links, i. e. also add
the underline during the hover effect and not let the
<directive> formatting overrule the hover effect.
I would also like to additionally change the background
color (to some light grey or light blue?) for hovering links,
like the W3C validator is doing that. Maybe this would even
be a solution if you don't want to change the color of a
<directive> during hovering. It should be as easy as possible
to identify links ... and as your style partially omits un-
derlining them in passive mode and forces the user to search
for them with mouse movements, at least this search should
be supported as good as possible by a clear visual feedback.

Some of the <note> tags do have some margin around the text,
some others don't. (Examples inside of mod_auth.xml: First
and second <note> have no margin, third and fourth note do
have one.) Thus should be unique for all tags of one kind.
(The difference seems to be that in one case <p> are used
to sub-structure the <note> content while in other cases
this is not done. So rather use one method for this in all
cases.)

I would like to have the left-sided navigation section
available all the time and not need to scroll to it.
I am using CSS to do that in my mod_gzip documentation
(visit http://www.schroepl.net/projekte/mod_gzip/browser.htm
with a Mozilla or Opera browser and scroll down), but this
is HTML code (with a <div> positioned absolutely) and I
am not sure whether the same can be done with XML code.
(Should be worth an experiment, though.)
Also, this absolute positioning currently has no effect
in the Internet Explorer, where the behaviour would be
just like your current solution, so only Mozilla and
Opera would profit from it.

mod_log_config.xml: The font sizes within the left-sided
navigation section differ, which doesn't look very nice.

logs.xml: Here the font for the navigation elements is
too small. I rather like the looks of the modules than
the one of the other documents. (I would suggest to use
some "condensed" font that has letters of a very small
width, so that even longer texts can be displayed there
without line-wrapping.)
And yes, the <related> tag looks ugly. ;-)

Layout: the <title> tag of the document is centered,
while other <title>s (inside <section>s) are left-
aligned. But both <title> tags have the same background
color. To me this looks confusing.
I would suggest to left-align all <title>s, and further-
more use (slightly) different background colors, to
visualize the hierarchy of these titles.
I like to see at once where a new section starts; I even
like cascading numbering of sections (like "4.1.3. Scope
of directives") to visualize them (but don't suggest
using them in the Apache docs, as there is not much
sections hierarchy in most of the documents). I like to
use many colors inside documents ... so don't take my
suggestions too important. ;-)

Printing these documents: I don't feel that links within
a document need to be visualized in the printed version
of the document. CSS allows for defining style sheets
depending on the media to be used, like
     @media screen { <some  CSS definitions> }
and   @media print  { <other CSS definitions> }
which can be quite different; modern browsers do support
this.
I am using this especially to suppress or modify colors,
as it may produce suboptimal results to print a document
rich of colors on a black and white laser printer where
the colors have been mapped to grey tones.
But you can of course as well omit the link underlining
in the CSS definitions for print output etc.

As for the content, two short notes:

"<p>Setting the <directive>AuthAuthoritative</directive> directive
    explicitly to <strong>'off'</strong> allows for both"
-> I wouldn't use <strong> for tagging some string that
describes a parameter of a directive.
Shouldn't this be <code> or something like that?

"... user groups for user authentication.  File-path is the path
 to the group file..."
-> Writing "File-path" with uppercase might suit the needs
of writing a syntactical correct sentence of the English
language, but it violates the need of writing the exact
reference to the symbol that should be cited, which is
written in lower-case. I would use the exact case-sensitive
form "file-path" in this case, even at the start of a sen-
tence, and make this a general rule for the documentation.



Regards, Michael



---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org


Mime
View raw message