divergence from mathbook

[Alex-Jordan]

I'm worried about two things. One is that the dev branch of MBX keeps getting improvements added to it that we can't immediately take advantage of. The other is that we are occasionally doing things like getting the basic siunitx commands to works, and not having a good way to share that back with MBX.

Do we want to rethink our development process? We could work more similarly to how I do WBWK stuff here. There is the master and dev branches at the MBX origin. Say we have a new feature to work on, like <quant>. We could checkout a new branch based off of origin/dev and develop <quant>. Then when we are happy, merge it into our own branch that we call omd. Meanwhile, since we branched from origin/dev, if the feature is appropriate, we can submit a pull request to MBX. All the while we would gain the improvements to origin/dev, or we could merge them directly.

I think that the Github openmathdocs organization would fork MBX. That's where we would do our xsl editing. Rather than omd2tex.xsl, etc, we'd modify MBX's xml2tex.xsl with version control. It would get the additions Rob puts into his origin/dev and our own additions, and with version control, we could ensure ours trump his when wanted.

Then this precalc repo would just become xml source for our precalc chapters, along with our tex preamble - no xsl in the precalc repo.

What do you think about all this? When we set things up in that coffee shop, I didn't understand a lot and had an impression that the xsl files were more closely linked to the content of Rob's book than I now understand them to be. I'm comfortable with the idea now of dropping a separate omd2tex.xsl etc, and just having an omd branch of MBX with its own xml2tex.xsl. (And what's more, that would uniformly apply to all our future books, not just one.)

[cmhughes]

I think I like this idea, it seems to make a lot of sense: we would have the option to easily incorporate updates/improvements from 'MBX upstream'. I didn't intend to diverge so far from Rob's template, but it doesn't handle a lot of the things that we need it to; for example, multiple objects next to each other, subtables, subfigures, our 'core' problems idea, etc (but that's not really relevant here).

Just to clarify then, we would have something like the following set-up, where origin represents https://github.com/rbeezer/mathbook :

openmathdocs/mathbook (forked from origin) | master (tracks origin/master) | dev (tracks origin/dev) | omd (does not track origin/dev, but could receive updates at will)

openmathdocs/precalc (our own repo) | master (eventually only contains xml and mainfile.tex) | dev (contains lots of stuff) | pureLaTeX (legacy branch, eventually gets deleted)

To clarify, we would need to push/pull work to/from two separate repositories? In the long-run, I don't think this will be a big deal; in the short-term, it might be a small pain, but nothing major.

I like the sound of this approach, as it will scale nicely; once we've completed precalc (!!!) we can move on to something else (e.g pre-college). With Obama's proposal (http://time.com/3660891/obama-proposes-free-community-college/) openmathdocs could become hugely successful (if we can get enough people to contribute); all we need is a robust template, which I think we nearly have....

[Alex-Jordan]

That's about what I was thinking except for one thing. Each time you have a new feature to work on, you don't work directly on dev or omd (or master). You make a new branch for the feature. For example:

openmathdocs/mathbook (forked from origin) | master (tracks origin/master) | dev (tracks origin/dev) | omd (does not track origin/dev, but could receive updates at will) | quant (tracks origin/dev - work here only on code related to quant; when done, merge with omd and possibly pull request to MBX; possibly delete branch once merging an pull requests are handled)

Yes, we'd be working in two repos. The chapters folder of precalc can be elevated to the repo's root folder (or maybe not). From in precalc/, you'd execute commands like xsltproc ../mathbook/xsl/xml2tex.xsl functions.xml and you'd want to be sure that mathbook was in the omd branch or the appropriate feature branch.

Or from in mathbook/xsl/, after editing a .xsl file, you'd run xsltproc xml2tex.xsl ../../precalc/functions.xml

Let's let it stew a few days before we do anything. Actually in my case, it will be next weekend before I can return to this.

I'm a bit unsure about Obama's proposal. Free CC is good. But Federal management of schools is a mixed bag. We'll have to see if details come out. Meanwhile, in Oregon, there is a proposal in the legislature to make community college free and pay with taxes, and another separate plan where you'd go to community college for free if you sign up to pay back 1.5% of your income over the next 20-30 years.

On Sun, Jan 11, 2015 at 12:20 PM, cmhughes notifications@github.com wrote:

I think I like this idea, it seems to make a lot of sense: we would have the option to easily incorporate updates/improvements from 'MBX upstream'. I didn't intend to diverge so far from Rob's template, but it doesn't handle a lot of the things that we need it to; for example, multiple objects next to each other, subtables, subfigures, our 'core' problems idea, etc (but that's not really relevant here).

