[haiku-doc] Re: Pahe III BlockCache.dox .diff

Hi Alan,

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

Other related posts: