{"id":16567822,"url":"https://github.com/sylvainhalle/papershell","last_synced_at":"2025-04-05T12:08:37.204Z","repository":{"id":23569600,"uuid":"26937411","full_name":"sylvainhalle/PaperShell","owner":"sylvainhalle","description":"Nice and flexible template environment for papers written in LaTeX","archived":false,"fork":false,"pushed_at":"2025-02-21T15:08:45.000Z","size":935,"stargazers_count":139,"open_issues_count":3,"forks_count":17,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-29T11:11:25.703Z","etag":null,"topics":["acm","conference","elsevier","ieee","journal","latex","makefile","overleaf","paper","research-paper","template","tex"],"latest_commit_sha":null,"homepage":null,"language":"TeX","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sylvainhalle.png","metadata":{"files":{"readme":"Readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"authors.txt","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-11-20T23:49:09.000Z","updated_at":"2025-02-21T15:08:49.000Z","dependencies_parsed_at":"2024-10-26T20:28:54.162Z","dependency_job_id":"801a7f12-13a1-4bf5-86d2-c259526bdbf3","html_url":"https://github.com/sylvainhalle/PaperShell","commit_stats":null,"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sylvainhalle%2FPaperShell","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sylvainhalle%2FPaperShell/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sylvainhalle%2FPaperShell/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sylvainhalle%2FPaperShell/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sylvainhalle","download_url":"https://codeload.github.com/sylvainhalle/PaperShell/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247332612,"owners_count":20921853,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["acm","conference","elsevier","ieee","journal","latex","makefile","overleaf","paper","research-paper","template","tex"],"created_at":"2024-10-11T21:07:35.362Z","updated_at":"2025-04-05T12:08:37.180Z","avatar_url":"https://github.com/sylvainhalle.png","language":"TeX","funding_links":[],"categories":[],"sub_categories":[],"readme":"A Flexible LaTeX Article Environment\n====================================\n\nThis repository provides a boilerplate environment for writing LaTeX\narticles using the popular templates from Springer, IEEE, ACM, AAAI,\nElsevier, etc. It provides:\n\n- The up-to-date style and bibliography files of many different publishers\n  (journals and conferences)\n- A script that generates the proper preamble (title, list of authors and\n  institution) specific to each style\n- A very advanced Makefile (by [Chris\n  Monson](https://github.com/shiblon/latex-makefile)) taking care of the\n  compilation/cleaning process\n- Scripts (for both Windows and Linux) to perform spell checking of the\n  LaTeX source with [GNU Aspell](http://aspell.net). The words added to the\n  dictionary while checking are also versioned with the project.\n- A script that can \"flatten\" your sources into a single compilable .tex file\n  (with all includes and bibliography) and export all resources in a\n  stand-alone folder (ideal for exporting the camera-ready sources to an\n  editor)\n- A `.gitignore` file suitable for a single-document LaTeX project\n- A script to clean up a BibTeX file\n- A script to produce the diff between two versions of the same paper\n  highlighting the edits (using `latexdiff` in the background)\n\nUsing this template, switching a paper from any stylesheet to any other\nsimply amounts to regenerating two files with an included PHP script. You\ndon't need to change a single line of the main, `paper.tex` document you\nare working on. What is more, the project's structure can be imported and\nused within [Overleaf](https://www.overleaf.com).\n\nWhy this template?\n------------------\n\nIf you have been writing lots of (Computer Science) papers, you may have\nbeen mostly using LaTeX with a couple of different document classes:\n\n- `aaai` for AAAI journals\n- `acmart` for ACM conferences and journals\n- `easychair` for [EasyChair EPiC Series and Kalpa Publications series](https://easychair.org/publications/for_authors)\n- `elsarticle` for Elsevier journals\n- `eptcs` for the *Electronic Proceedings in Theoretical Computer Science*\n- `IEEEtran` for IEEE conference proceedings and journals\n- `lipics` for the *Leibniz International Proceedings in Informatics*\n- `llncs` for Springer's *Lecture Notes in Computer Science* series\n- `sig-alternate` for ACM conference proceedings\n- `stvrauth` and similar for Wiley Journals\n- `svjour` for Springer journals\n- `usenix2019_v3` for USENIX publications\n\nFirst off, this repository provides a well-structured template project where\nall these classes are included, so you can pick the one you wish when\nstarting to write. Moreover, it comes with a very powerful Makefile that\ndoes all sorts of nifty things, such as suppressing useless output from\nLaTeX and colouring (yes, colouring) its meaningful output (errors in red,\netc.).\n\nThere do exist products, such as [Overleaf](https://www.overleaf.com), which\nallow you to instantiate a blank LaTeX paper using many of these templates\n(PaperShell can interact nicely with Overleaf; see below). However, there might\nbe various reasons for which you might want to switch an existing document from\none class to the other. For example, you started writing a paper without\ndeciding where to send it, only to find that the conference you've chosen has a\ndifferent publisher than the paper's current style. Or, a paper sent to a\nconference (and perhaps rejected) needs to be sent to another venue with a\ndifferent publisher. (Note that in the past, it used to be the *publisher's* job\nto format your manuscript to their taste. But that's another story.)\n\nAlas, it turns out these stylesheets are not directly interchangeable.\nRather than nicely overriding the behaviour of LaTeX's original commands\nfrom the `article` document class, each class decided to invent its own\ncommands to, e.g., define the title, authors and institution of a document\n--and none of them works the same way. For example, here is how to declare\nauthors and institutions in `llncs`:\n\n    \\author{Emmett Brown\\inst{1} \\and Marty McFly\\inst{1} \\and Biff Tannen\\inst{2}}\n    \\institute{%\n    Temporal Industries \\\\\n    Hill Valley, CA 90193 \\\\\n    \\and\n    BiffCo inc. \\\\\n    Hill Valley, CA 90193 \\\\\n    }\n\n...in `IEEEtran`:\n\n    \\author{%\n    \\IEEEauthorblockN{Emmett Brown, Marty McFly}\n    \\IEEEauthorblockA{%\n    Temporal Industries\\\\\n    Hill Valley, CA 90193\\\\\n    }\n    \\IEEEauthorblockN{Biff Tannen}\n    \\IEEEauthorblockA{%\n    BiffCo inc.\\\\\n    Hill Valley, CA 90193\\\\\n    }\n    }\n\n...in `acmart`:\n\n    \\author{Emmett Brown}\n    \\affiliation{\n      \\institution{Temporal Industries}\n      \\streetaddress{Hill Valley}\n      \\state{CA}\n      \\postcode{90193}\n    }\n    \\author{Biff Tannen}\n    \\affiliation{\n      \\institution{BiffCo inc.}\n      \\streetaddress{Hill Valley}\n      \\state{CA}\n      \\postcode{90193}\n    }\n\n...and in `elsarticle`:\n\n    \\author{Emmett Brown\\fnref{label1}}\n    \\author{Marty McFly\\fnref{label1}}\n    \\author{Biff Tannen\\fnref{label2}}\n    \\fntext{Temporal Industries, Hill Valley, CA 90193}\n    \\fntext{BiffCo inc., Hill Valley, CA 90193}\n\nFour different sets of commands and syntax for the same data ---and all this\nwhile `article.cls` already provides commands doing exactly that, which\ncould have easily been overridden! To make things even worse, the class\nelsarticle does not even use `\\maketitle` to print the title, which must be\nenclosed (along with the abstract) within a `frontmatter` environment *after*\nthe `\\begin{document}`. Therefore, switching between classes\nrequires some amount of braindead, yet frustrating copy-pasting from\nexisting files you have, which arguably becomes quite mind-numbing when\nyou've been doing that once in a while for the past ten years. And sadly,\ntools like Overleaf do not allow you to easily switch templates once you've\nstarted writing.\n\nIn this project, the paper's title, authors and institutions are written in\na separate file called `authors.txt`:\n\n    Applications of the Flux Capacitor\n    \n    Emmett Brown (1)\n    Marty McFly (1)\n    Biff Tannen (2)\n    \n    1\n    Temporal Industries\n    Hill Valley, CA 95420\n    \n    2\n    BiffCo inc.\n    Hill Valley, CA 95420\n\n(You can optionally separate first and last names with braces, e.g.\n`{Marty} {McFly}`. This is used in the EPTCS style for writing\nabbreviated author names, e.g. \"E. Brown, M. McFly, B. Tannen\", etc.)\n\nYou then call a script named `set-style.php` to generate a preamble and\npostamble with the proper syntax for the document classes you want to use. These\nfiles are called `preamble.inc.tex` and `postamble.inc.tex`.\n\nTo change the authors or title, or to switch between document classes, modify\n`authors.txt` and run`set-style.php` again. You then just need to recompile.\nVoilà!\n\nQuick Use\n---------\n\n0. [Download and unzip](https://github.com/sylvainhalle/PaperShell/releases/latest)\n   the PaperShell empty project in a folder of your choice.\n\n1. Modify `authors.txt` with the desired title, authors and institutions.\n   The file is self-documented and tells you how to do it.\n\n2. Call `php set-style.php style` to generate the include files, which\n   will be placed in the `Source` subfolder. (This requires\n   [PHP](http://php.net/) to be installed in your path.) The word `style`\n   must be replaced by the name of a paper template, which you can select\n   from a long list. Some of the available styles are: lncs,\n   ieee, acmconf, elsevier, springer, aaai, acmjour, eptcs, stvr, lipics,\n   easychair, usenix.\n\n3. Write your text as usual in `Source/paper.tex`. Figures should\n   be placed in the `fig` subfolder. Write your abstract in\n   `Source/abstract.tex`, and put any other imports and declarations in\n   `Source/includes.tex`. Write anything that should go after the\n   bibliography (such as appendices) in `Source/appendices.tex`.\n\n4. To compile, use `make all`. To remove temporary files, use `make clean`.\n   The Makefile has a very comprehensive list of other useful features. To\n   read them, run `make help`.\n\n5. To spell check, type `./aspell-check.sh` (in Linux) or `aspell-check.bat`\n   (in Windows) from the project's top folder. Any additions to the\n   personal dictionary will be reflected in changes to files\n   `.aspell.en.prepl` and `.aspell.en.pws`, which are versioned with the\n   rest of the project. See the file `aspell-check.readme` for instructions.\n   (Hint: you may also want to try\n   [TeXtidote](https://github.com/sylvainhalle/textidote)).\n\nExtras\n------\n\nAs an extra, the generated preamble files add a few commands that fix bugs\nin some document classes.\n\n- The preamble for IEEE journal fixes a [problem with a redefinition of the\n  `\\markboth` command](http://tex.stackexchange.com/a/88864) that would\n  otherwise prevent the document from compiling\n- The postamble for Elsevier fixes the fact that the bibliography [does not have a section\n  title](http://tex.stackexchange.com/questions/188625/no-references-title-using-elsevier-document-class)\n- The EPTCS BibTeX file incorrectly handles `doi` fields that contain an underscore.\n  PaperShell contains a fixed version.\n- The LIPIcs style is incompatible with the `subfig` package.\n  PaperShell contains a fixed version.\n- The Springer Nature journal style has a [bug causing Tikz to break compilation](https://tex.stackexchange.com/q/615012). PaperShell contains a fixed version.\n- The Springer Nature journal style also redefines the `\\href` command of the `hyperref` package in a way that the link's text is never shown. PaperShell has a version where this redefinition is commented out.\n\nIt also takes care of using fonts properly:\n\n- The original style files load obsolete font packages; PaperShell overrides\n  them with newer ones with much nicer math support (e.g. `lmodern` and\n  `mathptmx` instead of `cmr` and `times`)\n- In all styles, the Helvetica font (used in `\\textsf`) [is larger than the\n  text's normal font](http://www.hep.caltech.edu/~fcp/psnfss2e).\n  PaperShell fixes this issue by scaling down Helvetica.\n\nExporting your sources\n----------------------\n\nIf your paper is accepted (yay!), you may need to send the sources to the\neditor so they can produce the final, \"camera-ready version\". Just zipping\nyour PaperShell `Source` folder will confuse a few of them, especially if\nthey have scripts trying to compile it automatically (many of them just\ntry to compile the first .tex file they find, which won't be the right one\nin most cases).\n\nFrom the root folder, you can call\n\n    php export.php\n\nCreates a stand-alone directory with all the sources. This script\nreads the original source file (paper.tex using the defaults) and\nreplaces all non-commented\n`\\input{...}` instructions with the content of the file. It also includes\nthe bibliography (paper.bbl) directly within the file (so no need to\ncall BibTeX). The resulting,\nstand-alone LaTeX file is copied to a new folder (`Export`), along with all\nnecessary auxiliary files (basically everything in the Source folder that\nis not a .tex file).\n\nNormally, what is present in the `Export` folder is a single compilable .tex\nfile (no `\\include` or `\\input`), plus class files and images. It is suitable\nfor sending as a bundle e.g. to an editor to compile the camera-ready\nversion. You can also bundle the whole thing (except the main .pdf file and\nauxiliary files) in a single zip file using `zip-export.sh`.\n\nAs an option, the `export.php` script can also create a \"flat\" structure with no folders (some publishers ask for this when submitting source files). Use the `--flatten` command line option when invoking the script.\n\nOverleaf integration\n--------------------\n\n[Overleaf](https://www.overleaf.com) is an online collaborative platform for\nediting LaTeX documents. Provided you have run `set-style.php` once, you can\nimport the whole project structure into Overleaf and edit it there; don't forget\nto set `Source/paper.tex` as the main file.\n\nIf you want to change the document to another article class, simply re-run\n`set-style.php` on your computer and re-upload `preamble.inc.tex`,\n`midamble.inc.tex` and `postamble.inc.tex` to Overleaf. This is even easier if\nyou keep Overleaf in sync with a GitHub repository.\n\nCleaning up a BibTeX file\n-------------------------\n\nYou can uniformize the presentation of BibTeX entries (indentation, etc.) and\nremove duplicate entries by passing it into a script. In the root folder of\nyour project, type\n\n    php clean-bibtex.php\n\nThis will read and parse `Source/paper.bib` and re-output a cleaned up version\nat `Source/paper-clean.bib`. If everything looks good, you can then overwrite\nthe original `paper.bib` with this new file.\n\nOverriding defaults\n-------------------\n\nDefault settings can be overridden by giving values to parameters found\nin `settings.inc.php`. All these settings are documented in detail in the\nfile. Make sure to call `generate-preamble.php` again after you change the\nfile.\n\nIn the case of ACM journals, you also have to overwrite `acm-ccs.tex` and\n`acm-bottom.tex` with appropriate content.\n\n### Changing the paper's filename\n\nBy default, the main paper is called `paper.tex`. We recommend that you leave\nit that way: the whole point of using this environment is to use the same\ncommands and structure for all your papers, so customizing it for each paper\nkind of defeats that. If you *must* change it to something else:\n\n1. Make sure the filename does not contain spaces, or the `make` command\n   will not do anything.\n2. Make sure to change `paper.tex` by your filename in\n   `Source/Variables.ini`.\n\nGood practices\n--------------\n\n### Use a single tex file\n\nTry to keep your paper in a single file (`paper.tex` if you use the\nproject defaults) ---that is, do not split the paper into `section-1.tex`,\n`section-2.tex`, etc. that you `\\input` inside `paper.tex`. A few reasons\nfor doing so:\n\n- When spell checking, you have to run Aspell on a single file. Otherwise,\n  you need to run it on every input file every time, and you cannot use\n  the bundled script.\n- Some publishers require you to upload a single stand-alone TeX file when\n  submitting. PaperShell has a script that can do it for you if you use\n  the defaults, but it may not work if your paper has multiple parts in\n  separate files (this has not been tested).\n- When searching for a word or an expression in your text editor, you have\n  to search in a single file ---otherwise you have to search in all files.\n- If your text editor has a \"Compile with LaTeX\" button, clicking on it\n  when editing one of the `section-x.tex` will try to compile only that\n  file and will fail. You have to go back to the main file every time you\n  need to compile.\n- If the goal is to make it possible to edit different parts of the same\n  paper in parallel, don't forget you are using Git and that it should take\n  care of this even if you edit the same file.\n- If you move parts of text around, the changes are easier to track in Git\n  if they don't jump from one file to another.\n  \nIn all honesty, we don't see much benefit in splitting a 10-page paper\ninto multiple parts in separate files.\n\nAbout the Author\n----------------\n\nThis project is maintained by [Sylvain Hallé](http://leduotang.ca/sylvain),\nFull Professor at [Université du Québec à\nChicoutimi](http://www.uqac.ca), Canada.\n\n\u003c!-- :wrap=soft:maxLineLen=80: --\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsylvainhalle%2Fpapershell","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsylvainhalle%2Fpapershell","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsylvainhalle%2Fpapershell/lists"}