221261 - glossary has glaring omissions: [http, smtp, gopher, irc, socks], [uri, iri], [xslt], [idn]

Status: VERIFIED FIXED

(Documentation Graveyard :: Help Viewer, defect)

Description

[timeless]

For some reason File Transfer Protocol (FTP) is in the glossary, but HTTP isn't,
nor are smtp, gopher, irc or socks. 
dn is in the glossary, but idn isn't.
url is in the glossary, uri and iri aren't.
neither junk nor spam are in the glossary, they probably should be.
ecmascript isn't in the glossary, i could argue that it should be (not a
showstopper).

Calendar is in the glossary but has no entry.

for some reason world wide web doesn't have (www) after it, nor is WWW listed as
an alias.
for some reason TCP/IP is listed before its expansion in contrast to just about
everything else.

Comment 1

[R.J. Keller]

-> Doc: User

Confirming Bug.

Comment 2

[R.J. Keller]

Daniel, what do you think of these definitions? Maybe you and Nilson can fill in
the blanks and/or give feedback.

HTTP - The protocol used to move <link>HTML</link> across the Internet.
SMTP - A protocol used to send email from the SMTP server to the
<link>POP</link> or <link>IMAP</link> server.
IRC - A protocol used to chat live with over people over a server.
gopher - A protocol used to offer information in a menu format. (?)
socks - (?) Don't remember what this is ;)
uri - An address for a website on the internet.
iri - (?) Never heard of an IRI.
XSLT - Already there, just under Extensible Stylesheet Language Transformation.
I should probably correct this.

Comment 3

[Nilson Cain]

HTTP-  The Protocol used to move most files across the internet, including
<link>HTML</link> files, which webpages are composed of.  This is the protocol
used most of the time.

URI- Universal Resource Identifier.  Similar to a <link>URL</link>.

Comment 4

[Daniel Wang]

maybe use this http://www.geocities.com/rich_smithers/acpage.html ?

Please be consistent on what we put in glossary. If we put in gopher://, then
shouldn't we also put in chrome:// which is also in System Preferences (bug
151780) ?

SMTP - A protocol used for sending e-mail
gopher - A protocol pre-dating the Web used to retrieve information, generally
in a menu format

I don't think we should put in URI and IRI, unless someone can find these terms
used in the Help files. We are still missing defs for Junk, Spam, and IDN.

Are these definitions really useful? Most people can figure things out for
themselves without knowing what these terms mean.

Comment 5

[Bradley Baetz (:bbaetz)]

chrome shouldn't really ever be seen directly by the user. Not sure why its in
the prefs - is that a windows only thing?

Comment 6

[timeless]

For now i'd leave it out of glossary and merely add a help entry for
it in the appropriate pref panel help.

yes it's a windows thing, because we integrate to allow you to load
a .url shortcut to say chrome://navigator/content/

Comment 7

[R.J. Keller]

what's an IRI?

Comment 8

