Re: [Phpgroupware-docteam] Yes I said something Crazy about the manual

[Dan Kuykendall (Seek3r)]

address@hidden wrote:
> 
> On Thu, Nov 08, 2001 at 02:28:28PM -0600, Josh Miller wrote:
> >Id apreciate the server access.  I used to have a firewall I ran tests on,
> >but it went in May.
> >
> >I think Seek3r has decided to come up with a list of REQS for the inline
> >docs.  Hopefully he will ge that done this evening, and we can mold what is
> >in the CVs and what you have around them.
> 
> I have a simple program that can pull out the code documentation and get in 
> online until Seek3r has whatever he's working on ironed out.  I think having 
> it online will encourage other developers to update thier documentation.
> 

Cool. I will check it out.

> 
> My one caveat about this whole project is it seems to be getting 
> exponentially more complicated.  We don't even have a decent basic system 
> working and we worried about exporting to as yet unknown apps.
> I don't understand why the documentation has to be exportable, it's written 
> specifically for this app, not for another client or server.  It's hard 
> enough that we have to deal with multiple themes, it will be even harder if 
> we have to consider different clients.
> We can still have precompiled HTML along with the SGML on the same machine, 
> of all things, file system space should fall far below performance in 
> priorities.
> 

I agree. I think the talk about docbook has been over blown, and I think
a point I keep making is being overlooked/unnoticed.
I *dont* want our docs to be written in DocBook. I want to come up with
some *very* limited number of tags for our own custom xml documentation.
It would only need maybe 10 tags for everything we want. Since this will
then be a very basic xml file, it will be very easy to turn it into html
using some template for the manual. It can be converted to text very
easily, can be turned into real docbook by directly mapping some of our
tags (which will be, as I said a very limited subset).
So for the manual, I want to read these xml files and generate html on
the fly. This way any app that the user has rights to will seamlessly
plugin. We can also make sure one of the tags can be used for an inline
help system.

For the developer docs I want to have a javadoc type comments in the
code with a few extras so that we can generate WSDL. WSDL can be done
dynamicly, or staticly. The html/text and such will be done staticly
with some script.

> Which people are going to skip Docbook and write the HTML directly?  Right 
> now no one is doing anything, and once we have a standards document, writing 
> it in DocBook will be no more difficult that writing it in HTML, with the 
> added advantage that it can be put in printable and online documentation as 
> well.
> 

I think that if the number of tags are very limited and clear, people
wont mind using our xml format.

Seek3r