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

[brandonne]

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.

>Yeah, well about the SGML->(online) Documentation.. its a long one but here 
>goes. Seek3r wants the documentation to be portable, so it can be viewed 
>outside phpGW by external servers and client.(specificly I don't have 
>examples)  the API has functions to enable the XML functionality without all 
>the extra compiled dependencies, I don't know how this is in performance. 
>Requireing that external developers build docs in SGML and then compile to 
>HTML for help is just going to cause peopel to just create the html and skip 
>the docbook part, they care about the way it looks, not with it fitting into 
>the grand scheme.  Help Searches would be easier to implement if the data 
>was tagged.  I was arguing that any processor time, on what would be static 
>data, is too much processor time, but I think the overhead on this would be 
>low enough not to matter.  But I guess we aould need to see it to know for 
>sure.

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.  

What sort of XML functionality is built in to the API?  I currently don't have 
any access and I'm about ready to kill someone at @home.

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.

As for searching, the indexes should be built before they are actually used 
anyway right?  I don't see any reason that we can't build the indexes from XML 
and use that to point to the HTML.


>>What I was envisioning was sort of a php wrapper that created the >manual 
>>directory tree on the left side and on the right side displayed >the html, 
>>that way it's not linking to the html, but pulling it in to >the php.
>
>That was my origonal idea basicly. and my understanding of yours, but I can 
>see some longterm advantages of doing the docs XML style.  The logic for 
>pulling apart the docbook style SGML should be easy to hack out.  So I can 
>throw it together and try and get some idea of how reasonable it is to do.
>
>I have some personal feelings from a theory standpoint about all this XML 
>standards crap.  Kind of like I did with certian graph theory in an Automata 
>class.  It seems that you have some basic XML concept.  and then you add a 
>few rulles to how it should be laid out, and people treat it like it is some 
>whole other creature.( I know not what we were talkign about).
>
>But I am going somewhere with it.
>We could build a simpler XML style document based on the more specific SGML 
>format, and have something a bit more easy to parse or display, as HTML 
>itself can even be formatted in an XML style.  Actually I had thought about 
>this.  Assuming browsers wouldn't try anything funky, we could have custom 
>XML tags that would be overlooked by browsers, and be useable for searches 
>and feeding the data to off server locations.
>
>- Josh
>
>_________________________________________________________________
>Get your FREE download of MSN Explorer at http://explorer.msn.com/intl.asp
>
>
>_______________________________________________
>Phpgroupware-docteam mailing list
>address@hidden
>http://mail.gnu.org/mailman/listinfo/phpgroupware-docteam