Hacker News Reader

Comment by Carpetsmoker | Hacker News Reader

Back when I started using FreeBSD in the 4.x days the handbook was an extremely valuable and useful resource. For many years I touted it as a good advantage of FreeBSD over Linux, whose documentation was (and to some degree, still is) quite poor and scattered over many places.

I haven't used FreeBSD in quite a few years, but I'm sad to hear it's no longer what it was :-(

Looking at the source it looks like they went from the obscure SGML to ... some obscure XML. The entire thing looks horrible and a pain to edit, so I'm not surprised that few people contribute (including the OP).

View on HN

It's written in DocBook, which is hardly obscure.

No, but it is horribly verbose and a pain to work with. I personally find the flow of writing to be constantly interrupted with the demand to mark everything up just so, and for very technical documents with a lot of markup, the markup can dwarf the content several times over!

While they are less powerful, markdown, restructured text and other simpler markup languages are much more productive to work with. They are easier for beginners to understand, and the markup is sufficiently lightweight for most of the common cases that it doesn't interrupt your train of thought while trying to think about how to best describe complex technical details.

An alternative to retext is Mallard. It's pretty easy to use, see http://projectmallard.org/. It's used within GNOME for the documentation.

Thanks, I took a quick look. However, it appears to be XML-based markup not too different from HTML or DocBook. So I don't see this having the benefits which lightweight markup provides. It has all of the same disadvantages of HTML and DocBook in terms of the markup verbosity from what I can tell.

Which isn't to say it's not very good at what it does, just that I can't see a compelling difference over DocBook or HTML.

The nice thing about DocBook is that, because of how strictly structured it is, there are visual editors for it that provide experience far superior to anything that can be had with Markdown etc, especially for large quantities of documentation. I would dare say that it's also easier for beginners that way, too.

Long time no see :)

Reply on news.ycombinator.com