Rearranged starter process flowchart and added sidebar #416

ramink · 2025-01-05T05:56:28Z

Rearranged to make sure ready check comes before feeding.
Simplified by removing Discard block, and shortening block titles.
Details moved to legend box below.
Changed arrowheads to be cleaner "Latex" style.

- Rearranged to make sure ready check comes before feeding. - Simplified by removing Discard block, and shortening block titles. - Details moved to legend box below. - Changed arrowheads to be cleaner "Latex" style.

cedounet

Please make a PR to the debug branch not main until we decide/iron out details
Add white line (if you have not) after the first line of your commit message, and use imperative style. we don't really have a style. but "Rearrange starter process flowchart" is good, add your details after.
Make sure there is consistency as much as you can... In this case same colors and same arrows in all of the document (exceptions are ok but shall be justified)

Thanks!

cedounet · 2025-01-05T13:33:05Z

book/figures/fig-starter-process.tex

+  \node [fail, right of=limitcheck, node distance = 3.2cm] (abort) { Discard All, Start Over };
+  \node [success, right of=readycheck, node distance = 3.2cm] (final) { Done };
+
+  \draw [thick, -{Latex}] (start) -- (wait);


We will want all arrows in all flowcharts to look the same. So you will need to redefine arrows in flowcahrts_tikz.tex so we don't have to add [thick,-{Latex}] on every single one of them.

Please make sure this doesn't break plots or others flowcharts (or fix the other flowcharts)

I put in a PR for this.

I checked, and to me, it looks like the other figures aren't broken, at least in the web version. There's an inconsistency in arrows, though, still, as there are other places (not flowchart connections) where other styles of arrows are used.

cedounet · 2025-01-05T13:34:01Z

book/figures/fig-starter-process.tex

