On 4/17/2017 8:24 PM, Warren Young wrote:
On Apr 17, 2017, at 7:27 PM, Ross Berteig <r...@cheshireeng.com> wrote:
On 4/14/2017 9:15 PM, Warren Young wrote:
On Apr 14, 2017, at 5:09 PM, Ross Berteig <r...@cheshireeng.com> wrote:
1. It doesn’t tell you that globs and regexes are not the same thing.
True, it probably should.I'll work that into the second paragraph.
Better, but I wouldn’t say that regexes and globs are *related* so much as that
they both use some of the same special characters and both come to us out of
the Unix tradition.
I’m a bit of a student of Unix history, and I never recall hearing that globs
were developed from regexes or vice versa. As I understand it, they are just
two competing good ideas that both managed to survive within Unix because they
meet different needs: globs are simpler and thus more suited to ad-hoc pattern
matches on the command line, whereas regexes are more powerful and thus well
suited to scripts and compiled programs where the cost of crafting them can be
repaid many times through reuse.
They share some special characters because ASCII doesn’t have a whole lot to
choose from, not because they’re purposely half-compatible.
They are related because they are both notations for describing patterns
in text. You certainly can transform a glob into a regexp with a set of
very simplistic substitutions. Regexps are stronger in that you can say
more elaborate things.
But I'll reword because it still doesn't quite say what is needed.
3. GLOB is all-caps in Fossil help output because it’s a variable parameter
It is also the SQL operator that implements the pattern.
That feels like plumbing to me, not porcelain. Know your audience.
I'll preserve the all caps usage if I quote the command help, and otherwise use the word
"glob" as short for "glob pattern" most places.
You’ve still got an all-caps GLOB in the first header.
I could weasel and claim I did that because the only likely user
exposure to the term within fossil would be the help text. But instead,
I'll fix it. And also notice that the title here and in mkindex.tcl were
different even before that fix.
Do you prefer "filename" or "file name"?
I had used "file name" or just "name" in most of the text. I used "file
name" in the page title, but "filename" in the version of the title
provided to the index. I've regularized it to "file name" everywhere now.
That whole rest of the section is really just my whining about the state of the
current docs.
Right, but this document fixes the problem, and the eventual readers don’t need
to know there once was a problem. :)
Well, I hope it does at least!
There is no dependency on libics, and since the Image Cytometry Standard has
little impact on us, I'm not that surprised. ;-) ICU on the other hand
Yes, yes, *that* libics. The one where “s” is spelled “u”. :)
But I don't see any dependency on ICU4C, or any other Unicode support library.
See ext/icu/icu.c in the SQLite source code. It’s an optional dependency: you
can build SQLite with ICU or without it.
I didn't know that. But can fossil's build do that and does it take
advantage of it if it does? There's no selection for it in ./configure
and those are just about the only configuration options I've ever
wiggled here.
I also wonder if the SQLite intent was to follow POSIX or just a general sense of
"Unix is like this”.
There’s no one to enforce POSIX conformance in SQLite or Fossil; you can’t get
certified in that way.
But, there’s also no point being needlessly incompatible, if only to avoid
violating the principle of least surprise.
(There’s an obscure POSIX rule that says two leading slashes must be left
untouched...
Windows users expect \\SERVER\Share\some\file.txt to make sense.
Yes, I suspect the POSIX path rule is some kind of sop towards UNC.
Cygwin was able to take advantage of that rule: it understands
//server/share/path/to/file.txt for example. That’s why I know the rule: they
had to be careful not to break that behavior.
Occasionally, some path manipulation code will accidentally build up a double
leading slash on Cygwin, causing the victim to report that Cygwin has suddenly
gotten really slow, and obviously Cygwin has a bug. Then later, we learn that
the code has built up something like //usr/bin/vi, so it’s looking for a file
server named USR with a share called BIN, then taking a long time to get a DNS
timeout on the server name lookup.
Couple that with WINS lookup timeouts or poorly-configured AD DNS setups, and
this sort of error can turn into a major speed trap.
Yup. Been there. Got the bruises.
18. The “Where are they used” and “Platform quirks” headers should be bigger.
I think you have your # character counts mixed up in the Markdown source. (Or
---- where you mean ====, if you do your headings that way; I didn’t bother
looking.)
They are the same header level as Syntax and File Names to Match.
So they are. It appears to be a CSS problem on fossil-scm.org. <h2> is styled as
1.05 em high but <h3> is 1.17 em. Is it a default skin bug or an error in later
hand-customization?
The first header should use “#” rather than ======== styling, for consistency,
though.
I suspect the right answer here is to drop all mention of any matching other
than ms=GLOB, leaving the meanings of EXACT, LIKE, GLOB, and REGEXP in that
context to some other documentation entirely.
I agree. Again, porcelain vs. plumbing.
This entire document is actually about GLOB the SQLite operator.
Yes, but the reader doesn’t need to know that it is implemented in terms of
SQLite’s GLOB. The reader just needs to know what the rules are.
26. If you’re going to cover `.fossil-settings` here at all, make it clear that
this must be at the top level of the checkout directory.
...It is a lot more powerful to just say *.bak in one file instead of needing
it in every folder.
I don’t think we need to justify the way it is. This is just a good place to
document the fact that .fossil-settings/ignore-glob is not *quite* the same
thing as .gitignore. Similar purposes, but not 1:1 compatible.
My sense at the moment is that a separate document that takes either Git, SVN,
or CVS as the example would be the right answer for this since it is so
specific to a single setting.
An alternate viewpoint is that almost everyone using Fossil will have used some
other SCM tool in the CVS .cvsignore tradition, so when they first see the
versioned form of ignore-glob, they’ll go “Oh, I know what that is,” then
proceed to get bit by the impedance mismatch.
Let’s round that speed bump out a bit, ‘kay?
let you see the hash I made to the top half of the document
I stopped at “Platform quirks.” That is the dividing point you mean?
Yes, that is where I realized I should go make dinner and checked it in.
What I see is much better than the first version.
Some of the new material invites more comment, however:
1. “…match files either on the disk or in the active checkout…” Maybe I’m
missing something, but that looks like a distinction without a difference to me.
Probably my tendency to be pedantic poking out. But ignore-glob is
matched to names on disk and not in the repository, see the recent
kerfuffle on fossil-users caused by a new user who checked in a bunch of
fluff then set ignore-glob and was surprised that didn't immediately
stop fossil from tracking the fluff.
I think for an introduction, though, I can soften that to just
"...identify files needing special treatment...."
2. “If a glob must contain commas or spaces, surround it with single or double
quotation marks.” You repeat this two paragraphs later. I’d rather you held
off on this until the Syntax section. (That is, keep the second.)
Sure. Again, introduction can omit a detail for clarity that is
corrected later.
3. “Some examples of character lists:…” I’d merge this list of examples into
the first bullet point, as they are basically just illustrations of this same
point. The next point (…[A-z]…) could merge in here as well. Markdown
supports paragraph breaks inside a bullet point, if that’s all you were after.
I'll fuss with the order here a bit. The first bullet is trying to
define a range in a list, using an example. The next few bullets define
a few special cases that make it possible to name all (printable, at
least) characters in the character list notation.
4. “The glob */README does match src/README…” Maybe add *README as a way to
match all README files in the checkout tree.
But *README also matches YOUBETTERREADME as well as YOU/BETTER/README.
I'll see if I can think up some more compelling examples.
5. “operator in [SQLite][].” Missing link target. But if you remove the
discussion of the plumbing, this will go away anyway.
I rewrote that paragraph and lost that link entirely. I added links to
the documentation of each command and web page to that and nearby
paragraphs.
But perhaps, given the scale of that edit, you should get credit in the change
log for writing it. Richard shouldn't have any qualms about giving you checkin
privileges…
If y’all want me to check that in separately, let me know.
What with the postal holiday here in the US and the postal surge of Tax Day, I
wouldn’t expect my agreement to arrive in North Carolina before Friday.
I ended up having to email him a photo of my signature. I don't know if
the original ever arrived or not. He set up my access minutes after that
email exchange.
Either way, I might poke at the Platform Quirks section this afternoon.
It certainly
--
Ross Berteig r...@cheshireeng.com
Cheshire Engineering Corp. http://www.CheshireEng.com/
+1 626 303 1602
_______________________________________________
fossil-dev mailing list
fossil-dev@mailinglists.sqlite.org
http://mailinglists.sqlite.org/cgi-bin/mailman/listinfo/fossil-dev
