Convert project to Markdown

[DewaldDeJager]

As you have seen, I have been helping out with minor typo fixes and general enhancements. My observations:

• The source files are extremely difficult to read
• The source code examples are littered with HTML
• It is easy to make a typo because there is so much going on

Would you consider moving the book to something like Markdown? You could then convert this to an HTML site using something like Hugo. The source will be much easier to read and you can do some really powerful stuff such as add syntax highlighting so that you do not manually need to add CSS classes to the elements.

GitHub uses Markdown in issues, comments, PRs, etc. An example of converting the first part of the first chapter:

---

Encapsulation

As we know, Java is an object-oriented language, and all code must be inside a class.

class MyClass {
    String myField = "you";
    void myMethod() {
        System.out.println("Hi " + myField);
    }
}

Therefore, we have to create an object to use it:

MyClass myClass = new MyClass();
myClass.myField = "James";
myClass.myMethod();

One important concept in object-oriented programming languages is encapsulation, the ability to hide or protect an object's data.

Most of the time, when someone talks about encapsulation most people tend to think about private variables and public getters and setters and how overkilling this is, but actually, encapsulation is more than that, and it's helpful to create high-quality designs.

Let's consider the previous example.

First of all, it's good to hide as much as possible the internal implementation of a class. The reason, mitigate the impact of change.

For example, what if myField changes its type from String to int?

myClass.myField = 1;

If we were using this attribute in fifty classes, we would have to make fifty changes in our program.

But if we hide the attribute and use a setter method instead, we could avoid the fifty changes:

// Hiding the attr to the outside world with the private keyword
private int myField = 0;

void setMyField(String val) { // Still accepting a String
    try {
        myField = Integer.parseInt(val);
    } catch(NumberFormatException e) {
        myField = 0;
    }
}

You implement this attribute hiding by using access modifiers.

Java supports four access modifiers:

• public
• private
• protected
• default (when no modifier is specified)

You can apply these modifiers to classes, attributes and methods according to the following table:

	Class/Interface	Class	Class	Interface	Interface
		Attrib	Method	Attrib	Method
public	X	X	X	X	X
private		X	X
protected		X	X
default	X	X	X	X	X

---

As you can see, it looks more or less the same. The table support isn't excellent but you can actually embed HTML in Markdown.

What are your thoughts on this suggestion? If you would like help working on a proof of concept, let me know.

[eh3rrera]

Thanks, @DewaldDeJager.

Yes, on retrospective, it would have been better to use Markdown, but my workflow was different when I wrote the book (wow, almost 4 years ago), and at the beginning, I wasn't planning to release the book for free.

I'm concern about the time (effort) it would require to moving the book to Markdown/Hugo. I'd be great, but I don't have much time and I don't know if it's worth the effort (or somebody else's).