Slashdot Mirror
A Powerful, but Minimal Document Markup Language?
demi asks: "Okay, I'm looking for markup language to keep documentation in. The primary features I'm looking for is power--for example, I want tables to be at least as easy to describe as they are in HTML, and have similar power; output-independence--I want it to produce good-looking HTML and good-looking printed output, and I don't want to fiddle with typesetting at all; and I want it to be minimal--in particular, I don't want to have to markup paragraphs, these should be recognized in the same way POD or LaTeX does. POD is not powerful enough (no tables, headers, etc.). LaTeX is too oriented toward presentation, DocBook XML and SGML require too much markup, and Texinfo is really the same deal. I know I could roll my own but I'm looking for something standard-ish. My documentation will be focused on policies and procedures. Any suggestions?"
Why not go for some sane subset of XHTML? Since you have the ability to specify the markup yourself, you can choose what features of XHTML you want to include. That way you get the benefits of having half a jillion tools that already know how to work with your chosen format.
Since it is XML you can perform transforms on it that you need using XSL. One stylesheet for display, a second stylsheet for printing. You could use the XHTML dtd as a starting point, and just start cutting stuff out. The nice thing with starting with an existing format, is that somebody else has done a lot of the hard work already.
When I want your opinion I will beat it out of you.
Demi, you have some seriously conflicting requirements here:
However:
What you are asking for is what every user wants: "I need something that has all the features I want, but none of the features I don't want." It must be powerful -- but don't have anything unnecessary. Those things are in conflict.
Judging from some of your specifics, you sound very knowledgable on the subject of markup languages. It sounds like you are just sick of fiddling around with some of the more complex ones. You may also be the kind of person who winces when they think of the HTML produced by various office products. If my guess is correct, I suggest that you either: Acknowledge that nothing is perfect and simply open MS Word or OpenOffice and force yourself to accept them, or deal with the overcomplexity of the products you mentioned. I suppose a third possibility is to roll your own front-end for one of them.
Good Luck.
Pretty much. Get some good XML documentation and make up your own markup to your own standards. It's stupidly easy to get working and the learning curve for XML is about as quick as anything even remotely technical out there.
Also, using something you made up yourself will let you customize it faster when you figure out that your specs contradicted each other or some other normal technical hurdle comes up.