Instructions on how to use the template + VSCode users

README.md

@@ -1,4 +1,4 @@
-<h2>SJSU Thesis Template</h2>
+# SJSU Thesis Template
 
 I am not the original author of this template.  It is modified from a template created by the University of Rhode Island (URI).  A link to their original template is: http://egr.uri.edu/ele/thesisguide/step2/
 
@@ -13,3 +13,105 @@ As part of my thesis, I switched to BibTex.  The requirements needed to use BibT
 The example steps for BibTex were debugged on a Mac. Given the "*.bat" files, the approach above probably will not work out of the box on a Mac.  Here is a link with more general information on using BibTex.
 
 I am also including a Texmaker session so you can load it into Texmaker directly.  You need to modify the session file to match the local path on your machine.  If you can get TexStudio working instead, it is a better tool in my humble opinion.
+
+## How to use this template
+Do not fork this repository and work on it. Github forces all forks to be public.
+Instead, git clone this repository to your local machine and create a new repository in your own Github account.
+Then push the local repository to your new repository.
+
+## VSCode Users
+If you don't like TexMaker, you can use VSCode with the [LaTeX Workshop](https://marketplace.visualstudio.com/items?itemName=James-Yu.latex-workshop) extension.
+Make sure to download a Tex distribution like MikTex (Windows) or MacTex (Mac).
+Also, download `latexmk` if it is not included in your Tex distribution; this is the default compiler used by Overleaf.
+
+Then, add the following recipes and tools to your VSCode settings.json file.
+```json
+"latex-workshop.latex.tools": [
+        {
+            "name": "pdflatex",
+            "command": "pdflatex",
+            "args": [
+                "--shell-escape",
+                "-synctex=1",
+                "-interaction=nonstopmode",
+                "-file-line-error",
+                "%DOC%"
+            ]
+        },
+        {
+            "name": "latexmk",
+            "command": "latexmk",
+            "args": [
+                "-synctex=1",
+                "-interaction=nonstopmode",
+                "-file-line-error",
+                "-pdf",
+                "-outdir=%OUTDIR%",
+                "%DOC%"
+            ]
+        },
+        {
+            "name": "bibtex",
+            "command": "bibtex",
+            "args": [
+                "%DOCFILE%"
+            ]
+        },
+        {
+            "name": "latexmk-shell-escape",
+            "command": "latexmk",
+            "args": [
+                "-synctex=1",
+                "-interaction=nonstopmode",
+                "-file-line-error",
+                "-pdf",
+                "-outdir=%OUTDIR%",
+                "-shell-escape",
+                "%DOC%"
+            ]
+        },
+    ],
+"latex-workshop.latex.recipes": [
+    {
+        "name": "latexmk",
+        "tools": [
+            "latexmk"
+        ]
+    },
+    {
+        "name": "pdflatex",
+        "tools": [
+            "pdflatex"
+        ]
+    },
+    {
+        "name": "latex-shell-escape",
+        "tools": [
+            "latexmk-shell-escape"
+        ]
+    }
+]
+```
+
+To compile `thesis.tex`, simply run the `latexmk` recipe.
+The compiler will automatically run `bibtex` as needed to generate the bibliography.
+
+It is sometimes possible that the compiler will not generate the bibliography correctly.
+To fix this, simply force a recompilation from scratch by deleting the `thesis.pdf` file and run the `latexmk` recipe again.
+
+## Sharing your work
+Professors and colleagues may want to see your work including both the PDF and the source code.
+Email services like Gmail block script and executable files for security reasons.
+This repo has many `.bat` files that will be blocked by email services.
+A workaround if sharing via email, is to zip the entire project folder and send the zip file by using `git archive` and `.gitattributes`.
+First, create a `.gitattributes` file in the root of your project with the following content:
+```
+build/ export-ignore
+uribibtex.bat export-ignore
+```
+
+Then, create a zip file of your project with
+```
+git archive -o thesis.zip HEAD --add-file=thesis.pdf
+```
+We manually add the `thesis.pdf` file since it is not tracked by git.