MobilityDB-workshop version 1.1

Author: mschoema

.gitignore

@@ -0,0 +1,4 @@
+workshop.sql
+*.pdf
+*.epub
+*.html

CONTRIBUTING.md

@@ -1,61 +1,48 @@
 # MobilityDB Workshop Contribution Guide
 
-MobilityDB uses DocBook v4.5 to generate workshop guides. The instructions below provide a step-by-step guide to convert from a Notion markdown export to the XML format required to successfully compile using `dblatex`. The process uses a tool called `pandoc` to convert into DocBook v5 and then some manual editing to work with v4.5 of DocBook.
+MobilityDB uses DocBook v4.5 to generate workshop guides. The instructions below provide a step-by-step guide to contribute to the workshop guide.
 
 ## Conventions
 - Images are in `.png` format and use pascal case (e.g. `VeryImportantImage.png`) for filename. 
-- XML files use lowercase underscores (e.g. `my_filename.xml`)and acronyms remain uppercase (e.g. `my_AWS_example.xml`)
+- XML files use lowercase underscores (e.g. `my_filename.xml`) and acronyms remain uppercase (e.g. `my_AWS_example.xml`)
 
-## Start
+## Contribution Workflow
 
 Steps are as follows:
-- Export from notion to Markdown
-- Change folder to "images"
-- Rename file to AIS_Dashboard
-
-IN MARKDOWN
-Find and replace image folder `(Dashboard%20and%20Visualization%20of%20Ship%20Trajectories%20(%20845afa91ff30470181ea3a0b5ddf08b5/` with `(images/`
-Find and replace `%20` with `" "`. Refactor all image file names (use caption as image name, refactor name + pascal case)
-Remove initial heading
-Remove all caption duplicate text
-
-### Convert Markdown to DocBook v5
-
-From terminal run the following commands. Command arguments:
-- `FlightDataDashboard.md` -> The name of your notion markdown file.
-- `FlightDataDashboard.xml` -> Name of the output file.
-```bash
-cd <folder_with_markdown>
-pandoc FlightDataDashboard.md -f markdown -t docbook5 -s -o FlightDataDashboard.xml
+- Usually, the latest version of the workshop guide is in the `develop` branch. Refer always to this branch.
+- Fork the repository and clone it locally.
+- Create a new branch from `develop` and name it `feature/<your_feature_name>`. For example, 'feature/correcting_typos'.
+- Make your changes and commit them to your branch.
+- Push your branch to your forked repository.
+- Create a pull request from your branch to the `develop` branch of the main repository. Please, make sure to detail your changes in the pull request description. A nice way to do this is to use the following template:
+  
+  ```markdown 
+  Changes:
+  - Fix typos
+  - Add new section
+  - etc.
+  ```
+
+## Changing the Workshop Guide
+
+If you want to make changes to the guide, you will need to edit the xml file corresponding to the chapter you want to change. For example, if you want to propose a change to the `AIS_Dashboard` chapter, you will need to edit the `doc/AIS_Dashboard.xml` file.
+
+## Adding a New Chapter
+
+If you want to add a new chapter to the guide, you will need to create a new xml file in the `doc` folder. For example, if you want to add a new chapter called `My_New_Chapter`, you will need to create a new file called `doc/My_New_Chapter.xml`. 
+
+If you need to insert any images in the new chapter, you will need to add them to the `doc/images` folder. For example, if you want to add an image called `My_New_Image.png`, you will need to add it to the `doc/images` folder.
+
+You will also need to add the following line to the `mobilitydb-workshop.xml` file:
+
+```xml
+<!ENTITY My_New_Chapter SYSTEM "doc/My_New_Chapter.xml">
 ```
 
-## In Generated XML 
-
-- Delete header information `<!DOCTYPE ... </info>`
-- Insert `<chapter id ="AIS_Dashboard">` at beginning
-- Insert `<title>Dashboard and Visualization of Ship Trajectories (AIS)</title>`
-- Remove `</article>` at end
-- Insert `</chapter>` at end
-- Find/replace `<link xlink:href` with `<ulink url`
-- Find/replace `</link>` with `</ulink>`
-- Find/replace `<imagedata fileref` with `<imagedata width='80%' fileref`
-  - note: some pictures will need to have their width set manually.
-- Remove `xml:id=...` from the "section" tag which looks like: `<section xml:id=...>`
-  - `<section xml:id=...>` becomes `<section>`
-- Replace `<` with `&lt;`
-- Replace `>` with `&gt;`
-
-COPY AIS_Dashboard.xml into parent doc folder
-COPY all images from the notion export folder into the doc/images folder
-
-IN mobilitydb-workshop.xml
-ADD <!ENTITY GPX SYSTEM "[filename].xml"> at header
-ADD &FlightDataDashboard; at end
-
-# In Terminal
-```bash
-cd ..
-dblatex -s texstyle.sty -T native -t pdf -o mobilitydb-workshop.pdf mobilitydb-workshop.xml
+Finally, you will need to add the following line to the `mobilitydb-workshop.xml` file, in the appropriate place:
+
+```xml
+&My_New_Chapter;
 ```
 
-TODO: change image filename
+This will include the new chapter in the guide.