hoglet - hoglet - the easy way to write documentation

hoglet - the easy way to write documentation

Everyone knows that writing documentation for software (or anything) is a tedious job, especially when it is written in HTML. It's error prone, time consuming and difficult to ensure consistency throughout the documentation tree.

hoglet aims to make the writing of documentation (especially software documentation) easier by allowing a text document to be "marked up" in a similar way to HTML/XML. The hoglet syntax is simpler, more intuitive than HTML/XML and is easy to learn.

For example, you want to include some java source code in your documentation, you'd like it to be nicely formatted (correctly indented), maybe have line numbers included and highlight java keywords. Now to do this in HTML is just hell and would take forever, but with hoglet it's as simple as:

[java linenums=y]
public class MyClass
{

   public static void main (String argv[])
   {

       System.out.println ("Hello World");

   }

}
[java]

Which, when run through hoglet, produces:

 1:  public class MyClass
 2:  {
 3:  
 4:     public static void main (String argv[])
 5:     {
 6:  
 7:         System.out.println ("Hello World");
 8:  
 9:     }
10:  
11:  }

hoglet features

hoglet has the following features:

Easily extensible. You can easily define your own tags, those tags map to a TagHandler which is used to produce/process the content.
Simple, consistent and configurable syntax. In hoglet the verbosity of XML markup is removed. Tag definition is simple and easy. The start and end tag are the same, i.e. [java] (although [/java] can be used for the end tag if required). End tags are optional, if the start tag is closed with a /.
Each tag can have a number of options associated with it. These are basically name/value pairs, however if no name is provided then the name is defaulted to an integer (starting at 1). i.e.
```
[javadoc hoglet,org.hoglet.TagHandler/] 
```
means there are 2 options numbered 1 and 2.

Tags can be nested, i.e.

[java][javadoc java,java.lang.System]System[javadoc].out.println ("Hello World");[java]

The delimiters in hoglet can be configured. For example it is possible to configure hoglet to have tag definitions such as: *java%java#java.lang.System&! Not that this is recommended!
Can be integrated easily with other markup languages, i.e. HTML. This is important since it's not always desirable to solely rely on hoglet tags to markup the document.
Tag Handlers have access to the child tags within the tag they are processing. This allows them to process the tags in the way they see fit. It is also possible for handlers to get access to the tags' parent tag (if present)

See also: Tags, Core Tag Handlers.

How does hoglet compare to a wiki?

Wikis are great for just writing text, the trouble is if you want to do anything more than just regular expression replacements then wikis don't really cut it. Also, wikis tend to have the formatting tied closely to the overall wiki architecture (not always however). Wiki formatters also tend to have confused syntax that isn't easily extensible.

How does hoglet compare to Radeox

I looked into External site, opens in new window

Radeox early on and it seemed (at first glance) to do everything I needed. Trouble is, as I examined further it seemed to be dependent upon regular expressions and had a fixed format as a result. However, I wanted something that was flexible enough to integrate with regular HTML and could be configured to integrate into other text files.

Limitations

Of course hoglet also has a number of limitations, they are:

It's not possible to have the a tag nested within itself, i.e.
```
[java][java][java][java]
```
would NOT lead to nesting since, for simplicity, hoglet end tags are the same as start tags.