diff --git a/Portable_PDD/Compile.bat b/Markdown_to_TeX/Compile.bat similarity index 60% rename from Portable_PDD/Compile.bat rename to Markdown_to_TeX/Compile.bat index 5f281e4..00b4bfd 100644 --- a/Portable_PDD/Compile.bat +++ b/Markdown_to_TeX/Compile.bat @@ -1,12 +1,17 @@ @echo OFF + +REM This is a .bat file that can be used to compile a markdown file using a latex template file. +REM The latex template file has variables/sections that are populated from the markdown file. +REM This is a Windows file and there should be a corresponding linux/macos compile script. + REM This is where you specify the path of your document. -set DOCUMENT_PATH="markdown_template.md" +set DOCUMENT_PATH="Templates\\markdown_template.md" REM This is where you specify the final name of your document. Spaces will be replaced with underscores. set FINAL_DOC_NAME="50_SAT" REM This is the where you specify the template of the .tex file. -set PDD_TEMPLATE="spex_template.tex" +set PDD_TEMPLATE="Templates\\PDD_Template.tex" REM You can specify the type of compiler script. It expects an input of the path of the .tex document. set COMPILE_SCRIPT="..\\Compile_Scripts\\MikTexCompiler.bat" diff --git a/Portable_PDD/spex_template.tex b/Markdown_to_TeX/Templates/PDD_Template.tex similarity index 97% rename from Portable_PDD/spex_template.tex rename to Markdown_to_TeX/Templates/PDD_Template.tex index c39e8d3..a8126ec 100644 --- a/Portable_PDD/spex_template.tex +++ b/Markdown_to_TeX/Templates/PDD_Template.tex @@ -43,7 +43,7 @@ \makenomenclature{} % set title. choose something as descriptive and precise as possible. Descriptive > sounding cool. remember this! -\title{TITLETAG} +\title{TITLE_TAG} \author{ @@ -56,13 +56,13 @@ % Read here for a more advanced options to modifying footnotes in the author block: \url{http://tex.stackexchange.com/questions/826/symbols-instead-of-numbers-as-footnote-markers} % Here, we use the IEEE long-form author block. \IEEEauthorblockN{% This block is for author Names. - STUDENTTAG%\IEEEauthorrefmark{1}, + AUTHORS_TAG%\IEEEauthorrefmark{1}, } \IEEEauthorblockA{% This block is for the author Afficliations, aka department and university RIT Space Exploration, Rochester Institute of Technology \\ %\\ starts a new line Rochester, N.Y. \\ Email: - EMAILTAG%\IEEEauthorrefmark{1}tjt3085@rit.edu, + EMAIL_TAG%\IEEEauthorrefmark{1}tjt3085@rit.edu, } %% Below, we use the short-form author block and basically hack it to suit our needs. % Philip~Linden$^{*\dagger}$% @@ -86,17 +86,17 @@ %% There are ways to make LaTeX do this for you, but it is more advanced and not entirely necessary, especially for short author lists. Not worth the hassle, in my opinion. } % page header for pages other than cover page -\markboth{TITLETAG}% +\markboth{TITLE_TAG}% {Tarazevits \MakeLowercase{\textit{et al.}}: RIT Space Exploration} % Initial setup is over, start building the document itself \begin{document} -\maketitle% +\maketitle % correct bad hyphenation here, separated by spaces \hyphenation{explor-ation} \begin{abstract} -ABSTRACTTAG +ABSTRACT_TAG % The abstract is a brief summary of the design document. Typically it includes the purpose of the design document, key goals or objectives, and justifications. % Be sure not to confuse the abstract with the introduction. @@ -128,7 +128,7 @@ \nomenclature{CSLI}{CubeSat Launch Initiative} \nomenclature{AMSAT}{Amateur Radio in Space} -SECTIONTAG +SECTION_TAG \bibliography{SPEX50SAT} \onecolumn diff --git a/Markdown_to_TeX/Templates/markdown_template.md b/Markdown_to_TeX/Templates/markdown_template.md new file mode 100644 index 0000000..96c3abc --- /dev/null +++ b/Markdown_to_TeX/Templates/markdown_template.md @@ -0,0 +1,127 @@ +--- +TITLE_TAG: 50\$ Satellite PDD AUTHORS_TAG: Evan Putnam, Another Student +EMAIL_TAG: emp9173@rit.edu, someOtherEmail@spex.com TEMP_TAG: Hello World +--- + + + +# ABSTRACT +HERE BE A BIG HONKING ABSTRACT! + +# Section 1 +Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor +incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis +nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. +Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu +fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in +culpa qui officia deserunt mollit anim id est laborum. + +## Subsection 1.1 +Hey how is it going? + + +Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor +incididunt ut labore et dolore magna aliqua. + +Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut +aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in +voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint +occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim +id est laborum. + +## Subsection 1.2 +Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor +incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis +nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. +Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu +fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in +culpa qui officia deserunt mollit anim id est laborum. + + +# Section 2 +Here is another section! + +## Subsection 2.1 +Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor +incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis +nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. +Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu +fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in +culpa qui officia deserunt mollit anim id est laborum. + +# Section 3 +## Subsection 3.1 +You can also include subsections where the section does not include text. + + +Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor +incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis +nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. +Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu +fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in +culpa qui officia deserunt mollit anim id est laborum. + +# Section 4 +## LaTeX Tables + + +This is a table \autoref{table:somechart} + + +\begin{table} + \centering + \caption{Estimated Timeline} + \begin{tabularx}{\columnwidth}{@{}cXl@{}} \toprule + Phase & Task & Duration \\ \midrule + 1 & Review existing \$50SAT designs and materials & 2 weeks or less \\ + 2 & Subsystem development & 6 weeks \\ + & Order PCB design and/or assembly & 6 weeks \\ + & Review changes to mechanical strucuture and order materials & 2 weeks or less \\ + & Testing of individual subsystems & 2 weeks \\ + 3 & System Assembly & 1 week \\ + 4 & System testing & 2 weeks \\ + 5 & Generate documentation and delivery to SPEX & 1 week \\ + \bottomrule + \end{tabularx} +\label{table:somechart} +\end{table} \\ + + +\begin{figure}[h] + \centering + \includegraphics[width=12cm, height=9cm]{../spex.png} + \caption{Here is the SPEX Logo.} +\end{figure} diff --git a/Portable_PDD/markdown_compile.py b/Markdown_to_TeX/markdown_compile.py similarity index 80% rename from Portable_PDD/markdown_compile.py rename to Markdown_to_TeX/markdown_compile.py index 58bfa3d..8b18445 100644 --- a/Portable_PDD/markdown_compile.py +++ b/Markdown_to_TeX/markdown_compile.py @@ -1,32 +1,30 @@ """ Author: Evan Putnam -Description: This is a python file that converts basic markdown to the SPEX PDD. +Description: This is a python file that converts basic markdown to a latex file based on a template. -TODO: Have the option to easily define additional meta-data tags. TODO: Integrate some additional features. See LatexMarkdownCompiler.compile() function. -TODO: Add additional logging beyond print statements. The logic is not anything special and is just a state machine handling basic conditions. - -SPEX Members are free to improve upon it as they see fit. +SPEX Members are free to improve upon it as they see fit with the pull request system on Github. """ import os import sys import re import shutil +import logging import argparse -# Possible regex for removing comments. -TEMPLATE_FILE = "spex_template.tex" +#Possible regex for removing comments. +TEMPLATE_FILE = ".\\Templates\\PDD_Template.tex" COMPILER = ".\\Compile_Scripts\\MikTexCompiler.bat" +#Name of log file +LOG_FILE_NAME = "markdown_compile.log" + #Template tags that exist inside the SPEX document. -TITLE = "TITLETAG" -STUDENT_NAMES = "STUDENTTAG" -STUDENT_EMAILS = "EMAILTAG" -ABSTRACT = "ABSTRACTTAG" -SECTION_START = "SECTIONTAG" +ABSTRACT = "ABSTRACT_TAG" +SECTION_START = "SECTION_TAG" @@ -87,8 +85,10 @@ def _filter_out_comments(self): #Comments are malformed so this is an error. if start_comment == True or comment_balance != 0: - print("***** ERROR: Malformed comments. Can not parse the document. Please fix you comments to have a starting and ending tag." ) - print("In addition do NOT have anywhere in your markdown document that you do not expect a comment.") + error_message = "Malformed comments. Can not parse the document. Please fix you comments to have a starting and ending tag.\n" + error_message += "In addition do NOT have anywhere in your markdown document that you do not expect a comment." + print("***** ERROR: " + error_message) + logging.error(error_message) sys.exit(1) #Return markdown document text without markdown comments @@ -106,16 +106,13 @@ def _parse(self): #Start metadata search bool start_metadata = False - #Items to find from metadata in test.md - title = None - authors = None - emails = None - #Section storage current_section = None current_sub_section = None section_dict = {} + tag_key_values = {} + for line in markdown_file_str: #Start looking for metadata if line.startswith("---") and not start_metadata: @@ -128,24 +125,15 @@ def _parse(self): #If we are looking for metadata elif start_metadata: #Search for specific tags. - if "title:" in line: - temp = "title:" - title = line[line.find(temp) + len(temp):].strip() - elif "authors:" in line: - temp = "authors:" - authors = line[line.find(temp) + len(temp):].strip() - elif "emails:" in line: - temp = "emails:" - emails = line[line.find(temp) + len(temp):].strip() + line_parts = line.split(":") + tag_key = line_parts[0].strip() + tag_value = ":".join(line_parts[1:]).strip() + tag_key_values[tag_key] = tag_value + #Look at subsections else: - #If we can't identify metadata then error - if line.startswith("#") and title == None: - print("***** ERROR: Malformed metadata. Please include a title, authors, and emails" ) - print(line) - sys.exit(1) #If start of section - elif line.startswith("#") and not line.startswith("##"): + if line.startswith("#") and not line.startswith("##"): current_sub_section = None temp = "#" current_section = line[line.find(temp) + len(temp):].strip() @@ -157,6 +145,7 @@ def _parse(self): if current_section == None: print("***** Error: Subsection before section") print(line) + logging.error("Subsection before section: "+line) sys.exit(1) #Else handle section else: @@ -180,16 +169,14 @@ def _parse(self): elif line.strip() != "": print("***** Error: Malformed sections/subsections") print(line) + logging.error("Malformed sections/subsections") sys.exit(1) if self.verbose: #Print out wonderful information. - print(title) - print(authors) - print(emails) print(section_dict) #Items that populate the spex_template.tex file - return title, authors, emails, section_dict + return tag_key_values, section_dict #--------------------------------------------------------------------- # Converts the markdown items to latex format and puts it into @@ -200,12 +187,15 @@ def _latex_string(self, sections): #If no sections are detected then errors out. if len(sections) == 0: print("***** Error: No sections detected in your markdown file.") + logging.error("No sections detected in your markdown file.") sys.exit(1) #If no abstract it errors out. Shame on you... if "ABSTRACT" not in sections: - print("***** Error: No abstract in markdown. Make a section titled #ABSTRACT") - sys.exit(1) + print("----- Warning: No abstract in markdown. Most documents should have an abstract.") + logging.warning("No abstract in markdown. Most documents should have an abstract.") + + logging.debug(str(sections)) if self.verbose: print(sections) @@ -214,11 +204,12 @@ def _latex_string(self, sections): sections_str = "" #Get abstract data - for txt in sections["ABSTRACT"]["text"].split("\n"): - if txt.strip() == "": - continue - abstract_str += txt - abstract_str += (r"\\") + ("\n") + if "ABSTRACT" in sections: + for txt in sections["ABSTRACT"]["text"].split("\n"): + if txt.strip() == "": + continue + abstract_str += txt + abstract_str += (r"\\") + ("\n") #Get section data for section in sections: @@ -241,7 +232,9 @@ def _latex_string(self, sections): continue sections_str += txt sections_str += (r"\\") + ("\n") - + + logging.debug(str(abstract_str)) + logging.debug(str(sections_str)) if self.verbose: #Prints out latex formatted strings. print(abstract_str) @@ -262,13 +255,12 @@ def _latex_string(self, sections): # Somewhere between or after the self._parse() call and the self._latex_string call # there is opportunity to post process more if need be. The following features would be good. # - TODO: Include bold and italics - # - TODO: Include basic bullited lists. - # - TODO: Image syntax of some sort. - # For now users can default back to LaTeX tho and code has been provided in test.md for it. + # - TODO: Include basic bulleted lists. + # For now users can default back to LaTeX though and code has been provided in test.md for it. #--------------------------------------------------------------------- def convert(self): #Get information needed for document - title, authors, emails, sections = self._parse() + tag_key_values, sections = self._parse() #Get latex formatted abstract and sections/subsections abstract_latex, sections_latex = self._latex_string(sections) @@ -279,13 +271,16 @@ def convert(self): tex_contents = fle.read() #Replace template tags with relevant data. - tex_contents = tex_contents.replace(TITLE, title) - tex_contents = tex_contents.replace(TITLE, title) - tex_contents = tex_contents.replace(STUDENT_NAMES, authors) - tex_contents = tex_contents.replace(STUDENT_EMAILS, emails) - tex_contents = tex_contents.replace(ABSTRACT, abstract_latex) + if abstract_latex != "": + tex_contents = tex_contents.replace(ABSTRACT, abstract_latex) tex_contents = tex_contents.replace(SECTION_START, sections_latex) + for key in tag_key_values: + times_to_replace = tex_contents.count(key) + for i in range(0, times_to_replace): + tex_contents = tex_contents.replace(key, tag_key_values[key]) + + logging.debug(tex_contents) if self.verbose: #Output complete LaTeX document. print("") @@ -308,15 +303,22 @@ def convert(self): def compile(self, tex_path): #Compile the script. System call is bat script, path of file, path of - #folder that file exists in. - os.system("%(compiler)s %(tex_dir)s %(tex_file)s" % { - "compiler": self.bat_script, - "tex_dir": self.name, - "tex_file": ".\\" + tex_path - }) + #folder that file exists in. It compiles twice to fix fairly common issues with broken references in .aux file. + for i in range(0, 2): + os.system("%(compiler)s %(tex_dir)s %(tex_file)s" % { + "compiler": self.bat_script, + "tex_dir": self.name, + "tex_file": ".\\" + tex_path + }) + if __name__ == "__main__": + #Initialize logging. + if os.path.exists(LOG_FILE_NAME): + os.remove(LOG_FILE_NAME) + logging.basicConfig(filename=LOG_FILE_NAME) + #Create the parser. parser = argparse.ArgumentParser( description="converts basic markdown to TeX and PDF") parser.add_argument( diff --git a/Portable_PDD/spex.png b/Markdown_to_TeX/spex.png similarity index 100% rename from Portable_PDD/spex.png rename to Markdown_to_TeX/spex.png diff --git a/Portable_PDD/markdown_template.md b/Portable_PDD/markdown_template.md deleted file mode 100644 index d65a4dd..0000000 --- a/Portable_PDD/markdown_template.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -title: 50\$ Satellite PDD -authors: Evan Putnam, Another Student -emails: emp9173@rit.edu, someOtherEmail@spex.com ---- - - - - - -# ABSTRACT -This is where you should put your abstract text. This is very important for detailing how your document is about and every document is required to have one. - -# Section 1 -Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.s -## Subsection 1.1 -Hey how is it going? - - -Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. - -## Subsection 1.2 -Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. - - -#Section 2 -Here is another section! - -## Subsection 2.1 -Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. - -#Section 3 -## Subsection 3.1 -You can also include subsections where the section does not include text. - - -Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. - -#Section 4 -## LaTeX Tables - -\autoref{tab:timeline} - - -\begin{table} - \caption{Estimated Timeline} - \centering - \begin{tabularx}{\columnwidth}{@{}cXl@{}} \toprule - Phase & Task & Duration \\ \midrule - 1 & Review existing \$50SAT designs and materials & 2 weeks or less \\ - 2 & Subsystem development & 6 weeks \\ - & Order PCB design and/or assembly & 6 weeks \\ - & Review changes to mechanical strucuture and order materials & 2 weeks or less \\ - & Testing of individual subsystems & 2 weeks \\ - 3 & System Assembly & 1 week \\ - 4 & System testing & 2 weeks \\ - 5 & Generate documentation and delivery to SPEX & 1 week \\ - \bottomrule - \end{tabularx} -\label{tab:timeline} -\end{table} - - -\begin{figure}[h] - \centering - \includegraphics[width=12cm, height=9cm]{../spex.png} - \caption{Here is the SPEX Logo.} -\end{figure} \ No newline at end of file diff --git a/README.md b/README.md index 2527506..5343951 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,21 @@ # RIT-SPEX/latex-utils This repository contains scripts for turning TeX into beautiful documents. -## Prerequisite Software +## Table of Contents +* [Prerequisite Software](#prerequisite-software) +* [Install a LaTeX compiler on your machine](#Install-a-LaTeX-compiler-on-your-machine) + * [Tectonic](#Tectonic) + * [MikTeX](#MikTeX) + * [TeX Live](#TeX-Live) + * [Use a Docker container instead](#Use-a-Docker-container-instead) +* [Compiling Markdown to LaTeX with a Template](#Compiling-Markdown-to-LaTeX-with-a-Template) + * [Supported syntax](#Supported-syntax) + * [Special tags](#Special-tags) + * [Comments](#Comments) + * [Run the Markdown-to-TeX compiler](#Run-the-Markdown-to-TeX-compiler) + + +# Prerequisite Software These tools assume the user has the following software installed on their machine. Installation and usage instructions will not cover using this software. @@ -14,7 +28,7 @@ software. **Note:** Documentation for this repository assumes that a Windows user is using Windows Powershell. While most of the Linux instructions should work within the Windows Subsystem for Linux (WSL) environment on a Windows machine, -proceed at your own risk. +proceed at your own risk. # Install a LaTeX compiler on your machine Use the following instructions to install a LaTeX compiler on your local @@ -54,7 +68,7 @@ installed, you must install it using the included GUI package manager. | **Mac** | `brew cask install mactex` | | **Linux** | `apt-get install texlive` | -# Use a Docker container instead +## Use a Docker container instead Rather than installing and managing a TeX distribution on your local machine, you may prefer to send your TeX project to a Docker container for compilation. @@ -64,4 +78,63 @@ run virtual environments on your machine's turbo encabulators. Compile a TeX project with Tectonic with a docker container with ```shell ./compile_scripts/compile_with_tectonic.sh -``` \ No newline at end of file +``` + +# Compile Markdown to TeX with a Template +The Python script `Portable_PDD/markdown_compile.py` is used to convert a +Markdown (`.md`) text file into a LaTeX (`.tex`) file following a given TeX +template. This script also allows mixed Markdown and TeX formatting in the same +file. + +The Markdown to LaTeX compiler makes writing content faster, easier, and more +readable by beginning in Markdown and formatting to TeX automatically. A TeX +template is used to format the resultant `.tex` file, including titles, author +blocks, section formatting, and so on. + +## Supported syntax +| Syntax | Markdown | LaTeX | +| ------ | -------- | ----- | +| Sections | `# my section` | `\section{my section}` | +| Subsections | `## my subsection` | `\subsection{my subsection}` | +| Paragraph text | as is | as is | +| Line breaks | (empty line between paragraphs) | (empty line between paragraphs) | +| Basic LaTeX syntax | typed as normal text | as is | + +### Special tags +The `.tex` template defines the names of special tags and dictates where they +are used. At very start of the Markdown file, define tags and their values. The +values are injected directly into the `.tex` template exactly as they are +entered here. + +```markdown +--- +TITLE_TAG: 50\$ Satellite PDD +AUTHORS_TAG: Evan Putnam, Another Student +EMAIL_TAG: emp9173@rit.edu, someOtherEmail@spex.com +TEMP_TAG: Hello World +--- +``` + +### Comments +Comments are allowed in the Markdown file, but they are ignored by the compiler +will not appear in the resultant TeX file. + +There can only be one single line comment per line. Nested comments are not +supported. Multiline comments are only supported if you have a single start and +end on a separate line. + +``` + +``` +``` + +``` + +## Run the Markdown-to-TeX compiler +instructions on how to actually run the compiler