Issue 525 pristines-on-demand: user guide

[Julian Foad <ju...@apache.org>]

I have started a detailed user guide for the current design.

Attached to issue: <https://subversion.apache.org/issue/4893>
Markdown rendered: <https://lab.trax.im/svn/issue-525/-/snippets/1>

It is initially intended to help ourselves understand exactly what the
current design is and does, especially in the light of possible changes
to this design.

Secondly of course the final version is intended to be for users. It
might currently be a bit too detailed for a final user guide, because of
initially being aimed at the dev community.

The next thing I would like to add to it is a worked example or two.

- Julian

Re: Issue 525 pristines-on-demand: user guide

[Julian Foad <ju...@apache.org>]

Karl Fogel wrote:
> Might it be better to put that file on the branch, [...]

Yes, sure; I'm not really sure why I didn't.

There, r1898819, in 'notes/i525/i525-user-guide.md'.

- Julian

Re: Issue 525 pristines-on-demand: user guide

[Karl Fogel <kf...@red-bean.com>]

On 09 Mar 2022, Julian Foad wrote:
>Daniel Sahlberg wrote:
>> [...] an "iff". I guess this might be the "if and only if" 
>> meaning [...]
>
>Yes it is. OK, can change.
>
>> [...] mismatched quotes.
>
>Thanks. Both fixed now in my local copy.
>
>More substantive reviews are welcome too :-)

Might it be better to put that file on the branch, instead of 
attached to the issue ticket?  On the branch, we could treat it 
with all the usual vc-controlled file techniques...

Re: Issue 525 pristines-on-demand: user guide

[Julian Foad <ju...@apache.org>]

Daniel Sahlberg wrote:
> [...] an "iff". I guess this might be the "if and only if" meaning [...]

Yes it is. OK, can change.

> [...] mismatched quotes.

Thanks. Both fixed now in my local copy.

More substantive reviews are welcome too :-)

- Julian

Re: Issue 525 pristines-on-demand: user guide

[Daniel Sahlberg <da...@gmail.com>]

Den ons 9 mars 2022 15:30Julian Foad <ju...@apache.org> skrev:

> I have started a detailed user guide for the current design.
>
> Attached to issue: <https://subversion.apache.org/issue/4893>
> Markdown rendered: <https://lab.trax.im/svn/issue-525/-/snippets/1>
>
> It is initially intended to help ourselves understand exactly what the
> current design is and does, especially in the light of possible changes
> to this design.
>
> Secondly of course the final version is intended to be for users. It
> might currently be a bit too detailed for a final user guide, because of
> initially being aimed at the dev community.
>
> The next thing I would like to add to it is a worked example or two.
>

Very good!

Two small things:

Under "Functional and Timing Differences" (third paragraph) there is an
"iff". I guess this might be the "if and only if" meaning but I had to
Google it. Can you rewrite it to be more clear for someone not familiar
with the term?

Under Working Copy Format Upgrade and Compatibility, second bullet point,
incorrect formatting of the commands. Looks like mismatched single quotes
and back quotes.

Kind regards
Daniel Sahlberg