According to Ted Stresen-Reuter: > I've reviewed, briefly, both files mentioned. I'm not sure what they're > purpose is in terms of the whole project (I've been following the > discussion, but not closely - seems like these are default values for > every attribute based on the name), but it seems that the smartest thing > to do would be to write some php code that parses the defaults.xml > document and extracts the documentation from there. I could set this up > to be done on the fly (for each request) or as a php file that reads the > defaults.xml file and outputs a series of html files that could then be > uploaded to the web site (similar to a project I did for BBEdit: > http://www.tedmasterweb.com/glossary/ )
If we do go with PHP, I'd favour the latter approach, i.e. generating all the HTML files at once for the web site. More below... > How much control do we have on the htdig site (can we set options in > .htaccess, or better yet, modify the httpd.conf file directly)? Is > anyone opposed to moving the online documentation to php or to using php > on htdig.org? Can we customize the 404 error page? Can we use .htaccess? www.htdig.org is currently hosted on vhost.sourceforge.net. We definitely don't have access to httpd.conf on this site. We almost certainly have some options available via .htaccess, but I'd expect that it would be a fairly restrictive set that we can actually override. I've never actually looked into what options are set by default and what we can override, because fortunately it's never been an issue. I'd kind of like to keep it that way, so that we keep our options more open as far as where we can be hosted (as well as mirrored) in the future. If we start requiring features of our web service provider, like PHP and certain settable options, it may limit our options in the future, as well as possibly burdening our mirror sites. However, I believe some of the sites currently hosted by sf.net are PHP-based, so I expect it would be feasible to make the switch, other concerns notwithstanding. > Finally, could someone provide a gloss on the doctype declaration in > defaults.xml? I understand the basic structure of xml documents (and > have written a few smil docs by hand) but I could use a little > clarification on this one point. Oh, and, one last thing, why is there > both a defaults.cc and defaults.xml document? I can understand the > purpose of the .cc document, but what is the defaults.xml doc for? Is it > just a pretty way of presenting the .cc doc? I think Lachlan answered the last few questions, and I'll leave it to someone who knows XML to explain the doctype declaration. > One more thing... I tend to try and write XTHML 1.1 Strict copmliant > html. Does anyone have a problem with this? For those who are unfamiliar > with it, XHTML is an XML compliant version of HTML 4. No objection here! We want to make htsearch's output XHTML compliant very soon, hopefully in time for the b5 release, and it would be great to make all the HTML docs XHTML compliant too. ... and later... > Lachlan et al: > > Thank you for the excellent reply. I will use defaults.xml as the master > document for generating the indidvidual attributes pages. > > Geoff? Gilles? Any opinion on moving the documentation to dynamically > generated files using PHP? If so, I would suggest we procede as follows: ... > In addition to creating a dynamic interface into the documentation, I > would maintain the current design so the documentation could be browsed > as well. > > If this is something the htdig development team would like to see, I'll > do it and post my efforts to my own web site for review. I can see how going with PHP on the fly like this would simplify some things. However, my concerns are the following: 1) Right now, with HTML-only documentation, it's very easy to host the site wherever we want, mirror it anywhere, and include the HTML docs in with the source, allowing the end users to put the docs up on their own site easily, or just browse the HTML files directly off their hard drive. Requiring a PHP-enabled web server to host the docs would complicate things for a lot of people. 2) There's a learning curve associated with maintaining PHP files (one I haven't personally climbed yet). It's probably safe to say that most/all developers know HTML, and are able to maintain the docs as they are. Even defaults.cc/defaults.xml are pretty easy to get up to speed on, and the conversion programs for these don't need a whole lot of ongoing maintenance. Going with PHP for all docs might complicate things and reduce the amount of developers available to maintain the docs. 3) We're trying to minimize the amount of dependencies ht://Dig has. As-is, it needs a few libraries, autoconf/automake, and Perl. Adding PHP to the list could conceivably complicate matters for those installing the package, and consequently increase the amount of requests for help on the mailing lists. Using PHP just to generate the static HTML files for the attributes docs should minimize this problem, requiring only active developers to install PHP on their systems. If we do things right, end-users should not have to worry about doing this. However, if we don't use PHP for on-the-fly generation of docs, but just for building static HTML files, does this provide a big advantage over Brian White's scripts? -- Gilles R. Detillieux E-mail: <[EMAIL PROTECTED]> Spinal Cord Research Centre WWW: http://www.scrc.umanitoba.ca/ Dept. Physiology, U. of Manitoba Winnipeg, MB R3E 3J7 (Canada) ------------------------------------------------------- This SF.NET email is sponsored by: SourceForge Enterprise Edition + IBM + LinuxWorld = Something 2 See! http://www.vasoftware.com _______________________________________________ htdig-dev mailing list [EMAIL PROTECTED] https://lists.sourceforge.net/lists/listinfo/htdig-dev
