Re: [fossil-users] typos in `fossil help uv'

[j. van den hoff]

this has been addressed recently but not completely. there are still some  
glitches:


12,16c12,16
< repository so that it matches FILE on disk.
< Use "--as UVFILE" to give the file a different  
name

< in the repository than what it called on disk.
< Changes are not pushed to other repositories  
until

< the next sync.
---

repository so that they match FILEs on disk.
Use "--as UVFILE" to give a file a different name
in the repository than on disk. Changes are not
pushed to other repositories until the next
sync.





On Wed, 27 Jun 2018 14:57:43 +0200, j. van den hoff  
 wrote:



patch for `fossil help uv' output:

11,12c11,12

Re: [fossil-users] typos

[Ross Berteig]

On 4/4/2016 11:33 AM, Ross Berteig wrote:

On 4/2/2016 3:40 AM, Svyatoslav Mishyn wrote:
But why that commit [b6b50b12] is marked

as *FORK* in timeline.rss;
and as *BRANCH* in `fossil timeline`;
while here https://www.fossil-scm.org/index.html/info/b6b50b1244796110
looks like usual commit..


Oooh, that's weird.


Possibly not all that weird after all.


At a quick glance at the current batch, it looks like it is calling any
node a *FORK* if there is more than one descendent.


Bingo. The source code here:

https://www.fossil-scm.org/index.html/artifact/09319f9b1c1b31cf4c6340f6ce36c0ba0d1f8fb0?txt=1=186-192

clearly shows that it calls anything with more than one parent a MERGE 
and more than one child a FORK. It even has MERGE/FORK if both cases are 
true. Going out on a limb here, this was by design. A refinement would 
be to distinguish the case of a branch point from a fork, with the 
additional complication of a node that might be both, or even both and a 
merge point. (The same decision is made in the fossil rss command as well.)


So that raises the question of complexity versus clarity. From the 
definitions published in the documentation here:


https://www.fossil-scm.org/index.html/doc/trunk/www/branching.wiki

a branch point is a special case of a fork, even if it is strongly 
intended to be the only kind of fork that normally occurs.


I wouldn't oppose a change to the RSS feed however, if there's an easy 
way to do the right thing. I just don't have that fix at my fingertips.


--
Ross Berteig   r...@cheshireeng.com
Cheshire Engineering Corp.   http://www.CheshireEng.com/
+1 626 303 1602
___
fossil-users mailing list
fossil-users@lists.fossil-scm.org
http://lists.fossil-scm.org:8080/cgi-bin/mailman/listinfo/fossil-users

Re: [fossil-users] typos

[Ross Berteig]

On 4/2/2016 3:40 AM, Svyatoslav Mishyn wrote:

(Fri, 01 Apr 17:50) Ross Berteig:

Even better, Joe has already done that to trunk.


But why that commit [b6b50b12] is marked
as *FORK* in timeline.rss;
and as *BRANCH* in `fossil timeline`;
while here https://www.fossil-scm.org/index.html/info/b6b50b1244796110
looks like usual commit..


Oooh, that's weird. Narrowing to just checkins on trunk, we can see 
several more cases that have done the same thing. Someone more familiar 
with the RSS generator should take a look, it doesn't look right.


https://www.fossil-scm.org/index.html/timeline.rss?y=ci=trunk

At a quick glance at the current batch, it looks like it is calling any 
node a *FORK* if there is more than one descendent. But in all the cases 
covered right now, these are nodes that have branches and are not 
properly a *FORK* as we normally use the term in fossil. (And after 
quickly rereading 
https://www.fossil-scm.org/index.html/doc/trunk/www/branching.wiki I 
think the documentation does agree with that statement.)


It would be better to label it as "Branch Point" or possibly just 
"Branch" for brevity in the RSS feed. Unless it really *is* a fork, of 
course.


--
Ross Berteig   r...@cheshireeng.com
Cheshire Engineering Corp.   http://www.CheshireEng.com/
+1 626 303 1602
___
fossil-users mailing list
fossil-users@lists.fossil-scm.org
http://lists.fossil-scm.org:8080/cgi-bin/mailman/listinfo/fossil-users

