-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathguide.html
More file actions
551 lines (550 loc) · 21.8 KB
/
guide.html
File metadata and controls
551 lines (550 loc) · 21.8 KB
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
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta
name="viewport"
content="width=device-width, height=device-height, user-scalable=no, initial-scale=1.0"
/>
<link rel="stylesheet" href="src/guide/styles.css" />
<link rel="preload" href="openmoji.woff2" as="font" crossorigin />
</head>
<body>
<nav class="related">
<a href="/">Exit 🚪</a>
</nav>
<header>
<h1>📜 Guide</h1>
<p>
This is the manual for 🏫 Portal, an app built for independent
learners.
</p>
<p>
This document assumes that the reader is capable of understanding
English language text and has basic computer literacy.
</p>
<p>
🚧 Portal is a work in progress. Please
<a href="#reporting-issues">report any issues</a> you find.
</p>
</header>
<main>
<section>
<h2 id="adding-resources">📥 Adding Resources</h2>
<p>
In order to use the Portal app, you will need content to view within
it. Inside the app, content is referred to as resources.
</p>
<p>
The app can display two different types of resources: 📚 Courses
and 🗺️ Course Maps.
</p>
<p>
📚 Courses are a collection of textbooks. Textbooks can be
📕 completable, where you can track your progress, or they can be
📒 non-completable. Non-completable textbooks are typically
included as reference materials or supplemental reading.
</p>
<p>
🗺️ Course Maps are an interactive tree of 📚 Courses.
These help you plan your learning journey by providing an intended
order for completing courses.
</p>
<h3>🌐 Finding Resources</h3>
<p>
The developers who build Portal do not create resources. Instead, they
intend for Portal users to create resources for others to use.
</p>
<p>
Portal's developers maintain a Discussion Board for users
to share resources. This can be found in ⚙️ Settings, under the
🌐 Useful Websites drop-down.
</p>
<h3>📂 Importing Resources</h3>
<p>
Resources are distributed as files ending in <code>.Portal.zip</code>.
These files contain one or more 📚 Courses and may contain
🗺️ Course Maps.
</p>
<p>
In order to import a resource, open the Course Navigator,
and click the 📂 Open Resource Folder button. Then,
drag the files ending in <code>.Portal.zip</code> into the resource
folder. Once you have added the files into the folder, click the
🔄 Refresh Navigator button to update the app's list of
resources.
</p>
<p>
⚠ You should only import resources from creators you trust. Malicious
resources could pose a security risk.
</p>
<p>
🛑 Encountered an error? See the
<a href="#troubleshooting">🧰 Troubleshooting</a> section for
help.
</p>
</section>
<hr />
<section>
<h2 id="taking-courses">📚 Taking Courses</h2>
<h3> Planning Your Journey</h3>
<p>
In order to take a 📚 Course, you will need to add it to your
Active Courses. This is done using the
Course Navigator.
</p>
<p>
The Course Navigator displays all 📚 Courses and
🗺️ Course Maps imported into the app. You can click on
listed resources to view their details, and you can use the checkboxes
to add or remove items from your Active Courses.
</p>
<p>
When viewing 📕 completable 📚 Courses, you can use tools
under the 🛠️ Edit Progress drop-down to manually set its
completion. This be used to avoid retaking courses where you already
know the material, or to retake a course you previously completed.
</p>
<p>
When available, 🗺️ Course Maps can be useful for planning
your studying. They display an intended order to complete
📚 Courses in, along with a brief overview of course completion.
You can click on a 📚 Course displayed within a
🗺️ Course Map to view it's details.
</p>
<p>
In a 🗺️ Course Map, connections between 📚 Courses are
displayed with lines. If a line has an arrow, the connected
📚 Courses should be completed in the displayed order. If the
line does not have an arrow, the connected 📚 Courses can be
completed at the same time. If the line is dashed, the connection is
optional.
</p>
<p>
Some 🗺️ Course Maps may color-code 📚 Courses. The
meaning of these colors are specific to the 🗺️ Course Map
being displayed.
</p>
<h3>📖 Studying</h3>
<p>
On the 🏫 Home page, you can find your
Active Courses. Each listed 📚 Course contains
textbooks (📕 or 📒), which can be clicked on to open the
📖 Textbook Viewer.
</p>
<p>
Inside the 📖 Textbook Viewer, you can click on sections to
view them, and use the checkboxes to mark sections as completed. Time
spent within the viewer is shown on the ⏱️ stopwatch.
</p>
<p>
The ⏱️ stopwatch display contains multiple squares, with each
square representing a set length of time. The squares turn dark green
to indicate the amount of time spent within the 📚 Course today.
</p>
<p>
You can adjust the stopwatch to better fit your needs in
⚙️ Settings.
</p>
<h3>🗓 Monitoring Progress</h3>
<p>
On the 🏫 Home page, you can find your Active Courses
and 🗓 Progress.
</p>
<p>
Each 📚 Course contains a list of textbooks. Within each
📕 completable textbook, multiple squares are displayed,
with each square representing a chapter. Once all of the squares
become dark red, the textbook has been completed.
</p>
<p>
The 🗓 Progress section displays overall
⌛️ Studying Time and 📑 Chapter Completion in a
multi-week view, with each square representing one day. The outlined
square represents the current day, and the intensity of each square's
color represents the progress made on that day.
</p>
<p>
This can help provide useful encouragement by making progress visible.
You can adjust your goals to better fit your needs in
⚙️ Settings.
</p>
</section>
<hr />
<section>
<h2 id="troubleshooting">🧰 Troubleshooting</h2>
<h3>🛑 Understanding Errors</h3>
<p>Errors can happen for a wide variety of reasons:</p>
<p>
🐞 Application Errors are issues which are caused by
unexpected behavior in the app. Please
<a href="#reporting-issues">report these errors</a> if you encounter
them.
</p>
<p>
💽 Disk Errors are issues which prevent the app from reading
user data from the computer's disk. These are rare and have a wide
range of potential causes.
</p>
<p>
📄 Resource Errors are non-database issues that prevent
resources from being loaded.
</p>
<p>
🗃 Database Errors are issues with the app's internal
database. The internal database keeps track of user settings and
progress data.
</p>
<p>All possible error messages are listed below:</p>
<ul>
<li>
🐞 Application Errors
<ul>
<li>"An internal error occured"</li>
<li>"Unable to perform API call"</li>
</ul>
</li>
<li>
💽 Disk Errors
<ul>
<li>"Unable to create resource folder"</li>
<li>"Unable to write resource schema"</li>
<li>"Unable to check if Course exists"</li>
<li>"Unable to get Course and CourseMap list"</li>
</ul>
</li>
<li>
📄 Resource Errors
<ul>
<li>"Unable to get Course"</li>
<li>"Unable to get Course Map"</li>
<li>"Unable to display Course"</li>
<li>"Unable to display Course Map"</li>
</ul>
</li>
<li>
🗃 Database Errors
<ul>
<li>"Unable to load application database"</li>
<li>"Unable to get list of active Courses"</li>
<li>"Unable to update list of active Courses"</li>
<li>"Unable to get progress for Course"</li>
<li>"Unable to update progress for Course"</li>
<li>"Unable to get overall progress"</li>
<li>"Unable to get Settings"</li>
<li>"Unable to update Settings"</li>
</ul>
</li>
</ul>
<p>
ℹ Not all issues will cause an error message to be displayed. Issues
which cause the app to crash or refuse to open should always be
reported.
</p>
<h3>🛠️ Fixing Common Issues</h3>
<p>
In the absence of 💽 Disk Errors,
📄 Resource Errors are caused by resources which are
incompatible with the app. They can be fixed by removing the
problematic resource from the 📂 Resource Folder.
</p>
<p>
Issues with 📚 Courses are either a result of a course which is
corrupted, or a course which is not compatible with the active
application version. If
<a href="#installing-updates">updating Portal</a> does not fix the
issue, contact the resource creator.
</p>
<p>
Issues with 🗺️ Course Maps can result from a course map
which is corrupted, not compatible with the active application
version, or missing courses.
</p>
<p>
If the error message is "Unable to display Course Map", the course map
is missing one or more of the resources it is designed to accompany.
Contact the resource creator for more information.
</p>
<p>
If the error message is "Unable to get Course Map", the course map is
either corrupted or not compatible with the active application
version. If <a href="#installing-updates">updating Portal</a> does not
fix the issue, contact the resource creator.
</p>
<p>
🗃 Database Errors are rare. In the absence of
💽 Disk Errors, these usually result from an issue with the
app's internal database.
</p>
<p>
If the error message is "Unable to get Settings", try using the
⚙️ Reset Settings to Defaults action under the
error page's 🛠️ Database Actions drop-down.
</p>
<p>
If the error message is "Unable to get list of active Courses", try
using the 📚 Reset Active Courses action under the
error page's 🛠️ Database Actions drop-down.
</p>
<p>
If the error message is "Unable to load application database" and the
cause starts with "IO error: could not acquire lock on", there are
multiple copies of the app running. Try closing all app windows and
then re-opening the app. If this does not fix the issue, try
restarting your computer.
</p>
<p>
As a last resort, the app's database can be entirely reset. However,
this will
<strong>permanently erase all user settings and progress data</strong
>. To reset the database, open the 📂 Data Folder using the
action on the error page, and delete the folder with the name
"Internal Database". Once the folder has been deleted, close and
re-open the app.
</p>
<h3 id="installing-updates">⤴ Installing Updates</h3>
<p>
When mistakes in the app are discovered and fixed, new versions of the
app containing the fix are released. However, you will need to update
your copy of the app to receive these fixes.
</p>
<p>
In addition to this, newer versions often contain additional features.
Using a resource designed for a newer version of the app than the one
you have installed can cause issues.
</p>
<p>
The latest version of Portal can be downloaded from the
🏫 App Website. This website can be found in
⚙️ Settings, under the 🌐 Useful Websites drop-down.
</p>
<h3 id="reporting-issues">🐞 Reporting Issues</h3>
<p>
Once you have confirmed that an issue is caused by a mistake in the
app, rather than a mistake in one of your resources, you should report
it. This allows the developers who build the app to know that the
issue exists, so that they can fix it.
</p>
<p>
ℹ If you are having an issue with a specific resource, you should
contact the creators of that resource instead.
</p>
<p>
In ⚙️ Settings, you can find the 🐞 Issue Tracker under
the 🌐 Useful Websites drop down. If you are on an error
page, you can click on the 🔗 App Issue Tracker link.
</p>
<p>
Before filing an issue, you should check that someone else has not
already filed an report of that same issue. Use the search to find
existing issues which may be similar.
</p>
<p>
If an report does not already exist, click the "New issue" button and
fill out the provided template. An app developer will review your
issue shortly.
</p>
</section>
<hr />
<section>
<h2 id="creating-resources"> Creator's Guide</h2>
<p>
⚠ It is highly recommended that you read all preceding sections of
the manual before reading this section.
</p>
<p>
This guide is intended for those who would like to create resources
for Portal. Unlike using existing resources, creating resources
requires some technical knowledge.
</p>
<p>You will need a basic understanding of the following:</p>
<ul>
<li>Tom's Obvious Minimal Language (TOML)</li>
<li>Universally Unique Identifier (UUID)</li>
<li>JSON Schema</li>
<li>Web Browser Developer Tools ("Inspect Element")</li>
<li>EPUB 3 specification</li>
<li>ZIP archive format</li>
</ul>
<p>You will need the following digital tools:</p>
<ul>
<li>A file archiver, such as PeaZip or p7zip-zstd</li>
<li>
A code editor, such as Visual Studio Code
<ul>
<li>
A plugin to validate TOML files against a JSON schema
(recommended)
</li>
</ul>
</li>
</ul>
<p>
Throughout the rest of this section, Portal's user data folder will be
referred to as <code>$APPDATA</code>. Paths are case-sensitive
(assuming the underlying filesystem is) unless otherwise specified,
and files may be loaded by the app in any order.
</p>
<p>
ℹ When using UUIDs in filesystem paths, the UUID must be represented
in lowercase hexadecimal form, without separators (example:
<code>79a55c4e046343039424684764eccd8a</code>). When referring to
representations of UUIDs in filesystem paths, the syntax
<code>{UUID}</code> will be used.
</p>
<h3> Resource Schema</h3>
<p>
Portal preserves backwards-compatibility for documented behavior.
Updating Portal should not break existing resources — if this happens,
it's a bug. However, resources designed for newer versions of Portal
may fail to load on older versions.
</p>
<p>
In some cases, it may be preferable to use specific versions of Portal
for building resources. Portal automatically generates a folder
containing JSON schema upon startup, located at
<code>$APPDATA/Resource Schema/</code>. This schema documents the
structure and functionality of resource TOML files.
</p>
<p>
This manual's text aims to avoid being tightly coupled to a specific
app version, and will not repeat information that is within the scope
of the relevant schema files.
</p>
<h3>📚 Courses</h3>
<p>
Courses are folders containing a TOML file named
<code>course.toml</code> at their root. This file, adhering to the
<code>$APPDATA/Resource Schema/Course.json</code> schema, contains a
set of one or more textbooks (in EPUB format).
</p>
<p>
All files or folders referenced by the <code>course.toml</code> must
be contained within the Course folder. Files or folders within the
Course folder which are not referenced by the index are ignored.
</p>
<p>
Courses are loaded from the path
<code>$APPDATA/User Resources/{UUID}/</code>. On the 🏫 Home
page, only active courses are loaded. In the
📖 Textbook Viewer, only the Course being viewed is loaded.
In the Course Navigator, all Courses are loaded,
regardless of their active status.
</p>
<h4>📕 Textbooks</h4>
<p>
ℹ This section assumes that you have an existing textbook, in EPUB
format, that you would like to include in a Course. Converting
textbooks into the EPUB format or creating EPUB documents from scratch
is out of scope for this document.
</p>
<p>
All textbooks referenced by the <code>course.toml</code> must be
unpacked EPUB files (the EPUB container must be a folder, not a file).
Existing EPUBs can be unpacked by changing their extension to
<code>.zip</code> and then extracting the archive. Review the Course
schema for a list of supported EPUB versions.
</p>
<p>
In order for a textbook to be completable, a list of user-completable
chapters must be included in the configuration for that textbook. Each
referenced section in the chapter must match a valid identifier from
the Table of Contents. ToC identifiers can be found by opening Inspect
Element inside the 📖 Textbook Viewer and then clicking on
the Console tab.
</p>
<p>
ℹ Only make chapters or sections completable when their completion is
<em>meaningful</em>. Sections included for reference or as
supplementary material should not be marked as completable.
</p>
<p>
The 📖 Textbook Viewer is the only part of the application
which loads Course textbooks (all other areas of the app will only
load the
<code>course.toml</code>). It will only load the textbook being
actively viewed.
</p>
<p>
The Course Navigator is useful for checking the completion
of a Course. Like the 🏫 Home page, you can click on textbooks
within a displayed 📚 Course to open the
📖 Textbook Viewer.
</p>
<h3>🗺️ Course Maps</h3>
<p>
Course Maps are TOML files, adhering to the
<code>$APPDATA/Resource Schema/CourseMap.json</code> schema, which
contain a user-facing dependency tree of resources (referenced by
UUID).
</p>
<p>
Course Maps are loaded from the path
<code>$APPDATA/User Resources/{UUID}.toml</code> when using the
Course Navigator. An invalid Course Map will result in an
immediate error. However, a Course Map which references a non-existent
resource will only produce an error once the user attempts to open the
Course Map.
</p>
<h3> Packaging and Sharing Resources</h3>
<p>
⚠ You should
<strong
>always test all aspects of your resources in the Portal app</strong
>
before sharing them. Validating your resource against the relevant
schema will not catch all possible mistakes.
</p>
<p>
⚠ If you plan on publically distributing a Course, a basic
understanding of copyright law is required. Legal guidance is out of
scope for this document.
</p>
<p>
Resources are packaged as unencrypted ZIP archives, which are loaded
from the path
<code>$APPDATA/User Resources/*.zip</code> (extension is not case
sensitive). The Portal app automatically extracts the contents of all
detected archives into <code>$APPDATA/User Resources/</code>,
overwriting any files which already exist. Decompression will not be
performed recursively, so archives should not be put inside other
archives. Once the decompression process is successfully completed,
the archive will be deleted from the folder.
</p>
<p>
ℹ Unlike Courses or Course Maps, archive filenames do not convey
information to the app. You should use these filenames to inform the
<em>end user</em> of the archive's contents, and use the extension
<code>.Portal.zip</code> to inform the user that this archive is a
Portal resource.
</p>
<p>
ZIP archives can be uncompressed, or they can be compressed with any
of the algorithms supported by the app: DEFLATE, DEFLATE64, BZIP2,
ZStandard, LZMA, and XZ. ZStandard is generally the best option for
most use cases. Slower algorithms (BZIP2, LZMA, and XZ) should only be
used if archive size is more important than decompression speed.
Decompression of individual archives is single-threaded, but the app
will attempt to decompress multiple archives at a time.
</p>
<p>
Sets of Courses which are intended to be completed together should be
packaged together into one archive. If the collection is larger than
~1GB, it should be split into ~1GB archives (or 8 roughly equally
sized archives if the collection is larger than 8GB) with filenames
indicating their relation (example:
<code>My Course Collection (Part 1 of 4).Portal.zip</code>). Courses
and Course Maps should be distributed together, as one archive
containing all relevant resources. Do not distribute Course Maps
separately from Courses.
</p>
<p>
ℹ When distributing resources, you should inform the user of the
earliest Portal version that the resource supports. This information
should be stored outside of the resource, such as in description text
on a download page.
</p>
</section>
</main>
</body>
</html>