Suggested Improvements to HELP

[ceb]

This long note contains what might be a bug report but might just indicate I did not study the documentation enough. It also contains a lot of suggestions triggered by my difficulties as a new user of FreeFileSync.
I've been doing backups every night by copying directory trees to at least two other disks, and occasionally saving one of the backups to another disk. Now I want to automate it, saving a daily backup once per week, month, quarter and year. I picked FreeFileSync based on several reviews and it having a command line option.

When parsing a really, really bogus command it can be difficult to offer a useful error message. Her is the what might be a bug. On a WinDoze 7 system, a command similar to this badly misformed command
FreeFileSync.exe -e:\sourcedir -r:\destdir
yields this error message in a FreeFileSync popup window
Ccnnot find file "C:\Program Files\FreeFileSync\-e:sourcedir".
The ".exe" has been eliminated, the blank befor "-e" has been eliminated, and a backslash has been added.

Now for the suggestions. In some sense these are all nits. None of them make it impossible for someone to get their work done. But some of them might make it unlikely for them to become a user of FreeFileSync.

In the manual, I can click on "Command Line Usage". If I do, it tells me how to hunt down the information, instead of presenting it. It should display the information, to save the user the effort of chasing after it. But if it did, the user would see that the information is not very complete.

Square brackets are often used to indicate optional parameters. Is that the intent here? If so, it would be helpful to say so.

The syntax indicates that everything has to appear in the order shown. Is that really true? Switches are often allowed in any order. Since the non-switch parameters have different file types, there is enough information available to make everything work in any order. Whatever the situation, please tell us.

A global config file sounds very important. I could not find anything about it in help. It is even difficult to find in the manual since I could not find a search feature. Please tell us about it in help. What is in it? What does it do?

The config files sound almost as important, but more complicated since they are plural. I could not find anything about it in help. It is even difficult to find in the manual since I could not find a search feature. Please tell us about it in help. What is in it? What does it do? We also need details of the syntax. The * seems to admit more than one.
In the following read .g as .ffs_gui and read .b as .ffs_batch. Help the user understand which, if any, of the following are valid after the colon and blank.
a.g
b.b
c.g/d.b
e.b
/f.b
g.g/h.g
j.b/k.b/l.b
m.b/n.g/o.b/p.g/q.g/r.b/s.b

The edit switch refers to a configuration. Is that a master configuration file, a configuration file, some combination, or what? Please tell us.

A simple FFS command line with only leftdir and rightdir yields a popup window waiting for me to say "go do it"
I can't understand why, but this is obviously intentional behavior done by folks that have thought about it for much longer than I have. Perhaps the command line needs another parameter, -run or some such. Or perhaps help can cover the situation another way.

A blank in the syntax usually means any amount of white space, made with blanks and/or horizontal tabs. Please tell us so, or warn us if that is not the case.

Some programs allow a command to be split across several lines. If FFS does, please tell us how. If not, a few words after the main syntax description could tell us. Multiline commands might be a useful feature, but I will not suggest it until I have used FFS for at least a year.

Please add an index to the manual. Pretty please with sugar on it, add a search feature.

Thanks for taking the time to read this collection of relatively minor suggestions. I earned my living writing programs starting in 1960. I can tell the time, effort, and care that went into FFS so far. Thank you for all of it.

[Zenju]

Great feedback! I'm busy but I'll give a proper answer ASAP.

[Zenju]

this badly misformed command
FreeFileSync.exe -e:\sourcedir -r:\destdir
yields this error message in a FreeFileSync popup window
Cannot find file "C:\Program Files\FreeFileSync\-e:sourcedir".

This is "fine", in the sense of "garbage in, garbage out" and a direct consequence of how relative paths are handled in general.

I can click on "Command Line Usage". If I do, it tells me how to hunt down the information, instead of presenting it.

Makes sense, fixed!

Square brackets are often used to indicate optional parameters. Is that the intent here? If so, it would be helpful to say so.

The syntax indicates that everything has to appear in the order shown. Is that really true? Switches are often allowed in any order.

A blank in the syntax usually means any amount of white space, made with blanks and/or horizontal tabs. Please tell us so, or warn us if that is not the case.

Yes, but I think that should be obvious. My general style is to avoid words that convey little meaning with the goal of keeping the manual short and thereby maximizing the number of people who would read it.

A global config file sounds very important. I could not find anything about it in help.

This should be explained already further down on the page in section "5. Use a different GlobalSettings.xml file"

It is even difficult to find in the manual since I could not find a search feature.

I think a search feature isn't the best solution. Ideally, the manual should be as succinct and well-structured that the reader can easily find his way. I hope that's the case, but it's extremely diffcult to see problems when you're the author.

The config files sound almost as important, but more complicated since they are plural. I could not find anything about it in help.

The command line use of multiple config files is explained further down the same page in "2. Start a FreeFileSync GUI configuration", and "4. Merge multiple configurations".

But yes, it is not explained what they are in general, partly because it is too trivial. While I don't feel the manual needs to cover the super-basic stuff like "what is synchronization", "what is a configuration", etc. there is a (small?) information gap for first-time and new users. I'm planning to fill this by creating a few "explanation videos" which show basic usage scenarios like "mirror" and "two-way" sync as a screen recording.

The * seems to admit more than one.

No, this is the standard wildcard that stands for any file name. But I expect users to know this because this syntax is used in all file pickers control (=load file button).

In the following read .g as .ffs_gui and read .b as .ffs_batch. Help the user understand which, if any, of the following are valid after the colon and blank.

This should already be explained in "4. Merge multiple configurations"

The edit switch refers to a configuration. Is that a master configuration file, a configuration file, some combination, or what? Please tell us.

I'll clarify this by changing the description text:
"Open configuration for editing without executing it." =>
"Open the selected configuration for editing only without executing it."

A simple FFS command line with only leftdir and rightdir yields a popup window waiting for me to say "go do it"

You mean like: "FreeFileSync.exe -leftdir C:\Source -rightdir D:\Target"? This will immediately start a comparison (unless either of the two folders does not yet exist or "-edit" was passed).

Some programs allow a command to be split across several lines. If FFS does, please tell us how.

I have never heard of this as being a program feature. But maybe you refer to the ability to split a command line into multiple lines via "\" as on Linux.