windows guide should be in "chronological" order

[kcrisman]

I think that it's not going to be so easy for people to download the xsltproc stuff unless they first have the command line thing from git bash. So maybe those sections (and possibly others) should be switched.

@daverosoff as well

[kcrisman]

Here is a flow that worked for me on Windows 10. Sadly, Camstudio bit hard, so I was not able to make a proper video showing this. I will not make a PR for this - really no time, need to keep getting ready for the workshop - but will happily view one and sign off that "this worked for me".

• First, install Git Bash via installing git. There is a checkbox (at least on W10) that allows you to get it on your desktop (Git bash, that is) and I highly recommend this.

• At any time before actually using MBX, go back and git clone MBX. No need to switch to the dev branch, apparently this is standard now - @rbeezer is that an old instruction then?

• Next, use Git bash to issue the following command SOMEWHERE: mkdir xsltproc. It was easiest for me to do this in ~, but whatever.

• Next, install all the stuff from that guy's FTP site. The most annoying part of this, as you say. But at least it works, which is more than I can say for the last step. My recommendation is to leave all the downloads in the browser window, and then use the File Explorer to go to Downloads. Note that it's not that easy to get to the folder in xsltproc if you put it in ~, but eventually by navigating the File Explorer through C to Users to your name, you can get there. Yuck.

• The only editor that comes with Git bash is vi. Yuck. So I recommended going to the Start menu, typing Notepad, and then typing in that. Save to your home folder.

• Then - this is key - open git bash and FORGET ABOUT PATH NAMES. That is for experts. The export command echoed to .bashrc never worked for me; presumably because the PATH is filled with parentheses for crazy Windows stuff (even the "(R)" for registered trademarks is in the PATH!). So I did this instead:

  • Open Git Bash (hopefully you made a desktop icon)
  • Use ls to make sure that you have your xml file (maybe test.xml) and your xsltproc folder handy.
  • Give the full path to the xsltproc executable in your syntax! This worked perfectly and was plain easy. E.g. xsltproc/xsltproc.exe mathbook/xsl/mathbook-html.xsl test.xml
  • Success! I created an html file which actually looked nice!

• No hint on how to get LaTeX to install on your Windows box, though!

[daverosoff]

Karl-Dieter (or do you prefer KDC? ;),

Thanks for the feedback. I have some questions for you below.

I think that it's not going to be so easy for people to download the xsltproc stuff unless they first have the command line thing from git bash. So maybe those sections (and possibly others) should be switched.

I'm not sure why. Evidently you like using the command line--I do too. It's true that I didn't much think about the order of these sections, but you are evidently an expert command-line user. Most Windows folks are not, so I didn't imagine they would try to use Git Bash for any of the file/directory manipulation you describe below. What part of the xsltproc installation did you find the command line essential for?

I did just as you describe: leave the .zips from that guy's FTP site in the Download folder, use the Windows file browser to pick and choose the bits we need, and put them in a good location like c:\xsltproc. It seems like the only part you did with the CLI was mkdir xsltproc... or am I misunderstanding?

First, install Git Bash via installing git. There is a checkbox (at least on W10) that allows you to get it on your desktop (Git bash, that is) and I highly recommend this.

At any time before actually using MBX, go back and git clone MBX. No need to switch to the dev branch, apparently this is standard now - @rbeezer is that an old instruction then?

Reasonable, although isn't this step covered elsewhere in the Guide? Rob changed the "default branch" to dev a few months ago, IIRC, so I can drop that from the instructions.

Next, use Git bash to issue the following command SOMEWHERE: mkdir xsltproc. It was easiest for me to do this in ~, but whatever.

So you chose a wack pathname instead of c:\xsltproc. Noted! This is part of why I don't think it's necessarily easier to do all this in Git Bash. I imagined users doing it from the Windows file browser. On your recommendation, I'll go back and issue sterner encouragement to use immediate subdirectories of the root whose names are free of spaces for all parts of the installation.

Next, install all the stuff from that guy's FTP site. The most annoying part of this, as you say. But at least it works, which is more than I can say for the last step.

Sorry, I don't follow--which step are you saying didn't work?

My recommendation is to leave all the downloads in the browser window, and then use the File Explorer to go to Downloads. Note that it's not that easy to get to the folder in xsltproc if you put it in ~, but eventually by navigating the File Explorer through C to Users to your name, you can get there. Yuck.

As described above this is exactly what I did and what I thought the instructions said to do. I can make them clearer, or more specific, or both, but can you please explain how using the Git Bash command line simplifies things up to this point?

The only editor that comes with Git bash is vi. Yuck. So I recommended going to the Start menu, typing Notepad, and then typing in that. Save to your home folder.

I think you are referring to editing .bashrc. OK, you got me: my echo trick was a workaround for not using vi. But in this case, wouldn't it be simpler for the directions just to leave this part out--you aren't the first to have problems with it--and just have people change their environment variables?

