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. >> 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. > 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. :) > 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 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. >> 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? 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. 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.) 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. 4. “The glob */README does match src/README…” Maybe add *README as a way to match all README files in the checkout tree. 5. “operator in [SQLite][].” Missing link target. But if you remove the discussion of the plumbing, this will go away anyway. > 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. _______________________________________________ fossil-dev mailing list fossil-dev@mailinglists.sqlite.org http://mailinglists.sqlite.org/cgi-bin/mailman/listinfo/fossil-dev