Re: [fossil-users] typos

[Svyatoslav Mishyn]

(Fri, 01 Apr 17:50) Ross Berteig:
> Even better, Joe has already done that to trunk.

But why that commit [b6b50b12] is marked
as *FORK* in timeline.rss;
and as *BRANCH* in `fossil timeline`;
while here https://www.fossil-scm.org/index.html/info/b6b50b1244796110
looks like usual commit..


-- 
https://www.juef.tk/
___
fossil-users mailing list
fossil-users@lists.fossil-scm.org
http://lists.fossil-scm.org:8080/cgi-bin/mailman/listinfo/fossil-users

Re: [fossil-users] typos

[Ross Berteig]

On 4/1/2016 7:14 PM, Warren Young wrote:

On Apr 1, 2016, at 7:13 PM, Warren Young  wrote:

On Apr 1, 2016, at 6:50 PM, Ross Berteig 
wrote:

may I recommend just reading /test-all-help cover to cover once
in a while?

Okay.  Back in a few…  A few hours, that is. :)


Aaaand I’m back. :)

I found that page so helpful that I added a link to it from my Fossil
skin’s header.  Recipe:

html "RefMan\n”

Maybe this should be a standard feature?


I've done the same thing, or at least dropped the similar link into a 
prominent place, in several project repos of mine.


If it were to become a standard feature, I think it likely should be 
split into two major sections. One for the web face, and one for the 
CLI. Their audiences are, I think, different kinds of users.


That said, for the task I foolishly just dove into, having them all in 
one document is handy for proofreading and verifying consistency.



I’m not wild about the name RefMan.  I just thought “Help” implied
something a bit more like a user manual than what this link provides,
which is basically a reference manual.


Yeah, this is a pretty bare reference to all commands and web pages. A 
lot is left unsaid, or left to be inferred from the web of see also and 
casual name dropping. Including some additional overview topics in the 
compiled-in help would go a long way to softening some of the sharp edges.



It would be nice if there was a mode for the code that generates this
page to cause it to compress out the redundancy.  That is, instead of
separate annotate, blame and praise sections, I’d prefer a variant of
this page that just listed the three aliases together, with a single
copy of the explanatory text.


The implementation of /test-all-help is probably only seven lines of 
code, and simply spits out a section for each entry in the large array 
built by mkindex. The order in the output is exactly the order in the 
internal array. The new test-all-help command is very similar, except I 
added some options to pick and choose chunks in ways that made sense to 
me but likely aren't the best choice.


The fact that some commands are synonyms is almost entirely discarded by 
mkindex, and would be difficult for the help system to notice right now. 
(In effect, it would have to scan a table sorted by command name to find 
commands that happen to have the same function pointer stored.) But I'm 
sure if we had a mandate to make the help system more useful from the 
web that some combination of improvements to mkindex, the supporting 
data structures, and the page implementation could happen.



But, it’s quite useful as-is.


--
Ross Berteig   r...@cheshireeng.com
Cheshire Engineering Corp.   http://www.CheshireEng.com/
+1 626 303 1602
___
fossil-users mailing list
fossil-users@lists.fossil-scm.org
http://lists.fossil-scm.org:8080/cgi-bin/mailman/listinfo/fossil-users

Re: [fossil-users] typos

[Stephan Beal]

On Sat, Apr 2, 2016 at 3:13 AM, Warren Young  wrote:

> On Apr 1, 2016, at 6:50 PM, Ross Berteig  wrote:
> > To make my spell check easier, I added a new fossil test-all-help
> command, which dumps all the help text to stdout. It is otherwise
> essentially the same as the /test-all-help page.
>
> Good!  When I first read your comment about this, I went looking for that
> command and didn’t find it.  If you hadn’t included the leading slash, I
> wouldn’t have found it in fossil ui, either.
>

Just FYI, for those who don't know this: when the /help page was added we
needed a way to disambiguate like-named pages and commands ('timeline' vs
'/timeline'), so the help system uses a / prefix to mean "web page":

f help /test-all-help

will show the help specifically for that page (which is, perhaps
ironically, only a single line).

