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
Either search through the myriad of home-grown document markups yourself, or write something you like. Despite what you may believe, slashdot is still not freshmeat, nor is it google.
We aren't mind-readers either, but based on your request, it sounds like you won't be happy with anything, so you'd better start coding.
That's my suggestion.
pb Reply or e-mail; don't vaguely moderate.
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
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.
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.
take a look at simplified docbook. Here are some good DocBook editors
Consensus is good, but informed dictatorship is better
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.
ReSTructured Text and DocUtils
I can not emphasize this enough: use ReST and DocUtils. I've been doing technical publishing to PDF using it, and have been delighted all the way through.
ReST is output to XML which then flows through a proprietary XSL:FO to become PDF using XEP. (Whee! TLAs!)
ReST is plaintext. It's exactly the sort of thing you'd do in plain ol' email to *emphasize* a point or `show a link`_.
It does sections, sidebars, classes, everything you need for probably 95% of the technical documentation out there, and does it all using such ordinary tools.
There are some ReST-supporting wikis, too, which can be used in a similar workflow.
Keep you eye on it. ReST is about to hit critical mass.
_`like this link.`
ReSTructured Text and DocUtils
--
Don't like it? Respond with words, not karma.
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.
sed /' >destfile.html
kprinter -j none --nodialog destfile.html
If you want PDFs instead of hardcopy, use CUPS and add "-P nameofPDFqueue".
Got time? Spend some of it coding or testing