Week | Topic |
---|---|
1 | |
2 | |
3 | |
4 | |
5 | |
6 | |
7 | |
Study Week | (No scheduled topics this week) |
8 | |
9 | |
10 | |
11 | |
12 | |
13 |
School of Software Design and Data Science (SDDS)
Seneca College of Applied Arts and Technology
Seneca College IPC144 Course Notes
Home Page: https://ipc144.sdds.ca
License: Other
Week | Topic |
---|---|
1 | |
2 | |
3 | |
4 | |
5 | |
6 | |
7 | |
Study Week | (No scheduled topics this week) |
8 | |
9 | |
10 | |
11 | |
12 | |
13 |
School of Software Design and Data Science (SDDS)
Seneca College of Applied Arts and Technology
In #22 we landed initial support for running the site as a PWA, and it uses https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-pwa. The default behaviour of the plugin is to cache the site for offline use when installed. I wonder if we should consider doing this by default, since most people don't/won't install (it's a new feature not everyone knows about).
Another thing we could try is adding an "Install this for use Offline" type link or button on the main page?
I want to add the hyperlink of Weekly Schedule to the page footer because the page footer is kind of blank right now with a link to Contents only.
In addition, I want to remove the hyperlink of Weekly Schedule in Contents page because we would have the hyperlinks of Weekly Schedule in both left navigation bar and footer.
The Weekly Schedule is currently a table, but a list more similar to what we have in Table of Contents would probably make more sense, since we have unnecessary rows.
I would like to complete pointers-arrays-and-structs-md based on the following checklist mentioned in #18
In #3 we changed the overall colours to use Seneca's white/red theme. It works well in light mode, but dark mode is an issue:
We need to figure out what the Seneca-sanctioned approach to dark mode is. Red-on-Black isn't going to work.
This is a sub-issue of #18.
I'd like to audit and fix the Information.md page based on tasks listed below.
Make the proper dependencies and builds on CI, enabling user groups for docker?
ie. You need python 3.6.15 or newer with pyenv installed.
Refer to the following
https://docsearch.algolia.com/docs/legacy/run-your-own
You need to go through the steps of signup up for an account etc listed on CONTRIBUTION.md for Search section.
Refer to #10 for information on environment variables and secrets
https://github.com/marketplace/actions/algolia-docsearch-action
I would like to work on style-guidelines.md,
auditing it based on this checklist:
As mentioned in #18
<b>
and <i>
to do emphasis.I would like to audit and fix the computers.md page. As mentioned in #18.
This Audit will include the following checks:
docs/D-Modularity/pointers.md
, where we should reduce the vertical padding/margins on tables. The tables are too large, and probably shouldn't be tables at all.docs/D-Modulatirty/pointers.md
: there are places where > Blockquote are being used and Admonitions could replace it. “Note:” Lightbulb info Admonition.docs/8-Computations/logic.md
Flags image is white background, needs to work in dark. Create a “negative” or SVG so we can do Dark Mode? Can we programmatically create this negative?<b>
and <i>
to do emphasis.//
and /*...*/
) in dark mode (even light mode might need some work)***...***
was used as a fourth heading level, use ####
instead.This is a sub-issue of #18 and #24.
Prettier config file:
{
"arrowParens": "always",
"bracketSpacing": true,
"embeddedLanguageFormatting": "auto",
"endOfLine": "lf",
"htmlWhitespaceSensitivity": "css",
"insertPragma": false,
"jsxBracketSameLine": false,
"jsxSingleQuote": false,
"proseWrap": "preserve",
"quoteProps": "as-needed",
"requirePragma": false,
"singleQuote": true,
"tabWidth": 2,
"trailingComma": "es5",
"useTabs": false,
"vueIndentScriptAndStyle": false,
"printWidth": 100
}
Prettier ignore file:
# Dependencies
/node_modules
package.json
package-lock.json
yarn.lock
# Production
/build
# Generated files
.docusaurus
.cache-loader
# Misc
/static
CNAME
vercel.json
Scripts:
"prettier": "prettier --write \"./**/*.{md,jsx,json,html,css,js,yml}\"",
"prettier-check": "prettier --check \"./**/*.{md,jsx,json,html,css,js,yml}\"",
When running npm run prettier
, Prettier accidentally changes the asterisk *
(used for representing multiplication) into -
or _
, as it thought that those *
indicates a bulleted list or italic letters
Demo:
// Before running `npm run prettier`
* Giga or G (=1024M): 1 Gigabyte = 1024 * 1024 * 1024 bytes ~ 10<sup>9</sup> bytes
// After running `npm run prettier`
* Giga or G (=1024M): 1 Gigabyte = 1024 _ 1024 _ 1024 bytes ~ 10<sup>9</sup> bytes
For anyone who is working on parts of #18 , make sure to have Prettier installed with the above settings, and ran npm run prettier
after you have finished making changes to the Markdown. Locate any special characters that you don't want to be formatted by Prettier and escapes them with \
.
Places with the bug:
docs/A-Introduction/information.md
It's possible to configure the min/max depth of the table of contents (e.g., how many heading levels to show), see https://docusaurus.io/docs/api/themes/configuration#table-of-contents. We use up to 4 levels (i.e., h4
or ####
) but the final level isn't being displayed. Let's fix this. An example page is docs/B-Computations/logic.md
.
I'd like to work on expressions.md from B - Computations, keeping in mind the following criteria:
We'd like to have the production site get updated automatically on every push
/merge
to the main
branch. It would be ideal if we could do this automatically using GitHub Actions. Docusaurus has docs for this that someone should research and implement. You can test it out in your own fork and make sure it works before we merge it here.
Currently we are using an image for the EBCDIC Collating Sequence, see https://cghub.ca/Resources-Appendices/ebcdic-collating-sequence. This isn't accessible, and should be converted into text and a Markdown table.
Sub-issue of #18.
Auditing and fixing more-input-and-output.md
based on the following tasks:
docs/D-Modularity/pointers.md
, where we should reduce the vertical padding/margins on tables. The tables are too large, and probably shouldn't be tables at all.docs/D-Modulatirty/pointers.md
: there are places where > Blockquote are being used and Admonitions could replace it. “Note:” Lightbulb info Admonition.docs/8-Computations/logic.md
Flags image is white background, needs to work in dark. Create a “negative” or SVG so we can do Dark Mode? Can we programmatically create this negative?<b>
and <i>
to do emphasis.//
and /*...*/
) in dark mode (even light mode might need some work)***...***
was used as a fourth heading level, use ####
instead.Following the discussion I had with @dbelokon and @PananaPa, I learned that the design of the walkthrough table may be improved for better understanding.
The current layout of a walkthrough table looks like this:
and in the old version of the notes, the table looked like this:
We want to design walkthrough tables so that they are easier to read and scan at a first glance. Thus, we need a way to improve how the information is shown. If we improve the design, then we will be able to also simplify the representation of the table in the Markdown files.
This issue is to spark a discussion for a new design.
One thing we'd like to support is a PDF export of the entire text. It looks like there isn't an official way to do this, but there are some community attempts:
Let's experiment and see how well we can make this work.
Hi! I would like to work on the two-dimensional-arrays.md that mentioned in issue #18
Check List
Here are some things to consider:
docs/D-Modularity/pointers.md
, where we should reduce the vertical padding/margins on tables. The tables are too large, and probably shouldn't be tables at all.docs/D-Modulatirty/pointers.md
: there are places where > Blockquote are being used and Admonitions could replace it. “Note:” Lightbulb info Admonition.docs/8-Computations/logic.md
Flags image is white background, needs to work in dark. Create a “negative” or SVG so we can do Dark Mode? Can we programmatically create this negative?<b>
and <i>
to do emphasis.//
and /*...*/
) in dark mode (even light mode might need some work)***...***
was used as a fourth heading level, use ####
instead.Hi, I'd like to audit and fix arrays.md as part of #18. I'll be working on the following tasks:
<b>
and <i>
to do emphasis.***...***
was used as a fourth heading level, use #### instead.I'd like to work on input-functions.md
, auditing it based on this checklist:
docs/D-Modularity/pointers.md
, where we should reduce the vertical padding/margins on tables. The tables are too large, and probably shouldn't be tables at all.docs/D-Modulatirty/pointers.md
: there are places where Blockquote are being used and Admonitions could replace it. “Note:” Lightbulb info Admonition.docs/8-Computations/logic.md
Flags image is white background, needs to work in dark. Create a “negative” or SVG so we can do Dark Mode? Can we programmatically create this negative?<b>
and <i>
to do emphasis.//
and /*...*/
) in dark mode (even light mode might need some work)***...***
was used as a fourth heading level, use ####
instead.This is a sub-issue of https://github.com/Seneca-ICTOER/IPC144/issues/18
docs/D-Modulatirty/pointers.md
: there are places where > Blockquote are being used and Admonitions could replace it. “Note:” Lightbulb info Admonition.docs/8-Computations/logic.md
Flags image is white background, needs to work in dark. Create a “negative” or SVG so we can do Dark Mode? Can we programmatically create this negative?<b>
and <i>
to do emphasis.//
and /*...*/
) in dark mode (even light mode might need some work)***...***
was used as a fourth heading level, use ####
instead.Adding Prettier will allow us to have a general styling for every contributor that works on this project.
In #46 we're adding the Docusaurus ideal-image plugin. It lets you use an <Image />
component in your Markdown, and then automatically generates ideal image sizes, based on props you include:
import Image from '@theme/IdealImage';
import thumbnail from './path/to/img.png';
// your React code
<Image img={thumbnail} />
// or
<Image img={require('./path/to/img.png')} />
We should look at where to use this in our docs. Ideal candidate images would be those that are large enough, and can be given multiple sizes for different viewports. This would help a lot on mobile.
In #41 we're working on dynamically generating a PDF of the entire site's contents. It's going to be great to finallly have this.
The PDF that gets generated now is OK, but not as good as I'd like.
Let's see if we can improve some things:
Docusaurus has a really cool search feature, which can be integrated with the site. We'd like to add search, so it would be great if someone can pick this up.
Currently we are using an image for the ASCII Collating Sequence, see https://cghub.ca/Resources-Appendices/ascii-collating-sequence. This isn't accessible, and should be converted into text and a Markdown table.
This issue is a sub-issue of #18
<b>
and <i>
to do emphasis.***...***
was used as a fourth heading level, use ####
instead.While working on issue #12, I found that maybe it would be great to access the IPC144 resources on desktop&offline.
This plugin generates a Service Worker in production build only and allows you to create a fully PWA-compliant documentation site with offline and installation support.
Waiting for your opinions, here
Currently, all images and their palletes in the website are adapted to the light theme, but there is no variation of the images for the dark theme. Thus, we need a way to have a version of the image that has a pallete that fits the dark theme. If we do a simple invert of the colours, it results in a rather 'ugly' looking image. Thus, we need a person who can properly adapt the pallete. However, doing it manually is an error prone and time consuming task.
The way we can approach this is by creating a small program that will transform an image's pixels from one color to another, given two colors in hex notation: the source color and the result color. Something along the lines of:
let fromColor = 0x000000;
let toColor = 0x00FF00;
for pixel in pixelsFromImage:
if pixel.color == fromColor:
pixel.color = toColor;
This is a naive implementation. The problem with this implementation is that it doesn't cover certain pixels; due to compression, the color will not be exactly as fromColor
, instead it will be an average of the surrounding pixels. An example of this is the text of an image when you zoom in:
Notice that some pixels are slightly green or orange or gray. Thus, a simple exact comparison won't do a proper pallete conversion.
It would be nice if we could use an already existing program, but if not, we will have implement it in our own.
Hello there,
I'd like to audit and fix operators.md as part of #18.
As David instructed I'll be working on the following tasks:
Look for any typos
Make sure all Markdown is correctly done. The conversion was done automatically by a tool, so there may be more idiomatic ways to do some things
Check the page in a Desktop browser. Does it look OK? Are there any issues that need to be fixed?
Check the page in a Mobile browser. Does it look OK? Are there any issues that need to be fixed?
Try the page in both Light and Dark mode. Are there any issues that need to be fixed?
Try running the page through Lighthouse: https://developers.google.com/web/tools/lighthouse. Are there any issues that need to be fixed?
Try running the page through Web Hint: https://webhint.io/. Are there any issues that need to be fixed?
Tables that are really wide (types.md) could be converted to use SVG or flex/grid. Make wide visual tables fit in the available viewport. Another example is the table in docs/D-Modularity/pointers.md, where we should reduce the vertical padding/margins on tables. The tables are too large, and probably shouldn't be tables at all.
Prefer Markdown tables vs. raw HTML tags
Fix colours in tables so it uses global styles vs. inline styles
Use alt tags for all images. See https://supercooldesign.co.uk/blog/how-to-write-good-alt-text for suggestions
Avoid blockquote for indentation, and prefer q or blockquote only when actually quoting. Use Admonitions instead. Example: docs/D-Modulatirty/pointers.md: there are places where > Blockquote are being used and Admonitions could replace it. “Note:” Lightbulb info Admonition.
Make sure images work in dark and light modes. For example, docs/8-Computations/logic.md Flags image is white background, needs to work in dark. Create a “negative” or SVG so we can do Dark Mode? Can we programmatically create this negative?
Change colours for tables (don’t use Yellow). We should use the default colour theme.
Avoid using < b > and < i > to do emphasis.
Use backticks and all code for memory addresses and such in tables that use things like void, int, function names, memory addresses.
Make sure all code blocks use syntax highlighting
centre images horizontally (esp. when they are small) so they work well at all responsive sizes
check sub-script and super-script that they are correctly used in all cases
consider including inter-site links to other pages that have related info
all links should have descriptive text for accessibility
Make sure that sub-headings (right-hand side) for each document are correct.
Improve readability of code comments (i.e., // and /.../) in dark mode (even light mode might need some work)
In places where ... was used as a fourth heading level, use #### instead.
Fix Frontmatter for page to include proper id, title, slug, etc.
This is a sub-task of #18
docs/8-Computations/logic.md
Flags image is white background, needs to work in dark. Create a “negative” or SVG so we can do Dark Mode? Can we programmatically create this negative?<b>
and <i>
to do emphasis.//
and /*...*/
) in dark mode (even light mode might need some work)***...***
was used as a fourth heading level, use ####
instead.In #16 @menghif added support for 4 heading levels of depth in the table of contents. Doing so we also noticed that some pages are using a 4th level heading for Example
and it's probably not a great idea (e.g., we should just use bold text, so it doesn't get added to the toc).
Here are the files/lines doing this:
❯ rg "#### Example"
docs/B-Computations/expressions.md
460:#### Example
docs/B-Computations/a-simple-calculation.md
37:#### Example
106:#### Example \(continued\)
182:#### Example \(continued\)
232:#### Example \(completed\)
docs/B-Computations/logic.md
31:#### Example Simple Statement
38:#### Example Code Block
255:#### Example
333:#### Example
381:#### Example
398:#### Example
448:#### Example
And here's the list of every file/line that uses a 4th level indent:
❯ rg "#### "
docs/B-Computations/a-simple-calculation.md
37:#### Example
64:#### Escape Sequences
106:#### Example \(continued\)
182:#### Example \(continued\)
232:#### Example \(completed\)
docs/A-Introduction/information.md
23:#### Bits
29:#### Bytes
51:#### Words
55:#### Hexadecimal
docs/B-Computations/logic.md
31:#### Example Simple Statement
38:#### Example Code Block
99:#### Single Statement
106:#### Code Block \(more than a single statement\)
122:#### Binary Selection
135:#### Single Statement
144:#### Code Block \(more than a single statement\)
158:#### Multiple Selection
173:#### Compound Conditions
190:#### Case-by-Case
255:#### Example
333:#### Example
381:#### Example
398:#### Example
448:#### Example
docs/B-Computations/testing-and-debugging.md
212:#### Build and Execute
233:#### Tracing
263:#### Compile and Run
285:#### Debugging Commands
303:#### Crashes
317:#### Help
docs/A-Introduction/compilers.md
157:#### Documentation
161:#### Multi-Line Comments
170:#### Inline Comments
178:#### Whitespace
193:#### Indentation
docs/B-Computations/expressions.md
80:#### Operands
84:#### Binary
97:#### Unary
305:#### Binary Operands
316:#### Unary Operands
410:#### Promotion
432:#### Narrowing
460:#### Example
Let's fix this across all pages.
Hello! I would like to work on testing-and-debugging.md
file.
This is a sub-task of issue #18
I will audit and fix based on the following checks:
docs/D-Modulatirty/pointers.md
: there are places where > Blockquote are being used and Admonitions could replace it. “Note:” Lightbulb info Admonition.docs/8-Computations/logic.md
Flags image is white background, needs to work in dark. Create a “negative” or SVG so we can do Dark Mode? Can we programmatically create this negative?<b>
and <i>
to do emphasis.//
and /*...*/
) in dark mode (even light mode might need some work)Part of #18
Audit and fix type.md
<b>
and <i>
to do emphasis.***...***
was used as a fourth heading level, use ####
instead.Hi team, I would like to work on the audit and fix Compilers.md.
Tasks:
<b>
and <i>
to do emphasis.A nice addition that, I believe, would greatly enhance the learning experience is giving the option to run and modify the examples available.
There are several examples of this:
There are two phases to take care of: compilation and running the program, and we can either leverage the front-end, or a back-end, or both.
I would like to create a very simple prototype that demonstrates this use case, if possible. Any suggestions are welcome! 😃
This is an sub-issue of #18.
<b>
and <i>
to do emphasis.***...***
was used as a fourth heading level, use ####
instead.This is a meta issue, meant to organize the work necessary to audit and fix all existing markdown pages in docs/
. If you want to work on this, the first step is to file a new issue for a given page and then leave a comment here with a link to the issue and name of the file you're working on.
The IPC C notes are written in 30 Markdown files. These files have been automatically translated to Markdown:
When working on one of these pages, here are some things to consider
docs/D-Modularity/pointers.md
, where we should reduce the vertical padding/margins on tables. The tables are too large, and probably shouldn't be tables at all.docs/D-Modulatirty/pointers.md
: there are places where > Blockquote are being used and Admonitions could replace it. “Note:” Lightbulb info Admonition.docs/8-Computations/logic.md
Flags image is white background, needs to work in dark. Create a “negative” or SVG so we can do Dark Mode? Can we programmatically create this negative?<b>
and <i>
to do emphasis.//
and /*...*/
) in dark mode (even light mode might need some work)***...***
was used as a fourth heading level, use ####
instead.If you notice issues that you can't, or don't want to fix, please file separate issues.
Hi, I would like to work on output-functions.md
mentioned on issue-#18.
Look for any typos
Make sure all Markdown is correctly done. The conversion was done automatically by a tool, so there may be more idiomatic ways to do some things
Check the page in a Desktop browser. Does it look OK? Are there any issues that need to be fixed?
Check the page in a Mobile browser. Does it look OK? Are there any issues that need to be fixed?
Try the page in both Light and Dark mode. Are there any issues that need to be fixed?
Try running the page through Lighthouse: https://developers.google.com/web/tools/lighthouse. Are there any issues that need to be fixed?
Try running the page through Web Hint: https://webhint.io/. Are there any issues that need to be fixed? - [ ] Tables that are really wide (types.md) could be converted to use SVG or flex/grid. Make wide visual tables fit in the available viewport. Another example is the table in docs/D-Modularity/pointers.md, where we should reduce the vertical padding/margins on tables. The tables are too large, and probably shouldn't be tables at all.
Prefer Markdown tables vs. raw HTML tags
Fix colours in tables so it uses global styles vs. inline styles
Use alt tags for all images. See https://supercooldesign.co.uk/blog/how-to-write-good-alt-text for suggestions
Avoid blockquote for indentation and prefer q or blockquote only when actually quoting. Use Admonitions instead. Example: docs/D-Modulatirty/pointers.md: there are places where > Blockquote are being used and Admonitions could replace it. “Note:” Lightbulb info Admonition.
Make sure images work in dark and light modes. For example, docs/8-Computations/logic.md Flags image is white background, needs to work in dark. Create a “negative” or SVG so we can do Dark Mode? Can we programmatically create this negative?
Change colours for tables (don’t use Yellow). We should use the default colour theme.
Avoid using < b > and < i > to do emphasis.
Use backticks and all code for memory addresses and such in tables that use things like void, int, function names, memory addresses.
Make sure all code blocks use syntax highlighting
centre images horizontally (esp. when they are small) so they work well at all responsive sizes
check sub-script and super-script that they are correctly used in all cases
consider including inter-site links to other pages that have related info
all links should have descriptive text for accessibility
Make sure that sub-headings (right-hand side) for each document are correct.
Improve readability of code comments (i.e., // and /.../) in dark mode (even light mode might need some work)
In places where ... was used as a fourth heading level, use #### instead.
Fix Frontmatter for page to include proper id, title, slug, etc.
Thank you so much!
I would like to audit the file functions.md using the below checks as a guideline:
<b>
and <i>
to do emphasis.I would like to audit and fix the string-library.md
page based on tasks listed below.
<b>
and <i>
to do emphasis.***...***
was used as a fourth heading level, use #### instead.In https://github.com/Seneca-ICTOER/IPC144/pull/61/files#diff-e9bdd80935a7058d016ee32cb30d64969fd2d18cc9324d64a33b0557b18b12c9 and https://github.com/Seneca-ICTOER/IPC144/pull/60/files#diff-be05c13053f9c29afd50066de996d568f9913764c46318677fd945bd9a5c008dR2 we're starting to see a standard emerge for Markdown frontmatter. For example:
---
id: pointers
title: Pointers
sidebar_position: 2
slug: /modularity/pointers
description: A variable that holds an address is called a pointer.
---
The full list of properties we can define is at https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs#markdown-frontmatter.
Let's come up with a standard to use, and then roll it out across all the pages. We can come back to this after the first round of audits for #18 comes in.
Docusaurus has a cool plugin you can use for generating ideal image sizes/formats when doing a production build. We could use it to create responsive images for various screen sizes.
At this point, a lot of our images are small, but it would be interesting to experiment with this feature in a few places, and learn how it works. We could progressively add more of it as we replace images, and use higher resolution images that this plugin will scale for different use cases.
I'd like to audit and fix the a-simple-calculation.md
page based on tasks listed below.
Tasks:
This issue is a sub-issue of #18.
Follow up of #11
Our current PWA icons in (.static/img/pwa) using a low resolution and blurry icon. We want to replace that to a higher resolution.
I would like to audit and fix the records-and-files.md
mention on issue-#18.
Auditing and fixing based on the following tasks:
docs/D-Modularity/pointers.md
, where we should reduce the vertical padding/margins on tables. The tables are too large, and probably shouldn't be tables at all.docs/D-Modulatirty/pointers.md
: there are places where > Blockquote are being used and Admonitions could replace it. “Note:” Lightbulb info Admonition.docs/8-Computations/logic.md
Flags image is white background, needs to work in dark. Create a “negative” or SVG so we can do Dark Mode? Can we programmatically create this negative?<b>
and <i>
to do emphasis.//
and /*...*/
) in dark mode (even light mode might need some work)***...***
was used as a fourth heading level, use ####
instead.Docusaurus has a PWA plugin which adds a service worker in production builds, and can allow the app to be installed and run offline. Let's add this so users can work with the site offline.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.