search

loopspace / braids

TikZ package for drawing braids
6 stars 1 forks source link

suggestions for documentation improvement #5

Closed nilesjohnson closed 7 months ago

nilesjohnson commented 11 months ago

(continuing the discussion we started at #2, but as a separate issue)

Here are some more specific suggestions I had for the documentation of the tikz library. I could definitely do some of these, if you like (and others, with a little help explaining the parts I don't know). But I'm happy to defer to your judgement and let you handle them (or not) as you prefer.

  1. Section 2.2, line 4 mentions name prefix. Probably this should appear as one of the keys in the left margin, somewhere. It's not in the /tikz/braid/ namespace though, so maybe it should be listed before the 2.1 section break? (Update: oh, this is a general tikz thing that I didn't know about. Maybe a link to the tikz documentation for it?)
  2. Section 2.2, paragraph 2, the last sentence says "This node is not actually rendered, but its anchors can be used..." Do you mean the node doesn't really exist, or just that it's not drawn? What are some examples of the anchors that can be used? I expected something like \node at (braidname.south) {X}; to mark the bottom center of the braid, but it doesn't seem to work. I include name prefix=braidname, but I get Package pgf Error: No shape named 'braidname' is known.
  3. braid/.cd appears in the examples on page 6, but doesn't seem to be documented. (Update: after some testing, this appears to be a tikz change directory command!)
  4. page 3, in the last paragraph before item number 3, says "Replacing the floor pic will change how it is drawn". Does this mean one can draw floor shapes that are not rectangles? E.g., an oval?
  5. Related to the above, how can one draw a rectangular floor where only one of the edges is drawn? Is this possible?
  6. These explanations of braid/every floor and braid/floor <n> might be better placed on page 4, where those keys appear in the left margin. Then, the description in item number 2 on page 2 could be shortened with a reference to further details below.

I made a little example in this commit illustrating what I know about the above items, with several notes about how it might be improved. Here is a link to the pdf output.

nilesjohnson commented 11 months ago

p.s. I know people also ask about braids on tex.SE too. If you think that would be a better place for these questions, I'm happy to move there (maybe split into one question for nodes, and another for floors).

loopspace commented 11 months ago

I think here is the right place for this, especially since it's not really questions on how to do stuff but rather on how to improve the docs.

I'll take a look at your detailed comments/suggestions soon - the nature of my day job means that I tend to work on this stuff in bursts.

nilesjohnson commented 11 months ago

Great! (And no worries about timing; I'm in a temporary lull with my work so I wanted to record most of my ideas while I can; I think that's basically done now.)

loopspace commented 10 months ago

Been procrastinating, so have made a start on this.

  1. Added a footnote about name prefix

  2. The node doesn't really exist, in that there is no \node command that defines it. Rather, the stuff that TikZ/pgf remembers about a node is defined. I've had a go at making that clearer. I've tried \node at (braidname.south) {X}; and it works as I expected. Here's my code:

    \begin{tikzpicture}
\pic (braid) {braid={s_1}};
\node at (braid.south) {X};
\end{tikzpicture}

    So it is the pic that needs a name, and that name can involve a name prefix but doesn't have to.

    I've added an example.

  3. I've added a few notes about TikZ keys, there are probably a few others that are similarly less well-known.

  4. (and 5 & 6); I've added some more detail and examples on the floors.

I've also merged your node_anchors.tex into the repository so that I can take a look at it and see what else you've got for me there.

nilesjohnson commented 10 months ago

This looks great! I'll have to look at the floor examples later, but a quick glance seems like your new examples will resolve my questions.

For the anchor and name prefix, I still had errors trying to use it, and (after looking at the tikz documentation) I realized that the name prefix will also be concatenated with the anchor name, but without any intermediate character. This is in contrast with your other examples of name prefix, where there are dashes. (I now realize you must have added those internally.) So, I figured out the following example that combines the examples on pages 6 and 8. 

\begin{tikzpicture}[ultra thick]
  \pic[
  braid/.cd,
  name prefix=pfx,
  crossing height=.5cm,
  gap=.15,
  width=-1cm,
  anchor=north east,
  ] (B) at (1,2) {braid={1 s_1 s_2 1}};
  \draw[<-,cyan] (pfxB.east) -- +(1,0) node[right] {east};
  \draw[<-,cyan] (pfxB.west) -- +(-1,0) node[left] {west};
  \node[at=(pfxB-3-s),pin=north west:strand 3 start] {};
  \node[at=(pfxB-1-e),pin=north west:strand 1 end] {};
\end{tikzpicture}

Screenshot from 2023-10-13 08-20-08

In this example, the prefix, pfx and the anchor name B, have to be concatenated for things like (pfxB.east) and pfxB-3-s. (A sentence like this might be useful in the documentation, but probably you can find a better phrasing that avoids "...things like....".)

There are two other things I wanted to note that are related, but slightly tangential.

  1. For a novice, it's confusing to have so many different things called braid in the examples. Perhaps you would consider changing the examples on pages 6 and 8 (and maybe elsewhere?) so that the prefixes or anchors are a different word, and are different from eachother? (I don't think that my pfx and B are great choices, but I didn't have better ideas.)
    As a joke, the worst possible choice might be to choose name prefix=br and anchor name (aid) in my example above. Then the node references would look like (braid.east) and (braid-3-s), just like they do in the other examples! The second worst choice would be to leave both the prefix and anchor as braid, and then the node references would have to be (braidbraid.east) and (braidbraid-3-s).

  2. Working on this example made me realize that the "height" attribute is used on page 6. Presumably you plan to replace these with the new crossing height, but I wanted to make a note so it's not forgotten.

EDIT: I've now updated my node_anchors example to resolve 3/5 of the items there. I can probably resolve the last one (about floors) later. I've also included the above example (since that's where I tested it). The changes are here.

loopspace commented 10 months ago
nilesjohnson commented 10 months ago

Oh, this is great!

  • I've removed name prefix from the documentation. There's no need to introduce it here - if a user knows about it from TikZ then they will know how to use it, and if not then it's just confusing. All the examples with name prefix now just use name (or \pic[...] (name) at ...) and the documentation now explains how that affects coordinate names.

I think this makes a lot of sense. It's a useful thing to know about, but this documentation can't (and shouldn't) be a comprehensive tikz tutorial.

  • I've adjusted the examples so that each one uses a new name (even between the library and package examples).

:+1:

  • I've replaced all height by crossing height in the examples and tweaked the documentation of this key.

I think this is nicely done. I noticed that you left the negative value crossing height=-1cm for the example on page 6. I don't know if that was intentional or not (to demonstrate that the negative value is ignored). Combined with the negative width=-1cm, it seems like a pretty subtle example to me. A novice (who hasn't read page 4) might ask whether it's the negative height, or the negative width, that flips the picture. Since the braid is s_1 s_2, I think it's ambiguous.

A simple way to clarify would be to make it less symmetric. For example, a fourth strand that doesn't cross with the others, or changing the braid to s_1 s_2 s_1, or something else. Or, maybe you just want to change that crossing height to be positive, or, just ignore this; I think it's minor.

  • There's an example with a floor redefinition, I've also added one in to your node_anchors.tex file.

Thanks!! Your clarifications there are really helpful :)

I don't know if you intended to make that file a permanent part of the tests, or just added it for ease of working. You're welcome to delete it or keep it, as you like best (consider it public domain if necessary). If you keep it, you might consider deleting and/or editing the text so it's not so much of a discussion between just two people. (Or, you can leave it; it's fine by me either way.)

  • Also, in node_anchors.tex, I think I've answered your question about numbering the strands. If I've gotten that wrong, please clarify that for me.