+  \draw [thick, -{Latex}] (limitcheck) -- node { Yes } (abort);
+  \draw [thick, -{Latex}] (readycheck) -- node { Yes } (final);
+
+  \node [below of=feedok, node distance=2.5cm] (details1) [shape=rectangle,draw,fill=white!90!black]{


colors shall be defined in colors.tex (there is a maingray which migh tor might not be adequate)

Done. maingray seems adequate. It can be revisited of course. (I actually suspect the sidebar is not long for this world anyway, so I don't want to spend more time on it)

cedounet · 2025-01-05T13:36:45Z

book/figures/fig-starter-process.tex

+
+  \node [below of=feedok, node distance=2.5cm] (details1) [shape=rectangle,draw,fill=white!90!black]{
+        \begin{tabular}{c}
+	    \fontsize{7}{9}\selectfont For the \emph{Initial Mixture}, mix \qty{50}{\gram} flour/\qty{50}{\gram} water. \\


Do not use fontsize if you can avoid it, choose from \tiny,
\scriptsize, \footnotesize, \small \normalsize \large \Large but best we don't even change font size.

cedounet · 2025-01-05T13:41:49Z

book/figures/fig-starter-process.tex

+        \begin{tabular}{c}
+	    \fontsize{7}{9}\selectfont For the \emph{Initial Mixture}, mix \qty{50}{\gram} flour/\qty{50}{\gram} water. \\
+            \fontsize{7}{9}\selectfont The Mixture is \emph{Ready} when it has \emph{grown}, has \emph{bubbles}, and \emph{smells} vinegary/yoghurty. \\
+            \fontsize{7}{9}\selectfont The Mixture has \emph{Failed} when you have fed it too many (eg 10) times without success. \\


there is an \eg command in sourdough.sty please use it.... after we can argue if that is common enough in eglish to be in italic or not, but at least will be the same everywhere in the document.

I don't understand what is intended here. Won't that add e.g. before each of them?

Consistency… if we decide to remove italic because e.g. is English enough then we just remove italic everywhere at once.

On top of that In LaTeX, the spacing between sentences is longer than the spacing between words. LaTeX treats periods followed by a whitespace as ends of a sentence.
This leads to incorrect behaviour when using abbreviations like "e.g." or "cf.".

so use the command and we can fine tune the behaviour later…

Ay caramba! I see what you're talking about now. Sorry, I thought we were talking about italics vs bold in the rest of the sidebar. But you were referring to the itty bitty eg I have there! Hahaha. OK, thank you for letting me know about this command. I will update to use it now. In fact, I think everything is ready for MR. Will post shortly, once I do the git incantations.

Actually, I'm having a bit of trouble using it. Here is my code: too many (\eg~10) times

I get errors like this:

! Undefined control sequence. l.45 have fed it too many (\eg ~10) times without success.\\

I based my usage on what I found in mix-ins.tex. Am I using it incorrectly? Is sourdough.sty not being used in figures?

the-sourdough-framework/book/sourdough.sty

Line 38 in 35a0a89

\newcommand{\eg}{\emph{e.g.}\@ifnextchar.{\!\@gobble}{}}

is where this is defined... mwe.tex probably doesn't have it... not sure about standalone figures.

So digging around a bit, I only see sourdough.sty being added to the definition of src_tex in makefile, and I don't see mwe.tex being referenced anywhere, so I don't know how mwe.tex fits into the whole picture. Based on some web searches it looks like mwe stands for minimum working example, and maybe it's being used not to generate any files, but as a sort of internal template for us? If that's the case, I'll stop focusing on it.

As for sourdough.sty, I don't think I have enough knowledge of how these things are put together to connect sourdough.sty to the figure-generating pipeline. Could you nudge me in the right direction, please? For instance, could you tell me if sourdough.sty is being used in mix-ins.tex simply because sourdough.sty was added to src_tex, or if there is some explicit import command somewhere that I have missed, or if there's some other mechanism using it?

Yes I created mwe.tex just for you #393 (comment) in case the figure generation pipeline didn’t work and/or you needed to see how it fits in A4.

and correct this is minimum working example.

don’t worry about the \eg right now if that is too cumbersome… we can come back to it later.

thanks

Oh, I see. Thanks for linking to the comment about the mwe. Reading it over again, I also see that sourdough.sty is not being used only in the quick png generation path. So make website has no problem with the inclusion of \eg~ in the diagram. I can always remove it temporarily when testing, if I want the fast png generation.

I have made a new PR for the fixes that had been remaining in this PR.

cedounet · 2025-01-05T13:42:43Z

book/figures/fig-starter-process.tex

+  \draw [thick, -{Latex}] (readycheck) -- node { Yes } (final);
+
+  \node [below of=feedok, node distance=2.5cm] (details1) [shape=rectangle,draw,fill=white!90!black]{
+        \begin{tabular}{c}


I question the use of a tabular here? but let me experiment a little and come back to you.

Agreed. I had not understood how to use \node [align=left]. Thank you for the example. I changed it in the PR to do it the simpler way.

cedounet · 2025-01-05T13:45:41Z

book/figures/flowcharts_tikz.tex

@@ -1,6 +1,6 @@
 \tikzstyle{every picture}+=[font=\footnotesize\sffamily]
 \usetikzlibrary{calc, shapes, arrows, decorations.pathreplacing, calligraphy,
-                positioning}
+                positioning, arrows.meta}


is arrows needed on top of arrows.meta? Question, I do not know.

arrow is deprecated so now realising we probably don't want.

Having both arrows and arrows.meta does seem to be redundant. I replaced our original arrows with arrows.meta and everything seemed to work fine.

You haven’t removed it yet though?

Sorry, I should have been clearer. I have tried it that way and it looks fine. I haven't committed it yet. I'm trying to reduce the MR request burden by doing it all in one.

ramink · 2025-01-05T19:22:30Z

Thanks for all the feedback!

Let me just clear up one thing before I start addressing the particulars: you said I should make PRs to the debug branch. Looking at what's on GitHub now, it looks like you've already put in my changes there. So I think I should just continue from where that branch is and make a new PR to that branch with changes requested here. I'll respond here, but the changes will be in the new PR. Eventually, this PR will be closed/rejected. Does that sound right?

cedounet · 2025-01-05T20:02:35Z

Goal is to actually merge it once we all agree this is better. We might well realize this is a dead end but definitely not what we want. If nothing else the arrow.meta stuff will go in.
On branches: Yeah I have your changes but just because I copy pasted them(*)... I would rather we have your commits and people add on top of them. If nothing else I am not pretending I wrote what you actually did. So if you make a PR to the debug branch, I will merge it no questions asked and after that you can top with your own changes etc. We iterate this way.
Doing the above history will get messy, so once we are happy with the changes, you will branch out squash and cleanup stuff and make a new PR for main.

Does that make sense? If not or you have a better way we can do it differently.

(*) Only did the copy-paste for the sake of speed as I knew today I had time to look at it and can't guarantee this will happen until next weekend.

ramink · 2025-01-05T20:26:47Z

Goal is to actually merge it once we all agree this is better. We might well realize this is a dead end but definitely not what we want. If nothing else the arrow.meta stuff will go in.

That's what I understood. No problem, we're on the same page there.

On branches: Yeah I have your changes but just because I copy pasted them(*)... I would rather we have your commits and people add on top of them. If nothing else I am not pretending I wrote what you actually did. So if you make a PR to the debug branch, I will merge it no questions asked and after that you can top with your own changes etc. We iterate this way.

I actually have my changes committed to my local copy of the tiks_quick_debug branch. I only committed and PRed things this way because I didn't want to be making changes relative to your makefile changes that I wasn't sure you wanted to keep, and I wanted you to be able to treat the two changes independently. Sigh. So now we have a bit of a git headache to deal with.

OK. I think the best thing I can do is to just make a new PR from my tiks_quick_debug to your one after I have merged in your last few commits. There is still the matter of PRs and PR feedback and so on, but I think in terms of commit history, that will get us to the right place.

As for the PRs etc, I think what I said last time still applies, right? After the merge and PR, I will submit changes to the soon-to-be-requested PR relative to comments made relative to this soon-to-be-obsolete PR. Eventually this PR gets somehow pruned and we won't care about these discussions not being on the new PR. Correct?

Doing the above history will get messy, so once we are happy with the changes, you will branch out squash and cleanup stuff and make a new PR for main.

Does that make sense? If not or you have a better way we can do it differently.

I think so. If what I've said doesn't conflict with what you're thinking, I think we're good.

By the way, when I merge, do you care if I rebase or not?

cedounet · 2025-01-05T20:31:54Z

Yes and yes you can rebase…

ramink · 2025-01-06T06:38:15Z

OK, I think the rebase and PR are done. I learned a lot about git. (again - I hope I don't have to revisit that situation soon)

If things look OK to you there, I will start adding changes according to above feedback next.

cedounet · 2025-01-06T07:04:40Z

Ok closing this one then.

cedounet · 2025-01-09T14:34:11Z

@ramink Do I understand this is now "code complete" (i.e. you addressed all comments from the reviews?) ? If so I will start cherry-picking things one by one?

Thanks

ramink · 2025-01-09T16:07:01Z

That’s correct! Note, fig_starter_process.tex still has both versions in it.

cedounet · 2025-01-09T18:31:21Z

Cool can you post a picture of both block diagrams by side for @hendricius and I to compare?

I will start git fun as well :)

ramink · 2025-01-09T20:56:10Z

Sure. Here it is, literally side by side: live the-sourdough-framework.com version on left, tiks_quick_debug branch on the right. Note again, that the fact that the new version doesn't have the white background is not a deliberate choice on my part (I don't know why it is that way). But please don't consider that part of the comparison. The point is the more correct flow logic, the chart layout, the clearer text, and the new arrow style.

Also, I will eventually argue for the removal of the sidebar/footnote at the bottom, but let's look at this as an interim step. I know, I'm the one who added that extra element :-), but sometimes a middle step is helpful.

cedounet · 2025-01-09T21:44:20Z

I removed it :) and you made me reconsider... all good here

