Site Map - skip to main content

Hacker Public Radio

Your ideas, projects, opinions - podcasted.

New episodes every weekday Monday through Friday.
This page was generated by The HPR Robot at


hpr2378 :: Why Docbook?

Klaatu talks about why Docbook is the greatest

<< First, < Previous, , Latest >>

Hosted by Klaatu on 2017-09-13 is flagged as Clean and is released under a CC-BY-SA license.
xml, docbook, writing. 10.
The show is available on the Internet Archive at: https://archive.org/details/hpr2378

Listen in ogg, spx, or mp3 format. Play now:

Duration: 00:40:05

general.

What's so great about Docbook, any way? Glad you asked.


Comments

Subscribe to the comments RSS feed.

Comment #1 posted on 2017-09-13 02:36:01 by Mike Ray

kramdown

I completely agree that it is impossible to write anything complex in markdown without resorting to HTML tags.

For me it's putting anchor tags around headings to provide in-page links.

But you should take a look at kramdown. Debian install:

apt-get install ruby-kramdown

Has stuff that markdown doesn't, like tables, stuff like id and class attribs for css etc.

And auto-generation of tables-of-contents

Comment #2 posted on 2017-09-13 08:17:05 by Florian

whats so hard about code in a list?

7 spaces makes sense, it's 3 for everything belonging to the same point on you list plus 4 for the code, see experiments on https://gist.github.com/0xf10e/91f021b82a2bc4586b235e8f56c31f92 (Yeah, "github-flavored" markdown, but it's a common dialect these days)

I still prefer three backticks, but I come from trac-wiki syntax via ReStructuredText to markdown and using single backticks for inline monospace but {{{ Code here }}} in track still annoys me.

I understand the additional value semantic markup has but in many cases it's nice but not necessary.

-- sysadmin who never broke out into HTML in rst or markdown …

Comment #3 posted on 2017-09-15 10:33:15 by Klaatu

Kramdown

Had not heard of kramdown. I'll take a look at it, for kicks, because it sounds pretty good.

Comment #4 posted on 2017-09-15 10:42:29 by Klaatu

github markdown

I have found that Guthub markdown is a heck of a lot better than markdown. In fact, it's so significantly better that I don't see why it's not merged into markdown yet, except that as far as I can tell markdown proper is unmaintained.

The existance of Github-markdown reinforces my point: markdown needed fixing.

But I agree; sometimes docbook is overkill and [github] markdown is a better choice. If I didn't say that in this or my previous episode, I did mean to, but maybe I was blinded by docbook passion.

Comment #5 posted on 2017-10-06 06:22:55 by clacke

Markdown

Markdown the specification and Markdown the Perl script came out in March 2004 [0] and were last updated in December [1] the same year. I think it's fair to assume that John Gruber considers it perfected for the use case he had in mind.

Any further evolution of the language is now up to anyone who cares to implement a processor. There is nobody maintaining the language itself.

I absolutely agree that it is pretty useless for anything bigger than a small README without resorting to HTML, but I don't think that's a big problem, and I don't think it makes Markdown meaningless. I used to write documentation in HTML, and I think replacing 95% of the HTML with Markdown makes it much nicer to work with.

I wouldn't write a book in HTML, but there are those that have, using CSS3 print styling!

Before hearing your argument, If I were hypothetically to ever write a book, I would likely not even consider anything but LaTeX. But thanks to your episode, and you simply reminding me that DocBook is still out there, I might spare DocBook a look first. It was a good episode and your points are all valid. Thanks!

[0] https://daringfireball.net/2004/03/introducing_markdown

[1] https://daringfireball.net/projects/markdown/

Comment #6 posted on 2017-10-06 06:08:18 by clacke

SGML

You seemed unclear on what SGML is, so here's a quick summary:

SGML, to tell a simplifying lie, is the idea of using tag names enclosed in less-than and greater-than characters to mark up text. The original DocBook is one application, HTML is another.

XML is a further evolution of SGML, which both constrains and extends SGML to enable new ways of defining and working with applications of the format.

The counterpart of XML Schema in SGML is the DTD, the Document Type Definition, and the counterpart of XSL is DSSSL, which is a form of Scheme (yay!).

Comment #7 posted on 2017-10-17 07:13:04 by Bob Jonkman

Referenced your podcast in our NonProfit SysAdmin meeting

I conveniently listened to your podcast just before going to the KWNPSA (Kitchener Waterloo NonProfit SysAdmin) meeting on "Markup Languages and Note Taking", where I took notes for the meeting. I added the podcast as one of the resources.

Thanx for telling us about DocBook and some other markup languages!

--Bob.

Comment #8 posted on 2017-10-17 07:17:24 by Bob Jonkman

Should have provided a link to the KWNPSA meeting

I should have provided a link to the meeting notes for our KWNPSA meeting on Markup Languages and Note Taking:

https://sobac.com/wiki/Markup_Languages_and_Note_Taking/Meeting_Notes_2017-10-16

Maybe the HPR comment daemons can just append that link to my previous comment...

--Bob.

Comment #9 posted on 2017-11-07 05:32:42 by Klaatu

KWNPSA

I took a look at the page, Bob. Good stuff! One addition - there's a missing entry in your text editors section: GNU Emacs.

Probably just an oversight.

Comment #10 posted on 2018-12-22 04:52:40 by Klaatu

docbook rocks

https://docbook.rocks/ Is a neat site talking about docbook and how great it is.

Leave Comment

Note to Verbose Commenters
If you can't fit everything you want to say in the comment below then you really should record a response show instead.

Note to Spammers
All comments are moderated. All links are checked by humans. We strip out all html. Feel free to record a show about yourself, or your industry, or any other topic we may find interesting. We also check shows for spam :).

Provide feedback
Your Name/Handle:
Title:
Comment:
Anti Spam Question: What does the letter P in HPR stand for?
Are you a spammer?
What is the HOST_ID for the host of this show?
What does HPR mean to you?