|
| 1 | +--- |
| 2 | +title: "Open Authoring Tools" |
| 3 | +teaching: 30 |
| 4 | +exercises: 20 |
| 5 | +--- |
| 6 | + |
| 7 | +::: questions |
| 8 | +- What open authoring tools are available for writing scholarly articles? |
| 9 | +- How can I create manuscripts using Markdown, LaTeX, or RMarkdown? |
| 10 | +- How can open documents be converted to publisher-required formats like DOCX or PDF? |
| 11 | +::: |
| 12 | + |
| 13 | +::: objectives |
| 14 | +- Describe collaborative, open authoring tools that can be used to write scholarly articles. |
| 15 | +- Locate templates in Markdown and LaTeX that can be used to write a scholarly article. |
| 16 | +- Understand what tools can convert open document formats to proprietary ones required by scholarly publications. |
| 17 | +::: |
| 18 | + |
| 19 | +::: keypoints |
| 20 | +- Authors can use open source tools to write and produce manuscript submissions. |
| 21 | +- The open science community continues to develop workflows for submitting manuscripts to publishers that require proprietary formats. |
| 22 | +- Some journals do accept open source file formats during the initial submission or review stage. |
| 23 | +::: |
| 24 | + |
| 25 | +## Overview |
| 26 | + |
| 27 | +There are many collaborative authoring tools available today. DOC, DOCX, and PDF are the formats most commonly requested by scholarly publishers. Unfortunately, these formats are not open source. So how do we align our open science values with these constraints? |
| 28 | + |
| 29 | +By using alternative, open authoring tools. |
| 30 | + |
| 31 | +[AlternativeTo](https://alternativeto.net/) is a useful resource for discovering open-source or privacy-respecting alternatives to common proprietary tools. |
| 32 | + |
| 33 | +## WYSIWYG Tools |
| 34 | + |
| 35 | +If you prefer a *What-You-See-Is-What-You-Get* (WYSIWYG) editor, here are some common options: |
| 36 | + |
| 37 | +- **Google Docs**: free but not open source. |
| 38 | +- **LibreOffice**: free and open source — [feature comparison with Microsoft Office](https://wiki.documentfoundation.org/Feature_Comparison:_LibreOffice_-_Microsoft_Office) |
| 39 | +- **Apache OpenOffice**: free and open source, though not regularly updated. |
| 40 | + |
| 41 | +These tools support DOCX files and include features like collaboration and version history. However, they do not easily create semantically structured, machine-readable documents — a key goal for FAIR (Findable, Accessible, Interoperable, Reusable) outputs. |
| 42 | + |
| 43 | +## WYSIWYM Tools |
| 44 | + |
| 45 | +For semantic authoring, consider *What-You-See-Is-What-You-Mean* (WYSIWYM) formats such as: |
| 46 | + |
| 47 | +### Markdown |
| 48 | + |
| 49 | +Markdown is a plain text format with lightweight semantic markup. |
| 50 | + |
| 51 | +You can write Markdown in any text editor and save the file with a `.md` extension. A good place to get started is: |
| 52 | + |
| 53 | +- [CommonMark Tutorial (10 minutes)](https://commonmark.org/help/tutorial/) |
| 54 | + |
| 55 | +#### Markdown Resources |
| 56 | + |
| 57 | +- [PoisotLab manuscript template](https://github.com/PoisotLab/manuscript-template) |
| 58 | +- [Markdown for Manuscripts](https://github.com/djhocking/Markdown-for-Manuscripts) |
| 59 | +- [Sustainable authorship with Pandoc](https://programminghistorian.org/en/lessons/sustainable-authorship-in-plain-text-using-pandoc-and-markdown) |
| 60 | +- [The Carpentries Markdown lesson](https://swcarpentry.github.io/modern-scientific-authoring/02-markdown/) |
| 61 | + |
| 62 | +### RMarkdown |
| 63 | + |
| 64 | +RMarkdown combines Markdown with embedded R code to create reproducible research documents. It supports output to PDF, Word, and HTML. |
| 65 | + |
| 66 | +- [RMarkdown in Data Carpentry](https://datacarpentry.org/r-socialsci/instructor/06-rmarkdown.html) |
| 67 | +- [Reproducible submission to JMSACL](https://github.com/drdanholmes/jmsacl_reproducible_research) |
| 68 | + |
| 69 | +### LaTeX |
| 70 | + |
| 71 | +LaTeX is a document preparation system using plain text and markup for structure and formatting. You write `.tex` files and compile them into PDF. |
| 72 | + |
| 73 | +Start learning LaTeX: |
| 74 | + |
| 75 | +- [LaTeX: Document Structure Exercise](https://www.learnlatex.org/en/lesson-04) |
| 76 | +- [LaTeX Novice Typesetting (Carpentries Incubator)](https://carpentries-incubator.github.io/latex-novice-typesetting/) |
| 77 | +- [LaTeX Course (Parts 1 & 2)](https://jdlm.info/latex-course/en/) |
| 78 | + |
| 79 | +## Meeting Publisher Requirements |
| 80 | + |
| 81 | +If publishers only accept proprietary formats, how can you still use open tools? |
| 82 | + |
| 83 | +1. Most WYSIWYG editors allow export to DOCX or PDF. |
| 84 | + - **Caveat**: These may not be digitally accessible or semantically rich. |
| 85 | + |
| 86 | +2. Tools like **Pandoc** can convert Markdown, LaTeX, and other open formats into publisher-accepted ones. |
| 87 | + |
| 88 | +3. Some publishers accept open formats: |
| 89 | + - **LaTeX**: Commonly accepted at submission or for typesetting post-acceptance. |
| 90 | + - **Markdown**: Some open publishing platforms accept markdown submissions. |
| 91 | + |
| 92 | +### Examples |
| 93 | + |
| 94 | +- [Authorea](https://authorservices.wiley.com/author-resources/Journal-Authors/Prepare/authorea.html) |
| 95 | +- [PubPub](https://www.knowledgefutures.org/pubpub/) |
| 96 | +- [Overleaf](https://www.overleaf.com/) |
| 97 | +- [Journal of Open Source Software (JOSS)](https://www.theoj.org/) |
| 98 | +- [Programming Historian Guidelines](https://programminghistorian.org/en/author-guidelines) |
| 99 | + |
| 100 | +## Exercise: Markdown Basics |
| 101 | + |
| 102 | +Complete the [CommonMark tutorial](https://commonmark.org/help/tutorial/). Try creating headings, lists, links, and formatting text using a plain text editor. |
| 103 | + |
| 104 | +## Exercise: LaTeX Document Structure |
| 105 | + |
| 106 | +Work through the [LaTeX structure lesson](https://www.learnlatex.org/en/lesson-04) to get familiar with sections, document classes, and compiling. |
0 commit comments