Yeah, that's perfect! If I'm reading the history correctly, this isn't a new thing, but just something that I missed before and you've now highlighted a little more on page 5 of the documentation. Maybe it would make sense to add a forward reference like "(See section 2.3.)" to that explanation, since the next two examples don't use the start/end anchors?

(Alternatively, you could incorporate start/end anchors into the example on page 6, for the placement of the three dots. But, I can appreciate if you just want to focus on the simplest set of changes that will let this issue be done. That can include ignoring or postponing this suggestion too!)

  • Do you think it would be useful to introduce a key that changes the default behaviour of the crossings? In my libraries then I do try not to impose my own assumptions on how things should be. So there could be a key that just swaps the over/under interpretation of a group element.

I've thought a lot about this. Actually, it was something I thought about before any of these other suggestions. Maybe that's an indication that it's something other people might want too. But, the more I thought about it, the more I decided that I can draw the braids that I want with the functionality as is, and I could instead focus on understanding (possibly helping to improve) that functionality. That's why I didn't bring it up before.

So, I don't know anymore! Over the past few weeks that we've been discussing things here, I've been looking at various sources for what's "standard" braid presentation/notation, and, especially considering across the different areas of math that use braids (from geometric topology to category theory), it doesn't seem like there is any one standard. People use over/under crossings, up/down drawing, and diagrammatic/functional composition. So, maybe that's another indication that it would be useful to have an easy way to flip crossings.