I am reviewing your changes

Can you please fix the circular arrow?

Can you try on plots while at it?:

I would leave timeline arrows as is... they are fine I think.

Thanks

cedounet · 2025-01-09T22:29:19Z

@ramink I cleaned up and merged everything in https://github.com/hendricius/the-sourdough-framework/tree/new_starter_flowchart.

I would suggest you rebase on it yourself and make changes against it?

ramink · 2025-01-09T22:34:01Z

@ramink I cleaned up and merged everything in https://github.com/hendricius/the-sourdough-framework/tree/new_starter_flowchart.

I would suggest you rebase on it yourself and make changes against it?

OK. No problem. I was about to ask where I should commit the circular arrow fixes. You've answered that now: I will put it in the new branch.

Another question, what's the problem with the plots that needs to be fixed? Is it that you want Latex style arrows for the chart axes?

cedounet · 2025-01-09T22:36:02Z

Another question, what's the problem with the plots that needs to be fixed? Is it that you want Latex style arrows for the chart axes?

Yeah it might look better... but not a big deal, the circular arrows it looks really weird because there are other arrows on same flowchart.

ramink · 2025-01-09T23:12:55Z

OK. Thanks for clarification. If I can't figure out how to change the arrows in fig-yeast-sourdough-strength.tex (it's not jumping out at me so far), I will skip that. Agreed, it is less egregious an inconsistency.

How do you feel about TODO comments being put into the source?

hendricius · 2025-01-10T08:31:38Z

