Help Doc for Editors

Welcome! This document can help you learn the principle mechanisms of the Daily Bulletin project, and make you a successful editor of the Daily Bulletin. This article might seem a bit long because we aim to include every detail to avoid ambiguity, but the editing process is quite simple once you get used to it.

Before You Attempt to Start

As an editor, you need some basic knowledge to understand how things should work. You need to:

• Know what happens in a typical day in YK Pao School. To complete this step, you probably need to be a staff or student in the school. With such knowledge, you can understand the significance of each part of the Daily Bulletin.
• Know HTML and CSS. HTML is the standard markup language for Web pages; CSS is the language we use to style an HTML document. With such knowledge, you can edit web pages without pressure. You can learn HTML and CSS with MDN.
• Know Python. Python is a popular programming language. In this project, Python scripts are used to generate most of the HTML codes. With such knowledge, you know what to do when you need to alter the auto-generated parts. You can learn Python with Python Docs and IGCSE Computer Science.
• Know Git. Git is a version control system for software development. Our website is based on GitHub, which relies on Git for updates. With such knowledge, you know what to do update the website every day. You can get to know Git with GitHub Docs.
• Know important Python libraries, including but not limited to re, os, datetime, PyPDF2, and BeautifulSoup. They are utilized in many of the Python scripts, and you might need to understand their logic.
• Know this document well. Specifically, there are some rules to make the document more readable:
  • Verbs indicating what you need to do are marked like this.
  • DAWOH is an abbreviation for "Day After a Weekend or a Holiday". DBWOH is an abbreviation for "Day Before a Weekend or a Holiday".
  • The names of some files might vary due to time, so they are given temporary names in this document enclosed by {}. Some examples are {this-DAWOH}.html or {next-day}.html. Keep in mind that these names should actually represent a date in the yyyy-mm-dd convention, like 2024-01-01.
  • The names of other files with an external source might vary as well, so they are given temporary names enclosed by []. Some examples are [menu].pdf or [picture].png. Note that these names should be replaced with the real names of these external files.
• Lastly but most importantly, keep an open mindset. Be kind to your creative ideas and others' personal opinions. You should consider to:
  • Integrate new thoughts and designs into the Daily Bulletin whenever possible.
  • Respect suggestions from others, even if they sound unprofessional.
  • Accept and publish inspirations from others, no matter what opinions these shared contents represent, as long as they are generally factual, friendly, and safe.
  • Rephrase certain sentences in others' inspirations to reduce bias if needed, but never insert your own bias.

Keep in mind that you do not need to be an expert in the above fields. You must understand the basics, but you only need to understand the basics. You can learn more if you need by peeking into the previous source codes or consulting ChatGPT.

As You Start

This section gives you an outline and a check-list of what you should try do so that you can start to run the programs. The first steps should be easy, but some could be if you have little programming experience. If you encounter any problems, consult ChatGPT or any tech person around you.

• Clone the repository of the Daily Bulletin. Run the command git clone https://github.com/albertttan/albertttan.github.io.git in Terminal.
• Download other source files of the Daily Bulletin, including the various Python scripts.
• Download and install a web browser. Firefox is a personal recommendation, but any relatively modern browser i.e. not IE like Chrome, Safari and Edge should do.
• Download and install a text editor to edit and run HTML and Python files. Sublime Text is a personal recommendation, but a simple combination of Python's IDLE and macOS's TextEdit can work as well.
• Download and install Python, from the official Python website or with Homebrew.
• Download and install related Python libraries. You need to download PyPDF2 and beautifulsoup4. Run the command pip install PyPDF2 beautifulsoup4 in Terminal.
• Check if the next day is a school day.
  • If it is, continue on to create a Daily Bulletin.
  • If it is not, stop. You do not need to create a Daily Bulletin for a weekend or a holiday.
• The scripts are designed so that you can easily compile the Daily Bulletin for the next day. For example, if you run the scripts on 2024-01-01, the Daily Bulletin for 2024-01-02 will be created. This also means that it is much more difficult for you to create a Daily Bulletin for any day other than the next day, so don't procrastinate or attempt to do your job early!
• Check if the next day is a DAWOH.
  • If it is, continue to the following section. There are more steps you need to complete for a DAWOH.
  • If it is not, skip the following section and continue to the next.

Now you are ready.

If the Next Day is a DAWOH

First, you need to download some files.

