svn commit: r264667 - in /cocoon/gsoc/rgraham/refdoc/samples/annotated-code: doktor-about.txt doktor-future.txt doktor-usage.txt

[rg...@apache.org]

Author: rgraham
Date: Mon Aug 29 18:30:47 2005
New Revision: 264667

URL: http://svn.apache.org/viewcvs?rev=264667&view=rev
Log:
Added the documents created that are to be published. Almost completed the XSLT for publishing. Should be the next commit.

Added:
    cocoon/gsoc/rgraham/refdoc/samples/annotated-code/doktor-about.txt
    cocoon/gsoc/rgraham/refdoc/samples/annotated-code/doktor-future.txt
    cocoon/gsoc/rgraham/refdoc/samples/annotated-code/doktor-usage.txt

Added: cocoon/gsoc/rgraham/refdoc/samples/annotated-code/doktor-about.txt
URL: http://svn.apache.org/viewcvs/cocoon/gsoc/rgraham/refdoc/samples/annotated-code/doktor-about.txt?rev=264667&view=auto
==============================================================================
--- cocoon/gsoc/rgraham/refdoc/samples/annotated-code/doktor-about.txt (added)
+++ cocoon/gsoc/rgraham/refdoc/samples/annotated-code/doktor-about.txt Mon Aug 29 18:30:47 2005
@@ -0,0 +1,29 @@
+// @doktor key:doktor-about
+
+/*@doktor-start type:name
+About Doktor
+@doktor-end
+*/
+
+/* @doktor-start type:description, name:Many Thanks
+
+I'd like to thank the ASF and Google for making this porject a possibility. I think the
+GSoC program is great and I hope that it not only continues, but that I continue my
+involvement with it. I'd also like to thank Bertrand, Russ, and all the other guys on the dev list
+who helped me out this summer. It was a great experience and I thank you all.
+
+@doktor-end
+*/
+
+/* @doktor-start type:description, name:The Project
+
+Doktor is a project in the Cocoon project that is attempting to make it possible
+for Cocoon developers to document the Cocoon system near to the code with
+a novel system of comments that can be imbedded into any text files (XML, java, etc.)
+and then harvested by the system and published into HTML for searching/viewing.
+
+This project still has a long way to go to be where its creator envision it ending but it has
+taken a big leap this summer.
+
+@doktor-end
+*/
\ No newline at end of file

Added: cocoon/gsoc/rgraham/refdoc/samples/annotated-code/doktor-future.txt
URL: http://svn.apache.org/viewcvs/cocoon/gsoc/rgraham/refdoc/samples/annotated-code/doktor-future.txt?rev=264667&view=auto
==============================================================================
--- cocoon/gsoc/rgraham/refdoc/samples/annotated-code/doktor-future.txt (added)
+++ cocoon/gsoc/rgraham/refdoc/samples/annotated-code/doktor-future.txt Mon Aug 29 18:30:47 2005
@@ -0,0 +1,69 @@
+// @doktor key:doktor-future, filetype:text
+
+/*@doktor-start type:name
+Doktor Future
+@doktor-end
+*/
+
+/*
+@doktor-start type:description, name:Better Publishing
+
+Doktor currently is published with a simple XSLT method. In the future it might be done with Forrest or Daisy.
+
+
+@doktor-end
+*/
+
+/*
+@doktor-start type:description, name:More Automation"
+
+While modifying the sitemap and creating html pages that allow easy access to the snippets
+is a functional method of doing things I think that the future holds more automated ways of creating the index
+and publishing a set of doktor comments in a directory structure.
+
+@doktor-end
+*/
+
+/*
+@doktor-start type:description, name:Cleaner XSL"
+
+The state of the XSL files right now is not perfect. Many could be refactored together or
+refeactored themselves to do things more efficiently or effectively. This is especially true of
+the Neutral Doc templates. They could do with some refactoring and some thought on
+whether or not they could be improved in general. Perhaps changing the structure of neutral 
+documents or even changing the current tags to something else at some point.
+
+@doktor-end
+*/
+
+/*
+@doktor-start type:description, name:Better Indexing/Searching
+
+The project needs a more automated and programatic set of methods to index and search
+for keys. This would make doktor a much more interesting project.
+
+@doktor-end
+*/
+
+/*
+@doktor-start type:description, name:Dynamic Publishing"
+
+The doktor project would be greatly enhanced by the ability to search for any terms (not a key)
+and get a reasonable document returned. Currently that would be difficult to do, but it might be that
+you would want to return a document that simply detailed published documents -- those corresponding with a key --
+that were a near match to the sarch query. That mechanism could be established with some use of the see-also
+tag.
+
+@doktor-end
+*/
+
+/*
+@doktor-start type:description, name:Tag Specification
+
+The current set of tags (type values) in the doktor comments is just something that has been scraped together.
+I do not think that it represents the end of what these tags might be. It could be that they get changed completely
+or perhaps they just have the way they are published or used changed. Anything could happen here and I'm sure that
+many improvements could be made.
+
+@doktor-end
+*/
\ No newline at end of file

