252780 - Roaming Access needs to be documented in help

Status: RESOLVED FIXED

(Documentation Graveyard :: Help Viewer, defect)

Description

[Stefan [:stefanh]]

The Roaming Access feature and its preferences needs to be documented.

Comment 1

[Ben Bucksch (:BenB)]

I plan to write a tutorial, incl server setup, in the future, but have no time
in the immediate future.

Comment 2

[Prognathous]

Ben, how about posting what you already have at http://kb.mozillazine.org and
letting the community polish it with screenshots, details and tips? This text
can later be used as a base for a section in the Help.

Bug 124029, comment 238 is the only "documentation" that I managed to find so far.

Prog. 

Comment 3

[Ben Bucksch (:BenB)]

I have nothing at all atm, otherwise I would have posted it.

Comment 4

[Prognathous]

Henrik Gemal has just released a new item in his blog about "Using Roaming":
http://gemal.dk/archives/000635.html

I hope that's the kick-start this bug was looking for.

Prog.

Comment 5

[Matt Perry]

Attachment: Help system documentation for roaming profiles

Comment 6

[Stefan [:stefanh]]

Comment on attachment 172128 [details] [diff] [review]
Help system documentation for roaming profiles

Matt, Steffen doesn't do reviews for the Seamonkey help. Ian is the man ;)

Comment 7

[Ian Neal]

Comment on attachment 172128 [details] [diff] [review]
Help system documentation for roaming profiles

You also need to provide help for the "Roaming Users" preferences dialog and
link it into this and also to the preferences help button via pref-help.js

Comment 8

[Matt Perry]

(In reply to comment #7)
> You also need to provide help for the "Roaming Users" preferences dialog

Please clarify. I thought that was what I had already done, unless there's a
second roaming prefs dialog that I don't know about.

Comment 9

[Ian Neal]

If you look at how it is done for other preferences you will hopefully see what
I mean. There usually needs to be a section entitled "<main preference title>
Preferences" which describes the main and any subpages and what the various
buttons, checkboxes, fields, etc are and what they do - in this case it would be
Roaming User Preferences. As well as that you usually need a section on what you
would use these preferences for and further background information as required.

The patch you have provided has a mixture of both sections and I would suggest
splitting them into their separate sections. As previously mentioned, once you
have created it, you need to link the perferences section into the prefs page
help button via pref-help.js

Comment 10

[Giacomo Magnini]

Attachment: Provisional file open for comments.

Here is a slightly modified version of Matt's help. I've tried to split it into
the usual Preferences' style of help guide, but as you know, I'm not very good
in English: feel free to change it drastically! :)
Two issues:
1) I don't think that roaming help should really belong to this file
(profile_help). Maybe it needs a new cs-roaming-prefs-help.xhtml?
2) I had a look at how to link it from pref-help.js, but I'm unsure how to do
that: I do understand that the second argument is the "rdf name" given into
help-toc, and I guessed that the files I should be referencing in the first
argument are top.xul (for the main page) and files.xul (for the item selction
panel), but which is the correct chrome:// strng? :-/

Comment 11

[Ian Neal]

If you look at
http://lxr.mozilla.org/seamonkey/source/extensions/sroaming/resources/content/prefs/prefsOverlay.xul

that gives you the two chrome files you need to add links two from within
pref-help.js whether they link to the same place in help or not depends on how
you create the help.

Comment 12

[Ian Neal]

The file itself seems fine though - thanks.

Comment 13

[Matt Perry]

Is pref-help.js the right place to hook up the help button?  According to bug
244770 the roaming extension needs to be made an optional install component like
Chatzilla and Venkman are now.  If that's the case should the help button hookup
be done when the prefs overlay for roaming is added to the prefs window?

Comment 14

[Giacomo Magnini]

While we are at it: roaming access is not included in windows mozilla installer
builds. Should we note this in the help file?

Comment 15

[Ian Neal]

Other "optional install" components are already included within pref-help.js,
saying that, if the pref panel isn't installed, then the entry in pref-help.js
doesn't do anything anyway, so I'm happy for the two entries to be added.

Yes, it probably is worth mentioning in the help file that roaming profiles only
come as part of non-installer builds.

Comment 16

[Giacomo Magnini]

IS this enough? (right after Roaming profiles heading title):

<p><strong>Note</strong>: This feature is not available yet in the installer
  builds of &brandShortName;.</p>

I'm trying to hook up the help button here. If everything goes well, I will
provide a patch later.

Comment 17

[Giacomo Magnini]

Attachment: First attempt at fixing the bug all at once

Ok, I've made the following:
1) Split preferences from description paragraph
2) Modified pref-help.js to link up the help button to the right sections
3) Modified help-toc.rdf to show roaming profiles under the profile section
(preferences are in their own subparagraph)
4) Added an entry in help-indez1.rdf
5) Added an entry in help-glossary.rdf
6) Added an entry to glossary.xhtml (PLEASE double check!)

Built locally on linux and everything seems to work fine (links work and show
correctly, no js errors in console).
This has gone a little further than planned...

Comment 18

[Ian Neal]

Comment on attachment 172544 [details] [diff] [review]
First attempt at fixing the bug all at once

Looks good to me

Comment 19

[[e-mail]]

Comment on attachment 172544 [details] [diff] [review]
First attempt at fixing the bug all at once