Then - this is key - open git bash and FORGET ABOUT PATH NAMES. That is for experts. The export command echoed to .bashrc never worked for me; presumably because the PATH is filled with parentheses for crazy Windows stuff (even the "(R)" for registered trademarks is in the PATH!). So I did this instead:

1. Open Git Bash (hopefully you made a desktop icon)
2. Use ls to make sure that you have your xml file (maybe test.xml) and your xsltproc folder handy.
3. Give the full path to the xsltproc executable in your syntax! This worked perfectly and was plain easy. E.g. xsltproc/xsltproc.exe mathbook/xsl/mathbook-html.xsl test.xml

Whew, that could be a lot of typing. Makefiles, aliases, and so on are also for experts. What if I were to delete the echo trick and replace it with this solution?

Success! I created an html file which actually looked nice!

Good, I am glad.

No hint on how to get LaTeX to install on your Windows box, though!

Well, I never promised that. It'll be simple to add some description of MiKTeX and a link to the site, though.

Thanks again for your suggestions.

[kcrisman]

Thanks for the feedback. I have some questions for you below.

Fire away!

and put them in a good location like c:\xsltproc. It seems like the

only part you did with the CLI was mkdir xsltproc... or am I misunderstanding?

Correct. I wasn't sure how else to make this folder. I will admit I am very unfamiliar with the Windows file structure and how to use the File Explorer. But I really didn't know how to make a new folder; I guess in retrospect probably it would be obvious to a seasoned Windows user. Maybe one could at least add something like "recall that to make a new folder in Windows you click the following button".

highly recommend this.

At any time before actually using MBX, go back and git clone MBX. No need to switch to the dev branch, apparently this is standard now - @rbeezer https://github.com/rbeezer is that an old instruction then?

Reasonable, although isn't this step covered elsewhere in the Guide?

Yes, but a reminder is always helpful - I had four separate tabs I needed to keep open to follow instructions here! We shouldn't have people have to constantly be switching back and forth.

Rob changed the "default branch" to dev a few months ago, IIRC, so I can drop that from the instructions.

Yes.

Next, use Git bash to issue the following command SOMEWHERE: mkdir xsltproc. It was easiest for me to do this in ~, but whatever.

So you chose a wack pathname instead of c:\xsltproc. Noted!

It wasn't a whack name, it was just the place I ended up when I opened the shell. And for that matter, when in the File Explorer it is not trivial to get to C:, the easiest place to be is your user Documents folder. Even finding the User folder for your user is annoying, until you've done it a few times.

This is part of why I don't think it's necessarily easier to do all this in Git Bash. I imagined users doing it from the Windows file browser. On your recommendation, I'll go back and issue sterner encouragement to use immediate subdirectories of the root whose names are free of spaces for all parts of the installation.

If you can tell them what that even means! But if they can find C: and make a new folder there it should work.

My recommendation is to leave all the downloads in the browser window, and

then use the File Explorer to go to Downloads. Note that it's not that easy to get to the folder in xsltproc if you put it in ~, but eventually by navigating the File Explorer through C to Users to your name, you can get there. Yuck.

As described above this is exactly what I did and what I thought the instructions said to do.

You said it, but not explicitly about where to click to find such downloads, or how to use the File Explorer. I want to emphasize that I was basically new to every single instruction. See https://mathwithbaddrawings.com/2015/01/21/are-you-a-dish-washing-robot/

The only editor that comes with Git bash is vi. Yuck. So I recommended going to the Start menu, typing Notepad, and then typing in that. Save to your home folder.

I think you are referring to editing .bashrc.

Nope, I'm talking about writing your vewy fiwst xml file. But I see how you thought that.

OK, you got me: my echo trick was a workaround for not using vi. But in this case, wouldn't it be simpler for the directions just to leave this part out--you aren't the first to have problems with it--and just have people change their environment variables?

Maybe, but because the up-arrow allows you to get previous commands, I think that a simpler solution for just getting started is the following. I agree that long-term one might want to do all that, but the beginner just wants to see their pretty new toy work.

Whew, that could be a lot of typing. Makefiles, aliases, and so on are also for experts. What if I were to delete the echo trick and replace it with this solution?

I'm just saying the echo trick failed because of the parentheses in the pre-existing PATH. Luckily, it's not much typing at all; I assume that from your home folder (if that's where you put mathbook/), if you already wrote test.xml, you should be able to do /c/xsltproc/xsltproc.exe mathbook/xsl/mathbook-html.xsl test.xml and be done. Up-arrow to repeat.

No hint on how to get LaTeX to install on your Windows box, though!

Well, I never promised that. It'll be simple to add some description of MiKTeX and a link to the site, though.

Probably helpful, especially if you mention a standard way to invoke it from the command line - or maybe that requires further path futzing :(

Sorry for the detailed and naive list. If I'd been more familiar with Windows or been able to figure out what to do with the parentheses in the PATH this might have been a much shorter post!