Added: cocoon/gsoc/rgraham/refdoc/samples/annotated-code/doktor-usage.txt
URL: http://svn.apache.org/viewcvs/cocoon/gsoc/rgraham/refdoc/samples/annotated-code/doktor-usage.txt?rev=264667&view=auto
==============================================================================
--- cocoon/gsoc/rgraham/refdoc/samples/annotated-code/doktor-usage.txt (added)
+++ cocoon/gsoc/rgraham/refdoc/samples/annotated-code/doktor-usage.txt Mon Aug 29 18:30:47 2005
@@ -0,0 +1,31 @@
+@doktor key:doktor-usage
+
+@doktor-start type:description name:neutral-ordering.xsl
+This template does for ordering the snippets in the netral doc for publishing them.
+@doktor-end
+
+
+@doktor-start type:description name:add-attrs-neutralDoc.xsl
+This template moves the name, type, and key into the snippet tag as attributes. It takes in the search query as a parameter.
+@doktor-end
+
+
+@doktor-start type:description name:clear-bad-keys.xsl
+This template clears all snippets out of the document that do not have
+keys that match the search query. It takes in the search query as a parameter.
+@doktor-end
+
+
+@doktor-start type:description name:searchxml-to-neutralDoc.xsl
+This turns the search XML document into neutralDoc format. It takes in the search query as a parameter.
+@doktor-end
+
+@doktor-start type:description name:Search Pipeline
+The search pipeline is pretty simple. It sets the component parameter for the
+Lucene block search to display 100 search queries per page. This is so we can have them all in one place to process, but isn't really a permanent solution. Finally it simply uses the Lucene block's search generator and serializes the result to XML.
+@doktor-end
+
+@doktor-start type:description name:Neutral Doc Pipeline
+The Neutral Doc pipeline has a few stages. First is takes the search query and gets the document returned for that as from the search pipeline. It then hands that to searchxml-to-neutralDoc.xsl. That then moves to addattrs-neutralDoc.xsl, clear-bad-keys.xsl, and finally neutral-ordering.xsl.
+@doktor-end
+

Re: svn commit: r264667 - in /cocoon/gsoc/rgraham/refdoc/samples/annotated-code: doktor-about.txt doktor-future.txt doktor-usage.txt

[Bertrand Delacretaz <bd...@apache.org>]

Le 30 août 05, à 15:28, Robert Graham a écrit :
> ... I had planned to point everything back inside the refdoc block 
> after I completed the docs I was creating for being 'published...

Fine with me!

> ..' My question is, do you want the annotations to the slop block 
> saved in any way?..

You can save the annotated slop block code as a zip file under 
refdoc/misc for example, so that we can find it if we need it later, or 
use it for tests.

-Bertrand

Re: svn commit: r264667 - in /cocoon/gsoc/rgraham/refdoc/samples/annotated-code: doktor-about.txt doktor-future.txt doktor-usage.txt

[Robert Graham <in...@gmail.com>]

> 
> -It would be good to make the refdoc samples self-contained, that is
> avoid the dependency on the slop block (which is not yet annotated in
> SVN). I think using "codebase" in the snippets sitemap instead of
> "slopbase" would enable that. The goal is to make refdoc testable as is
> from SVN, the only exception being IIUC the currently required lucene
> config patch.



I had planned to point everything back inside the refdoc block after I 
completed the docs I was creating for being 'published.' My question is, do 
you want the annotations to the slop block saved in any way?

Thanks,
Robert

Re: svn commit: r264667 - in /cocoon/gsoc/rgraham/refdoc/samples/annotated-code: doktor-about.txt doktor-future.txt doktor-usage.txt

[Bertrand Delacretaz <bd...@apache.org>]

Le 30 août 05, à 03:30, rgraham@apache.org a écrit :

> ...Added the documents created that are to be published. Almost 
> completed the XSLT for publishing. Should be the next commit...

I've had a look at the current state and it looks good, I have just 
three small things to mention:

-The target JDK for Cocoon 2.2 is 1.4, we don't use 1.5-specific 
features like generics at this time. I've corrected the code where 
needed, but please keep this in mind for any changes.

-It would be good to make the refdoc samples self-contained, that is 
avoid the dependency on the slop block (which is not yet annotated in 
SVN). I think using "codebase" in the snippets sitemap instead of 
"slopbase" would enable that. The goal is to make refdoc testable as is 
from SVN, the only exception being IIUC the currently required lucene 
config patch.

-In the same way, it would be good to have all the information required 
to test the refdoc block on the http:// 
samples/blocks/refdoc/index.html page. I think you can get rid of the 
patch-README file and put the relevant info (Lucene config) on that 
page.

Thanks for your work - as you mention more work will be needed to make 
this directly usable for our docs, but all the important parts seem to 
be there.

-Bertrand