It may be too much, but if Axel has taken the trouble to write it, he must have forseen a use for it by someone. Therefore I feel it should be included somewhere at some time.
Since it is not written in tutorial fashion, more as an introduction to the API, I'd say that if Axel wants to, we should include this document in the haiku book.
> As how to convert this document: either we add the document as a > separate page, or we add the contents to the main content of the > syslog.dox file. The last solution is limited in the sense that you > cannot create subsections and headers. So I tend to incline to the > first one. However, I'd like to get some other thoughts on that (and > maybe we should ask Axel for permission first, and an opinion on the > cuality of this document). I was looking at adding into the syslog.dox file. We could add in into a seperate page, but there may be duplication between the content of that and the existing page; is that acceptable? I could always strip out the duplication though. I have experimented and you can use headings/subheadings without the page tag within the syslog.dox file, but it might not be formatted in the way we want. I can post an example if you like to check...
Well, I'm not sure on how to do it yet. I'd go for the option of creating a 'System Logging' page, which will serve as a guide on how to use the system logger and the API. So you move all the implementation details to the syslog.dox files, and then use the _support_system_logging.dox file to guide developers through the API. I hope you can also add the documentation for listening to the system logger.
You are right however, we do need to check with Axel first, without his permission this conversation becomes invalid.
I'm fairly confident Axel will say yes. I guess you could contact him, as you are going to rip apart his work :-)
Yes, we should not concentrate on minor details. Maybe I'm being too detailed. I just found Axel's document and thought it was good to give devs and understanding of the mechanisms for system logging. At the end of the day the documentation is there to help devs.
You're completely right.
In order to not get bogged down, I can continue with my corrections, working to the existing format of the syslog.dox file and submit my patch. Then, if we/Axel agree, create a seperate page with his info on it minimising the duplication accross the two docs. That way I can move on to the next task without too much trouble.
I think you should do both these tasks simultaneously (if Axel gives permission). That's more efficient. I don't see much use in just updating this limited syslog.dox file. But you should do what suits you better. Niels