November 16, 1998 To: [email protected] Fe: Lyno Sullivan <[EMAIL PROTECTED]> Re Debian Dictionary
At 09:18 AM 11/16/98 +0000, "Oliver Elphick" <[email protected]> wote: >Adam Di Carlo wrote: >Thanks for the ideas, but I haven't got time to write all these up! >Please concentrate on the method for getting the dictionary written, >before we worry about the content! That includes finding some >eager volunteer to put it together. I am willing to volunteer to help with this, as a learning task, provided that I can understand the process. If I have to create an SGML file now I am in trouble. If I can gather definitions and put them into an HTML file then I will be OK. I began by wondering, would it be possible, or even sensible, to use the FAQ-o-matic approach that would let people add definitions via the web? I am not obliquely volunteering to write the Dict-o-matic software, maybe later. Assuming suitable software doesn't exist, let me propose how I would handle this if it were mine to do now. A SIMPLE HTML EXAMPLE Let's use the example Debian This word is a contraction of the names of Debra and Ian Murdock, who founded the project. In an HTML Glossary, this could be stored as: <DL> <DT>Debian <DD>This word is a contraction of the names of Debra and Ian Murdock, who founded the project. </DL> WITH ANCHOR So that other documentation could create a URL pointing to the Debian Glossary, it might be smart to create an anchor. <DT>Debian would become <DT><A HREF="#Debian">Debian</A> IMAGES The matter gets more complicated if we include images. We might want to create a two column table or some other presentation technique. Since Debian has an icon image, we could add the image to the Glossary. <IMG src="Pics/banner-blue.gif" border="0" hspace="0" vspace="0" alt="Debian GNU/Linux" width="310" height="29"> The issue with images is that we would have to point to a permanent directory path on the user's local machine. This would imply there is a standard library of documentation and presentation jpeg images somewhere. Is there such a directory that can always be assumed. LINKS We would also want to add links to suitable web sites and documents. These would look like <A HREF="http://www.debian.org/";>Debian</A> SEPARATE FILES Putting all this together and we start to get a very big file. If the file gets too big people won't have the patience to download it, to lookup a simple word. That got me to thinking that one file wasn't a smart way to go. I wonder if we wouldn't be smarter to put all the definitions into a directory, with each definition in its own file. This approach has the advantage that it simplifies the issue of languages and clarifies the matter of the GNU/Linux dictionary, the Debian Dictionary, etc. Let me explain. SEPARATE DICTIONARY OVERLAY Let's assume that the user wants to build a final run-time Dictionary. When a user is installing the Dictionary they could begin with a copy in all the base English definitions. The install could then replace the English definition files with whatever definition files (of the same name) that might exist in their preferred language. In this manner they would always have a full set of definitions, albeit, many of them in English for a while, until the native language definitions were written. Maybe having definitions is separate files might simply the matter of automatically translating the definitions and then sending the raw translations to a native language review team, for final editing. Each installation could build the user's dictionary by copying in one Dictionary after another to end up with the final dictionary. For me the order would be: GNU/Linux Dictionary English Base Debian Dictonary English Base Overrides Debian Dictionary English Extensions GNU/Linux Maintainer Dictionary Debian Maintainer Dictionary A Suse install would use the Suse Overrides and Extensions. I might choose to keep the Debian Base and Extensions and also add the Suse and Redhat Extensions so that I get the Debain base with the extra terminology of the other releases. All documentation can create a URL pointing to the Word Definition File, within the Dictionary Directory, secure in the knowledge that the preferred definition will be there, each as a separate file within the Dictionary directory. The approach of separate Definition Files and Dictionary Directories that overlay one another, seems the easiest all around, based on my limited understanding of the technical issues. SUMMARY By the time I made it through my thinking, I ended up thinking we should create a Dictionary Item Template HTML file and ask people to complete them and send them in. When I think about the process issues, I imagine that CVS is the best place to store the definitions, so people don't overlay one another. CVS is well beyond my abilities at this time but I can easily email HTML definition snippets to [EMAIL PROTECTED] or some similar input point. Then, of course I kept pushing the notion to the absurd extreme of saying: maybe the entire documentation could extend the "separate definition item file" and the "dictionary directory overlay" scheme to the point where every section of documentation ought to be a separate file. Debian-doc should work with the LDP to build the GNU/Linux Encyclopedia (maybe the GNUpedia) and debian-doc would write the pieces that comprised the Debian Base and the Debian Extensions and help out with whatever else arises. Then I went crazy. Who is to say that I shouldn't start adding my cooking recipes into the GNU Encyclopedia, so they are available in time for the GNU Cookbook software. I started thinking about namespaces, search engines, etc. Then I got a headache and quit thinking. The Encyclopedia model makes sense because it means we are writing many discrete sections that would stand alone, but can refer to each other. I like this notion for one special reason, my pet "proof of concept" project is to create a standardized way that all Gnome applications can connect their application into a context sensitive GNU Help Facility. Having thousands of little files makes this task seem, somehow, less daunting. Also, I can always be assured that a specific piece of context sensitive help will be their, possibly in the user's preferred language. The thought of hooking into Anchor points, within multiple-language documents, seemed impossible. My hopelessness increased when I imagined having to cajole the documentation maintainers to leave their frigging anchor points in their documents. The notion of tens of thousands of little files that would always be there and have something useful to say seemed a whole lot more practical. I also saw how I could fit into that world. As I stumble along I would seek out the specific Tip file that could get me over my hurdle. If I didn't find one where it belonged, maybe I could stop to create one. If I found a generic GNU/Linux Tip that was wrong for Debian maybe I could create a Debian override file. I actually saw how this could work pretty well. I knew that a documentation producer could create some kind of a "Master Document" that could pull out selected pieces and assemble a somewhat coherent printed copy of the manual of my choice. But, given all that I saw, I am still unsure that I didn't make some really fundamental error along the way. I will be interested in the feedback. Does any of this make sense? LICENSING I believe Debian needs a Dictionary where all the definitions are GPL'd (or LGPL'd if we want to support mixing with non-copyleft'd definitions). I am uncomfortable supporting any copyleft license that is not listed on the "What Is Copyleft?" <http://www.gnu.org/copyleft/copyleft.html>. I chose Debian GNU/Linux above all other releases, specifically for this reason. I hope these ideas might be helpful. I am willing to help but I will need guidance to figure out how. Thanks for any feedback you might provide. -- Copyright(c) 1998 Lyno Sullivan; this work is free and may be copied, modified and distributed under the GNU Library General Public License (LGPL) <http://www.gnu.org/copyleft/lgpl.html> and it comes with absolutely NO WARRANTY; mailto:[EMAIL PROTECTED]
