docs/70555: [diff] changes to freebsd-glossary
Niclas Zeising
lothrandil at n00b.apagnu.se
Tue Aug 17 18:47:35 UTC 2004
Hi Giorgos!
Giorgos Keramidas wrote:
> On 2004-08-16 18:41, Niclas Zeising <lothrandil at 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
--
More information about the freebsd-doc
mailing list