From dev-return-76590-apmail-cocoon-dev-archive=cocoon.apache.org@cocoon.apache.org Mon Aug 01 08:58:20 2005 Return-Path: Delivered-To: apmail-cocoon-dev-archive@www.apache.org Received: (qmail 98626 invoked from network); 1 Aug 2005 08:58:19 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (209.237.227.199) by minotaur.apache.org with SMTP; 1 Aug 2005 08:58:19 -0000 Received: (qmail 75581 invoked by uid 500); 1 Aug 2005 08:58:15 -0000 Delivered-To: apmail-cocoon-dev-archive@cocoon.apache.org Received: (qmail 75460 invoked by uid 500); 1 Aug 2005 08:58:14 -0000 Mailing-List: contact dev-help@cocoon.apache.org; run by ezmlm Precedence: bulk list-help: list-unsubscribe: List-Post: Reply-To: dev@cocoon.apache.org List-Id: Delivered-To: mailing list dev@cocoon.apache.org Received: (qmail 75447 invoked by uid 99); 1 Aug 2005 08:58:14 -0000 Received: from asf.osuosl.org (HELO asf.osuosl.org) (140.211.166.49) by apache.org (qpsmtpd/0.29) with ESMTP; Mon, 01 Aug 2005 01:58:14 -0700 X-ASF-Spam-Status: No, hits=-0.0 required=10.0 tests=SPF_HELO_PASS X-Spam-Check-By: apache.org Received-SPF: neutral (asf.osuosl.org: local policy) Received: from [80.68.89.4] (HELO bm.codeconsult.ch) (80.68.89.4) by apache.org (qpsmtpd/0.29) with SMTP; Mon, 01 Aug 2005 01:58:04 -0700 Received: (qmail 25253 invoked from network); 1 Aug 2005 08:58:07 -0000 Received: from unknown (HELO ?192.168.0.163?) (62.220.137.25) by bm.codeconsult.ch with SMTP; 1 Aug 2005 08:58:07 -0000 Mime-Version: 1.0 (Apple Message framework v619.2) In-Reply-To: <92c58484050731213514b798f6@mail.gmail.com> References: <92c58484050731213514b798f6@mail.gmail.com> Content-Type: multipart/signed; micalg=sha1; boundary=Apple-Mail-10-698079091; protocol="application/pkcs7-signature" Message-Id: From: Bertrand Delacretaz Subject: Re: RefDoc - Neutral XML Document Format Input/Current State Date: Mon, 1 Aug 2005 10:58:02 +0200 To: dev@cocoon.apache.org X-Mailer: Apple Mail (2.619.2) X-Virus-Checked: Checked by ClamAV on apache.org X-Spam-Rating: minotaur.apache.org 1.6.2 0/1000/N --Apple-Mail-10-698079091 Content-Transfer-Encoding: 7bit Content-Type: text/plain; charset=US-ASCII; format=flowed Hi Robert, Thanks for your analysis - I hope others are going to answer as well, but here are at least my comments: > ....I've created several types and other proposed 'well-defined' bits > of > metadata to assist the publishing of these documents into a nice > format and easing the pain of parsing out such information. The types > are: > > *method* - this type is for documenting methods or functions > > *package* - this type indicates that the comment contains only the > package string for the file and perhaps the leading 'package' > declaration in java or a trailing semicolon > > *class-declaration* - this type contains only the class declaration > (and maybe the trailing '{') > *codeblock* - this type is for indicating that the comment contains > code for publishing purposes > ok - my view was a more high-level one than classes and methods, which are adequately covered by the javadocs. These are certainly useful though, but see the proposed use-cases below for a more component-oriented view. > > *name* - this type indicates the 'name' of the document of thing being > documented under > the current key (or specified key for this name > > *warning* - this type expresses warnings > > *example* - this type is used to indicate that the comment contains an > example > > *details* - this type must include another piece of metadata > indicating what it is detailing more on this in a minute ok > *variable* - this type is used to document a variable or parameter ok, we'll need to be more detailed here I think, differentiating sitemap parameters, component configuration parameters, etc. > *description* - this type is used to describe what the purpose of the > current thing being documented is as per the current/specified key ok > *see-also* - this type specifies that it contains a listing of doktor > keys that you might also want to look at/search for ok, this is a very important one. > A few new pieces of metadata: ... > *filetype* - this is usually supplied with the key for the document > and indicates what kind of document it is which may be used in a > publishing context... ok, this will be needed for example to republish XML snippets as XML I assume. > Issue #1: > The need to associate a codeblock with an example comes from > publishing interests. If I have an example with a block of text > explaining things and then a demostration in code then without > separating them but keeping them associated publishing it correctly > becomes a nightmare. I'm afraid though that this may introduce too > much complexity to deal with... The sorting of snippets to build the final document will be a problem as soon as there are more than a few snippets. Maybe introducing an "order number" metadata attribute would help and not be too hard to manage? We could then rearrange the snippets be changing their order numbers, while keeping the overall order based on the snippet types. > ....Issue #2: > Of course simple having to index so many different metadata keys might > be annoying and they should perhaps all be changed to one 'id' or > 'name' field. I feel this should be done. I'm not sure what you mean here, can you elaborate or give an example? > ...Issue #3: > I figured that the layout of the neutral XML would be similar to how a > javadoc document is arranged with the name and packge followed by a > description and then examples/methods/variables followed finally by > details and perhaps codeblocks. This may be too similar to javadoc, > however and I'd like input on formatting decisions... Starting from a javadoc model is certainly good. > ...Finally, any further comments, ideas, or discussion is welcomed... I'm just going to add a few brief use-cases, or rather a few example questions that I'd like refdoc-generated documentation to answer: a) What is the FileGenerator? scenario: search the refdoc for "FileGenerator" or navigate the refdoc: refdoc/components/FileGenerator b) Which generator can read URLs through a proxy? scenario: full-text search for a refdoc document from the "components" collection, containing both the "URL" and "proxy" words. c) What sitemap parameters can be used for the FileGenerator? scenario: find the document as in a), the document contains a list of parameters build from "sitemap-parameter" metadata elements found in doktor comments. The parameter descriptions stay up to date as the @doktor comments are right next to the source code which reads the parameter, so people remember to keep them up to date. d) I need an example of how to use the HtmlTransformer in a sitemap scenario: search the refdoc for a snippet ot type "sitemap-example" where property "component-name" is HtmlGenerator. The snippet points to its "parent document" which describes the HtmlGenerator. It might be good to elaborate on these use-cases and maybe document them in a text file in the refdoc block, but for now I hope they help clarifiy the needs and priorities. Note that these assume a dynamic search of the refdoc index - I think the full power of the refdoc will be available only when querying the Lucene index directly, as is done in some of these use-cases, but the document-oriented version (that will probably be published as static HTML pages) will contain the same information, only with less precise searches. The Lucene index will be available to people who start Cocoon on their own machines anyway, so I think having to use the Lucene index for precise queries is not a big problem. -Bertrand --Apple-Mail-10-698079091 Content-Transfer-Encoding: base64 Content-Type: application/pkcs7-signature; name=smime.p7s Content-Disposition: attachment; filename=smime.p7s MIAGCSqGSIb3DQEHAqCAMIACAQExCzAJBgUrDgMCGgUAMIAGCSqGSIb3DQEHAQAAoIIGRTCCAv4w ggJnoAMCAQICAw0p3DANBgkqhkiG9w0BAQQFADBiMQswCQYDVQQGEwJaQTElMCMGA1UEChMcVGhh d3RlIENvbnN1bHRpbmcgKFB0eSkgTHRkLjEsMCoGA1UEAxMjVGhhd3RlIFBlcnNvbmFsIEZyZWVt YWlsIElzc3VpbmcgQ0EwHhcNMDQxMDA0MTQyMzU0WhcNMDUxMDA0MTQyMzU0WjBtMRMwEQYDVQQE EwpEZWxhY3JldGF6MREwDwYDVQQqEwhCZXJ0cmFuZDEcMBoGA1UEAxMTQmVydHJhbmQgRGVsYWNy ZXRhejElMCMGCSqGSIb3DQEJARYWYmRlbGFjcmV0YXpAYXBhY2hlLm9yZzCCASIwDQYJKoZIhvcN AQEBBQADggEPADCCAQoCggEBALXTKyJRGv/islEqVhG+iE8FSGe+4ikts9rca6OUPD4CJ+vYcXS5 arpv87lSoi0cyC8QkjB6MzsXzsraQjyO3EOeFOcNWN1XFe0Qc2uqVBSdYM6LtaSs4A1OYSweKKFK iNscMmlsIIKXvZ8xb4QmbZZSkklh5tWdJh+aNNV0m++NEUXRsqRffz6eHRmf0RjYmwxBig3KpzmH dPAcGTtDcI9O7p2OpQ7zPFAt9n4tMPx6makpU97HeGKqvWPIaaprQa/4nLhTcWDaZ1AHyFYNhzru gyRI0SDyp6OijuUZKXsaESJWEEySke18l6aZbsflzXpoCMTS9ce93fJ0uBFax/kCAwEAAaMzMDEw IQYDVR0RBBowGIEWYmRlbGFjcmV0YXpAYXBhY2hlLm9yZzAMBgNVHRMBAf8EAjAAMA0GCSqGSIb3 DQEBBAUAA4GBAEBia6WrujKxJoVkme3aFszr/WmH4x+mIj+AmrAVG2tGB+RO0yCK/aal3wLzMBYn O6zr7TPW2PqOUmMGeP7Pgr5KSMn4rlfM+Hdfd/IvqCpHuWcqq/VAto47XF2cZyGNw32EdGx8IeCe 6BFaoRh6yJdS3GkOnbqSNCVTih/PdRlxMIIDPzCCAqigAwIBAgIBDTANBgkqhkiG9w0BAQUFADCB 0TELMAkGA1UEBhMCWkExFTATBgNVBAgTDFdlc3Rlcm4gQ2FwZTESMBAGA1UEBxMJQ2FwZSBUb3du MRowGAYDVQQKExFUaGF3dGUgQ29uc3VsdGluZzEoMCYGA1UECxMfQ2VydGlmaWNhdGlvbiBTZXJ2 aWNlcyBEaXZpc2lvbjEkMCIGA1UEAxMbVGhhd3RlIFBlcnNvbmFsIEZyZWVtYWlsIENBMSswKQYJ KoZIhvcNAQkBFhxwZXJzb25hbC1mcmVlbWFpbEB0aGF3dGUuY29tMB4XDTAzMDcxNzAwMDAwMFoX DTEzMDcxNjIzNTk1OVowYjELMAkGA1UEBhMCWkExJTAjBgNVBAoTHFRoYXd0ZSBDb25zdWx0aW5n IChQdHkpIEx0ZC4xLDAqBgNVBAMTI1RoYXd0ZSBQZXJzb25hbCBGcmVlbWFpbCBJc3N1aW5nIENB MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDEpjxVc1X7TrnKmVoeaMB1BHCd3+n/ox7svc31 W/Iadr1/DDph8r9RzgHU5VAKMNcCY1osiRVwjt3J8CuFWqo/cVbLrzwLB+fxH5E2JCoTzyvV84J3 PQO+K/67GD4Hv0CAAmTXp6a7n2XRxSpUhQ9IBH+nttE8YQRAHmQZcmC3+wIDAQABo4GUMIGRMBIG A1UdEwEB/wQIMAYBAf8CAQAwQwYDVR0fBDwwOjA4oDagNIYyaHR0cDovL2NybC50aGF3dGUuY29t L1RoYXd0ZVBlcnNvbmFsRnJlZW1haWxDQS5jcmwwCwYDVR0PBAQDAgEGMCkGA1UdEQQiMCCkHjAc MRowGAYDVQQDExFQcml2YXRlTGFiZWwyLTEzODANBgkqhkiG9w0BAQUFAAOBgQBIjNFQg+oLLswN o2asZw9/r6y+whehQ5aUnX9MIbj4Nh+qLZ82L8D0HFAgk3A8/a3hYWLD2ToZfoSxmRsAxRoLgnSe JVCUYsfbJ3FXJY3dqZw5jowgT2Vfldr394fWxghOrvbqNOUQGls1TXfjViF4gtwhGTXeJLHTHUb/ XV9lTzGCAucwggLjAgEBMGkwYjELMAkGA1UEBhMCWkExJTAjBgNVBAoTHFRoYXd0ZSBDb25zdWx0 aW5nIChQdHkpIEx0ZC4xLDAqBgNVBAMTI1RoYXd0ZSBQZXJzb25hbCBGcmVlbWFpbCBJc3N1aW5n IENBAgMNKdwwCQYFKw4DAhoFAKCCAVMwGAYJKoZIhvcNAQkDMQsGCSqGSIb3DQEHATAcBgkqhkiG 9w0BCQUxDxcNMDUwODAxMDg1ODAzWjAjBgkqhkiG9w0BCQQxFgQUQPOynlWSwbKaTXKPMdZmFGyp lUsweAYJKwYBBAGCNxAEMWswaTBiMQswCQYDVQQGEwJaQTElMCMGA1UEChMcVGhhd3RlIENvbnN1 bHRpbmcgKFB0eSkgTHRkLjEsMCoGA1UEAxMjVGhhd3RlIFBlcnNvbmFsIEZyZWVtYWlsIElzc3Vp bmcgQ0ECAw0p3DB6BgsqhkiG9w0BCRACCzFroGkwYjELMAkGA1UEBhMCWkExJTAjBgNVBAoTHFRo YXd0ZSBDb25zdWx0aW5nIChQdHkpIEx0ZC4xLDAqBgNVBAMTI1RoYXd0ZSBQZXJzb25hbCBGcmVl bWFpbCBJc3N1aW5nIENBAgMNKdwwDQYJKoZIhvcNAQEBBQAEggEAns+loocxuX5o0VlAAm8LpTPu 5Wo8QGXBVBVSgLw+W+bvS0UfIvtnLfyRC2X85mAZP5vsL6CJ2vrrbGbFQdGtw84OecGr/0hZCpe/ vBR2OVLqjVGmJINH+ym8LRByQc9OlWb7EsHtfP70R8Y5gkDnFmymYXIbd3jyxSi2ZM48dLZYyGWI IX9IrkXKBIg9ASySslOeABsSqu6wvSOcHC+38iY+BuZIOOMIcs1d7BSmx9gzJvLbiEJzsBPAE65M k4ul4BCQZWANEGUaQdfEXshybHgGXI304qsi6Z4J1CtM1aL6PUiKkMmKEpHatMrVd20fXSl/yAbk 7knzXR9KOrjZCgAAAAAAAA== --Apple-Mail-10-698079091--