Another suggestion I would like to make is that it can also make sense to split up the manpage into more than one. For example, there could be a syncevolution_config (5) manpage that lists and gives explanations of all the configuration properties, so that the syncevolution (1) manpage could just focus on the command-line switches. The man pages of many other programs with substantial configuration files are organized that way (ssh, sshd, openssl, dhclient, ntp, smb, and others come to mind).
--Todd Todd Wilson, PhD Department of Computer Science California State University, Fresno On Wed, Apr 16, 2014 at 1:05 PM, Patrick Ohly <[email protected]>wrote: > On Wed, 2014-04-16 at 19:43 +0200, Emiliano Heyns wrote: > > More specifically, I think we need to converge, not diverge the > > terminology. I *have* diverted from the existing syncevolution > > terminology where I think they suggest commonality where there is > > none; perhaps the technical implementation of the configuration of > > target-config and sync config share code, but if my understanding of > > them is correct, their behavior is non-trivially different, and that I > > have reflected in new naming. > > > > I am in no way specifically enamored by the new names I introduced, > > and I'll gladly swap them for others, but to have 3 sets of terms in > > play is not going to be helpful I think. > > I agree, we need to agree on updated terminology and (where necessary) > functional changes before we can adapt HOWTOs. The problem with the > HOWTOs is (and always has been) that many users will be on SyncEvolution > 1.4 or even older for a while to come. > > Any new HOWTO depending on new functionality will have to be very > explicit about the version of SyncEvolution that it depends on, and we > cannot remove the "old" content that it replaces right away. > > Regarding converging: we can follow two approaches or perhaps phases. > > First we reach consensus on key terms. Contentious (or at least not > explicitly accepted) are: > > * "originating source" in a local sync (proposed by me). > * "source" vs. "store" (I think both Todd and Emile preferred > store). > * "Client Endpoints" instead of "sync configs" (Emile) > * "Synced stores" as new term for the per-peer source properties > (Emile) > > The next phase then would be to pick the exact wording for README.rst, > using these agreed terms. We should do this using git commits in actual > repos, to facilitate merging and change tracking. If someone wants to > propose new text for the README.rst, please clone the new "doc" branch > in http://cgit.freedesktop.org/SyncEvolution/syncevolution/?h=doc and > post patches in "git format-patch" style to the list. Optionally also > push the updated git tree somewhere (github?), in particular if it > involves merges. > > I've push my own proposal there, but it is not final because I think I > will pick up more of your proposals once their is consensus on terms. > > Regarding the new terms, here's my position: > > +1 for "originating source". I think it is needed. > > +1 for "store" instead of "source". I agree with Todd's explanation that > the source incorrectly implies a data direction. > > -1 for "Client Endpoints". This is misleading because the same thing is > also needed for servers. "sync config" covers both because it is > neutral. > > -1 "Synced stores". This just doesn't sound right to me, but I cannot > quite nail why. Perhaps because I simply don't think of this as real > entities, just as some additional settings for a source (or soon, > store). > > > -- > Best Regards, Patrick Ohly > > The content of this message is my personal opinion only and although > I am an employee of Intel, the statements I make here in no way > represent Intel's position on the issue, nor am I authorized to speak > on behalf of Intel on this matter. > > > >
_______________________________________________ SyncEvolution mailing list [email protected] https://lists.syncevolution.org/mailman/listinfo/syncevolution
