httpd-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Rich Bowen <rbo...@rcbowen.com>
Subject Error documentation, more thoughts
Date Fri, 09 Mar 2012 15:35:12 GMT
I wanted to share this transcript from IRC, just to see what people think of the idea.



[10:15]  <DrBacchus> It would be nice (this is just wishful thinking) if when a AHxxxx
code is created, there was a piece of documentation that was created along with it listing
a more detailed explanation of what the message is supposed to mean, which could then be incorportaed
into the documentation
[10:15]  <DrBacchus> Imagine, for example, that each module had an errors.xml file that
lived in the same directory.
[10:15]  <DrBacchus> mod_rewrite_errors.xml or whatever.
[10:16]  <DrBacchus> And that was parsed in some way to create documentation.
[10:16]  <DrBacchus> Hmm. This is actually not too far-fetched.
[10:16]  <DrBacchus> Even if the docs team maintained those files, it would be a work-saver.
[10:17]  <DrBacchus> Then we'd have a script that went through and generated docs XML
from the error.xml files, and then that would in turn be turned into an error index list,
and a per-module error documentation file.
[10:17]  <Humbedooh> DrBacchus, that would be awesome
[10:17]  <DrBacchus> What do you think of that?
[10:17]  <DrBacchus> Is this at all feasible?
[10:17]  <DrBacchus> It would also greatly encourage the module authors to create docs,
because it would be right there when they're working onit.
[10:18]  <DrBacchus> and if we make it easier, it happens more often.
[10:18]  <Sling> yeah, now the documentation people are left to interpret the error
conditions, when the author probably knows best
[10:18]  <DrBacchus> So, let's pretend we're going to do this - what would go in that
file?
[10:19]  <DrBacchus> An error tag, the message itself, a more detailed explanation,
and optionally a URL.
[10:19]  <DrBacchus> Thoughts?
[10:19]  <DrBacchus> I should take this to the list. But it would be interesting to
hear some feedback of why this won't work before I put it out there.
[10:19]  <Sling> loglevel, errorcode, errormessage, variables, (optional modulename),
author comments
[10:19]  <DrBacchus> And presumably we could auto-generate the first run of that.
[10:20]  <DrBacchus> Or even have a script that updates an existing file non-destructively,
that thye could run after making edits.
[10:20]  <DrBacchus> the module name is in the name of the file.
[10:20]  <DrBacchus> The file is named mod_foo_errors.xml
[10:20]  <DrBacchus> Because there may be several in a given source directory.
[10:20]  <Sling> not all errors are in a module though, but i guess core_errors.xml
would work too
[10:21]  <DrBacchus> Yes. Not sure where that file is located, though.
[10:21]  <DrBacchus>  $SVN/httpd-trunk/modules/mappers/mod_rewrite_errors.xml
[10:23]  <Sling> perhaps an index xlink with paths to the other xmls and a description
tag as an abstraction from the path/filename
[10:23]  <Sling> as long as it can be updated without manual intervention :)
[10:32]  <DrBacchus> I want it to be as simple as possible.


--
Rich Bowen
rbowen@rcbowen.com :: @rbowen
rbowen@apache.org







Mime
View raw message