Options

Creating gitbooks for the course

Jonathan Bergquist wrote:

I have an idea that I'd like to propose: to put the more "static" material you're creating into gitbooks (https://www.gitbook.com/). It would make it easier and smoother to read, more publically available and more independent of the technical support of this forum (this might be wanted or not, I'm not entirely sure of your connection to the forum).

Since we're about 200 students, I'm sure we'd be able to transfer the material into a gitbook-format. If you think it's a good idea...

It might be a marginal improvement but subjectively I prefer the looks of gitbooks.

Is anyone interested in doing this?

I'd like to keep the copyright on my lectures, for example with a suitable Creative Commons copyright. However, I'd be very happy to spread this material widely. I don't have the energy to create gitbooks myself: I'm busy cranking out lectures, and then also I have a small vestigial thing called a "life". But I'd be delighted if the rest of you create them!

Comments

  • 1.

    I would like to assist with this but won't have a lot of time to commit. If someone else will set it up, I can help by copying John's lectures to the gitbook repository and working on formatting. I'd rather not commit to managing the repo when I am not certain how much free time I will have available in the near future.

    Comment Source:I would like to assist with this but won't have a lot of time to commit. If someone else will set it up, I can help by copying John's lectures to the gitbook repository and working on formatting. I'd rather not commit to managing the repo when I am not certain how much free time I will have available in the near future.
  • 2.

    For what it's worth, the source code for my lectures can be found here:

    http://math.ucr.edu/home/baez/mathematical/7_sketches/

    They're written using Markdown and MathJax, with pictures in HTML.

    Comment Source:For what it's worth, the source code for my lectures can be found here: http://math.ucr.edu/home/baez/mathematical/7_sketches/ They're written using Markdown and MathJax, with pictures in HTML.
  • 3.

    I created a repo on GitHub which we can use to construct the book from what you've made so far and future postings. I'm reading the GitBook documentation to understand how to properly format things and get MathJax working with GitBook (looks like a simple configuration option).

    I'll pull in your current lectures and images and create a ToC and try to get it posted tonight. I will attempt to update with new lectures twice a week.

    Comment Source:I created a repo on GitHub which we can use to construct the book from what you've made so far and future postings. I'm reading the GitBook documentation to understand how to properly format things and get MathJax working with GitBook (looks like a simple configuration option). - [Link to the repository](https://github.com/rabuf/applied-category-theory) I'll pull in your current lectures and images and create a ToC and try to get it posted tonight. I will attempt to update with new lectures twice a week.
  • 4.
    edited April 11

    It's still a bit of a work in progress. As with this site, sometimes you have to refresh a page to get the mathjax content to display correctly. I'm going to start with edits to the markdown files (particularly fixing image URLs to point to local copies of the images). Later tonight I'll copy Lecture 11 which I saw was posted here already.

    John: Please keep updating your own content (at the link you provided earlier) if you like, but with the "view source" option on comments here I should be able to do a copy/paste from each lecture into a markdown file myself.

    Additionally, I'm going to use the content from your welcome post as an introduction to the gitbook with some editing. If you'd like to write up something different you can post it here and I'll replace the Introduction section.

    Comment Source:- [Book URL](https://rabuf.github.io/applied-category-theory/) - [Book git repo](https://github.com/rabuf/applied-category-theory) It's still a bit of a work in progress. As with this site, sometimes you have to refresh a page to get the mathjax content to display correctly. I'm going to start with edits to the markdown files (particularly fixing image URLs to point to local copies of the images). Later tonight I'll copy Lecture 11 which I saw was posted here already. John: Please keep updating your own content (at the link you provided earlier) if you like, but with the "view source" option on comments here I should be able to do a copy/paste from each lecture into a markdown file myself. Additionally, I'm going to use the content from your welcome post as an introduction to the gitbook with some editing. If you'd like to write up something different you can post it here and I'll replace the Introduction section.
  • 5.

    Regarding licensing the content. I can add a license page if you tell me which license you'd like me to use. Creative Commons has a page that helps you select which specific variant you'd like. My guess would be their Attribution-NonCommercial-ShareAlike 4.0 International. This permits non-commercial uses, requires attribution, and allows adaptations to be shared as long as they're under a similar license as this book.

    If this is what you'd like (or you have something else in mind) let me know and I'll update accordingly.

    Comment Source:Regarding licensing the content. I can add a license page if you tell me which license you'd like me to use. [Creative Commons](https://creativecommons.org/choose/) has a page that helps you select which specific variant you'd like. My guess would be their [Attribution-NonCommercial-ShareAlike 4.0 International](http://creativecommons.org/licenses/by-nc-sa/4.0/). This permits non-commercial uses, requires attribution, and allows adaptations to be shared as long as they're under a similar license as this book. If this is what you'd like (or you have something else in mind) let me know and I'll update accordingly.
  • 6.

    Jared:

    Thanks for all your work! This is great.

    John: Please keep updating your own content (at the link you provided earlier) if you like, but with the "view source" option on comments here I should be able to do a copy/paste from each lecture into a markdown file myself.

    Thanks. I intend to keep updating the files at http://math.ucr.edu/home/baez/mathematical/7_sketches/ because I'm paranoid and like to have lots of backups.

    I'm happy to use a Attribution-NonCommercial-ShareAlike 4.0 International license. Thanks!

    By the way, most of the figures in my lectures are also stored at that site. I should put all of them in there. That'll make it slightly easier to get ahold of them. If we ever get serious about copyright issues, we will need to either credit the creators of these figures or eliminate them. Most are on Wikicommons under reasonable licenses. Some are not.

    Comment Source:Jared: Thanks for all your work! This is great. > John: Please keep updating your own content (at the link you provided earlier) if you like, but with the "view source" option on comments here I should be able to do a copy/paste from each lecture into a markdown file myself. Thanks. I intend to keep updating the files at http://math.ucr.edu/home/baez/mathematical/7_sketches/ because I'm paranoid and like to have lots of backups. I'm happy to use a [Attribution-NonCommercial-ShareAlike 4.0 International](http://creativecommons.org/licenses/by-nc-sa/4.0/) license. Thanks! By the way, most of the figures in my lectures are also stored at that site. I should put all of them in there. That'll make it slightly easier to get ahold of them. If we ever get serious about copyright issues, we will need to either credit the creators of these figures or eliminate them. Most are on Wikicommons under reasonable licenses. Some are not.
  • 7.

    I'm actually glad I've taken the time to do this. I've been rereading each lecture as I go through to verify the formatting. For some reason I was struggling with some of the terms and this (third or fourth or twentieth) review of the material has helped them stick a bit better.

    I'll update the license and make a small update to each lecture tomorrow afternoon or Thursday evening. At the bottom of each lecture page I'm adding a link back to the original discussion so that the reader can quickly get to the content.

    After I've finished going through this (and finally finish the last 5 or so pages of Chapter 1), I'll make another pass and start pulling out your puzzles from this forum if they weren't in the lectures already.

    Comment Source:I'm actually glad I've taken the time to do this. I've been rereading each lecture as I go through to verify the formatting. For some reason I was struggling with some of the terms and this (third or fourth or twentieth) review of the material has helped them stick a bit better. I'll update the license and make a small update to each lecture tomorrow afternoon or Thursday evening. At the bottom of each lecture page I'm adding a link back to the original discussion so that the reader can quickly get to the content. After I've finished going through this (and finally finish the last 5 or so pages of Chapter 1), I'll make another pass and start pulling out your puzzles from this forum if they weren't in the lectures already.
  • 8.
    edited April 11

    Thanks yet again, Jared! I'm glad you've found this beneficial. I always find that semi-mindless editing, reformatting and diagram-drawing chores give me a good chance to ponder the underlying mathematics.

    Comment Source:Thanks yet again, Jared! I'm glad you've found this beneficial. I always find that semi-mindless editing, reformatting and diagram-drawing chores give me a good chance to ponder the underlying mathematics.
  • 9.

    Haha, wow! This is amazing, thanks Jared! I'm offline for less than 24h, and magic happens! I'll look at it and see if there's anything left for me to do. Or you can let me know what you'd like me to do!

    Comment Source:Haha, wow! This is amazing, thanks Jared! I'm offline for less than 24h, and magic happens! I'll look at it and see if there's anything left for me to do. Or you can let me know what you'd like me to do!
  • 10.

    Jonatan: I think I will have lectures 1-11 finished tomorrow afternoon and updated (my afternoon, around 9pm UTC). There are some math formatting issues which my next push will address.

    At this point maybe a review of what I have posted. Suggestions on the format or content to include.

    GitBook allows for a glossary which would be a nice addition if you’d like to get started on it. These work with inline mathjax.

    Comment Source:Jonatan: I think I will have lectures 1-11 finished tomorrow afternoon and updated (my afternoon, around 9pm UTC). There are some math formatting issues which my next push will address. At this point maybe a review of what I have posted. Suggestions on the format or content to include. GitBook allows for a glossary which would be a nice addition if you’d like to get started on it. These work with inline mathjax. - [GitBook docs on glossaries](https://toolchain.gitbook.com/lexicon.html)
  • 11.

    Cool Do you know how to enable latex? I found this https://github.com/GitbookIO/plugin-mathjax that might help.

    Comment Source:Cool Do you know how to enable latex? I found this https://github.com/GitbookIO/plugin-mathjax that might help.
  • 12.
    edited April 11

    Mathjax should be enabled unless I screwed something up when I updated it this morning. If I did I'll correct it once I get home.

    Right now it does seem to have one glitch with mathjax in that you have to refresh the page for it to be applied. From reading comments on the plugin's repository, it seems that they're using an outdated CDN for it and this causes the glitch. I can try manually patching the plugin before publishing to see if that corrects the issue.

    I did discover that the mathjax issues we saw here with inserting curly braces and such (where here we need \\{ and \\}) aren't an issue with GitBook and mathjax. I removed all the extra backslashes in lecture 6 and will do the same for the others this afternoon when I get home.

    Comment Source:Mathjax should be enabled unless I screwed something up when I updated it this morning. If I did I'll correct it once I get home. Right now it does seem to have one glitch with mathjax in that you have to refresh the page for it to be applied. From reading comments on the plugin's repository, it seems that they're using an outdated CDN for it and this causes the glitch. I can try manually patching the plugin before publishing to see if that corrects the issue. I did discover that the mathjax issues we saw here with inserting curly braces and such (where here we need `\\{` and `\\}`) aren't an issue with GitBook and mathjax. I removed all the extra backslashes in lecture 6 and will do the same for the others this afternoon when I get home.
  • 13.

    Lecture 6 isn't formatting properly: https://rabuf.github.io/applied-category-theory/chapter_1/lecture_6.html

    Would you prefer we raised issues on github?

    Comment Source:Lecture 6 isn't formatting properly: https://rabuf.github.io/applied-category-theory/chapter_1/lecture_6.html Would you prefer we raised issues on github?
  • 14.

    Matthew: Raising issues on github would probably be best. It'll make it easier for us to see what's been spotted and what hasn't versus reviewing this thread where I'm more likely to miss something.

    Comment Source:Matthew: Raising issues on github would probably be best. It'll make it easier for us to see what's been spotted and what hasn't versus reviewing this thread where I'm more likely to miss something.
  • 15.
    edited April 11

    Jared - one problem I hadn't thought about: I repeatedly need to go back to previous lectures and correct mistakes. For example, today while writing Lecture 12 I had to go back and add a puzzle, Puzzle 34, to Lecture 11. I also discovered that a bunch of Lecture 10 was suboptimal, though I haven't gone back and changed it yet.

    One possible solution, for the future at least, is for you to wait until I give the go-ahead. This will probably happen each time I finish lecturing on a chapter.

    Comment Source:Jared - one problem I hadn't thought about: I repeatedly need to go back to previous lectures and correct mistakes. For example, today while writing Lecture 12 I had to go back and add a puzzle, Puzzle 34, to Lecture 11. I also discovered that a bunch of Lecture 10 was suboptimal, though I haven't gone back and changed it yet. One possible solution, for the future at least, is for you to wait until I give the go-ahead. This will probably happen each time I finish lecturing on a chapter.
  • 16.

    That works. I won't post lecture 12 until you've told me to, then.

    If you can drop a note here when you have updated past lectures, or via a github issue (if you have a github account). Either will work for me. When I see that I'll go back and update the version in the book. That way we aren't spending a lot of time manually checking what we have in the book with what's here in the forum (especially when things may be in flux).

    Comment Source:That works. I won't post lecture 12 until you've told me to, then. If you can drop a note here when you have updated past lectures, or via a github issue (if you have a github account). Either will work for me. When I see that I'll go back and update the version in the book. That way we aren't spending a lot of time manually checking what we have in the book with what's here in the forum (especially when things may be in flux).
  • 17.

    Jared - I'll post a note when I update past lectures, either here or on github. But it will be much easier for both of us if you lag behind a lot, waiting until a whole chapter is done before springing into action.

    Comment Source:Jared - I'll post a note when I update past lectures, either here or on github. But it will be much easier for both of us if you lag behind a lot, waiting until a whole chapter is done before springing into action.
  • 18.
    edited April 11

    John: I won't add anything else until you let me know then. In the meantime I'll work on formatting the content that I've already included. I'll add new (but not finalized) lectures as links to the discussion in this forum so readers will know where to look.

    For anyone who may take on the task of preparing John's material for the book:

    Mathjax with GitBooks does not center things created using $$\text{math stuffs}$$ like this forum does.

    $$\text{math stuffs}$$ Instead it keeps it aligned to the left. I did not see an option in the mathjax plugin to address this. So I'm just adding <center> and </center> around these to ensure they're formatted like in the forum.

    If you'd like to edit any of this on your own system, you'll need node to preview the text. Install node using your favorite package manager and then use npm install -g gitbook (-g makes it a global install, this may or may not be what you want but it's what I did).

    In the directory containing the book you can type gitbook serve and it'll compile it into html files and serve it at http://localhost:4000. Any changes you make to the markdown files will be immediately compiled and displayed in your browser once the file is saved. This is very handy for checking your modifications before submitting a pull request to the main repository.

    EDIT: Used the wrong /

    Comment Source:John: I won't add anything else until you let me know then. In the meantime I'll work on formatting the content that I've already included. I'll add new (but not finalized) lectures as links to the discussion in this forum so readers will know where to look. For anyone who may take on the task of preparing John's material for the book: Mathjax with GitBooks does *not* center things created using `$$\text{math stuffs}$$` like this forum does. $$\text{math stuffs}$$ Instead it keeps it aligned to the left. I did not see an option in the mathjax plugin to address this. So I'm just adding `<center>` and `</center>` around these to ensure they're formatted like in the forum. If you'd like to edit any of this on your own system, you'll need node to preview the text. Install node using your favorite package manager and then use `npm install -g gitbook` (-g makes it a global install, this may or may not be what you want but it's what I did). In the directory containing the book you can type `gitbook serve` and it'll compile it into html files and serve it at `http://localhost:4000`. Any changes you make to the markdown files will be immediately compiled and displayed in your browser once the file is saved. This is very handy for checking your modifications before submitting a pull request to the main repository. EDIT: Used the wrong `/`
  • 19.
    edited April 13

    Several comments on the GitBook version of lectures:

    1. I had hoped to migrate the hosting from my GitHub Pages location to gitbook.com proper. However, they don't support mathjax on the content they host so this is a no go. It could've greatly simplified the editing process (they have a built-in editor, and I could add other users as editors to control access).

    2. I have found several examples of using Travis CI (and similar) to automate the generation of the final rendered book using git commits to the master as a trigger. I will do this over the weekend, this'll reduce the risk of me screwing up anything by running the commands manually (I did make a script at least) or forgetting to do it after accepting someone's pull request.

    3. I goofed when I added the license and put in the wrong link (allows commercial uses which is not what we'd intended). I'll address this this evening. I'll also be putting the license into its own LICENSE.md file stating that the text is "copyrighted by John Baez" and add that file to the bottom of each of the lectures.

    Comment Source:Several comments on the GitBook version of lectures: 1. I had hoped to migrate the hosting from my GitHub Pages location to gitbook.com proper. However, they don't support mathjax on the content they host so this is a no go. It could've greatly simplified the editing process (they have a built-in editor, and I could add other users as editors to control access). 2. I have found several examples of using Travis CI (and similar) to automate the generation of the final rendered book using git commits to the master as a trigger. I will do this over the weekend, this'll reduce the risk of me screwing up anything by running the commands manually (I did make a script at least) or forgetting to do it after accepting someone's pull request. 3. I goofed when I added the license and put in the wrong link (allows commercial uses which is not what we'd intended). I'll address this this evening. I'll also be putting the license into its own LICENSE.md file stating that the text is "copyrighted by John Baez" and add that file to the bottom of each of the lectures.
  • 20.

    Thanks, Jared! I did a fair amount of messing around with Chapters 10-12 . I've noted the most important changes in the comments on these chapters, but there are probably other smaller changes. Sorry!

    Comment Source:Thanks, Jared! I did a fair amount of messing around with Chapters 10-12 . I've noted the most important changes in the comments on these chapters, but there are probably other smaller changes. Sorry!
  • 21.

    That's fine. Change is good, encourages us to go through the whole thread thoroughly too. It really is great for ensuring I read everything.

    Jonatan, Fredrick since you two have been helping I've added you both as collaborators on the repository. You now have push privileges to it.

    I'll continue to grab the most recent lectures (like Lecture 12 once John says it's good), and we can coordinate (here or there) on which lecture we're each responsible for maintaining after they've been added to the repo.

    Comment Source:That's fine. Change is good, encourages us to go through the whole thread thoroughly too. It really is great for ensuring I read everything. Jonatan, Fredrick since you two have been helping I've added you both as collaborators on the repository. You now have push privileges to it. I'll continue to grab the most recent lectures (like Lecture 12 once John says it's good), and we can coordinate (here or there) on which lecture we're each responsible for maintaining after they've been added to the repo.
  • 22.

    It took me too long, but the gitbook is now automatically generated when the master branch is updated. So at most it'll be a few minutes between updates to the content and updates to the displayed book. And now that it's an automated process, less room for me to dork it up.

    Comment Source:It took me too long, but the gitbook is now automatically generated when the master branch is updated. So at most it'll be a few minutes between updates to the content and updates to the displayed book. And now that it's an automated process, less room for me to dork it up.
  • 23.

    I've made a first pass edit at lectures 12, 13, and 14 for the mathjax portions. There's still a problem in Puzzle 42 in Lecture 14 that I haven't figured out yet. \\(f_{!}(P)\\) is not rendering correctly as \(f_{!}(P)\) in two locations (on my computer at least).

    Additionally, the cross-references to other lectures link back to this forum instead of to the other sections of the gitbook version. If someone could take a look at those and proofread to make sure I didn't miss any other formatting issues I'd appreciate it.

    Comment Source:I've made a first pass edit at lectures 12, 13, and 14 for the mathjax portions. There's still a problem in Puzzle 42 in Lecture 14 that I haven't figured out yet. `\\(f_{!}(P)\\)` is not rendering correctly as \\(f_{!}(P)\\) in two locations (on my computer at least). Additionally, the cross-references to other lectures link back to this forum instead of to the other sections of the gitbook version. If someone could take a look at those and proofread to make sure I didn't miss any other formatting issues I'd appreciate it.
  • 24.
    edited April 15

    Does it really make sense for you to work on lectures 12-14 before I okay it? I keep having to make changes - for example, Michael Hong added a picture to lecture 12, and I keep finding typos.

    Comment Source:Does it really make sense for you to work on lectures 12-14 before I okay it? I keep having to make changes - for example, Michael Hong added a picture to lecture 12, and I keep finding typos.
  • 25.

    Alright. Blanked out those 3. They now point to the discussion here so people can see the latest version as you edit them.

    Comment Source:Alright. Blanked out those 3. They now point to the discussion here so people can see the latest version as you edit them.
  • 26.

    I've gone through all the lectures and:

    Comment Source:I've gone through all the lectures and: * changed `$$ $$` to `\[ \]` wherever I saw it, * changed `PX` and `PY` to `P(X)` and `P(Y)` wherever I saw them, and * made all figures point to files in http://math.ucr.edu/home/baez/mathematical/7_sketches, just so they're all in one place.
  • 27.

    Roger. I'll attend to the updates this evening. Which lectures am I clear to include at this point?

    Comment Source:Roger. I'll attend to the updates this evening. Which lectures am I clear to include at this point?
  • 28.
    edited April 17

    The longer you wait, the less likely I'll discover more mistakes! However, if you're eager to tackle them, I think Lectures 1-13 have probably solidified by now. Not many people have commented on the more recent ones - am I burning people out with a too-rapid pace? - so there could easily be more mistakes lurking in these.

    Lecture 17 will be the last one on chapter 1; as mentioned elsewhere we will then have a 2-week break from lectures where we will go through all the Exercises in chapter 1.

    Comment Source:The longer you wait, the less likely I'll discover more mistakes! However, if you're eager to tackle them, I think Lectures 1-13 have probably solidified by now. Not many people have commented on the more recent ones - am I burning people out with a too-rapid pace? - so there could easily be more mistakes lurking in these. Lecture 17 will be the last one on chapter 1; as mentioned elsewhere we will then have a 2-week break from lectures where we will go through all the Exercises in chapter 1.
Sign In or Register to comment.