November 27th, 2009
You’ve heard it before but it’s worth mentioning again - you have to properly document you code! Programmers realized this back in the 1960s when the first industrial programming languages were defined, they came up with something called “comment lines”. For 27 years this was apparently considered enough, but in 1993 the first documentation generator was created by Eric Artzt, called Autoduck. Two years later, in 1995, a more commonly known documentation generator was released by Sun Microsystems, called Javadoc. In the year 2000 a similar generator was created by Joshua Eichorn for PHP, called the phpDocumentor and it’s this documentation generator that is the reason why I’m writing this post.
I’ve been using phpDocumentor for quite some time now but only to parse my classes to get an overview. Now I’m building a framework. I soon realized that writing a tutorial for each class wasn’t what I wanted. It’s always good with examples but it doesn’t show how a bunch of classes work together to solve a larger problem. I want to collect all documentation in one place so it’s impractical to write tutorials stored in some other place. So, for the first time I decided I’d take a look at the possibility to use external documentation with phpDocumentor.
DocBook “provides a system for writing structured documents using SGML or XML”, as stated in the preface in the DocBook documentation. It’s used in development projects like PHP and KDE. Although the PEAR manual states that DocBook should be used, nothing is said about the document type and no example is given. Instead, I found an short example in the phpDocumentor quickstart document. A more elementary example than that is hard to find, but if you combine that with the documentation about how you create a reference page in the DocBook documentation you’ll understand what you are doing. You don’t have to use the <refentry> top-level element but it is recommended if your code may become part of PEAR.
Since the phpDocumentor parses the DocBook file you can use some of the phpDocumentor syntax in your external documentation. It’s mainly two tags that you’ll use in your external documentation, and that’s the {@id} and {@toc} tags. The {@link} may also be useful to link between documents. There’s no need for me to dig any deeper in this, you can read a great tutorial about how to write tutorials for PHP at the phpDocumentor site.
Good luck!
Tags: DocBook, documentation, Programming
Posted in Programming | No Comments »
January 11th, 2009
Since this can be a sensitive subject I guess I’ll start to say that this is a post of a more philosophic nature. Many religions contains wise formulations about common sense that’s being abused and used as a front to gain power at many levels. With that said - let’s go…
In the beginning the religion was used to explain things that couldn’t be described with the knowledge at that point. This kind of religion is often called animism or shamanism and reaches back to the hunter-gatherers, that’s more than 15,000 years ago. The two are very similar in that they both states that the world we live in have spirits, they differ in what role the spirits have though.
The religion then evolved into what’s called polytheism. It means that you believe in multiple gods and you surely have heard of both the Roman mythology and the Greek mythology. Now the stories got a more human form but does not distinguish good from bad, both heroes and gods shows both good and bad sides. The mythologies developed when societies were founded and villages started to grow into cities. The human was no longer considered to be a part of nature but superior to it and thus the respect for animals, plants and natural forces decreased. When living in a society the need for rules and laws grows with the size of the society. As a result the religions we know as of today was formed containing rules for how to treat your neighbours.
During the time when, among others, Christianity was formed and documented or translated, politics and rhetorics had started to grow of importance with the Roman Empire. These new religions was a perfect target for greedy people to influence and inflict the new documents with hidden messages or just state that a certain interpretation is the correct one. There are many examples of how this is abused and how it changes over time. I do not maintain that the “modern” religions was the first ones to be used to gain power, I’m stating that they resulted in an opportunity to spread the message to a larger crowd.
In my opinion it’s obvious that the opportunity to power exists since Christianity ended up as being centrally controlled by the Holy See. A power that in many cases have lead to megalomania with disastrous, and sometimes amusing, results. A recent historic happening is the discovering of the Dead Sea scrolls, where you can get a good picture of the power that the Holy See can inflict.
Religious texts is often studied according to rhetorical principals that for reasons may not be used in modern law practice. This may, or may not, be a good thing, depends on the text and its message, but it’s something that you have to keep in mind when reading. After all, the purpose of the modern religions is to achieve compassion between people, a fantastic thing ruined by false interpretation of the word - call it “free will” if you like. I call it greed.
Posted in Philosophy, Politics, Religion | No Comments »
December 20th, 2008
It’s interesting how countries can have so different regulations. This for example would not be able to do in Sweden:
On the other hand there is a logical explanation. During the winter snow and ice will build up on the blades and can be thrown away as the wind increases. You don’t want to take a hit…
Posted in General, Politics | No Comments »