An option to flip crossings will effectively double the number of ways that any particular braid can be drawn by this package, so, that does make it more flexible. But it also adds another factor of 2 in the ways that people might be confused, especially when trying to learn to use the package. (Insert here: standard arguments for/against perl's "there's more than one way to do it" design principle.)

One balance to think about might be how many examples should or could be included with the documentation if this feature is added. Is one example sufficient? (Maybe; that's a genuine question that I'm not sure how to answer.)

Really, it would be cool to have this option. But, will the implementation be easy/simple, or will it be something that becomes a development burden over time? Maybe that's a discussion for a separate github issue. Feel free to tag me if you make one :)

loopspace commented 10 months ago

Documentation updated in 1970bd91c8d7207b06c3da5d9c173d9efd9a016e and crossing switch in 75f3679b1661b352870e5bfc5c44b12e4ff2e1e6 (the first of these is the most recent).

I'm curious as to what examples are the most useful. I think that the Examples section is the place for "showing off" the package (such as the circular braid) but there may be more places in the main documentation where a small example would be illustrative.

nilesjohnson commented 10 months ago

Fantastic! It looks like the crossing switch was not that difficult after all. If I'm understanding correctly, you basically just take the inverse of each crossing, which I think is reasonable. One subtlety though, is that this reverses the order of crossings specified by ranges like s_{1-4}, and that leads to some unexpected behavior. In ff01c7431d0a691599dd6cefa1a77f48ee717153 I extended the crossing tests to use braid={s_1 s_2^{-1} s_1^1 s_{1,4} s_{1-4}} and here is how the output looks. Screenshot from 2023-10-26 09-20-57

I can imagine 3 possible options:

  1. Leave this as is, and add to the documentation an explanation that crossing switch inverts the braid and therefore changes the order of crossings in s_{1-4}. (So, just accept that this is probably a violation of user expectation.)
  2. Leave the implementation the same, but change the name of the option to something like invert crossings, with explanation that this is a way to change crossings, but also reverses order for hyphenated subscripts.
  3. Change the internal implementation somehow to better match user expectation for crossing switch. (I don't know whether this is a reasonable option.)

... there may be more places in the main documentation where a small example would be illustrative.

You've already addressed my initial questions with the examples you've added/adjusted, so I think they're great! I don't know that any more examples are needed.

Since you asked though, I looked for places where an option was described, but no example followed. I noticed that the following options aren't demonstrated where they're described, but they do occur in the showy examples later.

So, you might consider a simple example of two braids side by side, one with the defaults for all of these, and one with some noticeably adjusted values for each one.

Another thing I noticed is that there isn't actually any example right after the new crossing height, just some examples for pic options. So, you might consider a simple example demonstrating that too. If you move the explanation of width before the height options, then you could demonstrate that at the same time.

I decided to make some simple examples of what I mean: 5937520. You could use these, or maybe combine them to one example, or decide it's not worth it (I almost feel that way now). image

loopspace commented 10 months ago

Ah, so what I've done replaces each braid element by its inverse, which means that since s_{1-4} is s_3 s_2 s_1 then it becomes s_1^{-1} s_2^{-1} s_3^{-1} but if the idea is simply to exchange over/under crossings then it should become s_3^{-1} s_2^{-1} s_1^{-1}.

And here was me thinking I was so clever in implementing it the way that I did - which was simply to invert the meaning of ^{-1}. But "swap over and under crossings" definitely means that the diagram should look the same but with all crossings switched. I think that shouldn't be too hard. I just need to switch the over/under meaning at the point where the paths are built. Now, if only I'd documented the code a bit better ...

The behaviour of s_{1,4} is still slightly ambiguous in that there's the question of the unused strands. As in your pictures, s_{1,4} causes strands 1 and 4 to swap places, leaving 2 and 3 alone. With both crossing conventions, strands 2 and 3 are behind strands 1 and 4. My inclination is to leave that as it is even with the crossings flipped. So set crossings=under only affects crossings that are explicitly described, which in the case of s_{1,4} means the crossing between strands 1 and 4, but not those involving 2 or 3.

How does that sound? Your point about the expected behaviour is key in this, I think. I don't want a repeat of the height issue that kicked all of this off!

An example showing all the lengths sounds like a good one.

loopspace commented 10 months ago

It's possible to have both behaviours: swap the meaning of ^1 and ^{-1} and swap over/unders. I think that set crossings fits better with the latter, so if you have a suggestion for a name for the former then that would be great!

nilesjohnson commented 10 months ago

ha ha, well I also thought inverting the generators was clever :) I think set crossings with values of under or over seems reasonable. Another option would be something like crossing convention=over (or under).

As a name for the other option, maybe something like invert generators=true? It's not quite ideal, because the shorthand s_{1,4} and s_{1-4} aren't really generators (at least, not in any standard presentation). Checking the documentation, I see you refer to the exponent of each s_{...}, so maybe negate exponents or invert exponents (inverting in the multiplicative group {+1,-1})? Those names may not be intuitively obvious without explanation, but then at least the user wouldn't have any strong expectation before reading the description.

Oh, here's another idea along these lines: the essential difficulty in coming up with a name here is that there isn't a word for the braid symbols that this package accepts ("generators" is too specific, and "braid expression" is too general). So, another option would be that you make up a term, like "braid symbols", "braid tokens", "braid primitives", or something better (without the redundant word "braid"?). Then, the option name could be invert symbols or whatever, and it would be perfectly clear. Is that worth the overhead of adding more terminology? Maybe (and maybe having a name for these things will make it easier to talk about them elsewhere).

About s_{1,4} specifically, I actually hadn't even noticed that the intermediate strands don't get swapped to the front! So, I guess that's a vote that user expectation (at least for me) is to leave them in the back. Now that you've mentioned it, I can't think of how I would get this package to draw the truly flipped version (with, say, strands 1 and 4 crossing behind strands 2 and 3). Do you know of a way? If not, maybe that's a vote for implementing it somehow (but this doesn't have to be the time to figure it out, if you don't want)!

loopspace commented 9 months ago

Okay, the latest commit addresses these:

Getting the intermediate vertical strands to go over the top of the crossing in s_{1,4} would be quite tricky to implement. When passing behind then the vertical strands need to be broken in the middle, which is easy to do. But if passing in front then the crossing strands would need to be broken at some non-central places, which is quite hard to figure out. So I'll keep it with just the current behaviour until someone persuades me that there's a real need for them.

Commit: https://github.com/loopspace/braids/commit/e15835477b02c896ff71bfce568685bb5a5ef288

nilesjohnson commented 9 months ago

This is great! The two new examples are particularly good; marking the various lengths controlled by each option in the second example is a great idea.

The only minor issue remaining for me is that I find set symbols=under to be sort of unclear. But, I understand the advantage of having both new options take the same values, and I don't have any idea for a better option. (Also, I understand the irony of making this complaint, after I specifically suggested using an option that the user would have no implicit expectation for!)

Maybe one actionable suggestion is to clarify the documentation in a couple of ways:

Both of these facts are strongly implied by what you've already written, but I can't tell anymore whether I would understand that just from what's there, or because we've already been discussing this so much. Anyway, this is getting down to really minor nitpicking, and I think the thing is in awesome shape overall!

Lastly,

Getting the intermediate vertical strands to go over the top ... I'll keep it with just the current behaviour until someone persuades me that there's a real need for them.

I think this is really a great idea. If someone reads about that in the documentation and decides it's really important to them, then maybe they'll also bring some new ideas for how to do it.

loopspace commented 9 months ago

I put in a little table showing the effect of the crossing convention and set symbols! See https://github.com/loopspace/braids/commit/0b5939068c897601a5b6b5a359c37d1d2cdea480

I'm feeling like this is converging on a CTAN release soon ... so if you have any niggles, however minor, please do say.

nilesjohnson commented 9 months ago

Awesome! The table is a fantastic idea. I think maybe an extra sentence or two might help, to explain the meaning of the phrase "The equivalences of this". I'll think a little more about this, and do a careful reread of the whole thing, this week.

One minor immediate thing is that the test file tests/crossings.tex doesn't compile, because it appears to use the old option names. Maybe that won't be part of a ctan release, but you probably want to fix it anyway ;) I'll get back to you with any final comments toward the end of the week.

nilesjohnson commented 9 months ago

It's almost the weekend! I finished my reread, and had just a few more suggestions.

Everything else looks good to me. I wondered if anything weird would happen combining the new crossing options with the floor and/or node examples in sections 2.1 and 2.2, but I didn't see anything unusual or unexpected!

loopspace commented 9 months ago

All excellent suggestions, implemented in 11a6d7371d96919e1f7834da451495d77164e2fd

loopspace commented 7 months ago

This has now gone to CTAN, so I'm closing this issue. Any new suggestions will be very welcome, but in a new issue.

Thanks again for all your help!