• Download Menu of the Week.
  • Find the link to it in an email sent by Parent Connect after school every DBWOH.
  • Download [menu].pdf.
  • Rename [menu].pdf as {this-DAWOH}.pdf.
  • Place {this-DAWOH}.pdf in the menu/ folder.
  • Open menu/{this-DAWOH}.pdf and keep it open.
• Download The Week Ahead.
  • Find the link to it in an email sent by SLO on 3^rd Sep 2023.
  • Download The Week Ahead 本周展望.pptx.
  • Open The Week Ahead 本周展望.pptx and keep it open.

Next, you need to do some manual editings.

• Community Time.
  • Navigate to community_time/.
  • Duplicate community_time/{last-DAWOH}.html to community_time/{this-DAWOH}.html.
  • Open community_time/{this-DAWOH}.html with your text editor.
  • Edit community_time/{this-DAWOH}.html: update the information according to The Week Ahead.
  • Save and close community_time/{this-DAWOH}.html.
• Important Events.
  • Navigate to important_events/.
  • Duplicate important_events/{last-DAWOH}.html to important_events/{this-DAWOH}.html.
  • Open important_events/{this-DAWOH}.html with your text editor.
  • Edit important_events/{this-DAWOH}.html: update the information according to Outlook Calendar.
  • Save and close important_events/{this-DAWOH}.html.
  • If you cannot see any events in your calendar, follow the instructions in this document.
• Notices.
  • Open part_regular_notices.html with your text editor.
  • Navigate to notices/.
  • Rename notices/latest.html to notices/{this-DAWOH}.html.
  • Open notices/{this-DAWOH}.html with your text editor.
  • Edit part_regular_notices.html: find and clear anything in part_regular_notices.html that are not in The Week Ahead anymore.
  • Edit part_regular_notices.html: find anything in notices/{this-DAWOH}.html that still appear in The Week Ahead; copy these contents and paste them into part_regular_notices.html.
  • Edit notices/{this-DAWOH}.html: clear everything in notices/{this-DAWOH}.html.
  • Edit notices/{this-DAWOH}.html: find every notice in The Week Ahead that did not appear in the last The Week Ahead; include these notices in notices/{this-DAWOH}.html.
  • Save and close part_regular_notices.html and notices/{this-DAWOH}.html.
  • When you edit, do not just copy and paste from the PowerPoint: remember to use HTML syntax.
• The School Inspires.
  • Open part_school_inspires.html with your text editor.
  • Edit part_school_inspires.html: clear everything in part_school_inspires.html.
  • Edit part_school_inspires.html: find every inspiration in The Week Ahead; include these inspirations in part_school_inspires.html.
  • Save and close part_school_inspires.html.
  • Poems, quotes, cartoons, and pictures are generally classified as inspirations.
• The School Recommends.
  • Open part_school_recommends.html with your text editor.
  • Edit part_school_recommends.html: clear everything in part_school_recommends.html.
  • Edit part_school_recommends.html: find every recommendation in The Week Ahead; include these recommendations in part_school_recommends.html.
  • Save and close part_school_recommends.html.
  • Articles talking about movies, people, activities, and exhibitions are generally classified as recommendations.
• Delicious Dinings.
  • Navigate to menu.
  • Open menu/menu_weekly.py with your text editor.
  • Edit menu/menu_weekly.py: find three blocks of lists named breakfast_info, lunch_info, and dinner_info; update the information according to menu/{this-DAWOH}.pdf.
  • Specifically, the rows and columns of these lists correspond with the rows and columns of the new menu. 0 should mark empty grids in the menu and grids that span multiple rows, while 1 should mark normal grids.
  • Save menu/menu_weekly.py.

Next, you need to run a script.

• Delicious Dinings.
  • Run menu/menu_weekly.py.
  • This can be achieved by pressing ⌘+B in Sublime Text or F5 in IDLE.

Finally, you need to do some more manual editings.

• Delicious Dinings.
  • Open menu/{this-DAWOH}.html with your text editor.
  • Check if the auto-filled contents correspond to the contents displayed in menu/{this-DAWOH}.pdf.
    • If everything is correct, continue.
    • If the amount of errors are acceptable, edit menu/{this-DAWOH}.html manually.
    • If there are numerous errors, re-edit and re-run menu/menu_weekly.py to regenerate menu/{this-DAWOH}.html.
  • Keep in mind that the table has been filtered and transposed.
  • Edit menu/{this-DAWOH}.html: correct capitalization, spacing, spelling, and punctuation errors in each grid.
  • Edit menu/{this-DAWOH}.html: adjust and fill grids that span multiple columns according to menu/{this-DAWOH}.pdf.
  • You can adjust the width occupied by such grids with the attribute rowspan after you remove excessive grids.
  • Save and close menu/{this-DAWOH}.html.
  • Close menu/{this-DAWOH}.pdf.

