caubert / CSCI_3410 (public) (License: CC BY 4.0) (since 2018-05-16) (hash sha1)
Material for Database Class.
Clone URLs: https://rocketgit.com/user/caubert/CSCI_3410 ssh://rocketgit@ssh.rocketgit.com/user/caubert/CSCI_3410 git://git.rocketgit.com/user/caubert/CSCI_3410
master
List of commits:
Subject Hash Author Date (UTC)
Working on install manual. 3702c6437ee163eb4a61b4d69cffee8c8a76dc3d aubert@math.cnrs.fr 2020-04-19 06:04:22
Worked on makefiles and example file. 4255d5e85bb684349f7f7798455dd8b3a273254b aubert@math.cnrs.fr 2020-04-19 04:56:53
Re-idented some of the code. 124375e6bed1edb96d1bb4bcec8f111c8a3a1197 aubert@math.cnrs.fr 2020-04-19 03:10:02
Java indentation 2b317a12b7ab52bdca576a1bb46b2a2ce295464f guest 2020-04-18 22:21:04
test 6fefa044794ff1d74a3d2493556c836b3dd97e74 guest 2020-04-18 22:18:44
Java indentation 5b0e0eb38484a8c67517a36a438f148bd5efa740 guest 2020-04-18 22:14:01
Worked on install notes. b46b931ef11e3cb7dfe87c7f91ec9d5c558567e6 aubert@math.cnrs.fr 2020-04-17 05:22:20
Started to integrate installation manual to notes. fd27b7686dd4c9d99163cf7badc720cd4a050221 aubert@math.cnrs.fr 2020-04-17 04:09:11
Replaced picture with text in Naming_Convention.md. aff8c98c70b0834f9b0f076b881975daf3cdda03 aubert@math.cnrs.fr 2020-04-17 03:48:38
Testing. b1a0942b15742ce987e4ad63848e9e2afcdde7ae aubert@math.cnrs.fr 2020-04-17 02:03:52
Added explanation on the importance of alt text in known bugs. 3bddd86e1072b095a9f9d02f8c035f8d8f3e7155 aubert@math.cnrs.fr 2020-04-17 01:44:51
Notes on passing parameters in url eea245da85acbc2e3cf2dd94e10170dcd10eb04f aubert@math.cnrs.fr 2020-04-16 01:55:57
Worked on Security Chapter. e18b82c85cf995279993fb681d53f798f14b2932 aubert@math.cnrs.fr 2020-04-15 15:23:07
Re-vamping the advanced java part. bc34886513772e6920a153752267149ef89d9a70 aubert@math.cnrs.fr 2020-04-13 18:25:23
Deleted Workflow file, since it is now in CONTRIb. 194d0e9f227b1f56f893a010247417268552b9e4 aubert@math.cnrs.fr 2020-04-13 14:45:21
SQL/XML indentation and comments 618fca553f0ffa355ca330e90e9adeeeb42c586d guest 2020-04-13 00:09:03
Cleaning 29f4f08496934561d3fdfbc46ea2393714cf1662 aubert@math.cnrs.fr 2020-04-10 21:21:37
Changing end-of-line tyes. b9efef4052a41d6444c7e3c173859f32b98f32b8 aubert@math.cnrs.fr 2020-04-10 19:54:21
Changes to ease merging. 77a481a4534bb0594e9fba45457450b14a7834b9 aubert@math.cnrs.fr 2020-04-10 19:51:38
? 556cbef3895848adcc86cf97120b03f8dbc047ea aubert@math.cnrs.fr 2020-04-10 18:41:38
Commit 3702c6437ee163eb4a61b4d69cffee8c8a76dc3d - Working on install manual.
Author: aubert@math.cnrs.fr
Author date (UTC): 2020-04-19 06:04
Committer name: aubert@math.cnrs.fr
Committer date (UTC): 2020-04-19 06:04
Parent(s): 4255d5e85bb684349f7f7798455dd8b3a273254b
Signer:
Signing key:
Signing status: N
Tree: f27239553f224f37d066a90a4012004ee45b7a6b
File Lines added Lines deleted
CONTRIB.md 174 5
KNOWN_BUGS.md 9 0
LICENSE.md 2 3
Naming_Convention.md 0 197
README.md 10 11
TO_DO.md 0 22
install/INSTALL.md 256 86
install/img/folderstructure.png 0 0
install/img/markdownproc.png 0 0
install/img/normaluser.png 0 0
install/img/rootuser.png 0 0
install/manual.md 82 16
notes/Makefile 16 14
File CONTRIB.md changed (mode: 100644) (index c024550..5cbd02b)
... ... The indentation makes all the difference in the block environment.
144 144
145 145 - Titles are capitalized using the Chicago Manual: - Titles are capitalized using the Chicago Manual:
146 146
147 > - Capitalize the first and the last word.
148 > - Capitalize nouns, pronouns, adjectives, verbs, adverbs, and subordinate conjunctions.
149 > - Lowercase articles (a, an, the), coordinating conjunctions, and prepositions.
150 > - Lowercase the ‘to’ in an infinitive (I want to play guitar).
147 1. Capitalize the first and the last word.
148 2. Capitalize nouns, pronouns, adjectives, verbs, adverbs, and subordinate conjunctions.
149 3. Lowercase articles (a, an, the), coordinating conjunctions, and prepositions.
150 4. Lowercase the ‘to’ in an infinitive (I want to play guitar).
151 151
152 152 - Please, keep in mind that, as [@knuth1989mathematical, p. 19] writes: - Please, keep in mind that, as [@knuth1989mathematical, p. 19] writes:
153 153
154 154 > Exercises are some of the most difficult parts of a book to write. Since an exercise has very little context, ambiguity can be especially deadly; a bit of carefully chosen redundancy can be especially important. > Exercises are some of the most difficult parts of a book to write. Since an exercise has very little context, ambiguity can be especially deadly; a bit of carefully chosen redundancy can be especially important.
155 155
156 # File Name
157 1. Make file names lowercase.
158 2. Separate words with underscores.
159 3. Use only standard ASCII alphanumeric characters in file and directory names.
160
161 # Naming Convention Standard/File Name Conventions
162
163 # Folder Name
164 1. Folder Name should be meaningful.
165 2. Make folder names lowercase.
166
167 # Figure Name
168
169 1. Figures Names should follow the Underscore Case.
170 2. Everything is in lower case and the words are separated by underscores.
171 3. This convention is also popularly known as snake case.
172
173 >### **Example:**
174 > figure_name.svg
175 >
176 # Tag Name
177
178
179
180 # Link Name
181
182
183 ### *Important* Notes:
184
185 * Do not use names which could misguide other developers.
186 * Names should be meaningfully distinct and pronounceable.
187
188
189
190
191
192 >### A collection of guidelines for writing file, folder, classes, figures, and images names in the project. These guidelines should help you toward that goal of not only correct code, but understandable.
193
194 * Our working directory is
195
196
197 ~~~{.plain}
198 .
199 ├── install/ -- How to install the requirements to compile the document.
200 ├── notes/ -- The notes themselves.
201 │   ├── bib/ -- References (including reference to the document).
202 │   ├── code/ -- Source code included in the document.
203 │   ├── fig/ -- Source code for various figures used in the document.
204 │   ├── filters/ -- Pandoc filters.
205 │   ├── img/ -- Various image files integrated in the document.
206 │   ├── latex/ -- Latex configuration file.
207 │   ├── lib/ -- Various libraries
208 │   ├── style/ -- css style used for the web page.
209 │   ├── lectures_notes.md -- The main file for the lecture notes.
210 │   ├── Makefile -- Directives to generate the lecture notes.
211 │   └── temp.md -- Temporary file, for debugging purposes.
212 ├── CONTRIB.md -- A guide on how to contribute.
213 ├── KNOWN_BUGS.md -- A list of possible bugs, improvements, things to check, ...
214 ├── LICENSE.md -- The license of those notes..
215 ├── README.md -- The present file.
216 └── WORKFLOW.md -- An step-by-step guide on how to edit those notes.
217 ~~~
218
219 * [Code Folder Naming Convention](#code-folder-naming-convention)
220 * [Text](#text)
221 * [File Names](#file-name)
222 * [Figures](#figure-name)
223 * [Folders](#folder-name)
224 * [The Tags in the Document](#tag-name)
225 * [The Links in the Document](#link-name)
226
227
228
229
230 # Code Folder Naming Convention
231
232 ### In code Folder, we have following folders
233
234 1. [JAVA](#java)
235 2. [SQL](#sql)
236 3. [XML](#xml)
237
238
156 239
157 240 ### Code Convention ### Code Convention
158 241
159 242 #### Java #### Java
160 All the java code is beautified by the [google-java-format](https://github.com/google/google-java-format/) program shared in the `lib` subfolder (cf. the `clean_java` macro in the makefile).
243
244 1. All the java code is beautified by the [google-java-format](https://github.com/google/google-java-format/) program shared in the `lib` subfolder (cf. the `clean_java` macro in the makefile).
245 2. Every JAVA file name will be written as UpperCamelCase.
246 3. Words are smashed together and the first letter of each word is capitalized. No word separator, like the underscore _, is used.
247
248 >### **Example:**
249 > FileName.java
250
251 3. If there is any version/number, it should be written as,
252
253 >### **Example:**
254 > FileName01.java, FileName02.java
255
256
257 * ## Classes and Interfaces Names
258 1. Class and interface names are generally noun or noun phrases.
259 2. Class and interface must begin with a capital letter.
260
261 >### **Example:**
262 > interface AqueousHabitat { ... }
263 > class FishBowl implements AqueousHabitat { ... }
264
265
266 * ## Method Names
267 1. Method names generally begin with a lowercase letter.
268 2. A call on a procedure is a statement to do something, so a procedure name is generally a verb phrase that is a command to do something.
269
270 >### **Example:**
271 > public void setTitle(String t) { ... }
272
273
274 3. A function call yields a value, so a function name is generally a noun phrase that describes the value.
275
276 >### **Example:**
277 > public double areaOfTriangle(int b, int c, int d) { ... }
278 4. The name of a boolean function is often a verb phrase starting with "is", thus describing what the value means,
279
280 >### **Example:**
281 > public boolean isEquilateralTriangle(int b, int c, int d) { ... }
282
283
284 * ## Variable Names
285 1. Variable names generally start with a lowercase letter.
286 2. Variable names should give the reader some hint about what the variable is used for.
287 3. A well-chosen name, which gives a hint at the meaning of the variable, helps document a program, making it easier to understand. On the other hand, using the names of your friends or flowers that you like as variable names just annoys and makes the program harder to understand. Don't do that.
288 4. Also, refrain from using vague names like counter or var or data; instead think about what the variable really is for and use a more concrete name.
289 5. There is a tension between writing long descriptive names and very short names.
290 6. We tend to use shorter names for parameters and local variables and longer names for fields and static variables.
291
292 * ## Parameter Names
293 1. Parameter names may be short, even one letter long.
294
295 >### **Example:**
296 > public boolean isEquilateralTriangle(int b, int c, int d) {return b == c && c == d;}
297
298 * ## Local variable names*
299 1. A local variable is a variable that is declared in a method body.
300 2. Its declaration should be placed as close to its first use as possible.
301 3. The scope of a local variable is usually short, and its meaning is often obvious either from a comment on its declaration or from the short code in which it is used. Therefore, names of local variables may be short.
302
303 * ## Fields and class (i.e. static) variables
304 1. The meaning of fields and class variables are typically given as comments by the declarations, far from where the variables are used.
305 2. Therefore, the names of field and class variables should be longer and as mnemonic as possible, giving the reader a good idea what the meaning are.
306
307 * ## Package names
308 1.Package names are usually all lowercase and consist of nouns.
309
310
161 311 ##### Comment Style(s): ##### Comment Style(s):
162 312 #. Documentation comments- These describe classes, methods, content, etc. Usually placed before declarations. #. Documentation comments- These describe classes, methods, content, etc. Usually placed before declarations.
163 313
 
... ... All the java code is beautified by the [google-java-format](https://github.com/g
202 352
203 353
204 354 #### XML #### XML
355
356 * XML Files in Code Folder
357 1. Camel case is a common naming rule in JavaScripts.
358 2. Uppercase first letter in each word except the first.
359 >### **Example:**
360 > firstName.xml
361
362
205 363 ##### Comment Style(s): ##### Comment Style(s):
206 364 ```{.xml} ```{.xml}
207 365 <!-- Single line --> <!-- Single line -->
 
... ... All the java code is beautified by the [google-java-format](https://github.com/g
219 377 #### CSS #### CSS
220 378 ##### Comment Style(s): ##### Comment Style(s):
221 379 W3C specifications says to define comments using ```/* ... */```{.css} whether single or multi-line because ```//```{.css} isn't supported on all browsers and can cause unexpected results. W3C specifications says to define comments using ```/* ... */```{.css} whether single or multi-line because ```//```{.css} isn't supported on all browsers and can cause unexpected results.
380
222 381 ##### Spacing: ##### Spacing:
223 382 * Use four spaces for each indent * Use four spaces for each indent
224 383 * Add one empty line between style definitions * Add one empty line between style definitions
 
... ... Example:
234 393 ``` ```
235 394 * Add a space after colons between properties and values * Add a space after colons between properties and values
236 395
396
237 397 # References {-} # References {-}
398
399 Inspirations:
400
401 * <https://www.geeksforgeeks.org/.>
402 * <https://www.w3schools.com/xml/xml_elements.asp.>
403 * <https://developers.google.com/style/filenames.>
404 * <https://guides.lib.purdue.edu/c.php?g=353013&p=2378293>
405 * <https://dev.to/danialmalik/a-beginner-s-guide-to-clean-code-part1-naming-conventions-139l>
406 * <https://www.cs.cornell.edu/courses/JavaAndDS/JavaStyle.html>
File KNOWN_BUGS.md changed (mode: 100644) (index e615b34..9b2ae67)
... ... OTHER
249 249 ----- -----
250 250
251 251 - It could be of interest to offer other formats (cf. <http://pandoc.org/> for a complete list), like `epub`, `docx`, or `mediawiki` (for this latest, a line is in the markdown, but the content has not been checked). - It could be of interest to offer other formats (cf. <http://pandoc.org/> for a complete list), like `epub`, `docx`, or `mediawiki` (for this latest, a line is in the markdown, but the content has not been checked).
252 - Add "Jump to solution" to every problem?
253 - Every time a problem is separated in questions, organize the solutions accordingly. So, do something like
254
255 > Solution to Problem 1.1 (A database catalog for a campus)
256 > Pb 1.1 – Solution to Q. 1
257 > …
258 > Pb 1.1 – Solution to Q. 2
259
260 Ideally, all the problems would be separated in questions.
252 261
253 262 TO DO TO DO
254 263 ======= =======
File LICENSE.md changed (mode: 100644) (index 9ae2387..e5c1f9f)
1 1 --- ---
2 2 title: License title: License
3 subtitle: CC BY 4.0
3 4 --- ---
4 5
5 6 <!-- <!--
 
... ... Markdown file for the licence courtesy of
7 8 https://github.com/idleberg/Creative-Commons-Markdown/ https://github.com/idleberg/Creative-Commons-Markdown/
8 9 --> -->
9 10
10 ## creative commons
11
12 # Attribution 4.0 International
11 # Creative Commons Attribution 4.0 International
13 12
14 13 Creative Commons Corporation (“Creative Commons”) is not a law firm and does not provide legal services or legal advice. Distribution of Creative Commons public licenses does not create a lawyer-client or other relationship. Creative Commons makes its licenses and related information available on an “as-is” basis. Creative Commons gives no warranties regarding its licenses, any material licensed under their terms and conditions, or any related information. Creative Commons disclaims all liability for damages resulting from their use to the fullest extent possible. Creative Commons Corporation (“Creative Commons”) is not a law firm and does not provide legal services or legal advice. Distribution of Creative Commons public licenses does not create a lawyer-client or other relationship. Creative Commons makes its licenses and related information available on an “as-is” basis. Creative Commons gives no warranties regarding its licenses, any material licensed under their terms and conditions, or any related information. Creative Commons disclaims all liability for damages resulting from their use to the fullest extent possible.
15 14
File Naming_Convention.md deleted (index 6389517..0000000)
1 # Naming Convention Standard/File Name Conventions
2
3 >### A collection of guidelines for writing file, folder, classes, figures, and images names in the project. These guidelines should help you toward that goal of not only correct code, but understandable.
4
5 * Our working directory is
6
7
8 ~~~{.plain}
9 .
10 ├── install/ -- How to install the requirements to compile the document.
11 ├── notes/ -- The notes themselves.
12 │   ├── bib/ -- References (including reference to the document).
13 │   ├── code/ -- Source code included in the document.
14 │   ├── fig/ -- Source code for various figures used in the document.
15 │   ├── filters/ -- Pandoc filters.
16 │   ├── img/ -- Various image files integrated in the document.
17 │   ├── latex/ -- Latex configuration file.
18 │   ├── lib/ -- Various libraries
19 │   ├── style/ -- css style used for the web page.
20 │   ├── lectures_notes.md -- The main file for the lecture notes.
21 │   ├── Makefile -- Directives to generate the lecture notes.
22 │   └── temp.md -- Temporary file, for debugging purposes.
23 ├── CONTRIB.md -- A guide on how to contribute.
24 ├── KNOWN_BUGS.md -- A list of possible bugs, improvements, things to check, ...
25 ├── LICENSE.md -- The license of those notes..
26 ├── README.md -- The present file.
27 └── WORKFLOW.md -- An step-by-step guide on how to edit those notes.
28 ~~~
29
30 * [Code Folder Naming Convention](#code-folder-naming-convention)
31 * [File Names](#file-name)
32 * [Figures](#figure-name)
33 * [Folders](#folder-name)
34 * [The Tags in the Document](#tag-name)
35 * [The Links in the Document](#link-name)
36
37
38
39
40 # Code Folder Naming Convention
41
42 ### In code Folder, we have following folders
43
44 1. [JAVA](#java)
45 2. [SQL](#sql)
46 3. [XML](#xml)
47
48 #### **JAVA**
49 * JAVA Files in Code Folder.
50 * Every JAVA file name will be written as UpperCamelCase.
51 * Words are smashed together and the first letter of each word is capitalized. No word separator, like the underscore _, is used.
52
53 | Example | FileName.java |
54 | ----------- | ------------- |
55
56 * If there is any version/number, it should be written as,
57 | Example | FileName01.java | FileName02.java |
58 | ----------- | --------------- | --------------- |
59
60 * *Classes and Interfaces Names*
61 * Class and interface names are generally noun or noun phrases.
62 * Class and interface must begin with a capital letter.
63
64 |interface Example | interface AqueousHabitat { ... } |
65 | -------------------- | -------------------------------- |
66
67 |Class Example | class FishBowl implements AqueousHabitat { ... } |
68 | -------------------- | ------------------------------------------------ |
69
70 * *Method Names*
71
72 * Method names generally begin with a lowercase letter.
73 * A call on a procedure is a statement to do something, so a procedure name is generally a verb phrase that is a command to do something.
74
75 | Example | public void setTitle(String t) { ... } |
76 | -------------------- | ------------------------------------------------ |
77
78
79 * A function call yields a value, so a function name is generally a noun phrase that describes the value.
80 | Example | public double areaOfTriangle(int b, int c, int d) { ... } |
81 | -------------------- | ------------------------------------------------ |
82
83 * The name of a boolean function is often a verb phrase starting with "is", thus describing what the value means,
84 | Example | public boolean isEquilateralTriangle(int b, int c, int d) { ... } |
85 | -------------------- | ------------------------------------------------ |
86
87 * *Variable Names*
88
89 * Variable names generally start with a lowercase letter.
90 * Variable names should give the reader some hint about what the variable is used for.
91 * A well-chosen name, which gives a hint at the meaning of the variable, helps document a program, making it easier to understand. On the other hand, using the names of your friends or flowers that you like as variable names just annoys and makes the program harder to understand. Don't do that.
92 * Also, refrain from using vague names like counter or var or data; instead think about what the variable really is for and use a more concrete name.
93 * There is a tension between writing long descriptive names and very short names.
94 * We tend to use shorter names for parameters and local variables and longer names for fields and static variables.
95
96 * *Parameter Names*
97 * Parameter names may be short, even one letter long.
98 | Example | public boolean isEquilateralTriangle(int b, int c, int d) {return b == c && c == d;} |
99 | -----------| ------------------------------------------------------------------------------------ |
100
101 * *Local variable names*
102 * A local variable is a variable that is declared in a method body.
103 * Its declaration should be placed as close to its first use as possible.
104 * The scope of a local variable is usually short, and its meaning is often obvious either from a comment on its declaration or from the short code in which it is used. Therefore, names of local variables may be short.
105
106 * *Fields and class (i.e. static) variables*
107 * The meaning of fields and class variables are typically given as comments by the declarations, far from where the variables are used.
108 * Therefore, the names of field and class variables should be longer and as mnemonic as possible, giving the reader a good idea what the meaning are.
109 * *Package names*
110
111 * Package names are usually all lowercase and consist of nouns.
112
113 #### **SQL**
114
115 * SQL folder has Homework Files.
116 * Every Homework will be followed by HW_ and filename.
117
118 | Example | HW_HomeworkName.sql |
119 | -----------| --------------- |
120 #### **XML**
121 * XML Files in Code Folder
122 * Camel case is a common naming rule in JavaScripts.
123 * Uppercase first letter in each word except the first
124
125 | Example | firstName.xml |
126 | ----------- | ---------- |
127
128
129 # File Name
130 * Make file names lowercase.
131 * Separate words with underscores.
132 * Use only standard ASCII alphanumeric characters in file and directory names.
133
134 * Recommended
135
136
137 Example | file_name.extension |
138 ---------|---------------------|
139
140 # Folder Name
141 * Folder Name should be meaningful.
142 * Make folder names lowercase.
143
144 # Figure Name
145
146 * Figures Names should follow the Underscore Case.
147 * Everything is in lower case and the words are separated by underscores.
148 * This convention is also popularly known as snake case.
149
150 | Example | figure_name.svg |
151 | ---------- | --------------- |
152
153 # Tag Name
154
155
156
157 # Link Name
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 ##### *Important* Notes:
183
184 * Do not use names which could misguide other developers.
185 * Names should be meaningfully distinct and pronounceable.
186
187
188
189
190
191 ### *Rules* are taken by:
192 * https://www.geeksforgeeks.org/.
193 * https://www.w3schools.com/xml/xml_elements.asp.
194 * https://developers.google.com/style/filenames.
195 * https://guides.lib.purdue.edu/c.php?g=353013&p=2378293
196 * https://dev.to/danialmalik/a-beginner-s-guide-to-clean-code-part1-naming-conventions-139l
197 * https://www.cs.cornell.edu/courses/JavaAndDS/JavaStyle.html
File README.md changed (mode: 100644) (index 6b70f50..080ef65)
... ... The source code, hosted at <https://rocketgit.com/user/caubert/CSCI_3410>, is or
18 18
19 19 ~~~{.plain} ~~~{.plain}
20 20 . .
21 ├── install/ -- How to install the requirements to compile the document.
21 ├── install/ -- Installing the requirements to compile the document.
22 22 ├── notes/ -- The notes themselves. ├── notes/ -- The notes themselves.
23 23 │   ├── bib/ -- References (including reference to the document). │   ├── bib/ -- References (including reference to the document).
24 24 │   ├── code/ -- Source code included in the document. │   ├── code/ -- Source code included in the document.
25 │   ├── fig/ -- Source code for various figures used in the document.
25 │   ├── fig/ -- Source code for various figures.
26 26 │   ├── filters/ -- Pandoc filters. │   ├── filters/ -- Pandoc filters.
27 27 │   ├── img/ -- Various image files integrated in the document. │   ├── img/ -- Various image files integrated in the document.
28 28 │   ├── latex/ -- Latex configuration file. │   ├── latex/ -- Latex configuration file.
 
... ... The source code, hosted at <https://rocketgit.com/user/caubert/CSCI_3410>, is or
33 33 │   ├── Makefile -- Directives to generate the lecture notes. │   ├── Makefile -- Directives to generate the lecture notes.
34 34 │   └── temp.md -- Temporary file, for debugging purposes. │   └── temp.md -- Temporary file, for debugging purposes.
35 35 ├── CONTRIB.md -- A guide on how to contribute. ├── CONTRIB.md -- A guide on how to contribute.
36 ├── KNOWN_BUGS.md -- A list of possible bugs, improvements, things to check, ...
37 ├── LICENSE.md -- The license of those notes..
38 ├── README.md -- The present file.
39 └── WORKFLOW.md -- An step-by-step guide on how to edit those notes.
36 ├── KNOWN_BUGS.md -- A list of possible bugs, improvements, …
37 ├── LICENSE.md -- The license of those notes.
38 └── README.md -- The present file.
40 39 ~~~ ~~~
41 40
42 41
43 Before compiling this document, you will need to install LaTeX, pandoc, and several other programs.
44 Refer to [install/INSTALL.md](install/INSTALL.html) for instructions on how to compile this document.
42 Before compiling this document, you will need to install git, LaTeX, pandoc, some of pandoc's filters, and several other programs.
43 Refer to [install/INSTALL.md](install/INSTALL.html) for instructions on how to compile this document, and to [notes/example.md](notes/example.html) for an example file.
45 44
46 45 To clone the source, use git and the command To clone the source, use git and the command
47 46
 
... ... To compile this document, simply change directory to `notes` and run
57 56
58 57 The Makefile in the `notes` folder is commented. The Makefile in the `notes` folder is commented.
59 58
60 ## Contributing
59 # Contributing
61 60
62 61 The simplest way to contribute is to report typos, errors or misleading statements. The simplest way to contribute is to report typos, errors or misleading statements.
63 62 You will find some instructions at [`CONTRIB.md`](CONTRIB.html) if you'd like, but you can… You will find some instructions at [`CONTRIB.md`](CONTRIB.html) if you'd like, but you can…
 
... ... You will find some instructions at [`CONTRIB.md`](CONTRIB.html) if you'd like, b
66 65 - …submit a pull request, cf. [`CONTRIB.md`](CONTRIB.html) for more information. - …submit a pull request, cf. [`CONTRIB.md`](CONTRIB.html) for more information.
67 66 - …submit bug reports at <https://rocketgit.com/user/caubert/CSCI_3410/bug> (requires an account). - …submit bug reports at <https://rocketgit.com/user/caubert/CSCI_3410/bug> (requires an account).
68 67
69 ## Authors and Contributors
68 # Authors and Contributors
70 69
71 70 - **Clément Aubert** - *Initial work* - <http://spots.augusta.edu/caubert/> - **Clément Aubert** - *Initial work* - <http://spots.augusta.edu/caubert/>
72 71 - **Crystal Anderson** - *Revisions* - **Crystal Anderson** - *Revisions*
 
... ... Crystal was supported by an [Affordable Learning Georgia](https://www.affordable
77 76 Bobby, Minh and Poonam benefited from the support and guidance of Dr. Onyeka Ezenwoye in the CSCI 4712 - Senior Capstone Project class. Bobby, Minh and Poonam benefited from the support and guidance of Dr. Onyeka Ezenwoye in the CSCI 4712 - Senior Capstone Project class.
78 77
79 78
80 ## License
79 # License
81 80
82 81 This project is licensed under the [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) licence: you are free to share and adapt this document, as long as you give proper credit. This project is licensed under the [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) licence: you are free to share and adapt this document, as long as you give proper credit.
83 82 Refer to [`LICENSE.md`](LICENSE.html) for the complete licence. Refer to [`LICENSE.md`](LICENSE.html) for the complete licence.
File TO_DO.md deleted (index c00aa6c..0000000)
1 - Fill the line "List all the entity integrity constraint and referential integrity constraint." with the actual constraints.
2
3 - Check that the title of the problems are *not* capitalized.
4
5 - Check that the numbering (and order) of the solution of the exercises and problems match the numbering of the exercises and problems.
6
7 - Look for arguments to help us decide if we should write "S.Q.L.", "U.M.L." and "E.R.", or "SQL", "UML" and "ER".
8
9 - Replace all the abbreviations (don't, won't, can't, etc.) with their "expanded" version (do not, will not, cannot, etc.)?
10
11 - Remove all the occurences of "I".
12
13 - Every time a problem is separated in questions, organize the solutions accordingly. So, do something like
14
15 > Solution to Problem 1.1 (A database catalog for a campus)
16 > Pb 1.1 – Solution to Q. 1
17 > …
18 > Pb 1.1 – Solution to Q. 2
19
20 Ideally, all the problems would be separated in questions.
21
22 - Add "Jump to solution" to every problem?
File install/INSTALL.md changed (mode: 100644) (index 140f701..3a242c4)
1 1 --- ---
2 title: How to install the required software and compile the lecture lecture_notes
2 title: Instruction Manual
3 3 --- ---
4 4
5 Please refer to [the example file](../notes/example.html) for a gentle test and guide on the syntax and tool of this document.
5 <!---
6 To compile this document, look, in the parent folder, for the "makefile" file.
7 It contains a "aux" rule that compile this document to an html document.
8 -->
6 9
7 Indicate how to clone the source code.
8 10
9 # Install
11 # Speed-Run
10 12
11 All the commands are typed as root.
13 To compile those notes, you need
12 14
13 Install Python3:
15 - The ability to execute [makefile](https://en.wikipedia.org/wiki/Makefile) (e.g., a UNIX system, a system with [Cygwin](https://en.wikipedia.org/wiki/Cygwin), or [some other trick](https://stackoverflow.com/q/2532234/2657549)),
16 - Python3 and pip,
17 - the latest version of [pandoc](https://github.com/jgm/pandoc/releases/),
18 - the latest version of [pandoc-include-code](https://github.com/owickstrom/pandoc-include-code), and of [pandoc-numbering](https://github.com/chdemko/pandoc-numbering),
19 - git (cf. <https://git-scm.com/>),
20 - LaTeX (cf. <https://www.latex-project.org/get/>, <https://tex.stackexchange.com/q/1092>)^[I recommend installing a minimal installation, and then fetching the missing packages one by one, using e.g. `/usr/local/texlive/2019/bin/x86_64-linux/tlmgr install environ`]),
21 - latexmk (cf. <https://ctan.org/pkg/latexmk/>, but it is possible that it is already part of your LaTeX installation),
22 - pdf2svg (cf. <https://github.com/dawbarton/pdf2svg>),
23 - librsvg2-bin,
24 - font-linuxlibertine
14 25
15 apt-get install python3-pip
26 Then, clone the repository at <https://rocketgit.com/user/caubert/CSCI_3410>, and refer to [the example file](../notes/example.html) for a gentle test and guide on the syntax and tool of this document.
27 Change the current folder to `notes`, and execute `make example`.
28 You can have a look at `notes/Makefile` to understand what is happening in the `example` rule.
16 29
17 Get the latest version of pandoc:
30 <!--
18 31
19 - Download the file "pandoc-XXX-amd64.deb" from <https://github.com/jgm/pandoc/releases>, where XXX is some version number,
20 - Navigate to that folder, and type
32 # Desinstall
21 33
22 dpkg -i pandoc-XXX-amd64.deb
34 All the commands are typed as root.
23 35
24 Install pandoc-include-code:
36 Clean all of cabal and the installed packages:
25 37
38 - Downloald <https://gist.githubusercontent.com/simonmichael/1185421/raw/7b5da412da62dadd204b9e41ccd9639097d2178e/gistfile1.sh>
26 39 - Type - Type
40 source gistfile1.sh
27 41
28 cabal update
29 - Type
30
31 cabal install pandoc-types
32 - Go to https://github.com/owickstrom/pandoc-include-code, download the archive, extract it, and type
33 42 - Type - Type
43 ghc-pkg-reset
34 44
35 cabal configure
36 cabal install
45 Completely remove pandoc:
37 46
38 Install pandoc-numbering:
47 apt-get purge pandoc
39 48
40 pip3 install pandoc-numbering
49 Uninstall pip:
41 50
42 # Testing
51 python -m pip uninstall pip
52 -->
43 53
44 All the commands are typed as a normal user, and assume that your current folder is `lecture_notes/CSCI_3410/install/`.
54 # Overview
45 55
46 ## Testing Pandoc
56 *The Generating Documents (Basic) Using Markdown User Manual outlines
57 the objectives, requirements, and needs to be addressed when training
58 users on how to generate a PDF, HTML, or ODT document using markdown
59 file. The plan presents the activities needed to support file
60 development.*
47 61
48 To test that pandoc is working properly:
62 # Introduction
49 63
50 pandoc test_pandoc.md -o test_pandoc.html
64 Markdown is a fast and easy way to take notes, create content for a website, and produce print-ready documents. It's a lightweight markup language with plain text formatting syntax. Markdown is designed to be converted to many different output formats such as PDF, Word, ODT, HTML, and many more. It is both portable and platform independent, more intuitive to read and write, and can be used for websites, documents, notes, books, etc., but is often used to format readme
65 files and in online discussion forums.
51 66
52 should produce a `html` file called `test_pandoc.html` containing
67 ## How Does Markdown Work?
53 68
54 ```{html}
55 <p>I’m a test for pandoc.</p>
56 ```
69 Markdown text is written and stored in plaintext file with a markdown extension (e.g. .md). Using a separate markdown application capable of processing markdown (we will be using Pandoc), it takes the markdown formatted text and converts it to HTML. The HTML file can then be viewable in a web browser or then converted to another file format, like PDF.
70
71 ![Figure 1.1: Markdown text file is converted and displayed in a web browser](markdownproc.png){ height=50% }
72
73
74 # Requirements
75
76
77 ## Skills required
57 78
58 Furthermore, the command
59 79
60 pandoc -v
80 * Markdown
81 * For a basic tutorial visit: <https://commonmark.org/help/tutorial/>
61 82
62 should produce an output that begins with
83 Helpful Skills:
63 84
64 > pandoc 2.9.1.1
65 > Compiled with pandoc-types 1.20, texmath 0.12, skylighting 0.8.3
85 * LaTex code
86 * Common terminal commands
87 * For more information visit: <https://www.dummies.com/computers/macs/mac-operating-systems/how-to-use-basic-unix-commands-to-work-in-terminal-on-your-mac/>
88 * Pandoc's Markdown
89 * For more information visit: <https://pandoc.org/MANUAL.html#pandocs-markdown>
90 * YAML (YAML Ain't Markup Language)
91 * For more information visit: <https://blog.stackpath.com/yaml/>
66 92
67 ## Testing pandoc-numbering
93 ## Software Requirements
68 94
69 To test that the pandoc-numbering filter is working properly:
95 For a fully functioning environment and step by step guide on installation instructions follow the instructions below:
70 96
71 pandoc test_pandoc-numbering.md --filter pandoc-numbering -o test_pandoc-numbering.html
97 NOTE: All the following steps must be installed on a Linux operating system.
72 98
73 should produce a `html` file called `test_pandoc-numbering.html` containing
99 1) Install [Git](https://github.com)
100 In your terminal, type (as root): `apt update`
101 then type: `apt install git`
74 102
103 NOTE: Upon opening your terminal, you may see username@hostname:~$. You want your terminal to run as root@hostname. To do this, upon opening your terminal, type: `su --`
104
105 Then enter your password. You should see something like this:
106
107 ![Terminal Root User](rootuser.png)\
108
109 2) Install [Make](https://gnu.org/software/make/manual/make.html)
110 In your terminal, type (as root): `apt-get update`
111 then type: `apt-get install build-essential`
112
113 3) Install [LaTex](https://latex-project.org)
114 * Download
115 [install-tl-unx.tar.gz](http://mirror.ctan.org/systems/texlive/tlnet/install-tl-unx.tar.gz)
116 from <https://www.tug.org/texlive/acquire-netinstall.html>
117 * Extract the folder
118 * In the terminal, navigate to the location of the extracted folder
119 * In the terminal, type (as root): perl install-tl
120 * When prompted, enter command: `I`
121
122 4) Install [Python 3](https://python.org/download/releases/3.0/)
123 In your terminal type (as root): `apt-get install python3-pip`
124
125 5) Install [Pandoc](https://pandoc.org)
126 * Download [[pandoc-2.9.2.1-amd64.deb]](https://github.com/jgm/pandoc/releases/download/2.9.1.1/pandoc-2.9.2.1-amd64.deb) (or higher) from <https://github.com/jgm/pandoc/releases/tag/2.9.1.1>
127 * From your terminal navigate to location of the downloaded Pandoc folder (most likely the downloads folder) and type: `dpkg -i pandoc-2.9.2.1-amd64.deb`
128
129
130 6) Install [pandoc-include-code](https://github.com/owickstrom/pandoc-include-code) filter
131 * In your terminal (as normal user) type: `cabal update`
132 * (cabal is a system for building and packaging Haskell libraries and programs. If cabal command not found then type (as root)):
133 `apt-get install haskell-platform`
134 * Then, (as normal user) type: `cabal update`
135
136 NOTE: To run terminal as a normal user, type: `su - username` where "username" is your username. You should see something like this:
137
138 ![Terminal Normal User](normaluser.png)\
139
140 * Then type: `cabal install pandoc-types`
141 * Go to <https://github.com/owickstrom/pandoc-include-code> and download the repository by clicking "Download ZIP" and extract the folder
142 * In your terminal, navigate to the extracted folder
143 * In your terminal type: `cabal configure`
144 * Then type: `cabal install`
145
146 7) Install [pandoc-numbering](https://github.com/chdemko/pandoc-numbering) filter
147 Type (as normal user): `pip3 install pandoc-numbering`
148
149 8) Install [latexmk](https://mg.readthedocs.io/latexmk.html) fully automated latex document generation
150 * Go to <https://ctan.org/pkg/latexmk/>
151 * Click download link and download and extract the file.
152 * Open the extracted latexmk folder, locate the "latexmk.pl" file and move it to "~/.local/bin" and rename it to "latexmk".
153
154 NOTE: You may need to expose hidden files while in "Home". To do this press Ctrl + H.
155
156 9) Install [pdf2svg](https://github.com/dawbarton/pdfsvg)
157 In your terminal type (as root): `apt-get install pdf2svg`
158
159 10) Install [librsvg2-bin](https://github.com/teemu/librsvg2-bin)
160 In your terminal type (as root): `apt-get install librsvg2-bin`
161
162 11) Install [texlive-xetex](https://packages.debian.org/sid/tex/texlive-xetex)
163 In your terminal type (as root): `apt-get install texlive-xetex`
164
165 12) Install linuxlibertine font and freefont
166 * In your terminal type (as root): `apt-get install fonts-linuxlibertine`
167 * Then type: `apt-get install fonts-freefont-ttf`
168
169 13) Clone this [basic folder structure](https://github.com/poonamveeral/GeneralRepo) (as a normal user)
170 Type: `git clone https://github.com/poonamveeral/GeneralRepo`
171
172 14) Testing Pandoc
173 * In your terminal, navigate to Course/install
174 * In your terminal type: `pandoc test_pandoc.md -o test_pandoc.html`
175 * In the install folder, you should see a file called "test_pandoc.html" containing
75 176 ```{html} ```{html}
76 <p><span id="exercise:1" class="pandoc-numbering-text exercise"><strong>Exercise 1</strong> <em>(The first exercise)</em></span></p>
77 <p><span id="exercise:2" class="pandoc-numbering-text exercise"><strong>Exercise 2</strong> <em>(The second exercise)</em></span></p>
177 <p>I’m a test for pandoc.</p>
78 178 ``` ```
79 179
80 ## Testing pandoc-citeproc
180 15) Testing pandoc-numbering
181 * In the same install folder, type:
182
183 `pandoc test_pandoc-numbering.md --filter pandoc-numbering -o test_pandoc-numbering.html`
184
185 * If you're receiving errors, in your terminal, type:
186 `export PATH=$PATH:/home/username/.local/bin`
187 * In the install folder, you should see a file called "test_pandoc-numbering.html" containing
188
189 ```{html}
190 <p><span id="exercise:1" class="pandoc-numbering-text exercise"><strong>Exercise 1</strong> <em>(The first exercise)</em></span></p>
191 <p><span id="exercise:2" class="pandoc-numbering-text exercise"><strong>Exercise 2</strong> <em>(The second exercise)</em></span></p>
81 192
82 To test that the pandoc-citeproc filter is working properly:
193 16) Test pandoc-citeproc
194 * In the same install folder, type:
83 195
84 pandoc --filter pandoc-citeproc test_pandoc-citeproc.md -o test_pandoc-citeproc.html
196 `pandoc --filter pandoc-citeproc test_pandoc-citeproc.md -o test_pandoc-citeproc.html`
85 197
86 should produce a `html` file called `test_pandoc-citeproc.html` containing
198 * In the install folder, you should see a file called "test_pandoc-citeproc.html" containing
87 199
88 200 ```{html} ```{html}
89 201 <p><span class="citation" data-cites="item1">(Doe 2005)</span></p> <p><span class="citation" data-cites="item1">(Doe 2005)</span></p>
 
... ... should produce a `html` file called `test_pandoc-citeproc.html` containing
94 206 </div> </div>
95 207 </div> </div>
96 208 ``` ```
97
98 ## Testing pandoc-include-code
99 209
100 To test that the pandoc-include-code filter is working properly:
101
102 pandoc -F pandoc-include-code test_pandoc-include-code.md
103
104
105 should produce a `html` file called `test_pandoc-include-code.html` containing
210 17) Test pandoc-include-code
211 * In the same install folder, type:
212 `pandoc --filter pandoc-include-code -o test_pandoc-include-code.pdf test_pandoc-include-code.md`
213 * In the install folder, you should see a file called "test_pandoc-include-code.html" containing
106 214
107 215 ```{html} ```{html}
108 216 <p>Here is some code:</p> <p>Here is some code:</p>
109 217 <div class="sourceCode" id="cb1"><pre class="sourceCode md"><code class="sourceCode markdown"><span id="cb1-1"><a href="#cb1-1"></a>I&#39;m a test for pandoc. </span></code></pre></div> <div class="sourceCode" id="cb1"><pre class="sourceCode md"><code class="sourceCode markdown"><span id="cb1-1"><a href="#cb1-1"></a>I&#39;m a test for pandoc. </span></code></pre></div>
110 218 ``` ```
111 219
112 # Desinstall
220 If you're receiving "Could not find executable pandoc-include-code"
113 221
114 All the commands are typed as root.
222 * Go to the root folder, and open the ".bashrc" file with a text editor
223 * Add the line below to the bottom of the file and click "save" to save the file:
115 224
116 Clean all of cabal and the installed packages:
225 `export PATH=$PATH:/home/username/.cabal/bin`
117 226
118 - Downloald <https://gist.githubusercontent.com/simonmichael/1185421/raw/7b5da412da62dadd204b9e41ccd9639097d2178e/gistfile1.sh>
119 - Type
120 source gistfile1.sh
121
122 - Type
123 ghc-pkg-reset
227 # Creating the Document
228 Follow these steps to learn how to create a simple markdown document utilizing bibliographies, images/figures, and code blocks.
124 229
125 Completely remove pandoc:
230 ## Step 1
126 231
127 apt-get purge pandoc
232 To start off, you're going to need a folder structure set up like this:
128 233
129 Uninstall pip:
234 ![Folder Structure](folderstructure.png)\
130 235
131 python -m pip uninstall pip
132
133 236
134 # Old Instructions
237 If you completed number 13 from 2.2 Software Requirements skip step 2. If not, continue on.
135 238
239 ## Step 2
136 240
137 Before compiling this document, you will need to install
241 You want each folder to contain:
138 242
139 - git (cf. <https://git-scm.com/>),
140 - LaTeX (cf. <https://www.latex-project.org/get/>, <https://tex.stackexchange.com/q/1092>)^[I recommend installing a minimal installation, and then fetching the missing packages one by one, using e.g. `/usr/local/texlive/2019/bin/x86_64-linux/tlmgr install environ`]),
141 - pandoc (cf. <http://pandoc.org/installing.html>) v. 2.7.3,
142 - pandoc-numbering (cf. <https://github.com/chdemko/pandoc-numbering#installation>) v. 3.1.0.3,
143 - pandoc-include-code (cf. <https://github.com/owickstrom/pandoc-include-code>) v. 1.2.0.1,
144 - latexmk (cf. <https://ctan.org/pkg/latexmk/>, but it is possible that it is already part of your LaTeX installation),
145 - pdf2svg (cf. <https://github.com/dawbarton/pdf2svg>),
146 - librsvg2-bin,
147 - font-linuxlibertine
243 ```{.plain}
244 .
245 ├── install/ -- How to install requirements to compile the document.
246 │   └── .md files -- To test Pandoc
247 ├── bib/ -- References (including reference to the document).
248 │   └── .bib files -- To store citations.
249 ├── code/ -- Source code included in the document.
250 │   └── code files -- (E.g. .java, .xml, .sql)
251 ├── fig/ -- Source code for various figures used in the document.
252 ├── img/ -- Various image files itegrated in the document.
253 ├── latex/ -- Latex configuration file.
254 ├── style/ -- CSS style used for the web page.
255 ├── Makefile -- Directives to generate example.md document.
256 ├── README.md -- The present file.
257 └── example.md -- Sample file to test.
258 ```
148 259
149 Because `pandoc-include-code` has not (yet?) being updated, a version equal to or less than 2.7.3. of pandoc (<https://github.com/jgm/pandoc/releases/tag/2.7.3>) and the version 1.2.0.1 of `pandoc-include-code` (<https://github.com/owickstrom/pandoc-include-code/releases/tag/v1.2.0.1>) need to be used.
150 Hopefully this bug, that I documented [here](https://github.com/owickstrom/pandoc-include-code/issues/25) and [there](https://github.com/jgm/pandoc/issues/5943) will be fixed soon.
260 An example of a basic template of a markdown file can be found at "example.md" in the generic repo from step 13 from above.
151 261
152 And because of some incompatibility between latest version of `panflute` and `pandoc-numbering`, you need to
262 # Compiling and Converting the Document
263 Follow these steps to learn how to compile and convert a markdown file to PDF, ODT, and HTML. Other possible conversion formats can be found here: <https://pandoc.org/>
264
265 * Open up a terminal, inside of it, change your directory to where your markdown file is located. In this example, navigate to your "Course" folder. To do this, simply type: `cd Course` where "Course" is the name of your Course folder.
266
267 * Next, type: `make fig`
268 "make fig" compiles all the latex code in order to produce the figures from the figures folder.
269
270 * Then type: `make fig_svg`
271 "make fig_svg" compiles all the latex code in order to produce the figures from the figures folder.
272
273 * To produce a PDF document common format is:
274
275 `pandoc <filters> inputfile.md -o outputfile.ext`
276
277 or
278
279 `pandoc <filters> -o outputfile.ext inputfile.md`
280
281 ## PDF
282 For our example, in your terminal, while in the directory of where your markdown file is located, which should be your "Course" folder, type:
283
284 `make pdf`
285
286 or
287
288 ```
289 pandoc --toc --filter pandoc-numbering --filter pandoc-citeproc --filter pandoc-include-code \
290 --top-level-division=chapter -M date="$(LANG=en_us_88591 date '+%B %e, %Y (%r)')" \
291 --pdf-engine=xelatex --pdf-engine-opt=-shell-escape -V links-as-notes \
292 --default-image-extension=pdf -o example.pdf example.md
293 ```
294
295 To check if the results worked, from your desktop, navigate to your "Course" folder. You should see a new file called "example.pdf".
296
297 ## ODT
298 For our example, in your terminal, while in the directory of where your markdown file is located, which should be your "Course" folder, type:
299
300 `make odt`
301
302 or
303
304 ```
305 pandoc  --toc --filter pandoc-numbering --filter pandoc-citeproc --filter pandoc-include-code \
306 --top-level-division=chapter -M date="$(LANG=en_us_88591 date '+%B %e, %Y (%r)')" \
307 --default-image-extension=svg -o example.odt example.md
308 ```
309
310 To check if the results worked, from your desktop, navigate to your "Course" folder. You should see a new file called "example.odt".
311
312
313 ## HTML
314 For our example, in your terminal, while in the directory of where your markdown file is located, which should be your "Course" folder, type:
315
316 `make html`
317
318 or
319
320 ```
321 pandoc --toc --filter pandoc-numbering --filter pandoc-citeproc --filter pandoc-include-code \
322 --top-level-division=chapter -M date="$(LANG=en_us_88591 date '+%B %e, %Y (%r)')" \
323 --css=style/style.css --toc-depth=1 --self-contained --default-image-extension=svg \
324 -o example.html example.md
325 ```
153 326
154 #. Fetch the latest version of `pandoc-numbering`, using, as root
327 where "style.css" is the name of your css file.
155 328
156 pip install --upgrade --force --no-cache git+https://github.com/chdemko/pandoc-numbering
157
158 #. Then, _downgrade_ to an old version of panflute, using
329 To check if the results worked, from your desktop, navigate to your "Course" folder. You should see a new file called "example.html".
159 330
160 pip install -Iv panflute==1.10.6
161 331
File install/img/folderstructure.png renamed from notes/img/folderstructure.png (similarity 100%)
File install/img/markdownproc.png renamed from notes/img/markdownproc.png (similarity 100%)
File install/img/normaluser.png renamed from notes/img/normaluser.png (similarity 100%)
File install/img/rootuser.png renamed from notes/img/rootuser.png (similarity 100%)
File install/manual.md changed (mode: 100644) (index 78d8a1c..3a242c4)
... ... title: Instruction Manual
3 3 --- ---
4 4
5 5 <!--- <!---
6 To compile this document:
7 Scroll down to Compiling and Converting the Document-- choose either command (HTML, ODT, PDF), change 'example' file to 'manual' and follow instructions from there.
6 To compile this document, look, in the parent folder, for the "makefile" file.
7 It contains a "aux" rule that compile this document to an html document.
8 8 --> -->
9 9
10 *Overview*
10
11 # Speed-Run
12
13 To compile those notes, you need
14
15 - The ability to execute [makefile](https://en.wikipedia.org/wiki/Makefile) (e.g., a UNIX system, a system with [Cygwin](https://en.wikipedia.org/wiki/Cygwin), or [some other trick](https://stackoverflow.com/q/2532234/2657549)),
16 - Python3 and pip,
17 - the latest version of [pandoc](https://github.com/jgm/pandoc/releases/),
18 - the latest version of [pandoc-include-code](https://github.com/owickstrom/pandoc-include-code), and of [pandoc-numbering](https://github.com/chdemko/pandoc-numbering),
19 - git (cf. <https://git-scm.com/>),
20 - LaTeX (cf. <https://www.latex-project.org/get/>, <https://tex.stackexchange.com/q/1092>)^[I recommend installing a minimal installation, and then fetching the missing packages one by one, using e.g. `/usr/local/texlive/2019/bin/x86_64-linux/tlmgr install environ`]),
21 - latexmk (cf. <https://ctan.org/pkg/latexmk/>, but it is possible that it is already part of your LaTeX installation),
22 - pdf2svg (cf. <https://github.com/dawbarton/pdf2svg>),
23 - librsvg2-bin,
24 - font-linuxlibertine
25
26 Then, clone the repository at <https://rocketgit.com/user/caubert/CSCI_3410>, and refer to [the example file](../notes/example.html) for a gentle test and guide on the syntax and tool of this document.
27 Change the current folder to `notes`, and execute `make example`.
28 You can have a look at `notes/Makefile` to understand what is happening in the `example` rule.
29
30 <!--
31
32 # Desinstall
33
34 All the commands are typed as root.
35
36 Clean all of cabal and the installed packages:
37
38 - Downloald <https://gist.githubusercontent.com/simonmichael/1185421/raw/7b5da412da62dadd204b9e41ccd9639097d2178e/gistfile1.sh>
39 - Type
40 source gistfile1.sh
41
42 - Type
43 ghc-pkg-reset
44
45 Completely remove pandoc:
46
47 apt-get purge pandoc
48
49 Uninstall pip:
50
51 python -m pip uninstall pip
52 -->
53
54 # Overview
55
11 56 *The Generating Documents (Basic) Using Markdown User Manual outlines *The Generating Documents (Basic) Using Markdown User Manual outlines
12 57 the objectives, requirements, and needs to be addressed when training the objectives, requirements, and needs to be addressed when training
13 58 users on how to generate a PDF, HTML, or ODT document using markdown users on how to generate a PDF, HTML, or ODT document using markdown
 
... ... files and in online discussion forums.
23 68
24 69 Markdown text is written and stored in plaintext file with a markdown extension (e.g. .md). Using a separate markdown application capable of processing markdown (we will be using Pandoc), it takes the markdown formatted text and converts it to HTML. The HTML file can then be viewable in a web browser or then converted to another file format, like PDF. Markdown text is written and stored in plaintext file with a markdown extension (e.g. .md). Using a separate markdown application capable of processing markdown (we will be using Pandoc), it takes the markdown formatted text and converts it to HTML. The HTML file can then be viewable in a web browser or then converted to another file format, like PDF.
25 70
26 ![Figure 1.1: Markdown text file is converted and displayed in a web browser](../notes/img/markdownproc.png){ height=50% }
27
71 ![Figure 1.1: Markdown text file is converted and displayed in a web browser](markdownproc.png){ height=50% }
28 72
29 73
30 74 # Requirements # Requirements
 
... ... NOTE: Upon opening your terminal, you may see username@hostname:~$. You want you
60 104
61 105 Then enter your password. You should see something like this: Then enter your password. You should see something like this:
62 106
63 ![Terminal Root User](../notes/img/rootuser.png)\
107 ![Terminal Root User](rootuser.png)\
64 108
65 109 2) Install [Make](https://gnu.org/software/make/manual/make.html) 2) Install [Make](https://gnu.org/software/make/manual/make.html)
66 110 In your terminal, type (as root): `apt-get update` In your terminal, type (as root): `apt-get update`
 
... ... then type: `apt-get install build-essential`
79 123 In your terminal type (as root): `apt-get install python3-pip` In your terminal type (as root): `apt-get install python3-pip`
80 124
81 125 5) Install [Pandoc](https://pandoc.org) 5) Install [Pandoc](https://pandoc.org)
82 * Download [[pandoc-2.9.1.1-1-amd64.deb]{.underline}](https://github.com/jgm/pandoc/releases/download/2.9.1.1/pandoc-2.9.1.1-1-amd64.deb) from <https://github.com/jgm/pandoc/releases/tag/2.9.1.1>
83 * From your terminal navigate to location of the downloaded Pandoc folder (most likely the downloads folder) and type: `dpkg -i pandoc-2.9.1.1-1-amd64.deb`
126 * Download [[pandoc-2.9.2.1-amd64.deb]](https://github.com/jgm/pandoc/releases/download/2.9.1.1/pandoc-2.9.2.1-amd64.deb) (or higher) from <https://github.com/jgm/pandoc/releases/tag/2.9.1.1>
127 * From your terminal navigate to location of the downloaded Pandoc folder (most likely the downloads folder) and type: `dpkg -i pandoc-2.9.2.1-amd64.deb`
128
84 129
85 130 6) Install [pandoc-include-code](https://github.com/owickstrom/pandoc-include-code) filter 6) Install [pandoc-include-code](https://github.com/owickstrom/pandoc-include-code) filter
86 131 * In your terminal (as normal user) type: `cabal update` * In your terminal (as normal user) type: `cabal update`
 
... ... In your terminal type (as root): `apt-get install python3-pip`
90 135
91 136 NOTE: To run terminal as a normal user, type: `su - username` where "username" is your username. You should see something like this: NOTE: To run terminal as a normal user, type: `su - username` where "username" is your username. You should see something like this:
92 137
93 ![Terminal Normal User](../notes/img/normaluser.png)\
138 ![Terminal Normal User](normaluser.png)\
94 139
95 140 * Then type: `cabal install pandoc-types` * Then type: `cabal install pandoc-types`
96 141 * Go to <https://github.com/owickstrom/pandoc-include-code> and download the repository by clicking "Download ZIP" and extract the folder * Go to <https://github.com/owickstrom/pandoc-include-code> and download the repository by clicking "Download ZIP" and extract the folder
 
... ... Type: `git clone https://github.com/poonamveeral/GeneralRepo`
127 172 14) Testing Pandoc 14) Testing Pandoc
128 173 * In your terminal, navigate to Course/install * In your terminal, navigate to Course/install
129 174 * In your terminal type: `pandoc test_pandoc.md -o test_pandoc.html` * In your terminal type: `pandoc test_pandoc.md -o test_pandoc.html`
130 * In the install folder, you should see a file called "test_pandoc.html"
175 * In the install folder, you should see a file called "test_pandoc.html" containing
176 ```{html}
177 <p>I’m a test for pandoc.</p>
178 ```
131 179
132 180 15) Testing pandoc-numbering 15) Testing pandoc-numbering
133 181 * In the same install folder, type: * In the same install folder, type:
 
... ... Type: `git clone https://github.com/poonamveeral/GeneralRepo`
136 184
137 185 * If you're receiving errors, in your terminal, type: * If you're receiving errors, in your terminal, type:
138 186 `export PATH=$PATH:/home/username/.local/bin` `export PATH=$PATH:/home/username/.local/bin`
139 * In the install folder, you should see a file called "test_pandoc-numbering.html"
187 * In the install folder, you should see a file called "test_pandoc-numbering.html" containing
188
189 ```{html}
190 <p><span id="exercise:1" class="pandoc-numbering-text exercise"><strong>Exercise 1</strong> <em>(The first exercise)</em></span></p>
191 <p><span id="exercise:2" class="pandoc-numbering-text exercise"><strong>Exercise 2</strong> <em>(The second exercise)</em></span></p>
140 192
141 193 16) Test pandoc-citeproc 16) Test pandoc-citeproc
142 194 * In the same install folder, type: * In the same install folder, type:
143 195
144 196 `pandoc --filter pandoc-citeproc test_pandoc-citeproc.md -o test_pandoc-citeproc.html` `pandoc --filter pandoc-citeproc test_pandoc-citeproc.md -o test_pandoc-citeproc.html`
145 197
146 * In the install folder, you should see a file called
147 "test_pandoc-citeproc.html"
198 * In the install folder, you should see a file called "test_pandoc-citeproc.html" containing
199
200 ```{html}
201 <p><span class="citation" data-cites="item1">(Doe 2005)</span></p>
202 <h1 class="unnumbered" id="references" class="unnumbered">References</h1>
203 <div id="refs" class="references hanging-indent" role="doc-bibliography">
204 <div id="ref-item1" role="doc-biblioentry">
205 <p>Doe, John. 2005. <em>First Book</em>.</p>
206 </div>
207 </div>
208 ```
148 209
149 210 17) Test pandoc-include-code 17) Test pandoc-include-code
150 211 * In the same install folder, type: * In the same install folder, type:
151 212 `pandoc --filter pandoc-include-code -o test_pandoc-include-code.pdf test_pandoc-include-code.md` `pandoc --filter pandoc-include-code -o test_pandoc-include-code.pdf test_pandoc-include-code.md`
152 * In the install folder, you should see a file called "test_pandoc-citeproc.html"
213 * In the install folder, you should see a file called "test_pandoc-include-code.html" containing
214
215 ```{html}
216 <p>Here is some code:</p>
217 <div class="sourceCode" id="cb1"><pre class="sourceCode md"><code class="sourceCode markdown"><span id="cb1-1"><a href="#cb1-1"></a>I&#39;m a test for pandoc. </span></code></pre></div>
218 ```
153 219
154 220 If you're receiving "Could not find executable pandoc-include-code" If you're receiving "Could not find executable pandoc-include-code"
155 221
 
... ... Follow these steps to learn how to create a simple markdown document utilizing b
165 231
166 232 To start off, you're going to need a folder structure set up like this: To start off, you're going to need a folder structure set up like this:
167 233
168 ![Folder Structure](../notes/img/folderstructure.png)\
234 ![Folder Structure](folderstructure.png)\
169 235
170 236
171 237 If you completed number 13 from 2.2 Software Requirements skip step 2. If not, continue on. If you completed number 13 from 2.2 Software Requirements skip step 2. If not, continue on.
 
... ... pandoc --toc --filter pandoc-numbering --filter pandoc-citeproc --filter pandoc-
256 322 --top-level-division=chapter -M date="$(LANG=en_us_88591 date '+%B %e, %Y (%r)')" \ --top-level-division=chapter -M date="$(LANG=en_us_88591 date '+%B %e, %Y (%r)')" \
257 323 --css=style/style.css --toc-depth=1 --self-contained --default-image-extension=svg \ --css=style/style.css --toc-depth=1 --self-contained --default-image-extension=svg \
258 324 -o example.html example.md -o example.html example.md
259 ```
325 ```
260 326
261 327 where "style.css" is the name of your css file. where "style.css" is the name of your css file.
262 328
File notes/Makefile changed (mode: 100644) (index 486777c..0fe6517)
... ... MAKEFLAGS:= -j
13 13 # Maximize parallel execution whenever possible # Maximize parallel execution whenever possible
14 14 OPTIONSPANDOC:= --toc --filter pandoc-numbering --filter pandoc-citeproc --filter pandoc-include-code --top-level-division=chapter -M date="$$(LANG=en_us_88591 date '+%B %e, %Y (%r)')" --lua-filter filters/default-code-class.lua -M default-code-class=sqlmysql OPTIONSPANDOC:= --toc --filter pandoc-numbering --filter pandoc-citeproc --filter pandoc-include-code --top-level-division=chapter -M date="$$(LANG=en_us_88591 date '+%B %e, %Y (%r)')" --lua-filter filters/default-code-class.lua -M default-code-class=sqlmysql
15 15 # Options common to all invokations of pandoc. Cf https://pandoc.org/MANUAL.html to understand them. # Options common to all invokations of pandoc. Cf https://pandoc.org/MANUAL.html to understand them.
16 # Option
17 # --indented-code-classes=.sqlmysql,.numberLines
18 # works only for indented code, not fenced one (i.e., ~~~ or ``` are not impacted).
16 OPTIONSPANDOCODT:= $(OPTIONSPANDOC) --default-image-extension=svg
17 OPTIONSPANDOCHTML:= $(OPTIONSPANDOC) --css=style/style.css --toc-depth=1 --self-contained --default-image-extension=svg
18 OPTIONSPANDOCPDF:= $(OPTIONPANDOC) --pdf-engine=xelatex --pdf-engine-opt=-shell-escape -V links-as-notes --default-image-extension=pdf
19 # Options for (respectively) the odt, html and pdf outputs.
19 20 .DEFAULT_GOAL:= all .DEFAULT_GOAL:= all
20 21 # By default, we construct all the files. # By default, we construct all the files.
21 22 FIG_FOLDER = fig/*/ FIG_FOLDER = fig/*/
 
... ... $(FIG_PDF): $(FIG_SOURCE)
58 59 # Rule to compile to html # Rule to compile to html
59 60
60 61 html: lectures_notes.md html: lectures_notes.md
61 pandoc $(OPTIONSPANDOC) --css=style/style.css --toc-depth=1 --self-contained --default-image-extension=svg -o lectures_notes.html $<
62 pandoc $(OPTIONSPANDOCHTML) -o lectures_notes.html $<
62 63
63 64
64 65 # Rule to compile to odt # Rule to compile to odt
65 66
66 67 odt: lectures_notes.md odt: lectures_notes.md
67 pandoc $(OPTIONSPANDOC) --default-image-extension=svg -o lectures_notes.odt $<
68 pandoc $(OPTIONSPANDOCODT) -o lectures_notes.odt $<
68 69
69 70
70 71 # Rule to compile to pdf # Rule to compile to pdf
71 72
72 73 pdf: lectures_notes.md pdf: lectures_notes.md
73 pandoc $(OPTIONSPANDOC) --pdf-engine=xelatex --pdf-engine-opt=-shell-escape -V links-as-notes --default-image-extension=pdf -o lectures_notes.pdf $<
74 pandoc $(OPTIONSPANDOCPDF) -o lectures_notes.pdf $<
74 75
75 76
76 77 # Rule to compile to mediawiki # Rule to compile to mediawiki
78 # This rule is not tested nor used.
77 79
78 mediawiki: lectures_notes.md
79 pandoc $(OPTIONSPANDOC) --default-image-extension=svg --to mediawiki -o lectures_notes.mw $<
80 #mediawiki: lectures_notes.md
81 # pandoc $(OPTIONSPANDOC) --default-image-extension=svg --to mediawiki -o lectures_notes.mw $<
80 82
81 83
82 84 ### ###
 
... ... example: example.md
90 92 pdf2svg fig/misc/schema_design.pdf fig/misc/schema_design.svg pdf2svg fig/misc/schema_design.pdf fig/misc/schema_design.svg
91 93 pdf2svg fig/rel_mod/actor.pdf fig/rel_mod/actor.svg pdf2svg fig/rel_mod/actor.pdf fig/rel_mod/actor.svg
92 94 pdf2svg fig/uml/hand.pdf fig/uml/hand.svg pdf2svg fig/uml/hand.pdf fig/uml/hand.svg
93 pandoc $(OPTIONSPANDOC) --default-image-extension=svg --css=style/style.css --toc-depth=1 --self-contained -o example.html $<
94 pandoc $(OPTIONSPANDOC) --default-image-extension=svg -o example.odt $<
95 pandoc $(OPTIONSPANDOC) --pdf-engine=xelatex --pdf-engine-opt=-shell-escape -V links-as-notes --default-image-extension=pdf -o example.pdf $<
95 pandoc $(OPTIONSPANDOCHTML) -o example.html $<
96 pandoc $(OPTIONSPANDOCODT) -o example.odt $<
97 pandoc $(OPTIONSPANDOCPDF) -o example.pdf $<
96 98
97 99 ### ###
98 100 # Rule to compile a temporary file, for testing purposes # Rule to compile a temporary file, for testing purposes
99 101 ### ###
100 102
101 103 temp: temp.md temp: temp.md
102 pandoc $(OPTIONSPANDOC) --default-image-extension=svg --css=style/style.css --toc-depth=1 --self-contained -o temp.html $<
103 pandoc $(OPTIONSPANDOC) --default-image-extension=svg -o temp.odt $<
104 pandoc $(OPTIONSPANDOC) --pdf-engine=xelatex --pdf-engine-opt=-shell-escape -V links-as-notes --default-image-extension=pdf -o temp.pdf $<
104 pandoc $(OPTIONSPANDOCHTML) -o temp.html $<
105 pandoc $(OPTIONSPANDOCODT) -o temp.odt $<
106 pandoc $(OPTIONSPANDOCPDF) -o temp.pdf $<
105 107
106 108 # "Phony" rule to compile all three versions (html, odt, pdf) of the document and the "auxiliary" files (readme, contrib, licence and known_bugs, instalation guides). # "Phony" rule to compile all three versions (html, odt, pdf) of the document and the "auxiliary" files (readme, contrib, licence and known_bugs, instalation guides).
107 109
Hints:
Before first commit, do not forget to setup your git environment:
git config --global user.name "your_name_here"
git config --global user.email "your@email_here"

Clone this repository using HTTP(S):
git clone https://rocketgit.com/user/caubert/CSCI_3410

Clone this repository using ssh (do not forget to upload a key first):
git clone ssh://rocketgit@ssh.rocketgit.com/user/caubert/CSCI_3410

Clone this repository using git:
git clone git://git.rocketgit.com/user/caubert/CSCI_3410

You are allowed to anonymously push to this repository.
This means that your pushed commits will automatically be transformed into a merge request:
... clone the repository ...
... make some changes and some commits ...
git push origin main