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
