[02:37:29] --- dev-zero@jabber.org has become available [02:37:31] --- dev-zero@jabber.org has left: offline [06:30:14] --- pod has become available [06:55:43] --- cclausen has become available [07:43:49] --- edgester has become available [08:51:26] --- Jeffrey Altman has become available [08:52:14] --- Jeffrey Altman has left [08:52:20] --- Jeffrey Altman has become available [08:57:46] I have the doc/pdf/*.pdf documents converted to doxygen. This includes the architecture and protocol docs. My original thought was that we could commit the protocol docs in the same directory as the .xg file. This would work well for the fs/cm doc (fsint), bos server (bozo), and rx (rx) but would fail for the vldb/vol doc because it covers two directories (volser and vlserver). The architecture doc would also be without a home. [08:58:35] I want to avoid creating a new doc/doxygen directory. I do not like the notion of organizing documentation by document format technology [08:58:47] * edgester nods [08:59:08] on the other hand, I'm not prepared at the moment to re-organize the entire doc tree [08:59:09] I'm working on the admin guide [08:59:22] understandable [09:00:34] although it really needs it. The html directory at this point can be removed. same for the pdf directory [09:01:05] I don't think documentation on the protocol and protocol architecture belongs in the openafs repository at all, though it is entirely reasonable to host it on the openafs web site. [09:01:46] do we need the old HTML and PDF stuff at all? [09:01:52] architecture could go in src/afs or src/fsint [09:02:27] we actually have doc/arch/ for architecture docs. There is a graphviz .dot file from the dafs work there [09:03:54] Actually, I'm sort of torn on the protocol docs. Eventually I want to reach the point where the protocol is documented by products of the standardization group, which look like (maybe are) RFC's. But it's going to be a long time, if ever, before the existing bits are documented in that way, and in the meantime keeping the historical stuff around is useful. [09:03:56] Heimdal contains a full set of every Kerberos / GSS / NTLM / etc. protocol document in its repository. I think its an important resource for developers to have at their finger tips [09:04:35] I agree that protocol docs should also exist somewhere else that is independent but OpenAFS should maintain copies [09:04:47] i'd like to keep the historical stff updated and in our tree for the time being. it can move later. we aren't committed to keeping it forever. it's not an interface. [09:04:55] the OpenAFS copies indicate what we implemented (or failed to) [09:05:32] OK, let me rephrase. I don't think the _authoritative_ copies of those documents belong in the openafs repository. The corrolary to that is that they don't really belong in openafs version control, because those copies aren't source files. But sometimes you need to compromise the "no non-source files" rule and include cached copies of external things to avoid going insane. [09:06:13] In any case, I do think that documentation belongs in the doc/ tree, and not scattered around the various source directories. [09:06:22] i'd rather put them in openafs vc for now, and move them later when there's aa logical something else to take them (and they match reality) [09:07:06] I'm going to propose the following. doc//arch for the architecture document and doc//protocol for the others [09:07:19] agree [09:07:27] Hm. If when there's a logical something else to take them, and that else has a version control repository, is there likely to be an easy way to copy stuff there from openafs and include all the version history? [09:07:37] if you use git :) [09:07:43] With doc/protocol being a new directory? sounds fine. [09:08:03] if you don't use git, then ymmv. (though tailor may help) [09:08:31] doc//protocol will be a new directory [09:09:23] Is there some semantic meaning to the double slash? [09:10:03] my client seems to interpret a single slash as an indication to italicize the following word [09:10:16] Oh, how friendly. [09:10:34] er, "friendly" [09:14:18] the reason that doxygen was used for this project over docbook is that I want to eventually be able to generate developer documentation from our source tree that contains references to the protocol documentation that describes what should have been implemented. [09:15:17] I think that's a good choice. In particular, I would love to eventually see .xg files with embedded documentation. [09:16:27] yes, that is where I was headed with this. Each doc is a .h file that could be combined with documentation pulled from the .xg and the supporting implementation. [09:16:37] Unfortunately, I'm not sure what the licenses are on these documents, and I know the license on the .xg files in OpenAFS is too restrictive for them to be used as a basis for something distributed for other implementers to use. [09:18:29] the conversion work is licensed bsd [09:18:53] the source documents are whatever they were before IBM gave them to us. [09:19:23] Yeah, that's the problem. I don't think they were anything useful. [09:19:51] But I'm more worried about the xg files. [09:36:16] --- dev-zero@jabber.org has become available [09:36:23] --- dev-zero@jabber.org has left: offline [09:59:03] where can I get an XSL file for the HTML admin guide? [10:18:48] never mind, I got it [10:26:46] if you are working off the head or 1.5 the Makefiles should build them for you [10:27:23] I'm not sure if everything has been pulled up to 1.4. Although I suspect it has [10:27:55] protocol doc sources committed [10:28:31] folks should now feel free to start to update those docs for the protocol enhancements since 1991 [10:29:17] makefiles to auto-generate the doxygen config files will be added later. [11:05:16] --- pod has left [11:16:24] --- pod has become available [11:33:12] --- Russ has become available [11:56:02] --- pod has left [11:56:11] --- pod has become available [12:20:57] --- Russ has left: Replaced by new connection [12:20:57] --- Russ has become available [12:57:53] --- Russ has left: Replaced by new connection [12:57:53] --- Russ has become available [13:53:06] --- haba has become available [15:09:47] FYI, I added the newsletter as the third news item on the homepage [15:17:28] --- dev-zero@jabber.org has become available [15:17:33] --- dev-zero@jabber.org has left: offline [16:01:59] --- Russ has left: Disconnected [16:32:48] --- cclausen has left [18:45:36] > duping hostList in the h_Enumerate routines 'should' have no side > effect [18:45:56] if you 1) take refs and 2) don't assume the next in them continues to be as-is. [19:26:52] --- edgester has left [21:53:52] --- Simon Wilkinson has become available [22:09:03] --- Russ has become available [23:17:44] --- Russ has left: Disconnected [23:18:18] --- reuteras has become available