@ramink thanks a lot for these great changes and congrats on getting that PR merged. A small step for us, a big step for all the bakers reading the book 😎

cedounet · 2025-01-10T08:45:22Z

@hendricius it is not merged to main yet… but yes I think this is great work.

hendricius · 2025-01-10T08:46:40Z

@cedounet Ah then I was mistaken seeing another branch merged 😎

cedounet · 2025-01-10T10:07:31Z

Yeah it has been a little of a branch fest as I was helping @ramink find his way through TikZ and the code in general...

We are now to the lion's part the actual flowchart layout... @hendricius do you have comments on @ramink's proposition? Things you would like different we could try.

Personally I would like to see less text in the box at the bottom... Ideally just feed the mixture and the "ready/is good?" definition if that is at all possible.

Immediate perfection isn't realistic so if no strong objections or counter proposal I am also happy to merge as-is though.

cedounet · 2025-01-10T19:05:37Z

My

proposal

ramink · 2025-01-11T04:21:25Z

I'm very happy with your proposal, @cedounet. It looks like an excellent compromise in being compact yet informative.

So it's with some hesitation that I offer another alternative to consider, only slightly different to my previous one. My reasoning is that flowcharts don't have to be entirely self-contained and detailed. They are really giving us a bird's eye view of the process in broad strokes. They are as power point slides are to a speech: giving us a skeleton of a framework that will be fleshed out in the discussion. And just like power point slides, trying to put too many details into the slides makes them less effective.

I would suggest something like this:

It's even more compact (due to omission of table) which will help with the layout on A4 media, has less text, communicates the stages very clearly, and as a bonus, the decision diamonds are the same size. I'm even appreciating that the Start node has the word "Start" in it. Note, I've added a little nod to the incompleteness of the information in the caption below the figure ("see details in text" -- perhaps not the best wording). You could even argue that the flowchart ends up being a "hook" drawing the reader in, wanting to know more, and reading the text. Otherwise the temptation will be to use the flowchart and ignore the text.

Of course, it would be even better if the text of this section were massaged into a form that better supports/complements the flowchart. For instance, the term feeding is not explicitly introduced, and doing so would recall and complete the flow chart in a nice way. So each question raised by the flowchart (What's the initial mixture? What is Feeding? What is Failure? What is Ready?) is clearly answered in the text, probably in the order that they are encountered in the chart.

But again, I do like the version from @cedounet very much. Especially in that all the recipes are available immediately. So, really, I'm happy either way! :-)

Rearranged starter process flowchart and added sidebar

d9414ca

- Rearranged to make sure ready check comes before feeding. - Simplified by removing Discard block, and shortening block titles. - Details moved to legend box below. - Changed arrowheads to be cleaner "Latex" style.

ramink mentioned this pull request Jan 5, 2025

Clarity on Starter Flow chart #393

Open

cedounet requested changes Jan 5, 2025

View reviewed changes

cedounet closed this Jan 6, 2025

ramink mentioned this pull request Jan 8, 2025

Bring previous commits in line with standards. #423

Merged

ramink deleted the starter-flowchart branch January 9, 2025 23:44

Rearranged starter process flowchart and added sidebar #416

Rearranged starter process flowchart and added sidebar #416

Conversation

ramink commented Jan 5, 2025

cedounet left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ramink Jan 8, 2025 • edited Loading

Choose a reason for hiding this comment

cedounet Jan 8, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ramink commented Jan 5, 2025

cedounet commented Jan 5, 2025

ramink commented Jan 5, 2025

cedounet commented Jan 5, 2025

ramink commented Jan 6, 2025

cedounet commented Jan 6, 2025

cedounet commented Jan 9, 2025

ramink commented Jan 9, 2025

cedounet commented Jan 9, 2025

ramink commented Jan 9, 2025

cedounet commented Jan 9, 2025

cedounet commented Jan 9, 2025

ramink commented Jan 9, 2025

cedounet commented Jan 9, 2025

ramink commented Jan 9, 2025

hendricius commented Jan 10, 2025

cedounet commented Jan 10, 2025

hendricius commented Jan 10, 2025

cedounet commented Jan 10, 2025

cedounet commented Jan 10, 2025 • edited Loading

ramink commented Jan 11, 2025 • edited Loading

ramink Jan 8, 2025 •

edited

Loading

cedounet Jan 8, 2025 •

edited

Loading

cedounet commented Jan 10, 2025 •

edited

Loading

ramink commented Jan 11, 2025 •

edited

Loading