Update Usage, add install_local.sh, devdocs

README.md

@@ -4,6 +4,10 @@ Build a latex paper with IISER Mohali logo and superb formatting with just Markd
 
 Visit website [https://iiserm.github.io/PaperBuilder](https://iiserm.github.io/PaperBuilder)
 
+# Contributing
+
+See [devdocs](https://iiserm.github.io/PaperBuilder/devdocs)
+
 ## Credits
 
 - Mayukh Chakrabarty of MS18 made this template, all credits to him.

docs/devdocs.md

@@ -0,0 +1,54 @@
+# Contributing
+
+When contributing to this repository, please first discuss the change you wish to make via an issue with the maintainers of this repository before making a change.
+
+## Where can I find the open issues?
+
+See the issues tab in the [GitHub repo](https://github.com/IISERM/PaperBuilder).
+If you wanna add a feature that isn't there already, make a new issue.
+
+## What is this mess of a project?
+
+It isn't THAT messy. Fine it is a little messy, but I'm doing all the work alone anyway 😤
+
+```
+PaperBuilder
+├───docs            # This is where the website resides
+│   └───test        # This should reflect latest release
+├───linux           # Template installer script. Actual one built by dist.ps1
+├───prereq          # pandoc.msi
+├───src             # Main PaperBuilder script and init md and bib templates
+│   └───default     # The templates
+├───windows         # windows nsis build tools and running .bat file template
+├───maketests.ps1   # builds the examples
+└───dist.ps1        # creates a release distribution
+```
+
+## Ok, how do I add my feature?
+
+1. Clone the repo (surprise surprise)
+2. Change PaperBuilder.py and the templates. Be sure to change all the templates, the tex ones AND the .md and .bib files
+3. Test it by manually installing pandoc and Latex distro(MikTex on Win and texlive on linux)
+   - You can install the linux deps by reading the `.../linux/install.sh` file and running the appropriate commands
+4. Build the docs/test and make sure things look ok
+5. Send a PR, and explain your changes
+
+## How TF do I build this?
+
+Well... It's KIND of easy...Building only works on Windows rn, because that is my OS.
+
+### Setup
+
+1. Install MSVC BuildTools. Install the default C++ options. [See this](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2019)
+2. Install Python3.7.x [See Here](https://www.python.org/downloads/release/python-379/)
+3. Install nuitka via pip [See this](https://nuitka.net/doc/user-manual.html#install-nuitka)
+4. Install clcache if you want [See this](https://nuitka.net/doc/user-manual.html#caching-compilation-results)
+5. Install nsis [See this](https://nsis.sourceforge.io/Main_Page)
+6. Add the EnVar plugin for nsis [See this](https://nsis.sourceforge.io/EnVar_plug-in)
+
+### Building
+
+1. Activate the x64 version of the build tools in a powershell windows [See this](https://gist.github.com/DhruvaSambrani/d9f6e6ec617b43f5e1fd60900f89c919)
+2. Run `...\dist.ps1`. This adds an untracked `release` folder.
+3. Check if `...\release\PaperBuilder-Setup.exe` works
+4. In a linux os, run `...\linux\install_local.sh` and see if everything works

docs/index.md

@@ -30,7 +30,7 @@ $$your latex code here$$
 
 And everything just works :)
 
-## That's cool, I wanna see how it looks!
+## That's cool, show me how it looks!
 
 We have a minimal example in the [Examples Page](./examples). Be sure to check it out!
 
@@ -40,6 +40,10 @@ Look at the [Installation](./installation) and the [Usage](./usage) pages for a
 
 We'd LOVE to add more templates. Make a template according to pandoc's rules, and send in a PR. Don't know what any of this is? That's ok, share an Overleaf or some such template which we'll try to add if we like it and have time!
 
+## I Wanna contribute too!
+
+See the [devdocs](./devdocs)
+
 ## WOW! SUCH A SUPERB TEMPLATE! WHO MADE IT?
 
 Why, thanks! Mayukh Chakrabarty of MS18 made this template, all credits to him. Tailoring it to use with pandoc was done by Dhruva Sambrani. Drop in a thanks to Dhruva @ ms18163 or Mayukh @ ms18046

docs/int_usage.md

@@ -0,0 +1,51 @@
+# WARNING
+
+This is an older version of the pprb which had an interactive mode. But it was built in a very half assed manner, so it's deprecated for now.
+
+# Usage
+
+All usage is explained as in interactive mode. CLI Mode is the same as interactive mode, except you must run as `PaperBuilder command_with_params`.
+
+## Start PaperBuilder
+
+### Windows
+
+The installation adds an entry to the start menu. Simply search for `PaperBuilder` and click.
+
+### Linux
+
+The installation adds an alias to your `~/.bashrc` file. Simply running `pprb` in a bash terminal should be enough for most.
+
+If you are using another terminal, add an alias to, or run `~/.PaperBuilder/PaperBuilder.py`.
+
+### If you were too smart
+
+Run the `PaperBuilder.py` from wherever it is installed.
+
+## New project
+
+In the interactive shell, run `new new_project_path`
+
+This creates a folder `new_project_path` and 2 files in it, `content.md` and `bibliography.bib`.
+
+`content.md` is where you put your content. Markdown syntax is already available in the file. Once you have read it, clear it and put your content. Add the metadata.
+
+`bibliography.bib` is where all your references go in bibtex format. Almost all websites allow you to download citations in bibtex. Cite as [@citationname] in `content.md`. For example, [@einstein] will cite the bibtex entry with name `einstein`
+
+## Build paper
+
+This is where the magic happens.
+
+In the interactive shell, run `pdf path_to_project`
+
+And voila, if you've done everything correctly, you should have `content.pdf` in your project folder!
+
+Incase you are unable to/ don't want to install latex, you can also use `latex path_to_project` which creates a latex file `content.tex` which you can compile online using Overleaf. This is also useful if you want to make some changes to the Latex file.
+
+## Other Running options
+
+These are not necessary for normal use. This is for debugging.
+
+- `--help` - Display help
+- `--debug` - Print debug info
+- `--noop` - No operation mode. Use with `--debug` if no actions are to be taken

docs/usage.md

@@ -2,27 +2,31 @@
 
 All usage is explained as in interactive mode. CLI Mode is the same as interactive mode, except you must run as `PaperBuilder command_with_params`.
 
-## Start PaperBuilder
+## Open a Terminal
 
 ### Windows
 
-The installation adds an entry to the start menu. Simply search for `PaperBuilder` and click.
+1. Hit `Win-X` then `i`. This will open a powershell terminal. 
+2. Run `cd ~\Documents` or some other location
+3. Run `PaperBuilder --help`. This should print a help screen
 
-### Linux
+### Linux - Default installation
 
-The installation adds an alias to your `~/.bashrc` file. Simply running `pprb` in a bash terminal should be enough for most.
+1. Start a terminal
+2. `cd ~/Documents` or some other location
+3. Run `pprb --help`. This should print a help screen
 
-If you are using another terminal, add an alias to, or run `~/.PaperBuilder/PaperBuilder.py`.
+### Non Standard installations
 
-### If you were too smart
-
-Run the `PaperBuilder.py` from wherever it is installed.
+1. Start a terminal
+2. `cd ~/Documents` or some other location
+3. run the `\path\to\PaperBuilder.py --help`. This should print a help screen
 
 ## New project
 
-In the interactive shell, run `new new_project_path`
+Run `PaperBuilder new new_project_path`. Replace `PaperBuilder` with `pprb` for linux.
 
-This creates a folder `new_project_path` and 2 files in it, `content.md` and `bibliography.bib`.
+This creates a folder `new_project_path` in the cwd(`Documents` if you used the above location) and 2 files in it, `content.md` and `bibliography.bib`.
 
 `content.md` is where you put your content. Markdown syntax is already available in the file. Once you have read it, clear it and put your content. Add the metadata.
 
@@ -32,16 +36,48 @@ This creates a folder `new_project_path` and 2 files in it, `content.md` and `bi
 
 This is where the magic happens.
 
-In the interactive shell, run `pdf path_to_project`
+Run `PaperBuilder build_type path_to_project` where `build_type` is one of the types in the table below. Replace `PaperBuilder` with `pprb` for linux.
 
 And voila, if you've done everything correctly, you should have `content.pdf` in your project folder!
 
-Incase you are unable to/ don't want to install latex, you can also use `latex path_to_project` which creates a latex file `content.tex` which you can compile online using Overleaf. This is also useful if you want to make some changes to the Latex file.
+Incase you are unable to/don't want to install latex, use the `ltx*` build types, which create a latex file `content.tex` which you can compile online using Overleaf. This is also useful if you want to make some changes to the Latex file directly.
+
+| Build Type | Use Case                                                      |
+| ---------- | ------------------------------------------------------------- |
+| report     | An elaborate format for building talk reports/seminar reports |
+| assign     | Simple format for assignments                                 |
+| ltxreport  | LaTeX file for `report` format                                |
+| ltxassign  | LaTeX file for `assign` format                                |
+| pdf        | same as `report`                                              |
+| latex      | same as `ltxreport`                                           |
+
+See the [Examples](./examples) page for a sneak peak into how each format looks
+
+## The --extra option
+
+In some cases you may need to send extra arguments to pandoc. For these use the `--extra="Your args"` option. Pandoc arguments can be found [here](https://pandoc.org/MANUAL.html#options)
+Be careful of double quoting and spaces.
+
+Example: `PaperBuilder report test --extra="--pdf-engine=xelatex"`
+
+### The default extras
+
+For cases below, the default `--extra` is often enough. See [Examples](./examples) for a demo.
+
+- Using unicode characters directly
+- Adding a dark theme for code blocks
+- Adding Bold SmallCaps characters (used in the title of `report`)
+
+To use this, the following setup needs to be done
+| OS      | Change                                                                         |
+| ------- | ------------------------------------------------------------------------------ |
+| Windows | In MikTex Console, go to Packages, search for `gyre` and install both results. |
+| Linux   | Install `texlive-xetex` using apt                                              |
 
 ## Other Running options
 
 These are not necessary for normal use. This is for debugging.
 
-- `--help` - Display help
-- `--debug` - Print debug info
+- `--help` - Display help. A minimal help to remind you what is what.
+- `--debug` - Print debug info. Especially useful for choosing the correct extra args
 - `--noop` - No operation mode. Use with `--debug` if no actions are to be taken

linux/install.sh

@@ -15,7 +15,7 @@ echo "    Installing..."
 sudo apt install ~/.paperbuilder/temp/pandoc.deb
 
 echo "  Installing texlive"
-sudo apt install texlive-latex-extra texlive-xetex
+sudo apt install texlive-latex-extra
 
 echo "  Installing python3"
 sudo apt install python3

linux/install_local.sh

@@ -0,0 +1,33 @@
+echo "Updating packages"
+sudo apt update
+sudo apt upgrade -y
+sudo apt autoclean
+
+echo "Installing Pre Requisites..."
+
+mkdir -p ~/.paperbuilder/temp
+
+echo "  Pandoc"
+echo "    Downloading..."
+curl -#L https://github.com/jgm/pandoc/releases/download/2.11.0.2/pandoc-2.11.0.2-1-amd64.deb -o ~/.paperbuilder/temp/pandoc.deb
+
+echo "    Installing..."
+sudo apt install ~/.paperbuilder/temp/pandoc.deb
+
+echo "  Installing texlive"
+sudo apt install texlive-latex-extra
+
+echo "  Installing python3"
+sudo apt install python3
+
+echo "Installing PaperBuilder from repo"
+cp ./src/* ~/.paperbuilder
+
+echo "  Adding pprb alias to ~/.bashrc"
+echo "alias pprb=~/.paperbuilder/src/PaperBuilder.py" >> ~/.bashrc
+
+echo "  Deleting temp files"
+rm -r ~/.paperbuilder/temp
+
+echo "DONE!"
+echo "run 'source ~/.bashrc' and then 'pprb' to start"