likewise:

f help timeline
vs
f help /timeline

(in fact, /timeline was the main reason the disambiguation was needed.)

-- 
- stephan beal
http://wanderinghorse.net/home/stephan/
http://gplus.to/sgbeal
"Freedom is sloppy. But since tyranny's the only guaranteed byproduct of
those who insist on a perfect world, freedom will have to do." -- Bigby Wolf
___
fossil-users mailing list
fossil-users@lists.fossil-scm.org
http://lists.fossil-scm.org:8080/cgi-bin/mailman/listinfo/fossil-users

Re: [fossil-users] typos

[Ross Berteig]

On 4/1/2016 6:13 PM, Warren Young wrote:

On Apr 1, 2016, at 6:50 PM, Ross Berteig  wrote:

...
* "mtime" or "modification time”?

That one’s different, with a much stronger claim: man 2 stat.
That is, it is a ~45-year old term of art, not a neologism.


Well, yes. That one isn't a neologism, it is a symbol retained from an 
era when the linker used to link the original Unix kernel could only 
handle six character names. And since even really really early Unix file 
systems kept distinct fields for access, modification, and creation 
times, it likely is ~45 years old. I likely first encountered it on a 
VAX 11/780 that booted a BSD Unix in the early 80s, but that was still 
quite a while ago.



You can argue that fossil shouldn’t be exposing Unix plumbing here,
but you can’t argue that mtime is not well-understood by those versed in
the art of Unix.


While it is true that any seasoned Unix user (and likely even newcomers 
who grew up on linux and may not even know why their OS has a funny 
name) will recognize it, it is very much a platform-specific bit of 
jargon. It would likely be unfamiliar to anyone having only Windows API 
experience, for instance.


I think in most places that it is used, a longer phrase would fit as 
well in context, and would be clear to both Unix and Windows folks alike.


--
Ross Berteig   r...@cheshireeng.com
Cheshire Engineering Corp.   http://www.CheshireEng.com/
+1 626 303 1602
___
fossil-users mailing list
fossil-users@lists.fossil-scm.org
http://lists.fossil-scm.org:8080/cgi-bin/mailman/listinfo/fossil-users

Re: [fossil-users] typos

[Warren Young]

On Apr 1, 2016, at 7:13 PM, Warren Young  wrote:
> 
> On Apr 1, 2016, at 6:50 PM, Ross Berteig  wrote:
>> 
>> may I recommend just reading /test-all-help cover to cover once in a while?
> 
> Okay.  Back in a few…  A few hours, that is. :)

Aaaand I’m back. :)

I found that page so helpful that I added a link to it from my Fossil skin’s 
header.  Recipe:

  html "RefMan\n”

Maybe this should be a standard feature?

I’m not wild about the name RefMan.  I just thought “Help” implied something a 
bit more like a user manual than what this link provides, which is basically a 
reference manual.

It would be nice if there was a mode for the code that generates this page to 
cause it to compress out the redundancy.  That is, instead of separate 
annotate, blame and praise sections, I’d prefer a variant of this page that 
just listed the three aliases together, with a single copy of the explanatory 
text.

But, it’s quite useful as-is.
___
fossil-users mailing list
fossil-users@lists.fossil-scm.org
http://lists.fossil-scm.org:8080/cgi-bin/mailman/listinfo/fossil-users

Re: [fossil-users] typos

[Warren Young]

On Apr 1, 2016, at 6:50 PM, Ross Berteig  wrote:
> 
> may I recommend just reading /test-all-help cover to cover once in a while?

Okay.  Back in a few…  A few hours, that is. :)

> To make my spell check easier, I added a new fossil test-all-help command, 
> which dumps all the help text to stdout. It is otherwise essentially the same 
> as the /test-all-help page.

Good!  When I first read your comment about this, I went looking for that 
command and didn’t find it.  If you hadn’t included the leading slash, I 
wouldn’t have found it in fossil ui, either.

> I would like to make some nomenclature consistent across the help text, page 
> content, and CLI output.

Yes, go go go!

