Skip to content

Commit

Permalink
Finished cheatsheet; adding resources page
Browse files Browse the repository at this point in the history
  • Loading branch information
@emprice
emprice committed Aug 16, 2023
1 parent 815ab05 commit be14cda
Show file tree
Hide file tree
Showing 8 changed files with 320 additions and 14 deletions.
59 changes: 59 additions & 0 deletions ejs/partials/motivation.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
<h1>Motivation</h1>
<h2>Why not PDF?</h2>
<p>PDF (Portable Document Format) has arguably become the <i>de facto</i>
standard in academic publishing. There are many reasons one could
imagine that this became the case.</p>
<ul>
<li>
<p>PDF documents "look" nice. Electronically-typeset PDFs usually have
nice vectorized fonts that scale with infinite resolution.</p>
</li>
<li>
<p>Furthermore, PDFs typeset with LaTeX appear professional
right out of the box because of careful stylistic choices, like using
Computer Modern Roman as the default font rather than Times New Roman,
a surefire way to spot a document made with Microsoft Word.</p>
</li>
<li>
<p>Though costly PDF authoring software certainly exists, LaTeX
submissions are accepted by many academic journals. The LaTeX
software is free and open source, with a long history of producing
high-quality documents for publishing.</p>
</li>
<li>
<p>PDFs are standalone, meaning you can download one file, save it locally,
and open it later in any PDF reader you like. You don't have to browse
back to the journal's archive to read the paper, which adds to the
convenience of the PDF format.</p>
</li>
</ul>
<p>Considering each of these points in turn, however, may show you why PDF
is not necessarily the perfect choice for academic publishing.</p>
<ul>
<li>
<p>PDF documents do look nice, but they are not the only vehicle for
aesthetically-pleasing content. Vectorized fonts are readily available
outside the PDF standard. Changing to another document format does not
mean the documents have to be rasterized or lose their visual appeal.</p>
</li>
<li>
<p>Academics, myself included, can usually spot a document typeset with
LaTeX from a mile away. We see them every day on preprint servers and
journal archives, to the point that information conveyed in LaTeX source
or PDF just seems more trustworthy now. Don't believe me?
<a href="https://xkcd.com/1301">It's literally the subject of an xkcd comic.</a></p>
</li>
<li>
<p>LaTeX is a common tool for typesetting publication-quality documents that
many researchers use frequently. It is not the only authoring tool freely
available, though, just the current standard.</p>
</li>
<li>
<p>Though standalone digital files, PDFs are inherently linked to the idea
of print media. When you download a journal article as a PDF, the document
you receive is divided into pages already, complete with headers, footers,
and page numbers, which are arguably unnecessary in an age when most
academics read the paper in its digital form. When did you last print
out an article on actual, physical paper?</p>
</li>
</ul>
1 change: 1 addition & 0 deletions ejs/partials/nav.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@
<li><a href="tutorial/basic.html">Basic HTML syntax</a></li>
<li><a href="tutorial/skeleton.html">Simple HTML skeleton</a></li>
<li><a href="tutorial/cheatsheet.html">LaTeX to HTML cheatsheet</a></li>
<li><a href="tutorial/resources.html">Resources</a></li>
</ul>
</li>
<li class="is-drilldown-submenu-parent"><a href="#">Toolbox</a>
Expand Down
148 changes: 148 additions & 0 deletions ejs/tutorial/partials/cheatsheet.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -171,6 +171,154 @@ <h2 class="permalink" id="common-misc">
\end{lstlisting}</code></pre>
</td>
<td>
<pre><code class="language-html">&lt;code&gt;
def the_song_that_never_ends():
print('Yes: It goes on and on, my friends!')
the_song_that_never_ends()
&lt;/code&gt;</code></pre>
<p>The <code class="language-html">&lt;code&gt;</code> block does not
take care of syntax highlighting for you; it just indicates that
the contents are code. You can use a library like
<a href="https://highlightjs.org">highlight.js</a> to lex and
highlight many programming languages.</p>
<p>You might also nest the <code class="language-html">&lt;code&gt;</code>
block inside a <code class="language-html">&lt;pre&gt;</code> block,
a section of preformatted text. A default styling for both
<code class="language-html">&lt;code&gt;</code> and
<code class="language-html">&lt;pre&gt;</code> might be monospaced
font, but this can also be customized with styling.</p>
</td>
</tr>
<tr>
<th>Superscripts and subscripts</th>
<td>
<pre><code class="language-latex">Have you heard about the dangers of dihydrogen monoxide, commonly known as H\textsubscript{2}O? It is the 1\textsuperscript{st} most abundant molecule in the human body!</code></pre>
</td>
<td>
<pre><code class="language-html">Have you heard about the dangers of dihydrogen monoxide, commonly known as H&lt;sub&gt;2&lt;/sub&gt;O? It is the 1&lt;sup&gt;st&lt;/sup&gt; most abundant molecule in the human body!</code></pre>
</td>
</tr>
</table>
<h2 class="permalink" id="inline-mods">
<a href="tutorial/cheatsheet.html#inline-mods">Inline text modifiers</a>
</h2>
<div class="callout attention">
<div class="title md-warning"></div>
<p>HTML5 changed the definitions of <code class="language-html">&lt;b&gt;</code>,
<code class="language-html">&lt;i&gt;</code>, <code class="language-html">&lt;s&gt;</code>,
and <code class="language-html">&lt;u&gt;</code> from the previous standard.
Before, those elements were only given a visual definition, so
<code class="language-html">&lt;b&gt;</code> indicated bold text but did not
convey any particular intent. These elements now represent text that would
conventionally be typeset with each font variant. <code class="language-html">&lt;em&gt;</code>
and <code class="language-html">&lt;strong&gt;</code> still carry more
unambiguous intent, which allows styling to be specified independently.</p>
</div>
<table>
<tr>
<th></th>
<th>LaTeX</th>
<th>HTML</th>
</tr>
<tr>
<th>Emphasis</th>
<td>
<pre><code class="language-latex">\emph{I really want to emphasize this!}</code></pre>
<p>Text enclosed in <code class="language-latex">\emph{...}</code> is
usually typeset in italic font. The difference between
<code class="language-latex">\emph{...}</code> and
<code class="language-latex">\textit{...}</code> is subtle and seems
to be related to inter-character spacing when the font changes. Whether
the intent of emphasis makes it into the PDF is not clear (to me).</p>
</td>
<td>
<pre><code class="language-html">&lt;em&gt;I really want to emphasize this!&lt;/em&gt;</code></pre>
<p>Text between <code class="language-html">&lt;em&gt;</code> and
<code class="language-html">&lt;/em&gt;</code> tags may be shown to the
user in italic font, but <code class="language-html">&lt;em&gt;</code>
more specifically indicates text with "emphatic stress." There is no
ambiguity about the intent, for example, if the document is being
rendered as audio.</p>
</td>
</tr>
<tr>
<th>Strong importance</th>
<td>
<p>LaTeX does not seem to have a standard way of typesetting strong
importance. If you roll your own macro, you might use bold or
bold-italic font, but that choice can easily vary from user to
user or even document to document.</p>
</td>
<td>
<pre><code class="language-html">&lt;strong&gt;This is strongly important.&lt;/strong&gt;</code></pre>
<p>Text between <code class="language-html">&lt;strong&gt;</code> and
<code class="language-html">&lt;/strong&gt;</code> tags may be shown to the
user in boldface, but <code class="language-html">&lt;strong&gt;</code>
more specifically indicates text with "strong importance." There is no
ambiguity about the intent, for example, if the document is being
rendered as audio.</p>
</td>
</tr>
<tr>
<th>Boldface</th>
<td>
<pre><code class="language-latex">\textbf{I think this looks nice in bold.}</code></pre>
<p>Text enclosed in <code class="language-latex">\textbf{...}</code> will
always be typeset in boldface, but the significance of the formatting may
or may not be clear from context.</p>
</td>
<td>
<pre><code class="language-html">&lt;b&gt;I think this looks nice in bold.&lt;b&gt;</code></pre>
<p>Text between <code class="language-html">&lt;b&gt;</code> and
<code class="language-html">&lt;/b&gt;</code> tags may be shown to the
user in boldface. The element itself does not indicate emphasis, just
that the conventional formatting would be boldface.</p>
</td>
</tr>
<tr>
<th>Italics</th>
<td>
<pre><code class="language-latex">\textit{I think this looks nice in italic.}</code></pre>
<p>Text enclosed in <code class="language-latex">\textit{...}</code> will
always be typeset in italic font, but the significance of the formatting may
or may not be clear from context.</p>
</td>
<td>
<pre><code class="language-html">&lt;i&gt;I think this looks nice in italic.&lt;i&gt;</code></pre>
<p>Text between <code class="language-html">&lt;i&gt;</code> and
<code class="language-html">&lt;/i&gt;</code> tags may be shown to the
user in italic font. The element itself does not indicate emphasis, just
that the conventional formatting would be as italicized text.</p>
</td>
</tr>
<tr>
<th>Underline</th>
<td>
<pre><code class="language-latex">\underline{I think this looks nice underlined.}</code></pre>
<p>Text enclosed in <code class="language-latex">\underline{...}</code> will
always be typeset underlined, but the significance of the formatting may
or may not be clear from context.</p>
</td>
<td>
<pre><code class="language-html">&lt;u&gt;I think this looks nice underlined.&lt;u&gt;</code></pre>
<p>Text between <code class="language-html">&lt;u&gt;</code> and
<code class="language-html">&lt;/u&gt;</code> tags may be shown to the
user underlined. The element itself does not indicate emphasis, just
that the conventional formatting would be as underlined text.</p>
</td>
</tr>
<tr>
<th>Strikethrough</th>
<td>
<p>LaTeX does not have a standard command for strikethrough text, though
additional packages may add that capability.</p>
</td>
<td>
<pre><code class="language-html">&lt;s&gt;I think this looks nice struck out.&lt;s&gt;</code></pre>
<p>Text between <code class="language-html">&lt;s&gt;</code> and
<code class="language-html">&lt;/s&gt;</code> tags may be shown to the
user struck through with a horizontal line. It is used to indicate
content that is "no longer accurate or no longer relevant.".</p>
</td>
</tr>
</table>
76 changes: 76 additions & 0 deletions ejs/tutorial/partials/resources.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
<h1>Further reading</h1>
<h2 class="permalink" id="general">
<a href="tutorial/resources#general">General guidance</a>
</h2>
<dl>
<dt>
<a href="https://info.arxiv.org/about/accessibility_research_report.html">arXiv Accessibility Research Report</a>
</dt>
<dd>
<p>This is a more data-driven look at the current state of accessibility
in science publishing that makes several recommendations for how we
can improve things going forward, starting today.</p>
</dd>
<dt>
<a href="https://accessibility2023.arxiv.org">arXiv Accessibility Forum 2023</a>
</dt>
<dd>
<p>The forum took place on April 17, 2023. Even if you weren't there,
recordings of the speakers with ASL translation, presentations, and
discussion boards are all available on the arXiv site.
</dd>
<dt>
<a href="https://accessibility.digital.gov/visual-design/getting-started">Accessibility for visual designers</a>
</dt>
<dd>
<p>The U.S. government has a website dedicated to best practices for accessible
content, geared towards teaching government employees who design federal
websites how to ensure that their content is accessible and inclusive.</p>
</dd>
<dt>
<a href="https://designsystem.digital.gov/components/typography">U.S. Web Design System typography guide</a>
</dt>
<dd>
<p>These best practices for typography are of particular interest in
publishing. They give advice about font sizes, line height, and typefaces
best suited for accessible digital content.</p>
</dd>
</dl>
<h2 class="permalink" id="alttext">
<a href="tutorial/resources#alttext">Image alternate text</a>
</h2>
<dl>
<dt>
<a href="https://www.w3.org/WAI/GL/WCAG3/2021/how-tos/text-alternatives">WCAG 3.0 draft guidelines for text alternatives</a>
</dt>
<dd>
<p>While WCAG 3.0 is still in the draft stage, you can consult the current
version for basic guidance.</p>
</dd>
<dt>
<a href="https://www.perkins.org/resource/how-write-alt-text-and-image-descriptions-visually-impaired">Perkins School for the Blind, How to write image descriptions for the visually impaired</a>
</dt>
<dd>
<p>This is a practical primer on what should and should not appear in
alt-text. There are also links showing how to add alt-text in MS Office
software.
</p>
</dd>
<dt>
<a href="https://uxdesign.cc/how-to-write-an-image-description-2f30d3bf5546">"How to write an image description" by Alex Chen</a>
</dt>
<dd>
<p>This resource is particularly helpful for constructing alt-text with
an informative syntax. Alex gives additional advice on describing
race and gender in an inclusive and respectful way.</p>
</dd>
<dt>
<a href="https://discover.hubpages.com/art/Image-Descriptions-And-How-To-Write-Them">"Image descriptions and how to write them" by SotD and Zera</a>
</dt>
<dd>
<p>This resource in particular calls attention to the different "modes" of
writing that might be used to describe the same image. Your goal might be
to draw focus to a particular aspect of the image or to describe the entire
thing, and your image description should reflect that goal.</p>
</dd>
</dl>
4 changes: 4 additions & 0 deletions scss/main.scss
View file
Original file line number Diff line number Diff line change
Expand Up @@ -65,4 +65,8 @@ p, li {
}
}

li p {
margin-bottom: 0.5rem;
}

// vim: set ft=scss:
2 changes: 1 addition & 1 deletion scss/theme/code/_hljs.scss
View file
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ code, code.hljs {
}
}

.hljs-keyword, .hljs-tag {
.hljs-keyword, .hljs-name {
font-weight: bold !important;
}

Expand Down
35 changes: 24 additions & 11 deletions scss/tutorial.scss
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,20 +32,10 @@ $block-margin: 1rem;
background-color: map.get($theme, "body-background");
}

[data-theme="#{$name}"] tr:hover {
background-color: color.mix(map.get($theme, "body-font-color"),
map.get($theme, "body-background"), 2.5%);
}

[data-theme="#{$name}"] tr:nth-child(2n) {
background-color: color.mix(map.get($theme, "body-font-color"),
map.get($theme, "body-background"), 5%);
}

[data-theme="#{$name}"] tr:nth-child(2n):hover {
background-color: color.mix(map.get($theme, "body-font-color"),
map.get($theme, "body-background"), 7.5%);
}
}

td {
Expand All @@ -60,9 +50,14 @@ th {
.permalink {
display: inline-block;

&:hover::after {
& a::after {
content: '\00b6';
margin-left: 0.5em;
visibility: hidden;
}

&:hover a::after {
visibility: visible;
}

@each $name, $theme in $themes {
Expand Down Expand Up @@ -99,6 +94,24 @@ p, li {
}
}

// definition lists
dt {
@each $name, $theme in $themes {
[data-theme="#{$name}"] & a {
color: color.mix(map.get($theme, "palette-primary"),
map.get($theme, "body-font-color"), $weight: 70%);
text-decoration: underline dotted;
}

[data-theme="#{$name}"] & a:hover,
[data-theme="#{$name}"] & a:active {
color: color.mix(map.get($theme, "palette-primary"),
map.get($theme, "body-font-color"), $weight: 60%);
text-decoration: underline solid;
}
}
}

pre {
@include breakpoint(medium up) {
white-space: pre-wrap;
Expand Down
Loading

0 comments on commit be14cda

Please sign in to comment.