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 rbo...@rcbowen.com :: @rbowen rbo...@apache.org
