Re: Debian Documentation: Debian Dictionary
November 16, 1998
To: debian-doc@lists.debian.org
Fe: Lyno Sullivan <lls@freedomain.org>
Re Debian Dictionary
At 09:18 AM 11/16/98 +0000, "Oliver Elphick" <olly@lfix.co.uk> 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 debian-dict@lists.debian.org 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:lls@freedomain.org
Reply to: