-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.html
126 lines (100 loc) · 4.99 KB
/
README.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
<!DOCTYPE html>
<title>READ ME - Generating accessible documents with Pandoc</title>
<body>
<h1>READ ME - Generating accessible documents with Pandoc</h1>
<p>This document explains how to use the files in this archive (you should have found it inside
<strong>AccessibleDocTool-master.zip</strong>).
</p>
<h2>What is Pandoc? How can I use it?</h2>
<p>Pandoc is a powerful text file converter. It can convert between formats like DOCX, LaTeX, PDF, EPUB, TXT, MD and
much more.</p>
<p>We're interested in its ability to convert from Markdown (<a
href="https://en.wikipedia.org/wiki/Markdown">Wikipedia article on Markdown</a>), a simple to use formatting
system to the following formats:</p>
<ul>
<li>DOCX - regular Microsoft Word files that are easier to navigate with screen readers;</li>
<li>PDF - portable files that look crisp at any zoom level for low vision users;</li>
<li>EPUB - book publication files that can be read on multiple devices and programs and easily allow users to
adapt colors and fonts families and sizes to their needs.</li>
</ul>
<p>After installing Pandoc and a LaTeX package, you'll be able to write accessible documents in Markdown and convert
them by running the <strong>.bat</strong> file on <strong>Windows</strong> or the <strong>.sh</strong> file on
<strong>Linux or macOS</strong>.
</p>
<h2>What do I install again?</h2>
<p>Pandoc and a LaTeX distribution.</p>
<h3>Installing Pandoc</h3>
<p>Go to <a href="https://pandoc.org/installing.html">Pandoc's installation page</a> and download the installer for
your platform. It'll be the first link in the page's main content. There are other installation options you may
prefer, if you're a more technical individual.</p>
<h3>Installing LaTeX</h3>
<p>After installing Pandoc itself, you'll need LaTeX. LaTeX is a powerful typesetting markup language, usually used
by academics, but we only need it as an intermediate step for generating PDFs.</p>
<p><strong>If you don't need to generate PDFs, skip this step.</strong></p>
<p>Pandoc recommends the following options depending on your operating system:</p>
<ul>
<li>Windows - <a href="https://miktex.org/">MiKTeX</a>;</li>
<li>macOS - <a href="https://tug.org/mactex/">MacTeX;</a></li>
<li>Linux - install the <strong>texlive</strong> package.</li>
</ul>
<p>Since this step is particularly platform dependent further details are outside the scope od this guide.</p>
<h2>OK, so what are all these files? Where do I start?</h2>
These are the files contained in this archive and what they're for:
<table>
<tr>
<th>File name</th>
<th>Description</th>
</tr>
<tr>
<td>README.html</td>
<td>This file. Hi!</td>
</tr>
<tr>
<td>cover.jpg</td>
<td>A cover for the EPUB file - replace it with the appropriate image.</td>
</tr>
<tr>
<td>title.txt</td>
<td>Contains the metadata for the document - title and subtitle, author, etc.</td>
</tr>
<tr>
<td>text.md</td>
<td>Contains the document itself, formatted in Markdown.</td>
</tr>
<tr>
<td>accessible.docx</td>
<td>A template Word file with styles appropriate for low vision users.</td>
</tr>
<tr>
<td>accessible.css</td>
<td>Contains styles that are appropriate for low vision users for EPUB files.</td>
</tr>
<tr>
<td>build.bat</td>
<td>The script to build the converted files on Window.</td>
</tr>
<tr>
<td>build.sh</td>
<td>The script to build the converted files on macOS or Linux.</td>
</tr>
<tr>
<td>out</td>
<td>The folder where the converted files go.</td>
</tr>
</table>
<h2>I installed everything, now what?</h2>
<p>Run either <strong>build.bat</strong> or <strong>build.sh</strong> depending on your operating system.</p>
<p>You should now have a DOCX, an EPUB and a PDF file in the <strong>"out" folder</strong>. If not, there's
something wrong with your installation. Unfortunately, there are too many scenarios, so troubleshooting is
outside the scope of this guide.</p>
<h2>Writing and converting documents</h2>
<p></p>
<ol>
<li>Fill in the metadata in <strong>title.txt</strong>;</li>
<li>Get a cover page and rename it to <strong>cover.jpg</strong>;</li>
<li>Write the actual document, formatted in Markdown in <strong>text.md</strong>;</li>
<li>Generate fhe output files by running either <strong>build.bat</strong> or <strong>build.sh</strong>
depending on your operating system.</li>
</ol>
<p>Your output files should now be in the <strong>out</strong> folder!</p>
</body>