You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs@httpd.apache.org by Tim Gerundt <ti...@gerundt.de> on 2002/10/05 00:11:37 UTC
suggestions for the documentation style
Hello!
I have few suggestions for the documentation style.
Only little things, nothing world-moving thing! ;)
<note type="warning">...</note>
You should use a light red background-color for
warning notes.
That makes the warning clearer!
<name>Name</name>
<syntax>Syntax ...</syntax>
<sourcefile>sourcefile.c</sourcefile>
For this tags from <modulesynopsis> and <directivesynopsis>
you should use the <code>-tag with the html-output.
It looks better, like the <default> tag.
Maybe you can use it for <identifier> too.
Also, in headers (h1, h2, ...), you can use the <code>-tag
to modulname and directive.
So it looks like the links to modules or directives.
Last but not least:
The the centered title from notes and examples look
not so good, because nothing else at the page are centered.
I think the bolder font from the title is enough to take off
form the note and example.
*ww*
Tim
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: suggestions for the documentation style
Posted by Joshua Slive <jo...@slive.ca>.
On Tue, 8 Oct 2002, André Malo wrote:
> * Joshua Slive wrote:
>
> > +1 for the red border around warnings, and +1 for left-aligning the
> > titles for both notes and examples. I think putting <code> in the
> > titles is a little ugly, however.
>
> ok, done.
> Hmm, I think, the example/warning/note heading font-size should be
> increased, shouldn't it?
I'm not sure; I'd have to see the result. If you think it looks better,
then go for it.
>
> By the way: I'd like to remove the surplus css files. Or are there any
> reasons to hold them in the repository?
Nope. They should be removed.
Joshua.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: suggestions for the documentation style
Posted by André Malo <nd...@perlig.de>.
* Joshua Slive wrote:
> +1 for the red border around warnings, and +1 for left-aligning the
> titles for both notes and examples. I think putting <code> in the
> titles is a little ugly, however.
ok, done.
Hmm, I think, the example/warning/note heading font-size should be
increased, shouldn't it?
By the way: I'd like to remove the surplus css files. Or are there any
reasons to hold them in the repository?
nd
--
Gefunden auf einer "Webdesigner"-Seite:
> Programmierung in HTML, XML, WML, CGI, FLASH <
# André Malo # http://www.perlig.de/ #
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: suggestions for the documentation style
Posted by Joshua Slive <jo...@slive.ca>.
+1 for the red border around warnings, and +1 for left-aligning the
titles for both notes and examples. I think putting <code> in the
titles is a little ugly, however.
Joshua.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: suggestions for the documentation style
Posted by Tim Gerundt <ti...@gerundt.de>.
* André Malo wrote:
>>what do you think about a red border? (see below for an example)
That is good, too!
Main thing it gives one differentiated to the normal notes.
>>ok for me.
For the modulename from a directive, too?
>>looks only good with mozilla for me (see below...), so I tend to -0.
Mhh, with the IE it look also good.
But perhaps that should a few more people decide.
>>However, I moved the warnings title to the left (so you may compare with
>>the note titles, which are kept centered), but I think, it looks not
>>very good. I like the centered variant.
I like the left variant more! ;)
It is better to read, because you find the title faster,
as a little "note" in den middle.
>>Note, that the warning's border is dashed, but since the MSIE cannot
>>display dashed lines, he uses solid ones...
My IE 5.5 show dashed lines.
*ww*
Tim
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: suggestions for the documentation style
Posted by Astrid Kessler <ke...@kess-net.de>.
I have to see it, to be able to tell you my opinion about. So tahnk you
for the example, nd.
>> <note type="warning">...</note>
>> You should use a light red background-color for
>> warning notes.
>> That makes the warning clearer!
>
> yes and no. light colored backgrounds are not very visible, e.g. on
> laptop screens. and darker backgrounds are hard to read on normal
> screens...
I'am using a notebook, so I can tell you thats's true. Light colors are
only shemes at a notebook diplay. A light red color would not have any
sinaling effect there.
> what do you think about a red border? (see below for an example)
Ah, please, use solid borders, not dashed. The dashed one lets the block
be uneasy and makes the text difficult to read.
>> <name>Name</name>
>> <syntax>Syntax ...</syntax>
>> <sourcefile>sourcefile.c</sourcefile>
<syntax> and <sourcefile> are ok (+1), but not <name>. This is used
within the headers and looks terrible.
>> Also, in headers (h1, h2, ...), you can use the <code>-tag
>> to modulname and directive.
>> So it looks like the links to modules or directives.
>
> looks only good with mozilla for me (see below...), so I tend to -0.
see above, -0 from me
>> The the centered title from notes and examples look
>> not so good, because nothing else at the page are centered.
>> I think the bolder font from the title is enough to take off
>> form the note and example.
When using a border, left and centered will both be ok for me. But
without a border centered would be better.
> Note, that the warning's border is dashed, but since the MSIE cannot
> display dashed lines, he uses solid ones...
This is the first time, I'm using IE instead Mozilla. Grats nd, you got
me switching ;-)
Kess
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: suggestions for the documentation style
Posted by André Malo <nd...@perlig.de>.
* Tim Gerundt wrote:
> <note type="warning">...</note>
> You should use a light red background-color for
> warning notes.
> That makes the warning clearer!
yes and no. light colored backgrounds are not very visible, e.g. on
laptop screens. and darker backgrounds are hard to read on normal
screens...
what do you think about a red border? (see below for an example)
> <name>Name</name>
> <syntax>Syntax ...</syntax>
> <sourcefile>sourcefile.c</sourcefile>
ok for me.
> For this tags from <modulesynopsis> and <directivesynopsis>
> you should use the <code>-tag with the html-output.
> It looks better, like the <default> tag.
> Maybe you can use it for <identifier> too.
-0. too much <code> (i.e. monospace font) sections make the text hard to
read/scan.
> Also, in headers (h1, h2, ...), you can use the <code>-tag
> to modulname and directive.
> So it looks like the links to modules or directives.
looks only good with mozilla for me (see below...), so I tend to -0.
> The the centered title from notes and examples look
> not so good, because nothing else at the page are centered.
> I think the bolder font from the title is enough to take off
> form the note and example.
hmm. the letter bars are centered and the "Apache 2.0 HTTP-Server" in
page header is "centered" (on the right side...).
However, I moved the warnings title to the left (so you may compare with
the note titles, which are kept centered), but I think, it looks not
very good. I like the centered variant.
Example: <http://cvs.apache.org/~nd/manual/mod/mod_proxy.html.en>
Note, that the warning's border is dashed, but since the MSIE cannot
display dashed lines, he uses solid ones...
nd
--
print "Just Another Perl Hacker";
# André Malo, <http://www.perlig.de/> #
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org