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?"
I'd still suggest going with DocBook, even though it has a lot of markup. You can mostly fix that problem with a good text editor. Any decent editor will have quick-keys that makes your life much easier, and you'll benefit from all of the existing tools.
This is what you need. Outputs to HTML, Latex, XML. Easy to write, easy to read.
Forrest and XMLMind
XHTML and CSS? Really pretty powerful, once you can wrap your head around browser-independent and effective ways to use CSS.
Most wikis seem to do something like what you want - taking simple text and producing HTML from it.
My Journal
The problem with docbook isn't the complexity of the markup, but the lack of decent editors. I hate markup languages. They always manage to grow larger than the set of markups you can store in your memory for occasional use.
If I'm concentrated on developing in language X and architecture Y using technologies Q,R and T. I don't want to also have to juggle around markup language Z in order to properly document the project.
My advice would be to use XMLMind to write Docbook. It's much like Lyx in that it's a WYSIWYM editor, but it was written from the ground up to do Docbook XML. It's also not Open Source, but the basic version that handles Docbook well is freely available from the author's site.
It helps to have some knowledge of Docbook to use XMLMind, but it takes most of the work away. You can save and convert the output using the standard docbook tools that come with most Linux distros. It's not a silver bullet to this particular problem, but it sure does help a lot.
Arrogance is Confidence which lacks integrity. -- me
http://csgwww.uwaterloo.ca/sdtp/watscr.html
Try some of the simple marup in a wiki text page:
PhpWiki TextFormattingRules
I have to say, I wish slashdot would support this kind of markup. Kuro5hin has a similar 'auto-format', but PhpWiki's is more powerful.
-molo
Using your sig line to advertise for friends is lame.
Felt like mentioning YAML, just to add that missing "offtopic" to my collection. YAML is certainly as minimal as markup can get in keystroke count. It's beautiful. Unfortunately, folks use it only for data serialization so far. You'll have to write your own HTML/etc. converters in Perl or Ruby.
http://www.yaml.org/
Another approach is simply to define your own markup language. Since your needs are simple, you probably don't need to validate your documents, so an informal description of a well-formed XML document is all the design you need to do. You'll also need to write transform software that creates HTML or whatever other deviverables you're trying to create. That's easy enough to do in XSLT.
One last suggestion: if you're serious about using markup that separates content and presentation (an attitude I heartily applaud) Slashdot is probably not the best place to get advice. You're inviting criticism and trolls from people who think that TeX, or even "Plain ASCII" is all anybody really needs. Try some of the XML forums, like XML doc
I've heard very good things about txt2tags but I haven't used it myself. It's used to generate the pages of Dicas-L which hosts a famous Brazilian mailing list which sends daily computer related tips.
Gustavo.
Have a look at Markdown. It's like other text languages, but has 'fallback to HTML' easily available and is designed to be standards-nice:
http://daringfireball.net/projects/markdown/
There is also a flavour which guarantees XML-wellformedness, called xMarkdown (you can find a link to it on the Markdown list).
"Elmo knows where you live!" - The Simpsons
A wiki brings a lot to the table to facilitate documentation, and excels at cooperative documentation. We're using MediaWiki software internally with some success. Installation is not difficult (requires MySQL, PHP and Apache) and is well documented. Any web browser is used to view and / or edit documents, and the resultant HTML may be saved and viewed off-line.
Of course I want it all! Isn't that what software promises me? :)
Seriously, I don't think that something needs the huge "markup-to-content" ratio that DocBook has (<para/> for every paragraph? You've got to be kidding me.)
And maybe I should have mentioned that I also want to store structured document markup in a source-code control system, which are most powerful operating on line-oriented text files. And of course, they're all about presentation, not structure.
I do know that nothing is perfect, but it looks like others have made some great suggestions that come closer than anything I've found so far. Thanks for the response!
demi
What? You obviously haven't used LaTeX very much, have you? LaTeX is oriented precisely away from presentation - it is oriented towards describing the document's structure rather than how it should look. That's why the majority of academic papers and theses are written using LaTeX.
While HTML tools may have style as you mentioned, valid XHTML specifically separates style from presentation. Everything you mentioned above [with the exception of the "hr". I believe that to be valid.] are supposed to be in CSS, the presentation layer. XHTML is valid XML.
And just because the tools may have them, you aren't forced to use all the buttons!
Blocklevel: Practical Information Architecture
Indeed. But not everyone cares (or even knows) about that. Even on Slashdot there are a huge number of folks who didn't see the point of the LDP moving to CSS. And this is supposedly a more tech-saavy group than the general public. Setting policy with a tool that follows that policy instead of working against it is always a good thing.
Once again, to my knowledge, no XHTML tool excludes the presentational elements. You're better off using Emacs to help with DocBook XML generation. (ick!)
- I don't need to go outside, my CRT tan'll do me just fine.