[Christian :Biesinger (don't email me, ping me on IRC)]

an iri is an internationalized resource identifier

Comment 9

[R.J. Keller]

Attachment: Patch

Comment 10

[Daniel Wang]

Comment on attachment 133045 [details] [diff] [review]
Patch

>  (HTTP).</b>&nbsp; The Protocol used to move most files across the internet,

Internet, not internet. But to be correct, it should be the Web. and Protocol
shouldn't be capitalized.

>  including <a href="#Hypertext_Markup_Language">HTML</a> files, which
>  webpages are composed of.</p>

awkward. How about:

+  (HTTP).</b>&nbsp; The protocol used to move most information across the
+  Web, such as web pages.

>  used to chat live with other people live over a server.</p>
should be
+  used to chat live with other people over the Internet.</p>

>  &nbsp; The protocol used to send email.</p>
nitty picky
+  &nbsp; The protocol used to send e-mail.</p>

And if we have HTTP://, we should also have HTTPS://

Comment 11

[[e-mail]]

>awkward. How about:
>
>+  (HTTP).</b>&nbsp; The protocol used to move most information across the
>+  Web, such as web pages.

Still awkward :-P How about: The protocol used to access websites.

Comment 12

[James "Kovu" Russell]

Here's some definitions as well as some fixes to existing entries; see what you
think:

HTTP (Hyper Text Transfer Protocol) - The protocol used to move information
across the Internet by parsing (translating) the <link>HTML</link> protocol.

HTTPS (Hyper Text Transfer Protocol Secure) - The secure version of the HTTP
protocol that uses SSL to ensure the privacy of customer data (such as credit
card information) while en route over the Internet. 

SMTP (Simple Mail Transfer Protocol) - A protocol that transfers e-mail messages
from an SMTP server to the <link>POP</link> or <link>IMAP</link> server.

IRC (Internet Relay Chat) - A protocol used to chat live with other people over
a server using an IRC software client (such as <link>Chatzilla</link>.

Gopher - A menu-based system protocol used to offer information in a menu
format. Mostly deprecated now due to bonafide search engines on the Web.

RELURL (Relative URL) - A URL that's relative to the user's current location;
for example, a Web browser assumes mozilla.org to be http://www.mozilla.org. See
also URL and URI.

Socks - A protocol that uses a system of proxies and sockets to forward client
requests across the Internet. Socks software is built into servers and Web
clients (typically Web browsers).

URI (Universal Resource Indicator) - An address for a Web site on the Internet.
URIs can be either <link>URLs</link> or <a>Relative URLS</a> (RELURL).

XSLT (Extensible Stylesheet Language Transformation) - A language used to
convert an XML document into another XML document or into some other format. For
information on Netscape support for XSLT, see Advanced Preferences - Advanced.

Web page - A single document on the World Wide Web that is specified by a unique
address or URL and that may contain text, hyperlinks, and graphics.

Web site - A group of related Web pages linked by hyperlinks and managed by a
single company, organization, or individual. A Web site may include content such
as (but not limited to) text, graphics, audio and video files, and links to
other Web sites.

URL (Universal Resource Locator) - A string of text characters that point to a
location on the Internet. URLs are full (as opposed to <a>RELURLS</a>); for
example http://www.mozilla.org is a full URL whereas mozilla.org is a RELURL.

World Wide Web - Also known as the Web and by the acronym WWW. The Web defines
the portion of the Internet that is made up of Web pages stored by Web servers
and displayed by clients called Web browsers (such as Mozilla).

iri - (?) Never heard of an IRI.

I think IRI is seriously stretching it... I can't find a definition on this
easily and I'm not sure I should bother.

Comment 13

[R.J. Keller]

> <link>HTML</link> protocol.

HTML is not a protocol.


I see that you're missing <link>'s, but I'm sure that you know that. Great job!

Comment 14

[James "Kovu" Russell]

Attachment: gloss vrev jr 1

pre-patch. Feedback please. There are a couple revisions to existing entries,
new entries, etc.

Comment 15

[James "Kovu" Russell]

I have yet to make a patch out of this; I can do that tonight. I just wanted to
get the changes up for review. Also, note that I'll have to go through the whole
glossary; right now the glossary is not consistent in whether the definition is
ACRONYM (FULL NAME) or FULL NAME (ACRONYM). I prefer the former, because users
are going to search for HTML not Hypertext... because HTML is by far the most
common usage (that's the point of acronyms).

Comment 16

[Daniel Wang]

Hyper Text Transfer Protocol Secure
-> HyperText Transfer Protocol Secure

bonafide <-- no latin please

<p><b id="IRC">IRC (Internet Relay Chat).</b>&nbsp;A protocol used to chat live
with other people over a server using an IRC software client (such as <a
href="#Chatzilla">Chatzilla</a>).
->
<p><b id="IRC">IRC (Internet Relay Chat).</b> A protocol used for people to
communicate with each other in real-time (live).

<p><b id="IRC_client">IRC client.</b>&nbsp;Software that enables users to chat
live with other people over a server using an <a href="#IRC">IRC</a> software
client (such as <a href="#Chatzilla">Chatzilla</a>).
->
<p><b id="IRC_client">IRC client.</b> Software that enables users to talke to
other people in real-time over <a href="#IRC">IRC</a>. <a
href="#Chatzilla">Chatzilla</a> is an example of this.

<p><b id="Chatzilla">Chatzilla.</b>&nbsp;An open source <a
href="#IRC_client">IRC client</a> that enables users to chat live with other
people over a server using an <a href="#IRC">IRC</a> software client (such as <a
href="#Chatzilla">Chatzilla</a>) 
->
<p><b id="Chatzilla">Chatzilla.</b> Mozilla&#8217;s <a href="#IRC_client">IRC
client</a> component (optional install). This component allows users to
communicate in real-time (live) over IRC networks, such as talking to Mozilla
users and developers over Mozilla's <a href="irc://irc.mozilla.org/">IRC
network</a>.

RELURL A URL that's relative to the user <-- where is this mentioned in the Help
files?

Search engine. A Web-based program that allows users
-> Search engine. Web portal that allows users

> SMTP (Simple Mail Transfer Protocol). A protocol that transfers
> e-mail messages from an SMTP server to a POP or IMAP server.

I think there's only one such protocal. Let's keep it simple and use

SMTP (Simple Mail Transfer Protocol). The protocol for sending e-mail messages.

Comment 17

[Daniel Wang]

-> Kovu

Comment 18

[James "Kovu" Russell]

Attachment: gloss rev jr 2

Some changes based on feedback.

Comment 19

[R.J. Keller]

Comment on attachment 133293 [details]
gloss rev jr 2

Daniel, can you review this?

Comment 20

[James "Kovu" Russell]

"RELURL A URL that's relative to the user <-- where is this mentioned in the
Help files?"

It isn't to my knowledge. It's in the Webster's New World Dictionary of Computer
Terms, though. I figure we either dump URI and just have URL or include both
types of URIs (URLs and RELURL).

"I think there's only one such protocal. Let's keep it simple and use SMTP
(Simple Mail Transfer Protocol). The protocol for sending e-mail messages."

It's still "A protocol" so I think it's okay.

See other changes; most of them were made with a couple compromises/rewrites.

Comment 21

[R.J. Keller]

> It isn't to my knowledge.

take it out. I've seen URI used, but never seen RELURL

> SMTP (Simple Mail Transfer Protocol). A protocol that transfers
> e-mail messages from an SMTP server to a POP or IMAP server.

Remove the "from an SMTP server to a POP or IMAP server". It's too complicated.
Just have "a protocol that sends email". I think you misinterpreted what Daniel
said.

Comment 22

[James "Kovu" Russell]

Attachment: glossary rev3 jr

tweaks based on feedback

Comment 23

[James "Kovu" Russell]

Attachment: gloss rev4 jr

oops, forgot to change the URL def

Comment 24

[R.J. Keller]

Comment on attachment 133301 [details]
gloss rev4 jr

Daniel, can you review this?

Comment 25

[Daniel Wang]

> a menu format. Mostly deprecated

use complete sentences: "a menu format, mostly deprecated"

> HTTP (HyperText Transfer Protocol). The protocol used to
> move information across the Internet by parsing (translating)
> the HTML markup language.

Internet != Web
parsing sounds too technical

 HTTP (HyperText Transfer Protocol). The protocol used to
 transfer hypertext documents (web pages) between browsers
 and servers over the World Wide Web.

> IRC client. Software that enables users to chat live with
> other people over IRC using a software client such as
> Chatzilla.

recursive definition: "...using a software client"

 IRC client. Software that enables users to chat live with
 other people over IRC networks. Chatzilla is an example.

> The search engine may search the full text of Web documents
> or a list of keywords, or use librarians who review web
> documents and index them manually for retrieval.

 A search engine may use any combination of full-text
 document search, keyword index, and human-edited database.

> links to relevant web pages.

don't forget doc and pdf:
 links to the relevant web documents.

> Socks. A protocol that uses a system of proxies and
> sockets to forward client requests across the Internet.

what is sockets?

> Socks software is built into servers and
> Web clients (typically Web browsers).

don't think we need this.

> The new Internet Engineering Task Force (IETF) standard
> called Transport Layer Security (TLS) is based on SSL

you might want to link to ssl_help.html#ssl_prefs
and also mention that TLS and SSL are both supported.
Another entry for TLS is probably needed.

> URI (Universal Resource Indicator). An address for a
> Web site on the Internet. By far the most common type
> of URI is a URL.

 URI (Universal Resource Indicator). A compact string of
 characters for identifying resources (text, images, etc.)

> URL (Universal Resource Locator). A string of text
> characters that point to a location on the Internet.

grammar: "that points to"

> Web browser. Software that enables users connected to
> the Internet to visit (or surf) Web sites on the Internet.
> Mozilla and Netscape Navigator are both Web browsers.

 Web browser. Software that enables users connected to
 the Internet to surf (or access) Web sites.
 Mozilla Navigator is a Web browser.

> Web client. Software that makes requests of Web servers.

how about "Software that interact with Web servers"?

> For information on support for XSLT, see Advanced
> Preferences - Advanced.

Let's just mention it's supported.

Portion of the text is based on http://www.w3.org/1999/05/WCA-terms/

Comment 26

[Daniel Wang]

Kovu, do you know how to make patches with cvs?

Comment 27

[Nilson Cain]

patch -u patchfile >> patch.patch

Comment 28

[Christian :Biesinger (don't email me, ping me on IRC)]

>patch -u patchfile >> patch.patch

well, almost :) it is "cvs diff -u filename_of_changed_file(optional) > patch"

Comment 29

[Nilson Cain]

Well, that's what I meant...   I was still thinking about patching a bug in my
tree, so I confused it

*oops*

Comment 30

[Oleg Sidletskiy]

>Mozilla Navigator is a Web browser.

please call it something else, not Navigator, maybe just "Mozilla"

Comment 31

[Mike Connor [:mconnor]]

the browser within the suite is referred to as Navigator still, and will
continue to be called that for a long time yet

if its official documentation, use the official branding, take it up with
drivers@ or staff@ if you want to bitch about it

Comment 32

[James "Kovu" Russell]

"you might want to link to ssl_help.html#ssl_prefs"

For users I think this is too much, especially when you had me remove the
reference to further info on XSLT.

Thinking about it, for SSL and TLS, is this too much info? "TLS runs above
TCP/IP and below HTTP, LDAP, IMAP, NNTP, and other high-level network protocols."

I've checked in and out to CVS before but so rarely I forget every time. I've
never done a diff, but I'll have to learn and it seems pretty easy.

""cvs diff -u filename_of_changed_file(optional) > patch"  What is "(optional)"
exactly? Does the name of the original file not go somewhere?

Revised entries to follow. Please review.

Comment 33

[James "Kovu" Russell]

Attachment: glossary rev5 jr

Comment 34

[Axel Hecht]

Erm.
About the glossary item for XSLT. Has anybody looked for an advanced pref? Right,
there is no pref for XSLT. And that help item doesn't mention XSLT either, no 
idea how that ever went in.

Please add a link to http://www.mozilla.org/projects/xslt/.

This contains essential information about using XSLT on Mozilla and common 
pitfalls.
rlk, could you backport that to firebird?

Comment 35

[R.J. Keller]

> Please add a link to http://www.mozilla.org/projects/xslt/.

I'd prefer not to because if a distributor (Beonex, etc.) wanted to use the Help
docs, they would have to modify this. I'm hoping to have the help docs use
&brandShortName; so that they would have to make little modifications to the
help documents to use them in their distribution.

kovu:
> <p><b id="XSLT">XSLT (Extensible Stylesheet Language
Transformation).</b>&nbsp;A language used to convert an <a href="#XML">XML</a>
document into another XML document or into some other format.

Definition feels unclear to me.

>  stored by <a href="#Web_server">Web servers</a> and displayed by

should be "stored on"


I'll try and review the other words within the next couple of days.

Comment 36

[Axel Hecht]

> I'd prefer not to because if a distributor (Beonex, etc.) wanted to use the Help
> docs, they would have to modify this. I'm hoping to have the help docs use
> &brandShortName; so that they would have to make little modifications to the
> help documents to use them in their distribution.

The link provided is not about Mozilla, but about the details of the XSLT
implementation used. Thus it is completely independent of a distributor or 
branding. In addition, it provides guidelines to filing bugs on XSLT, which 
AFAICT still end up in the mozilla bug database.

> Definition feels unclear to me.
There is no easy explanation of XSLT. XSLT is hard. If you don't care about it,
why not just follow the advice of those that do? The given explanation is as
close as you get to XSLT in one sentence without a lie.

Comment 37

[R.J. Keller]

> The link provided is not about Mozilla, but about the details of the XSLT


I know that. I would just prefer official sources or no sources at all. This is
a glossary, not an encyclopedia.


> implementation used. Thus it is completely independent of a distributor or 
> branding. In addition, it provides guidelines to filing bugs on XSLT, which 
> AFAICT still end up in the mozilla bug database.


If it's indepedent on branding then why does it have guidelines on filing bugs
on XSLT?


> There is no easy explanation of XSLT. XSLT is hard. If you don't care about it,
> why not just follow the advice of those that do? The given explanation is as
> close as you get to XSLT in one sentence without a lie.


I do care about it. This is what I was thinking:
A language used to convert an <a href="#XML">XML</a> document into another format.

Having "into another XML document or into some other format." seemed useless to
me and only cause confusion.

You need to think in the eyes of the user.

Comment 38

[Axel Hecht]

Please either drop XSLT out of the help alltogether or add the link.
Thinking as a user, I want help on XSLT. Of course you could port the 
webpages to the help docs. Or add a link to the webpage.

"into another format" is not what we do.
Say "to another DOM tree". That should cover both xml and html output and even
for text output, we generate a DOM.

Comment 39

[R.J. Keller]

> Please either drop XSLT out of the help alltogether or add the link.
> Thinking as a user, I want help on XSLT. Of course you could port the 
> webpages to the help docs. Or add a link to the webpage.

I strongly disagree. I'll make the patch for this bug and get it in, then. As
much as I love kovu's definitions, we need to go at a faster pace. I'll have
this done tonight.

Comment 40

[Peter Van der Beken [:peterv]]

I agree with Pike on the definition, please change it into something involving
"tree". I personally don't care much about the link.

Comment 41

[James "Kovu" Russell]

"As much as I love kovu's definitions..."

Actually, I was waiting for y'all to figure this XSLT thing out. Speaking as a
"real" user, I don't off the top of my head know what XSLT is, nor do I care, so
I just bowed out of the discussion.

I have a doc on my hard drive at home that will help you to patch; I integrated
all of the new defs into the glossary HTML. I can post it tonight if you can
wait that long.

Comment 42

[James "Kovu" Russell]

Attachment: pre patch HTML file

Ready to go, I believe, except for the XSLT issue.

Comment 43

[R.J. Keller]

Kovu: Can you update the RDF file? Also, if possible, can you make a cvs diff
("cvs diff -u > new.diff" should work) patch? It would make things a lot easier.

Comment 44

[James "Kovu" Russell]

Attachment: Patch

a patch

Comment 45

[R.J. Keller]

kovu: why are you making all of these whitespace changes? It makes the HTML very
difficult to read.

Comment 46

[James "Kovu" Russell]

reassigning to moi

Comment 47

[R.J. Keller]

Kovu: Can we get a new patch? I think your old one is far obsolete :).

Comment 48

[Stefan [:stefanh]]

I think we should just add things that are used in the Help text. 

Comment 49

[Stefan [:stefanh]]

Not much time left, but hope to fix this before 1.8b.

Comment 50

[Stefan [:stefanh]]

Attachment: Glossary overhaul (checked in)

This growed more than intended... The main idea was to add some items to the
glossary, then I noted that having the terms listed in the format Full Name
(Abbreviation) makes it very hard for a user to find the meaning of an
abbreviation, since he/she won't see it in the left pane. So most of those
terms in help-glossary.rdf are now abbreviations only. I think this is the
right way to go.

Terms in the glossary itself are now in the format of Abbreviation (Full Name).
Some terms are in the old format -- when the abbrevation is trivial.

This might however cause some consistency problems, because terms in the help
files are sometimes (not always...) in the Full Name (Abbreviation) format. Not
sure if that is a problem, though.

Also added a bunch of links, fixed the indentation in glossary.xhtml, corrected
a minor error in using_certs_help and changed the copyright date in all the
altered files.

Comment 51

[Ian Neal]

Comment on attachment 173118 [details] [diff] [review]
Glossary overhaul (checked in)

Looks fine to me

Comment 52

[Stefan [:stefanh]]

(In reply to comment #51)
> (From update of attachment 173118 [details] [diff] [review] [edit])
> Looks fine to me
> 
BTW, some credits could probably go to the old patch author, since i ripped some
definitions from that patch.

Comment 53

[Stefan [:stefanh]]

Ian,

Can you check in the patch, please?

Comment 54

[Ian Neal]

Comment on attachment 173118 [details] [diff] [review]
Glossary overhaul (checked in)

Checking in cert_dialog_help.xhtml;
/cvsroot/mozilla/extensions/help/resources/locale/en-US/cert_dialog_help.xhtml,
v  <--	cert_dialog_help.xhtml
new revision: 1.13; previous revision: 1.12
done
Checking in composer_help.xhtml;
/cvsroot/mozilla/extensions/help/resources/locale/en-US/composer_help.xhtml,v 
<--  composer_help.xhtml
new revision: 1.28; previous revision: 1.27
done
Checking in glossary.xhtml;
/cvsroot/mozilla/extensions/help/resources/locale/en-US/glossary.xhtml,v  <-- 
glossary.xhtml
new revision: 1.37; previous revision: 1.36
done
Checking in help-glossary.rdf;
/cvsroot/mozilla/extensions/help/resources/locale/en-US/help-glossary.rdf,v 
<--  help-glossary.rdf
new revision: 1.19; previous revision: 1.18
done
Checking in mail_help.xhtml;
/cvsroot/mozilla/extensions/help/resources/locale/en-US/mail_help.xhtml,v  <-- 
mail_help.xhtml
new revision: 1.52; previous revision: 1.51
done
Checking in nav_help.xhtml;
/cvsroot/mozilla/extensions/help/resources/locale/en-US/nav_help.xhtml,v  <-- 
nav_help.xhtml
new revision: 1.48; previous revision: 1.47
done
Checking in page_info_help.xhtml;
/cvsroot/mozilla/extensions/help/resources/locale/en-US/page_info_help.xhtml,v 
<--  page_info_help.xhtml
new revision: 1.15; previous revision: 1.14
done
Checking in using_certs_help.xhtml;
/cvsroot/mozilla/extensions/help/resources/locale/en-US/using_certs_help.xhtml,
v  <--	using_certs_help.xhtml
new revision: 1.46; previous revision: 1.45
done
Checking in validation_help.xhtml;
/cvsroot/mozilla/extensions/help/resources/locale/en-US/validation_help.xhtml,v
 <--  validation_help.xhtml
new revision: 1.31; previous revision: 1.30
done

Comment 55

[Stefan [:stefanh]]

Marking as fixed. If someone misses any entries, please open a new bug.

Comment 56

[Stefan [:stefanh]]

v