Re: removed
in core.xml

[Astrid Keßler <ke...@kess-net.de>]

> [Back to the list, because I think it is of general interest.]

Your are right, this should be discussed here.


> On Sun, 29 Jun 2003, Astrid Keßler wrote:

>> Joshua,
>>
>> I didn't realize earlier that you removed the following <br> in
>> core.xml:

> [in a <default> entry]

> The immediate reason I did it was because it screwed things up in LaTeX.
> But, of course, that could be solved other ways (by throwing that field
> into a minibox).

> The more important reason is that I don't believe such block-level
> formatting belongs in that type of field.  The reason is that this data
> could be repurposed and used in any number of ways, and this kind of
> repurposing will be much simpler if the formatting is kept very simple.
> For example, imagine that an apache configuration tool wanted to display
> this information.  Or what about the directive quick-reference? It makes
> it much harder to do stuff like this when there is complex formatting in
> those fields.

The directive quickreference is able to handle this. It uses the first
line only and appends a + sign. Other formatings are able in the same
way. I don't want to block <br>'s just because of some tools. It is
realy easy to transform a <br> into a space. But it is much harder to
add a line break at the right place if you want to offer better
readability; we have to support them.

But there is another point ...

> Really, the <default> shouldn't contain anything at all other than exactly
> what you need to put in the config file to get the default behavior.  In
> cases like ErrorLog where the default is not so simple, we should probably
> just eliminate the field and discuss it in the text.

The overview box should give a _short_ overview. Long (more than one (?)
line) descriptions are better placed in the text. So I tend to agree
with you to replace long defaults, etc. with "see description". Only, I
fear an inflation of "see description"s.

Kess

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

Re: removed
in core.xml

[Joshua Slive <jo...@slive.ca>]

Let me put it this way: My point is that <default> should contain the
default, AND NOTHING ELSE.  Putting any extra formatting, multiple
choices, references, or "see elsewhere" in the field seems like a "type
mismatch" (for want of a better phrase).

I think of the xml structure of the module docs much like a database.  The
xsl transformations should extract data from that database and make it
presentable.  It seems to me that by placing <br> or "see elsewhere", we
are mixing up the content and the presentation.

One solution is to have a <seeusage/> tag that could be transformed into
"see usage" or whatever.  I'm not sure how much better that would be.

One thing to think about: If this is done correctly, then the translations
could source the syntax/context/status/module entries directly out of the
english version.  Only description/compatibility/usage would need to be
translated.

On Wed, 2 Jul 2003, Astrid Keßler wrote:
> Wouldn't 2.2 be a good place to switch?

I think error_log/access_log are so much a part of apache that it would be
more painful to switch than any gain in consistency.  Think of all the
hand-written scripts that operate on those names.

Anyway, this is a lot of discussion for a relatively minor issue ;-)  If
you really think I'm wrong, feel free to change it back.

Joshua.

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

Re: removed
in core.xml

[Astrid Keßler <ke...@kess-net.de>]

> On Wed, 2 Jul 2003, Astrid Keßler wrote:
>> The directive quickreference is able to handle this. It uses the first
>> line only and appends a + sign. Other formatings are able in the same
>> way.

> Absolutely; but why make each new transformation technique more
> complicated than necessary?

It's really hard to read different default values in one line. I
remember, that I had to read it a second and third time. Imho better
readability is worth that small effort.


>> > Really, the <default> shouldn't contain anything at all other than exactly
>> > what you need to put in the config file to get the default behavior.  In
>> > cases like ErrorLog where the default is not so simple, we should probably
>> > just eliminate the field and discuss it in the text.
>>
>> The overview box should give a _short_ overview. Long (more than one (?)
>> line) descriptions are better placed in the text. So I tend to agree
>> with you to replace long defaults, etc. with "see description". Only, I
>> fear an inflation of "see description"s.

> Yes, I think we all basically agree on this.  It is just a question of how
> strict we want to be.  A couple points:

> 1. I'd just drop the field in this case, rather than using "see
> description".

We have this somewhere in the docs. And I remember that I was wondering
if the directive does not have any default value. Removing the whole
field would give a wrong impression to users just scanning the text. A
"see description" would force the user a little bit more, to read the
text.

> 2. This is an area where we need to work with the developers to assure
> that they don't overload the same directive for too many different uses.
> This particular example (error_log/error.log) is an unfortunate historical
> thing.  It really needs to be error.log on windows because of the
> extension==type issue.  It could also be error.log on unix, except there
> is too much history in the old name, so we need to live with it now.

Wouldn't 2.2 be a good place to switch?

 Kess

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

Re: removed
in core.xml

[Joshua Slive <jo...@slive.ca>]

On Wed, 2 Jul 2003, Astrid Keßler wrote:
> The directive quickreference is able to handle this. It uses the first
> line only and appends a + sign. Other formatings are able in the same
> way.

Absolutely; but why make each new transformation technique more
complicated than necessary?

> > Really, the <default> shouldn't contain anything at all other than exactly
> > what you need to put in the config file to get the default behavior.  In
> > cases like ErrorLog where the default is not so simple, we should probably
> > just eliminate the field and discuss it in the text.
>
> The overview box should give a _short_ overview. Long (more than one (?)
> line) descriptions are better placed in the text. So I tend to agree
> with you to replace long defaults, etc. with "see description". Only, I
> fear an inflation of "see description"s.

Yes, I think we all basically agree on this.  It is just a question of how
strict we want to be.  A couple points:

1. I'd just drop the field in this case, rather than using "see
description".

2. This is an area where we need to work with the developers to assure
that they don't overload the same directive for too many different uses.
This particular example (error_log/error.log) is an unfortunate historical
thing.  It really needs to be error.log on windows because of the
extension==type issue.  It could also be error.log on unix, except there
is too much history in the old name, so we need to live with it now.

Joshua.

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