Date: Tue, 17 Aug 2004 20:47:39 +0200 From: Niclas Zeising <lothrandil@n00b.apagnu.se> To: Giorgos Keramidas <keramida@FreeBSD.org> Cc: freebsd-doc@freebsd.org Subject: Re: docs/70555: [diff] changes to freebsd-glossary Message-ID: <412252CB.2020708@n00b.apagnu.se> In-Reply-To: <20040817114201.GC6960@orion.daedalusnetworks.priv> References: <200408161841.i7GIfVvZ033191@www.freebsd.org> <20040817114201.GC6960@orion.daedalusnetworks.priv>
next in thread | previous in thread | raw e-mail | index | archive | help
Hi Giorgos! Giorgos Keramidas wrote: > On 2004-08-16 18:41, Niclas Zeising <lothrandil@n00b.apagnu.se> wrote: > > Nice work! Thanks! > > If you can tolerate my knit-picking we can probably get a lot of good > glossary entries out of this. Let's see what we can do :) It's no problem with your knit-picking :) Good feedback is always welcome. > > >>+ <glossentry id="api-glossary"> >>+ <glossterm>Application Programming Interface</glosterm> >>+ <acrponym>API</acronym> >>+ <glossdef> >>+ <para>A set of routines, protocols and tools to make it >>+ easier to develop applications.</para> >>+ </glossdef> >>+ </glossentry> > > > Does this look better as a description of "API" ? > > "A set of procedures, protocols and tools that specify the canonical > interaction of one or more program parts; how, when and why they do > work together, what data they share or operate on, etc." That sounds good to me. It's a more allorund description, and it propably fits better. I'll add it to my diff if it's ok. > > > >> <glossterm>Basic Input/Output System</glossterm> >> <acronym>BIOS</acronym> >> <glossdef> >>- <para></para> >>+ <para>A <acronym>ROM</acronym>-chip with basic software to >>+ provide an interface between sofware and hardware.</para> > > > The term BIOS is some times used in an ambiguous manner, with the actual > meaning depending on the context. For some "BIOS" is the ROM-chip > itself, for others the set of routines that are contained there and help > in bootstrapping the system. For others, it might even be the "text > mode GUI" that the user can use to configure the bootstrapping process. > The term is also very PC/x86-specific, so we might want to capture this > in its definition too. Okay, I try to rewrite and extend the definition of BIOS, so it will become better and more general. Thanks for the pointer. > > >> <acronym>CPU</acronym> >> <glossdef> >>- <para></para> >>+ <para>Also known as the prosessor. This is the brain of the computer >>+ where all calculations take place.</para> > > > This is also an oversimplification, but anyway :-) It was the best I could come up with, I can try and get some more info, but that's IMHO a okay explaation. Maybe i should add something about diffrent architechtures (x86, alpha, etc) as well? > > >> <acronym>DNS</acronym> >> <glossdef> >>- <para></para> >>+ <para>The system that converst humanly readable hosts to ip addresses >>+ and vice versa.</para> > > > Please fix the typo s/converst/converts/. Perhaps we should add an > example here too: > > "The system that converts host or domain names > (i.e. mail.example.net) to IP addresses and vice versa." Yeah, it probably makes it easier to understand. > > >>- <para></para> >>+ <para>A protocol that dynamically assigns ip addresses to a cumputer >>+ (host) when it requests one from the server. The ip assignment is >>+ called a lease.</para> > > > Typo: s/cumputer/computer/. I would also prefer "ip assignment" written > as: "The address assignment is called a <quote>lease</quote>." and IP > capitalized when used to signify the Internet Protocol. I'll fix that. > > >> <glossterm>File Transfer Protocol</glossterm> >> <acronym>FTP</acronym> >> <glossdef> >>- <para></para> >>+ <para>Protocol used to transfer files over a network.</para> > > > I'd probably write this with a bit more detail: > > "A member of the family of high-level protocols implemented on top > of <acronym>TCP</acronym>, FTP can be used to transfer files over a > TCP/IP network." > > This way the reader knows that FTP works only with TCP/IP networks; > it's clear that it doesn't work (at least not without a TCP > compatibility layer) with IPX networks :-) Okay, I'll use your definition, mine was a bit to oversimplicated. > > >> <glossterm><acronym>IP</acronym> Version 4</glossterm> >> <acronym>IPv4</acronym> >> <glossdef> >>- <para></para> >>+ <para>The old IP protocol which uses 32 bits for addressing.</para> > > > I wouldn't call "old" something that is still so widely in use ;-) Well, it's like old in computer terms ;). Isn't IP like 20 years? > > Since IPv4 has played such a major role in the development of what > Internet is today, I'd probably like it a lot better if we expanded the > description a bit. My network connectivity at work SUCKS today and I > can't seem to be able to reach Google, but good idea if you're > interested in expanding this a bit is probably to see how Sun, Cisco or > others describe IP in their own glossaries. > > We can probably "borrow" ideas if not the text itself. I'll see what I can find. > > >>@@ -718,7 +739,8 @@ >> <glossterm>Internet Protocol</glossterm> >> <acronym>IP</acronym> >> <glossdef> >>- <para></para> >>+ <para>A packet transmitting protocol. The basic protocol on the >>+ internet.</para> > > > This should be a reference to "IPv4" since a lot of text that simply > refers to "IP" implicitly means "IPv4". Okay. > > > >> <acronym>ISP</acronym> >>+ <para>A company that gives access to the internet.</para> > > > Capitalize "Internet" please. > > >> <glossterm>Kilo Bits Per Second</glossterm> >> <acronym>Kbps</acronym> >> <glossdef> >>- <para></para> >>+ <para>Used to measure bandwith. The Kilo prefix can be changed to Mega, >>+ Giga, etc. as nessecary.</para> > > > ===> Mental note to myself: > > "Bandwidth" is probably a term that would need clarification for someone > who doesn't know what Kbps means. Do we have a definition of teh term > "bandwidth" in our glossary? No, we don't have a definition of "Bandwith". If it's nesesary it's easily addet thoug. But do we need it? I can always try to make an in-line description of bandwith in the explanation of "Kbps". > > >> <glossterm>Local Area Network</glossterm> >> <acronym>LAN</acronym> >> <glossdef> >>- <para></para> >>+ <para>Network used on a local area, eg office, home etc. Often refered >>+ to as network.</para> > > > I think that "eg" is not a real word and should be written either as > "i.e." or removed as part of a sentence rewrite. "Referred" is also > spelt with two r's. > > >> <glossterm>Mail Transfer Agent</glossterm> >> <acronym>MTA</acronym> >> <glossdef> >>- <para></para> >>+ <para>Application used to transfer e-mails. The most common and well >>+ known is SendMail.</para> > > > Ok, to transfer e-mails... but where and why? When referring to > Sendmail it's probably a good idea to mention that an MTA has > traditionally been part of a BSD system, that Sendmail is included in > the base system for this reason and that there are countless alternative > MTAs with Postfix, qmail and Exim being the most popular today. Okay, I'll fix this. > > >> <glossterm>Mail User Agent</glossterm> >> <acronym>MUA</acronym> >> <glossdef> >>- <para></para> >>+ <para>Application used to display and write e-mails.</para> > > > Used by whom? > > >> <glossterm>Operating System</glossterm> >> <acronym>OS</acronym> >> <glossdef> >>- <para></para> >>+ <para>The underlying programs which controls the computer hardware, >>+ memory and so on.</para> > > > What you describe as "hardware, memory and so on" can collectively be > described as "resources": > > A set of programs, libraries and tools that provide access to > the hardware resources of a computer. Operating systems range > today from simplistic designs that support only one program > running at a time, accessing only one device to fully > multi-user, multi-tasking and multi-process systems that can > serve thousands of users simultaneously, each of them running > dozens of different applications. > > Does this sound better? Yes. We'll use that instead. > > >> <glossterm>Process ID</glossterm> >> <acronym>PID</acronym> >> <glossdef> >>- <para></para> >>+ <para>A unik ID every process gets to distinguish it from all other >>+ processes.</para> > > > Typo: s/unik/unique/. ID cannot be used as an explanation of ID. We > should probably rewrite this as: Unik is the Swedish word for unique :), I must've typed wrong in the rush. > > Process ID (identifier). &os; is a multiprocessing operating > system. A lot of programs might be running "at the same time". > Different programs or even the same program can be loaded > multiple times. The kernel of &os; uses a unique process > identifier (PID) to distinguish between each running program > instance. Okay. > > >> <glossterm>Request For Comments</glossterm> >> <acronym>RFC</acronym> >> <glossdef> >>- <para></para> >>+ <para>A set of documents defining internet standards, protocols etc. >>+ Can be found here: <ulink url="http://www.rfc-editor.org/">RFC-editor >>+ </ulink>. Also used if someone has suggestions on something and wants >>+ feedback.</para> > > > I don't like the way two different descriptions of the "RFC" acronym > blend together. We definitely want to keep them separate; probably in > different paragraphs. You've got i point. I use two paragraphs. > > Regards, > > - Giorgos > Thanks a lot for the feedback. I'll get on doing the changes right away! I'll drop an e mail when the new diff is up. If you have additionall additions, comments or anything. Just yell! :) I'll cc Tom Rhodes (trhodes@) as well. (And the list, forgot the first time ;) Cheers! //Niclas --
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?412252CB.2020708>