Skip to content

Commit 39f2553

Browse files
committed
markdown source builds
Auto-generated via `{sandpaper}` Source : 7cc5ccb Branch : main Author : Tim Dennis <[email protected]> Time : 2025-04-30 16:59:34 +0000 Message : Update config.yaml
1 parent dc54bbe commit 39f2553

File tree

3 files changed

+109
-1
lines changed

3 files changed

+109
-1
lines changed

config.yaml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,7 @@ contact: '[email protected]' # FIXME
6767
# Order of episodes in your lesson
6868
episodes:
6969
- scholarly-publishing-process.md
70+
- open-authoring-tools.md
7071

7172
# Information for Learners
7273
learners:

md5sum.txt

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,11 @@
11
"file" "checksum" "built" "date"
22
"CODE_OF_CONDUCT.md" "c93c83c630db2fe2462240bf72552548" "site/built/CODE_OF_CONDUCT.md" "2025-04-30"
33
"LICENSE.md" "16e8eaad880865bc4a41811b3e8fa945" "site/built/LICENSE.md" "2025-04-30"
4-
"config.yaml" "51b0521084eee1b261c2b6305c4d3119" "site/built/config.yaml" "2025-04-30"
4+
"config.yaml" "6ef36dee29946f0358d9ab1a1e7b4194" "site/built/config.yaml" "2025-04-30"
55
"index.md" "a02c9c785ed98ddd84fe3d34ddb12fcd" "site/built/index.md" "2025-04-30"
66
"links.md" "8184cf4149eafbf03ce8da8ff0778c14" "site/built/links.md" "2025-04-30"
77
"episodes/scholarly-publishing-process.md" "1c85e4f5da4862027078b4f2fcdfd0ad" "site/built/scholarly-publishing-process.md" "2025-04-30"
8+
"episodes/open-authoring-tools.md" "13efd8c37d014fd306189776cf60f5b0" "site/built/open-authoring-tools.md" "2025-04-30"
89
"instructors/instructor-notes.md" "cae72b6712578d74a49fea7513099f8c" "site/built/instructor-notes.md" "2025-04-30"
910
"learners/reference.md" "1c7cc4e229304d9806a13f69ca1b8ba4" "site/built/reference.md" "2025-04-30"
1011
"learners/setup.md" "5456593e4a75491955ac4a252c05fbc9" "site/built/setup.md" "2025-04-30"

open-authoring-tools.md

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
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

Comments
 (0)