From: Ted Stresen-R. <ted...@ma...> - 2003-01-09 18:59:35
|
All good arguments for automating the production of flat files and, for the time being, leaving the 404 error page as is. Furthermore, perhaps the best solution is to add the creation of the html documentation to Brian White's scripts. I'll take a look at them (if someone can point me to their current location) and see if I could possibly contribute on that level (I'm not too optimistic, though, as I don't have any significant shell programming experience). If that just seems like too much of a challenge for me for right now, I'll resort to creating the php scripts that do the same thing. Ted On Thursday, January 9, 2003, at 12:01 PM, Gilles Detillieux wrote: > 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: <gr...@sc...> > Spinal Cord Research Centre WWW: http://www.scrc.umanitoba.ca/ > Dept. Physiology, U. of Manitoba Winnipeg, MB R3E 3J7 (Canada) > > ------------------------------------------------------------------------------------ Homepage: http://www.tedmasterweb.com/ My JavaScript Window Management Tool: http://www.tedmasterweb.com/wmo/ |