> And the perennial: "UID", "checkin ID", and lots of similar terms. As far as 
> I know, we never really have settled on the right single word to adopt for 
> what we mean here. I don't have an answer, just noticing again that there's a 
> lot of terms used in the help text.

The biggest confusion I’ve had was in differentiating artifact ID from checkin 
ID from tag, since they’re all somewhat interchangeable in Fossil commands.  
You end up needing to learn how Fossil works internally to disentangle it.

That’s exposed plumbing.

I don’t have a proposal for new porcelain, but I think a pass over the text to 
make it rigorously consistent in terminology would help.

> On a wider content and style theme, I've noticed a few cases where global 
> options (options parsed out of the fossil command line by main() before any 
> subcommand is parsed) are called out explicitly in the help for a subcommand, 
> but not used in a special way.

I agree that this is a problem, but… 

> I'm wondering if we shouldn't add a "fossil" subcommand that is there solely 
> as a placeholder for documentation of things like --args, -R, as well as the 
> general usage line for fossil itself.

…that sounds like an over-obedience to the lesson of the DRY principle.

While extracting global option descriptions to a single location reduces 
redundancy, it means that you have to issue two different “help” commands to 
get all the options that apply to any given command, exchanging code redundancy 
for programmer typing redundancy.  Programmer time has been worth more than CPU 
time and disk space in most software-dependent industries for a very long time 
now.

It would be better if there were just a boilerplate function inside Fossil that 
each “help” function called to include the common options into its own output 
at an appropriate location.

For commands where, say, -R means something a little different from normal, it 
can still call the boilerplate function, then add further details below that:

   When -R is given to the foonly command, it frobulates the emscapulator before
   opening the repository.

> my inner grammar nag is questioning these random non-standard English terms. 
> On the one hand, using a neologism as a jargon term with an exact meaning in 
> this context is probably good. On the other, where plain English would do 
> just as well, it probably should be preferred.
> 
> * "webpage" or "web page”?
> * "filename" or "file name"?
> * "timestamp" or "time stamp”?

These are examples of normal language evolution.  Noun phrases become 
hyphenated, then become compound nouns.  Absolutely normal.

Another one that I often have to teach spell checkers is “filesystem”.

I don’t mind if you break them up.  I’m just saying that they’re perfectly 
cromulent as they are.

> * "mtime" or "modification time”?

That one’s different, with a much stronger claim: man 2 stat.

That is, it is a ~45-year old term of art, not a neologism.

You can argue that fossil shouldn’t be exposing Unix plumbing here, but you 
can’t argue that mtime is not well-understood by those versed in the art of 
Unix.
___
fossil-users mailing list
fossil-users@lists.fossil-scm.org
http://lists.fossil-scm.org:8080/cgi-bin/mailman/listinfo/fossil-users

Re: [fossil-users] typos

[Ross Berteig]

On 4/1/2016 8:08 AM, jungle Boogie wrote:
> I bet if you make some patches, people will apply them.

Even better, Joe has already done that to trunk.

Which I'm glad I checked before I decided to dive in and just do it. But 
that inspired me to take /test-all-help and run it through a spell 
check. (Notably documented to be the reason that page exists.)


As an aside, may I recommend just reading /test-all-help cover to cover 
once in a while? I learned a few things on this pass through it that I 
didn't know were there...


To make my spell check easier, I added a new fossil test-all-help 
command, which dumps all the help text to stdout. It is otherwise 
essentially the same as the /test-all-help page.


I found and fixed a few more simple typos in the help text.

I reworded some help text for grammar and clarity.

I would like to make some nomenclature consistent across the help text, 
page content, and CLI output. I've changed a couple of spots, but 
stopped short of sweeping the entire source kit for all the others. I 
notice that these appear in the help text and in page content (and 
likely CLI output) with inconsistent spelling.


First: "technote", "tech note", "tech-note", "Tech-Note", and more 
variations. I propose that we call them "technical notes" in running 
text (with initial cap and/or plural as appropriate to context), and 
pick one abbreviation and stick to it where a shorter form is preferred. 
I like "technote" for that case, but I'm an engineer (and magician) and 
as such not at all a "normal" user. It looks like DRH intended to use 
"tech-note", but wasn't perfectly consistent. I'm happy with either, as 
long as we are consistent. Note: we should look for any dangling use of 
"event" too, I just noticed that fossil dbstat says "events" not 
"tech-notes".


