Merge pull request #30 from gadilashashank/master

ODXT · web-flow · commit 0ddca3c868a4 · 2018-06-12T09:14:27.000-04:00
Add chapter on ABC
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,52 +1,208 @@
 # How to contribute
 
+## Prerequisites
+
+First of all fork [this repository](https://github.com/devRant-Community/Community-Programming-Book/)
+and join this [discord server](https://discord.gg/TDut3Fq).
+
+Throughout this guide, changes to files are to be made in your personal fork
+and submitted for merging in the main repository through a pull-request (PR).
+
+Taking the above mentioned points as granted the contributing guide begins now.
+
 ## Language already complete
 
-You can change and correct the files, by forking and changing the files in the directory /book/languages/[language] in your forked repo. After you're finished make a PR from your forked repo to this repo.
+Change/correct the files present in the directory /book/languages/[language]
+where [language] is a placeholder for the language you want to change.
+
+Please refer to the "After writing the chapter" section below and make
+appropriate changes to the Summary.md file.
 
 ## Language not present
 
-You must create a new subdir on /book/languages with the name of your language
+Create an issue on the main repository(mentioned in pre-requisites) with title
+"Add Chapter on {Name of language}", assign this issue to yourself and add the
+label "Enhancement". This helps in identifying that you are writing that
+particular chapter.
 
-### Example
+Create a new sub-directory in /book/languages with the name of the language.
 
 ``` md
 /book/languages/kotlin
 ```
 
-On this subdir you must create the files
+In the sub-directory of the language add the files README.md and intro.md (Compulsory)
 
 ``` md
-readme.md
-intro.md
+/book/languages/kotlin/
+  README.md
+  intro.md
 ```
 
-The Readme.md is just to get into the next language, something like this:
+README.md is a transition from one chapter to the next. An example is given.
 
 ``` md
 # Welcome
-> This chapter has been authored by (Your name goes here)
+> This chapter has been authored by <Your name goes here>
+
 Well, next we will talk a bit about Kotlin, the new JVM language by Jetbrains.
 Kotlin is less verbose than the original JVM language Java and is now one of
 the main development languages of the Android Platfom. Let's get into it.
 ```
 
-The intro should be a bit longer, it should give you an brief look at the language. Talk about the story of language or tell from where it came. Look into the file intro.md at the repo root for inspiration.
+The intro.md should give a brief look at the language. Talk about the story of
+language or tell from where it came. Look at the file intro.md present in the
+root of the repository for inspiration.
 
-You should also add your new language to the /book/Summary.md by adding
+The contents of the chapter are to be added as separate .md files for
+each sub-chapter. An example sub-directory with sub-chapters is given.
 
 ``` md
-* [<Language>](/languages/<Language>/readme.md)
-  * [Intro](/languages/<Language>/intro.md)
+/book/languages/kotlin/
+  README.md
+  intro.md
+  <name_of_sub-chapter>.md
+```
+
+It is advised to divide the chapters into sub-chapters for better organization and
+readability. If the author decides not to do so then the entire
+contents of the chapter should be written in the intro.md file itself.
 
+### After writing the chapter
+
+After writing the chapter, an entry should be made in the Summary.md file similar
+to the one given in the example below.
+
+```md
+* [<Name of language>](languages/assembly/README.md)
+
+  * [Introduction](languages/assembly/intro.md)
+
+  * [<Name of sub-chapter>](languages/assembly/<name of file>.md)
 ```
 
-## Adding chapter
+Note that Summary.md contains the order in which various chapters and the
+sub-chapters appear in the final product, hence the entries should be made
+appropriately. Also, note that various languages in the Summary.md file appear
+in the order of creation/release.
 
-To start writing on a new chapter create a new file called [chapter].md at the root of language directory. Also you should add it to the /book/Summary.md
+For example the Summary.md file with two languages, Assembly and Python.
+
+```md
+* [Assembly](languages/assembly/README.md)
+  * [sub-chapter](languages/assembly/{name of file}.md)
+(leave a blank line)
+* [Python](languages/python/README.md)
+   * [sub-chapter 0](languages/python/{name of file}.md)
+   (leave a blank line)
+   * [sub-chapter 1](languages/python/{name of file}.md)
 
-``` md
-* [<Language>](/languages/<Language>/readme.md)
-  * [Intro](/languages/<Language>/intro.md)
-  * [<Chapter>](/languages/<Language>/<Chapter>.md)
 ```
+
+Feel free to ask for help regarding this aspect or anything in general.
+
+You may also add your details in the credits.md in a similar way as other existing entries.
+
+## Pull request and CI
+
+After finishing your work, submit a pull request (PR) for merging your changes
+into the base branch. Add  the editing team as reviewers. If the pull request
+adds a new chapter, then add the label "new-chapter".
+
+Also, close any previously opened issue(s) which are fulfilled by the
+pull request.
+
+Every pull request undergoes an automatic build process which automatically
+generates the updated book. A set of rules on the format of the content is
+defined all of which should be followed for the build to be successful.
+
+These rules are given below.
+
+* Lines should **NOT** have trailing whitespace.
+
+* *List elements*, *fenced code blocks* and *headers* should be surrounded with **blank lines**.
+
+```md
+Some sentence.
+
+* List element 1 or ## Header 1
+
+* List element 2 or ## Header 2
+
+Continuation.
+```
+
+* Each line should contain a maximum of **300** characters.
+
+* Emphasis should **NOT** be used as a header.
+
+* Use ``---`` for horizontal rules
+
+* Two top-level headers should **NOT** be present.
+
+```md
+This is wrong format
+
+# Heading 1
+
+# Heading 2
+```
+
+* Always use ATX style headers
+
+```md
+Correct:
+# ATX style H1
+
+
+Wrong:
+## Closed ATX style H2 ##
+
+Setext style H1
+===============
+```
+
+* Leave a space after hash on atx style header and after the "\*" symbol in list elements.
+
+```md
+Correct:
+# Heading
+* List element
+
+Wrong:
+#Heading
+*List element
+```
+
+For everything else the standard rules, described [here](https://github.com/markdownlint/markdownlint/blob/master/docs/RULES.md), apply.
+
+If there are any mistakes in format, the build will fail and the mistakes are
+prompted by @SkayoBot to be corrected. An example prompt is given.
+
+"------------------Prompt Begins------------
+
+Checks failed - mdlint output:
+
+```md
+devRant-Community/Community-Programming-Book/book/languages/abc/conclusion.md
+  9:3 no-space-in-links [MD039] Spaces inside link text "...aking of python-An interview ]"
+devRant-Community/Community-Programming-Book/book/languages/abc/disadvantages.md
+  9:100 no-trailing-spaces [MD009] Trailing spaces [Expected: 0; Actual: 3]
+devRant-Community/Community-Programming-Book/book/languages/abc/misc.md
+  6 no-emphasis-as-header [MD036] Emphasis used instead of a header "Function to convert given temp..."
+  37:85 no-trailing-spaces [MD009] Trailing spaces [Expected: 0; Actual: 2]
+devRant-Community/Community-Programming-Book/book/languages/assembly/advantages.md
+```
+
+Please fix these errors before merging!
+
+"-----------Prompt Ends-------------
+
+After the CI is successful please wait for the editing team to make changes
+(if any) and finally approve your work for merging. You are free to discuss
+with the concerned editor(s) about any edits made.
+
+Though this guide is extensive it need not be exhaustive. If you have any
+doubts or questions feel free to ask.
+
+Happy Contributing ! :)
diff --git a/book/SUMMARY.md b/book/SUMMARY.md
@@ -21,6 +21,22 @@
   * [Conclusion](languages/assembly/conclusion.md)
 
 
+* [ABC](languages/abc/README.md)
+
+  * [Introduction](languages/abc/intro.md)
+
+  * [History](languages/abc/history.md)
+
+  * [What it solves?](languages/abc/what_it_solves.md)
+
+  * [Advantages](languages/abc/advantages.md)
+
+  * [Disadvantages](languages/abc/disadvantages.md)
+
+  * [An Example](languages/abc/misc.md)
+
+  * [Conclusion](languages/abc/conclusion.md)
+
 * [Python](languages/python/README.md)
 
   * [Introduction](languages/python/intro.md)
@@ -37,7 +53,6 @@
 
   * [Conclusion](languages/python/conclusion.md)
 
-
 * [C#](languages/csharp/README.md)
 
   * [Introduction](languages/csharp/intro.md)
@@ -50,10 +65,9 @@
 
   * [Conclusion](languages/csharp/conclusion.md)
 
-
 * [C++](languages/cpp/README.md)
   * [Introduction](languages/cpp/intro.md)
 
 ## End
 
-* [Credits](credits.md)
+* [Credits](credits.md)
diff --git a/book/languages/abc/README.md b/book/languages/abc/README.md
@@ -0,0 +1,6 @@
+# ABC
+
+> This chapter has been authored by Gadila Shashank Reddy.
+
+Now is the chapter on ABC. We will try to understand its roots and
+how was it able to inspire Python, one of the most popular programming languages in current times.
diff --git a/book/languages/abc/advantages.md b/book/languages/abc/advantages.md
@@ -0,0 +1,16 @@
+# Advantages
+
+* Easy to learn and use and is intuitive.
+
+* Structured programming and data structuring are supported.
+
+* It has only 5 data types which are sufficient for most purposes. Others have a larger number of data types.
+
+* The code length is typically much smaller compared to other languages without compromising
+  on readability or user understanding.
+
+* Great for general purpose programming and prototyping.
+
+* There are no limitations on size of data except due to physical factors.
+
+* This language has introduced the concept of indented code blocks.
diff --git a/book/languages/abc/conclusion.md b/book/languages/abc/conclusion.md
@@ -0,0 +1,11 @@
+# A final word
+
+ABC is an excellent attempt at making programming understandable and user-friendly. It has
+introduced some terrific features which have inspired several other languages the most notable
+one being Python. Despite few design flaws it still is successful in programming more accessible and powerful.
+
+## Sources and further reading
+
+* [Making of python-An interview](https://www.artima.com/intv/pythonP.html)
+
+* [The official page of ABC](https://homepages.cwi.nl/~steven/abc/)
diff --git a/book/languages/abc/disadvantages.md b/book/languages/abc/disadvantages.md
@@ -0,0 +1,12 @@
+# Disadvantages
+
+* Some issues with syntax like uppercase for keywords.
+
+* Variables are persistent and global. Memory management thus is an issue.
+
+* It has a very monolithic design that is low-level optimizations to the code is not possible.
+
+* I/O from files was not implemented. Thus, it could not be used for reading and writing from files.
+
+* Because of the way variables were implemented it was not possible to implement temporary or
+  session specific variables without exclusively deleting them.
diff --git a/book/languages/abc/history.md b/book/languages/abc/history.md
@@ -0,0 +1,24 @@
+# History
+
+## Creation
+
+ABC was created in the early 1980s by Leo Geurts, Lambert Meertens and Steven Pemberton at
+the Centrum Wiskunde & Informatica (CWI) in the Netherlands. ABC language was developed iteratively
+with it being the fourth iteration. All the previous versions/iterations of this language were called as B.
+
+It is said that the first version of B appeared in 1969. So we can say that ABC went through a long
+phase of development and changes before it took its current form.
+
+Note that B is not a predecessor of the C programming language.
+
+## Purpose
+
+ABC was intended for teaching and prototyping purposes rather than systems programming.
+It was created to replace some older languages such as BASIC, Pascal and AWK. As it turns out ABC
+is easier to learn than BASIC but more powerful than Pascal. It's initial aims were to be:
+
+* Simple
+
+* Interactive
+
+* Structured
diff --git a/book/languages/abc/intro.md b/book/languages/abc/intro.md
@@ -0,0 +1,8 @@
+# Introduction
+
+ABC is a powerful, easy to learn and use, interactive and imperative high level
+programming language. This language was born after a lot of research on creating a programming
+language that was both powerful with respect to features and also easy to learn.
+
+It is a high level language and supports data structuring and structured programming.
+During its time, ABC was a powerful language for beginners and experts alike.
diff --git a/book/languages/abc/misc.md b/book/languages/abc/misc.md
@@ -0,0 +1,37 @@
+# An example
+
+This section is meant to illustrate a sample code in ABC and compare it with
+equivalent code in Python and C.
+
+## Function to convert given temperature from Fahrenheit to Celsius
+
+In ABC language.
+
+```ABC
+HOW TO PRINT CELSIUS FROM a:
+   PUT (a-32)*5/9 IN c
+   WRITE a, "Fahrenheit =", 2 round c, "Celsius" /
+```
+
+The same code in Python3.
+
+```Python
+def to_celsius(a):
+  c = (a-32)*5/9
+  print(a + "Fahrenheit = %.2f",c + "Celsius" )
+```
+
+And in C
+
+```C
+void to_celsius(float a)
+{
+  c = (a-32)*5/9;
+  printf("%f Fahrenheit is %.2f Celsius",a,c);
+  return;
+}
+```
+
+The purpose of this example is to illustrate two things: The similarity between ABC and
+Python and also a glimpse of how ABC is slightly easier to code in compared to C. The second point
+might not be too obvious because the example is too short to notice the differences.
diff --git a/book/languages/abc/what_it_solves.md b/book/languages/abc/what_it_solves.md
@@ -0,0 +1,7 @@
+# What it solves
+
+ABC was not designed to solve a specific purpose or problem, instead it was intended for general
+purpose programming. It was created to be easy to learn and use yet include powerful features.
+Programming in this language is relatively more intuitive and easy. It was the first language to have
+implemented indented blocks of code which has also been adopted in python. A better explanation on
+its powerful features are mentioned in the next section.
diff --git a/book/languages/assembly/README.md b/book/languages/assembly/README.md
diff --git a/book/languages/assembly/advantages.md b/book/languages/assembly/advantages.md
diff --git a/book/languages/assembly/disadvantages.md b/book/languages/assembly/disadvantages.md
diff --git a/book/languages/assembly/what_it_solves.md b/book/languages/assembly/what_it_solves.md