Just to clarify then, we would have something like the following set-up, where origin represents https://github.com/rbeezer/mathbook :

openmathdocs/mathbook (forked from origin) | master (tracks origin/master) | dev (tracks origin/dev) | omd (does not track origin/dev, but could receive updates at will)

openmathdocs/precalc (our own repo) | master (eventually only contains xml and mainfile.tex) | dev (contains lots of stuff) | pureLaTeX (legacy branch, eventually gets deleted)

To clarify, we would need to push/pull work to/from two separate repositories? In the long-run, I don't think this will be a big deal; in the short-term, it might be a small pain, but nothing major.

I like the sound of this approach, as it will scale nicely; once we've completed precalc (!!!) we can move on to something else (e.g pre-college). With Obama's proposal ( http://time.com/3660891/obama-proposes-free-community-college/) openmathdocs could become hugely successful (if we can get enough people to contribute); all we need is a robust template, which I think we nearly have....

— Reply to this email directly or view it on GitHub https://github.com/openmathdocs/precalc/issues/12#issuecomment-69509542.

Alex Jordan Mathematics Instructor Portland Community College

[cmhughes]

Yep, that sounds good.

I am on board with this, but I do still think that the omd branch of mathbook may be quite divergent/different from origin/master. With the process you've outlined, it would be much easier to bring in the changes from origin.

For this week, I'll keep pushing changes as I have been.

[cmhughes]

I've been thinking about this a lot, and I'm still on board with the idea. I do have the following scenarios to consider, though:

scenario 1 (a feature that MBX accepts)

We make a feature using

git checkout dev
git checkout -b <nameOfFeature>
<do work>
git commit -m ...
git push ...

submit a pull request to the OMD branch, and one to MBX (origin/dev). If MBX accepts the change, we run

git checkout dev
git pull

and dev is now up to date, and OMD is exactly the same as dev and origin/dev

---

scenario 2 (a feature that isn't accepted by MBX)

Assume the same process as in Scenario 1, except that MBX does not accept our work. In this scenario, the OMD branch has now diverged.

How would we update this feature (that is not a part of origin/dev)? Presumably we would have to keep the feature branch alive, as we could no longer branch from origin/dev.

It is, of course, still possible to merge updates from origin/dev, but there may be conflicts.

---

If we are to go down this route, perhaps it is worth considering adding a final line to each of mathbook-latex.xsl and mathbook-html.xsl that says <xsl:import href="./omd-latex.xsl" /> and <xsl:import href="./omd-html.xsl" />, respectively; each of these files contains the differences that MBX won't accept.

[Alex-Jordan]

This is why I would do feature development branching from MBX's dev branch, not omd's dev branch.

If it's a new standalone feature that does not interact with previous omd additions, then all is good.

If it's a new feature that does interact with a previous new omd feature, was the old feature accepted by MBX? If so then it is in the MBX/dev that we branched from. If not, then after making our new branch from MBX/dev, we pull from omd/oldfeature.

On Thu, Jan 15, 2015 at 1:26 PM, cmhughes notifications@github.com wrote:

I've been thinking about this a lot, and I'm still on board with the idea. I do have the following scenarios to consider, though: scenario 1 (a feature that MBX accepts)

We make a feature using

git checkout dev git checkout -b

git commit -m ... git push ... submit a pull request to the OMD branch, and one to MBX (origin/dev). If MBX accepts the change, we run git checkout dev git pull and dev is now up to date, and OMD is exactly the same as dev and ## origin/dev scenario 2 (a feature that isn't accepted by MBX) Assume the same process as in Scenario 1, except that MBX does _not_ accept our work. In this scenario, the OMD branch has now diverged. How would we update this feature (that is not a part of origin/dev)? Presumably we would _have_ to keep the feature branch alive, as we could no longer branch from origin/dev. It is, of course, still possible to merge updates from origin/dev, but ## there may be conflicts. If we are to go down this route, perhaps it is worth considering adding a final line to each of mathbook-latex.xsl and mathbook-html.xsl that says and , respectively; each of these files contains the differences that MBX won't accept. — Reply to this email directly or view it on GitHub https://github.com/openmathdocs/precalc/issues/12#issuecomment-70164927.

Alex Jordan Mathematics Instructor Portland Community College

[Alex-Jordan]

Ah I should have read more closely. Yes, I'm thinking that we keep feature branches alive.

I think it will be rare that our work actually modifies any MBX content. Mainly we are making new xml elements, and so merge conflicts are not a concern. I suppose things like table handling might be the exception though. Ideally we should aim to make such modifications work for MBX too. It needs decimal handling etc. as well, and if we do those things right (and backwards-compatible with existing xml files) then we can hope for them to take it.

So thinking more about merge conflicts, can you imagine them becoming unmanageable? With a project like WeBWorK, with interwoven code all over the place, I can see that being a problem. I'm having a hard time foreseeing nasty merge conflicts in xsl files .

On Thu, Jan 15, 2015 at 1:45 PM, Alex Jordan alex.jordan@pcc.edu wrote:

This is why I would do feature development branching from MBX's dev branch, not omd's dev branch.

If it's a new standalone feature that does not interact with previous omd additions, then all is good.

If it's a new feature that does interact with a previous new omd feature, was the old feature accepted by MBX? If so then it is in the MBX/dev that we branched from. If not, then after making our new branch from MBX/dev, we pull from omd/oldfeature.

On Thu, Jan 15, 2015 at 1:26 PM, cmhughes notifications@github.com wrote:

I've been thinking about this a lot, and I'm still on board with the idea. I do have the following scenarios to consider, though: scenario 1 (a feature that MBX accepts)

We make a feature using

git checkout dev git checkout -b

git commit -m ... git push ... submit a pull request to the OMD branch, and one to MBX (origin/dev). If MBX accepts the change, we run git checkout dev git pull and dev is now up to date, and OMD is exactly the same as dev and ## origin/dev scenario 2 (a feature that isn't accepted by MBX) Assume the same process as in Scenario 1, except that MBX does _not_ accept our work. In this scenario, the OMD branch has now diverged. How would we update this feature (that is not a part of origin/dev)? Presumably we would _have_ to keep the feature branch alive, as we could no longer branch from origin/dev. It is, of course, still possible to merge updates from origin/dev, but ## there may be conflicts. If we are to go down this route, perhaps it is worth considering adding a final line to each of mathbook-latex.xsl and mathbook-html.xsl that says and , respectively; each of these files contains the differences that MBX won't accept. — Reply to this email directly or view it on GitHub https://github.com/openmathdocs/precalc/issues/12#issuecomment-70164927 .

Alex Jordan Mathematics Instructor Portland Community College

Alex Jordan Mathematics Instructor Portland Community College

[cmhughes]

Here are the main things that I have implemented so far, that I think will probably cause conflicts with or may be rejected by MBX:

• multobjects, which allows multiple tables, figures, subtables, subfigures; this does modify the table and figure commands
• OMD also modifies the way that tables, figures, and other numbered objects are counted, because we use <chapter>.<number>
• OMD needs to significantly modify the exercise template because of our sophisticated latex problem structure
• we need to be able to define new math operators such as sq (which has been done in one of our commits)
• we need to train MathJax to use nicefrac (which has been done in one of our commits)

I can see that 'stand alone' features such as quant will probably be welcomed by the MBX project; in fact, I might even imagine them welcoming the multobjects and nicefrac work. However, some of our stuff, e.g the core problem stuff, is too specialist.

All this being said, I still think that there is value in the approach that you have outlined, and it will probably cause us to think about our modifications/enhancements in a more structured & thoughtful way. There will be merge conflicts, and there will be times when we diverge, but that's ok.

To try and address your last question: if we have something that is unique to OMD, we could put it in its own omd-latex.xsl and/or omd-html.xsl file, and link it at the end of mathbook-latex.xsl and/or mathbook-html.xsl respectively. For example, when we change the figure template, we can leave the version alone in mathbook-*.xsl, knowing that the version from omd-latex.xsl will over rule it.

[cmhughes]

I'm happy to commit to this idea. I imagine that you're keen to do this so that we can realize our improvements in other projects (e.g the Linear Algebra text), and I think that makes a lot of sense.

As it's your vision, do you want to set it up? Once it is set up, can we merge our own pull requests? I can envisage making quite a few pull requests immediately (nicefrac, sq operator, multobjects, cleveref options, exercise environment tweaks to allow solutions as knowls, decimal alignment in tables, figure code in tikz to standalone files and to svg).

We've been through quite a few different iterations of workflow over the years--do you think that this will get us closer to optimal? :)

[cmhughes]

List of things to put into feature branches (add to as necessary!):

• DONE quant
• DONE nicefrac (as sfrac)
• sq operator (probably not relevant to MBX)
• multobjects (high priority)
• option for cleveref (not convinced we need this urgently, as it has been handled in the original now)
• figure descriptions for alternative texts
• AWAITING FEEDBACK from MBX: table decimal column alignment (high priority)
• DONE re-remove auto-generated \label from section, chapter, etc commands
• exercise environment tweaks to allow solutions as knowls (probably not relevant to MBX)
• figure code in tikz to standalone files (and to svg)--it looks like Rob has a solution for this already, so I'm not convinced this needs to happen...

[Alex-Jordan]

Also, sq is a "single quote" tag in MBX. So we need to work around that.

On Thu, Jan 22, 2015 at 12:00 PM, cmhughes notifications@github.com wrote:

List of things to put into feature branches (add to as necessary!):

• quant DONE (but Alex needs to submit pull request to OMD)
• nicefrac DONE (as sfrac)
• sq operator (probably not relevant to MBX)
• multobjects
• option for cleveref
• figure descriptions for alternative texts
• table decimal column alignment
• exercise environment tweaks to allow solutions as knowls (probably not relevant to MBX)
• figure code in tikz to standalone files (and to svg)--it looks like Rob has a solution for this already, so I'm not convinced this needs to happen...

— Reply to this email directly or view it on GitHub https://github.com/openmathdocs/precalc/issues/12#issuecomment-71087863.

Alex Jordan Mathematics Instructor Portland Community College

[cmhughes]

The sq operator is a math operator--I don't believe it will end up having an xml tag...(?)

[Alex-Jordan]

Ah OK. I thought maybe it was also a text mode operator.

On Thu, Jan 22, 2015 at 2:03 PM, cmhughes notifications@github.com wrote:

The sq operator is a math operator--I don't believe it will end up having an xml tag...(?)

— Reply to this email directly or view it on GitHub https://github.com/openmathdocs/precalc/issues/12#issuecomment-71108311.

Alex Jordan Mathematics Instructor Portland Community College

[cmhughes]

Our new workflow is now in place. Pull requests submitted to origin/dev; so far 1/6 accepted.

Closing this issue.