> <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 would love to agree with you, but then the "ErrorLog"
directive might be considered a violation against the
"underlying data model" as well.
(Of course the developers didn't know about this "data
model", so their had little chance to be compatible to it.)
So the question seems to be whether
- the documentation data model should reflect reality or
- it should present some ideal world which reality is then
made compatible with.
And you did already name the reasons for keeping these two
different file names ...
> I think of the xml structure of the module docs much like a database.
So do I - or at least this is how I think it should be,
unless other aspects turn out to be more important.
> 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.
+1
> 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.
Before specifying such a specific additional XML element I would
rather want to find out in how many locations this would be of use.
If you end up to need five more XML fields that are used in no
more than three locations each, then this will make things more
complicated for documentation writers.
An alternative might possibly be to have some "string" field
(have the semantics as unspecified as possible) for "add things
here that don't fit into the other fields of the data structure".
This might not be an ideal relational model of its content, but
it would at least be easy to use for both authors and readers.
(Its name might be something like "Miscellaneous" or "Notes".)
> 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.
A field that could contain information of unspecified semantics
will most likely be subject to translation as well.
And in a way, it is unfortunate that the "usage" field will be
subject to translation at all, but the use of 'meta elements'
(like "<pathname>") that are named in a specific language seems
to be unaviodable.
> 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.
Would it be a "solution" to have one directive default name for
the sake of documentation, then have two different platform
dependent httpd.conf files to provide compatibility for end users?
(My guess is you'll say "no" because some users have their
customized "httpd.conf" and don't even use any directive to
provide the requirements their scripts rely upon ... but isn't
it _their_ fault then?)
Regards, Michael
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