I assume the copyright lines in changed files need updating.

>+        <rdf:li><rdf:Description ID="profile-help-roaming-item-selection" nc:name="Roaming User Preferences - Item selection" nc:link="profiles_help.xhtml#roaming_item_selection"/> </rdf:li>
In the index this should just be called Item Selection. I'm not convinced with
the way you've grouped it either.

>+<p class="noMac"><strong>Note</strong>: This feature is not available yet in
"...not yet available in"

sr=me with these nits fixed, assuming Ben's happy with it.

Comment 20

[Ben Bucksch (:BenB)]

> across multiple installations.</dd>

s/installations/computers/

> For example, you may wish to use
> &brandShortName; both at work and at home keeping your bookmarks, address book,
>  and other settings in sync.</p>

"or a company may want to allow its employees to use their Mozilla profile on
any computer."

> need a local user name and password

on the server, not local

> Roaming profiles can be stored in a local directory for computers that use a
> common file share, or stored on a FTP or HTTP server.  For the latter, you will
> need a local user name and password so that you can access the appropriate
> directory for storing and retrieving your profile.

I'd mention HTTP first, because that's the main usage:
"Roaming profiles can be stored on a FTP or HTTP server. You will
need a user name and password on that server, so that you can have write access
to the appropriate directory for storing and retrieving your profile.
Alternatively, for computers that use a common file share, you can store the
profile in a local directory using the Copy method."

+   <li><strong>Base URL</strong>: Type the URL of the directory where
+   the roaming profile will be stored.</li>

... "This can be an FTP, HTTP or HTTPS URL. FTP is probably easiest to set up on
a home network. In other cases, esp. when transmitting over the Internet, it is
strongly recommended to use HTTPS, because otherwise, all your saved passwords
and bookmarks (depending on your Item Selection) might be read by other people
on the same network."

+ <p><strong>Note</strong>: This is not recommended as the user name
+ and password are stored in clear text in the roaming preference
+ files.</p>

Remove that.
Entering the password each startup/shutdown is not so great. Local storage is
irrelevant (keyboard sniffers can read it anyways) and passwords are not roamed
by default. Use HTTPS, if you care.

Under "Item selection", maybe add (not sure, if people are that dumb):
"If all items are greyed out, make sure to have Roaming enabled."

In any case, please also add:
"You cannot roam your local email, partly because that would take too long. Use
IMAP for this purpose."

Please check the comma settings throughout, e.g. "To enable ...*,* follow" or
"Whenever ...*,* your profile".

Apart from that, it sounds good. Thanks!

Comment 21

[Ben Bucksch (:BenB)]

Oh, and maybe add (at URLs) the following examples:
 <ftp://user@ftp-server//path/to/dir/>
 <http://user@http-server/path/to/dir/>
 The number of slashes is important, esp. the double-slash after the FTP
hostname (but not HTTP), it may not work otherwise, no idea why.
 Servers tested: wu-FTPd and Apache with mod_roaming

References about 4.x roaming with HTTP:
<http://www.klomp.org/mod_roaming/>
  (HTTP MOVE is not used by my implementation)
<http://web.archive.org/web/20020605164606/http://help.netscape.com/products/client/communicator/manual_roaming2.html>

Comment 22

[Giacomo Magnini]

Attachment: Updated patch to cope with Neil's suggestions, ready for checkin after Ben's approval

Updated (C) lines, switched "yet" position and modified the file structure to
be more consistent with the grouping in the toc. Awaiting for Ben approval.

Comment 23

[Giacomo Magnini]

Comment on attachment 172567 [details] [diff] [review]
Updated patch to cope with Neil's suggestions, ready for checkin after Ben's approval

Didin't see Ben comments, so I didn't address them...
Will provide another patch later. Sorry for bugspam.

Comment 24

[[e-mail]]

The double-slash is used in FTP to indicate the server's root rather than the
user's home. For instance, ftp://user@server/dir/file might be equivalent to
ftp://user@server//home/user/dir/file etc.

Comment 25

[Giacomo Magnini]

Attachment: Added Ben suggestions

Comment 26

[Ben Bucksch (:BenB)]

Comment on attachment 172573 [details] [diff] [review]
Added Ben suggestions

Great! Thanks. r=BenB.

For bonus points, use these examples (changes to https and incorporates Neil's
comment):
<kbd>&lt;https://user@http-server/dir/&gt;</kbd><br>
<kbd>&lt;ftp://user@ftp-server//home/user/dir/&gt;</kbd><bt> 
<kbd>&lt;ftp://user@ftp-server/dir/&gt;</kbd>

Comment 27

[Ben Bucksch (:BenB)]

> <bt>

<br>, of course

Comment 28

[Stefan [:stefanh]]

--> Giacomo


Great job!

Just one comment: I wouldn't use <h1> for the "Roaming Profiles" heading since
"Managing Profiles" is the main heading (<h1>).

Comment 29

[Giacomo Magnini]

Attachment: Added new examples, ungrouped Roaming sections and removed h1...

I think this is ready to go. Carrying over r/sr flags.
Can someone please check this in?
TIA, Giacomo.

Comment 30

[Giacomo Magnini]

Attachment: Missed a retun to begin of section, humf...

Comment 31

[[e-mail]]

Fix checked in.