I agree with Sebastian's feeling, if we can get away with just appending comments to files, it would be preferable to using a database if possible. The "keep it simple" principle is important here because the doc tools chain is already quite complicated.
The major problem is how to deal with spam and editing the comments that are submitted. Maybe submitting a comment should always just email some admin list, and hold the page in a temporary file, and an admin can approve or edit it when they get around to it. On Sun, May 25, 2008 at 9:24 PM, David Temkin <[EMAIL PROTECTED]> wrote: > This is not related to the documentation effort. The database is being put > in the distro so that LZProject (an end-to-end reference/example app) can go > in, since it requires the presence of a DB and we don't want to require > casual developers to install a separate DB. If a comment-generation tool > were to be written, it could leverage this library... nothing more. > - D. > > > On May 25, 2008, at 1:40 PM, Sebastian Wagner wrote: > > okay, so lets try this. > > I guess this will be integrated into the current doctool ( > http://wiki.openlaszlo.org/LzxdocTool), or will the process of generating > Documentation change? > > > sebastian > > > 2008/5/25 David Temkin <[EMAIL PROTECTED]>: > >> Note that we are about to add a simple database to the OL distro -- Apache >> Derby -- in order to put LzProject in the distro. That might be a good >> starting point rather than files. >> >> - D. >> >> >> On May 25, 2008, at 6:29 AM, Sebastian Wagner wrote: >> >> maybe its better to store the comments in files instead of a database? >> That way people do not need to set up a database connection for the >> doc-tool. If you redistribute the Docs with the Platform people could run it >> out of the box without configuration. >> You just have to figure out something clever for the naming strategy of >> these files and folders. >> For the iFrame you could take simple velocity-templates and people can >> style them in their needed design. >> >> sebastian >> >> 2008/5/25 Henry Minsky <[EMAIL PROTECTED]>: >> >>> I wonder if we could make a general purpose "doc comment" tool, which is >>> an iframe or something in each doc page that fetches,displays, and accepts >>> comments. It could store the doc comments in a database, keyed by some >>> keyword from the doc page. That would de-couple it from the doc tools chain, >>> and also potentially make it useful for other applications as well... >>> >>> So for example the doc page for "datapath" might have this in it, >>> generated by the doc tools >>> >>> <iframe src="doc_comment_page.jsp?key=datapath"> >>> >>> and the doc_comment_page.jsp would generate an html page dynamically >>> drawing the comments from something very simple like a file directory >>> tree. >>> >>> There would need to be a simple admin tool to either moderate submitted >>> comments, or else >>> be able to query for recent comments and delete bogus ones. >>> >>> >>> >>> >>> >>> >>> On Sun, May 25, 2008 at 7:09 AM, Sebastian Wagner <[EMAIL PROTECTED]> >>> wrote: >>> >>>> sorry for my late reply, >>>> I think there is no such tool around. >>>> Would it make sense to start such a project (lzx doctool with dynamic >>>> comment extension?!) ? >>>> >>>> sebastian >>>> >>>> 2008/5/22 P T Withington <[EMAIL PROTECTED]>: >>>> >>>> Yes, we'd all like something like this. People have cited, for >>>>> instance, the way the PHP manual works. >>>>> >>>>> The reference manual is now generated by docbook, so if there is an >>>>> open-source tool that someone knows of that can provide this facility, >>>>> we'd >>>>> look into it! >>>>> >>>>> >>>>> On 2008-05-22, at 08:17 EDT, Sebastian Wagner wrote: >>>>> >>>>> hi, >>>>>> >>>>>> I often would like to add some comments to the documentation and I >>>>>> think I'm >>>>>> not the only one. For example if you use a function xy or LzView and >>>>>> see >>>>>> that something is special about it but no comment on it in the >>>>>> reference, it >>>>>> would be helpfull if there is a *add Comment* function next to each >>>>>> Method. >>>>>> Maybe these comments can go into the *main-docs* and reviewed in some >>>>>> kind >>>>>> of cycle. >>>>>> I know that the docs are auto-generated by a tool and it will by some >>>>>> kind >>>>>> of tricky to link comments into it but I think without comments you >>>>>> will >>>>>> loose the *voice of the community* :) and a lot of experience people >>>>>> got who >>>>>> are using it day-by-day. >>>>>> >>>>>> >>>>>> sebastian >>>>>> >>>>>> -- >>>>>> Sebastian Wagner >>>>>> http://www.webbase-design.de >>>>>> http://openmeetings.googlecode.com >>>>>> http://www.laszlo-forum.de >>>>>> [EMAIL PROTECTED] >>>>>> >>>>> >>>>> >>>> >>>> >>>> -- >>>> Sebastian Wagner >>>> http://www.webbase-design.de >>>> http://openmeetings.googlecode.com >>>> http://www.laszlo-forum.de >>>> [EMAIL PROTECTED] >>>> >>> >>> >>> >>> -- >>> Henry Minsky >>> Software Architect >>> [EMAIL PROTECTED] >>> >>> >> >> >> -- >> Sebastian Wagner >> http://www.webbase-design.de >> http://openmeetings.googlecode.com >> http://www.laszlo-forum.de >> [EMAIL PROTECTED] >> >> >> > > > -- > Sebastian Wagner > http://www.webbase-design.de > http://openmeetings.googlecode.com > http://www.laszlo-forum.de > [EMAIL PROTECTED] > > > -- Henry Minsky Software Architect [EMAIL PROTECTED]