And the perennial: "UID", "checkin ID", and lots of similar terms. As 
far as I know, we never really have settled on the right single word to 
adopt for what we mean here. I don't have an answer, just noticing again 
that there's a lot of terms used in the help text.


We aren't consistent about what help text begins with a capital letter 
and contains whole sentences. I've touched a number of cases in option 
lists where some descriptions start with a lower case letter. I haven't 
swept for all of them, but having a mix in the same list is jarring.


On a wider content and style theme, I've noticed a few cases where 
global options (options parsed out of the fossil command line by main() 
before any subcommand is parsed) are called out explicitly in the help 
for a subcommand, but not used in a special way. That was part of what 
caused me to write the documentation of environment variables and global 
options. But I'm wondering if we shouldn't add a "fossil" subcommand 
that is there solely as a placeholder for documentation of things like 
--args, -R, as well as the general usage line for fossil itself. Either 
that or the help text for "fossil help" could include it, or even the 
usage text produced by "fossil" with no command at all. I'm not sure 
which is best, or necessarily that we should restrict it to just one of 
those places. It is hard to imagine the mind set of the new user, after all.


Finally, and down at the "can it be worth even thinking about this" 
priority, my inner grammar nag is questioning these random non-standard 
English terms. On the one hand, using a neologism as a jargon term with 
an exact meaning in this context is probably good. On the other, where 
plain English would do just as well, it probably should be preferred.


 * "webpage" or "web page"?
 * "filename" or "file name"?
 * "timestamp" or "time stamp"?
 * "mtime" or "modification time"?


--
Ross Berteig   r...@cheshireeng.com
Cheshire Engineering Corp.   http://www.CheshireEng.com/
+1 626 303 1602
___
fossil-users mailing list
fossil-users@lists.fossil-scm.org
http://lists.fossil-scm.org:8080/cgi-bin/mailman/listinfo/fossil-users

Re: [fossil-users] typos

[jungle Boogie]

On 1 April 2016 at 03:56, Svyatoslav Mishyn  wrote:
> Hello everyone,
> just found some typos:


I bet if you make some patches, people will apply them.


-- 
---
inum: 883510009027723
sip: jungleboo...@sip2sip.info
xmpp: jungle-boo...@jit.si
___
fossil-users mailing list
fossil-users@lists.fossil-scm.org
http://lists.fossil-scm.org:8080/cgi-bin/mailman/listinfo/fossil-users

Re: [fossil-users] typos in docu

[Stephan Beal]

On Wed, Oct 2, 2013 at 1:21 PM, j. van den hoff
veedeeh...@googlemail.comwrote:

 by the by: what is preferred way of reporting such things these days? the
 mailing list or the ticketing system?


The mailing list, please. i'll patch these later today. Thanks!

-- 
- stephan beal
http://wanderinghorse.net/home/stephan/
http://gplus.to/sgbeal
___
fossil-users mailing list
fossil-users@lists.fossil-scm.org
http://lists.fossil-scm.org:8080/cgi-bin/mailman/listinfo/fossil-users

Re: [fossil-users] typos in docu

[Stephan Beal]

On Wed, Oct 2, 2013 at 1:49 PM, Stephan Beal sgb...@googlemail.com wrote:

 On Wed, Oct 2, 2013 at 1:21 PM, j. van den hoff veedeeh...@googlemail.com
  wrote:

 by the by: what is preferred way of reporting such things these days? the
 mailing list or the ticketing system?


 The mailing list, please. i'll patch these later today. Thanks!


Richard beat me to it - your fixes are checked in. Please keep submitting
:).

-- 
- stephan beal
http://wanderinghorse.net/home/stephan/
http://gplus.to/sgbeal
___
fossil-users mailing list
fossil-users@lists.fossil-scm.org
http://lists.fossil-scm.org:8080/cgi-bin/mailman/listinfo/fossil-users