Great. Now you are ready to move on to the next part.

What You Should Do Every Day

First, you need to do some manual editings.

• Daily Inspiration.
  • Navigate to daily_inspiration/.
  • Check if the next day is a DAWOH.
    • If it is, duplicate daily_inspiration/{last-DBWOH}.html to daily_inspiration/{next-day}.html.
    • If it is not, duplicate daily_inspiration/{today}.html to daily_inspiration/{next-day}.html.
  • Open daily_inspiration/{next-day}.html with your text editor.
  • Edit daily_inspiration/{next-day}.html: clear everything in daily_inspiration/{next-day}.html.
  • Edit daily_inspiration/{next-day}.html: include 1 to 3 gathered inspirations in daily_inspiration/{next-day}.html.
  • You should have inspirations submitted to you through Microsoft Forms. Feel free to include your own inspiration, especially when you are running short of submitted inspirations. Feel free to collect inspirations from people around you actively, but ask for consent. Respect others if they want to keep their inspirations anonymous.
  • Check if you need to include images in daily_inspiration/{next-day}.html.
    • If you do need to include images, continue with the following example of [picture].png.
    • If you do not need to include images, skip the following steps; save and close daily_inspiration/{next-day}.html.
  • Compress [picture].png to [picture]_compressed.jpeg.
  • You can compress through scaling down and / or reducing image quality. It is a good idea to first use macOS' build-in "Convert Image" to turn every picture into a JPEG file scaled down to the size "Large", then use ImageMagick to increase the compression ratio. Aim for no more than 100 kilobytes per picture along with an acceptable quality.
  • Place [picture]_compressed.jpeg in the files/ folder.
  • Edit daily_inspiration/{next-day}.html: link the src of the <img> element to files/[picture]_compressed.jpeg.
  • Copy files/[picture]_compressed.jpeg to the Git repository.

Next, you need to run a script.

• Concatenate HTML.
  • Check that your internet is configured so that it is able to open https://www.wikipedia.org.
    • If it is, continue.
    • If it is not, do your best to configure your internet.
  • The script you run will call another script to fetch the In the News section from Wikipedia. Therefore, you must be able to access Wikipedia.
  • Open concat.py with your text editor.
  • Run concat.py.

Next, you need to do some more manual editings.

• Edit HTML.
  • Navigate to html/.
  • Open html/{next-day}.html with your text editor.
  • Edit html/{next-day}.html: find Day * in <html> → <body> → <header> → <p>; replace * with the real day of the cycle.
  • Check if the auto-filled contents are correct.
    • If everything is correct, continue.
    • If the amount of errors are acceptable, edit html/{next-day}.html manually.
    • If there are numerous errors, re-edit the documents responsible for whichever section that goes wrong; re-run concat.py to regenerate html/{next-day}.html.
  • Keep in mind that the pictures cannot and should not display normally because they are under the files/ directory, which is not present under the html directory. To check the pictures, you can temporarily move html/{next-day}.html to {next-day}.html under the main directory, but do not forget to move it back.
  • Check if the next day is a DAWOH.
    • If it is, edit the On this Day section in html/{next-day}.html to include the titles of all the days in the weekend or holiday as described in the files under on_this_day/ and on_this_day_zh/.
    • If it is not, continue.
  • Check if everything in html/{next-day}.html is safe for you to publish, especially under the sections On this Day and In the News.
    • If it is, continue.
    • If it is not, clear everything unsafe in html/{next-day}.html.
  • We need to do our best to keep an open mindset, but it is always a good idea to maintain the longevity of you and Daily Bulletin as a whole. You can choose to delete the single <li> element, delete the entire section, or state that we have a technical problem.

Next, you need to run another script.

• Pack HTML.
  • Open pack.py with your text editor.
  • Run pack.py.
  • This should always be the last script you run every day. Run this script once you made any changes to html/{next-day}.html, manual or automatic. This script packs your HTML into an email message, copies your HTML to the Git repository, and pushes your changes. You need a token for your first push to the git repository, but then the script will work fine.

Finally, you need to send the email.

• Since different email clients work very differently, this part only shows a brief idea of what you should do. Specific implementations might vary.
• Place eml/{next-day}.eml to the Drafts folder in your email client.
• Open this draft.
• Choose Send Later to send the email at 06:30 the next day.

Congratulations! You've done your job. Sleep well!