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
You might consider adapting the markup used in Wikis - it's very straightforward.
WordML.
plain text. So use plain text. If you want HTML tables, use HTML. If you want a standards-based markup, use DocBook. Markup languages are as descriptive as they are for a reason.
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.
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.
rkz posts nothing but trolls. See his history for more.
Thanks to all the moderators who didn't bother following links.
I've finally had it: until slashdot gets article moderation, I am not coming back.
Did you try UML (Universal Markup Language)... because since it is universal it will cover every need and it is used by companies like Rational, who a lot of tools for it.
Yes I know this isn't what UML is but I've got Karma to burn
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/
Since AC's are popping out of the woodwork to claim I accuse falsely, the link for GNML goes to a a post on a discission blog, one that allows javascript injection. The post contains this:
< /td></tr>
<script>setTimeout("window.location = 'http://wrt.spacker.net/faq/'",1250)</script></p>
Ok, so it's not tubgirl -- I'm not exactly an expert on the subject. I suppose the picture is pretty illustrative of what folks like rkz are doing to slashdot...
Oh well, another entry in the ol enemies list, at least til he gets another account.
I've finally had it: until slashdot gets article moderation, I am not coming back.
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
and tags these days coupled with CSS. A lot of the XHTML/HTML tags are cruft left over from early HTML days, CSS eliminates a lot of the clutter. The beauty of CSS, of course, is that the way the document looks can be completely changed at any time.
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
What Is `groff'?
================
`groff' belongs to an older generation of document preparation
systems, which operate more like compilers than the more recent
interactive WYSIWYG(1) (*note What Is groff?-Footnote-1::) systems.
`groff' and its contemporary counterpart, TeX, both work using a
"batch" paradigm: The input (or "source") files are normal text files
with embedded formatting commands. These files can then be processed
by `groff' to produce a typeset document on a variety of devices.
Likewise, `groff' should not be confused with a "word processor",
since that term connotes an integrated system that includes an editor
and a text formatter. Also, many word processors follow the WYSIWYG
paradigm discussed earlier.
Although WYSIWYG systems may be easier to use, they have a number of
disadvantages compared to `troff':
* They must be used on a graphics display to work on a document.
* Most of the WYSIWYG systems are either non-free or are not very
portable.
* `troff' is firmly entrenched in all UNIX systems.
* It is difficult to have a wide range of capabilities available
within the confines of a GUI/window system.
* It is more difficult to make global changes to a document.
"GUIs normally make it simple to accomplish simple actions and
impossible to accomplish complex actions." -Doug Gwyn (22/Jun/91
in `comp.unix.wizards')
Warning: this article may contain humor, sarcasm, parody, and perhaps even irony. Read at your own risk.
This could be worth a look.
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.
... If you opt to write a frontend for another markup language. I'm serious. The fact is that it would be trivial to add the appropriate functions and macros to transform your markup language into whatever markup language you wish. As a plus, you would also get the full functionality of a programming language! I know that there are a few such libraries available, but the only one that I can think of at that moment is that of PLT Scheme, see their page for details
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
What you want is very similar to something like XML. You could define a
set of shortcuts for yourself, and write a very simple script (e.g., in
Perl) that just fixes up your shortcuts into the real thing. For example,
if you don't feel like typing <p> at the beginning of every paragraph and
</p> at the end, you could make the rule that blank lines delimit
paragraphs; then your preprocessing script will have to insert all the
paragraph tags. (This is not as hard as it sounds; for each blank line,
you replace it with </p><p>, then you go traverse backward and forward from
that point over the largest possible wellformed block that does not include
any blank lines, and that's where you put the other start tag and end tag.
The hardest part about this is writing a parser that can go either direction
(forward or backward) and understands what "wellformed" means.)
Any other shortcuts you want to define are fine too, as long as you can write
the preprocessor to turn them into the desired equivalent standard markup.
Run your stuff through your handrolled preprocessor script, and you've got
standard markup.
Of course, you want to pick the standard markup that's closest to your
needs, both in terms of requiring the minimum amount of work out of your
preprocessor and in terms of being able to be converted into the maximum
range of other formats using standard off-the-shelf tools. DocBook has
been suggested, and it's hard to disagree, but XHTML will probably do in
a pinch, especially with judicious use of classes to mark things like
sidebars and examples. You could have a rule, for example, that a level
2 header introduces a new chapter, and that sort of thing, so that it
would be relatively easy to use XML::Parser or the equivalent (or even
XSLT if you're into that) to transform your final document into whatever
format you happen to want it in, including DocBook or whatever.
Cut that out, or I will ship you to Norilsk in a box.
I'm surprised that I didn't see Textile mentioned here. It's a simple, yet fairly powerful human readable markup language. Examples:
You can make a span of text *bold by using asterisks,* or _italic by enclosing it in underscores._
* bulleted lists
* are easy
* to make...
|Here's a table cell|and another|one more|
|another|row|here|
There are many other styles; and simple ways to mark spans with styles and classes (for html output).
For more information, examples, and a live demo, look at http://www.textism.com/tools/textile/
If it's sufficient for your needs I'd _really_ reccomend asciidoc.
Take a look at: http://www.methods.co.nz/asciidoc/userguide.html
Brilliant for minimal markup, easy readability and conversion into other formats.
Sure, Waterloo Script is a 370-ish system, but it's just one of an entire class of early text formatters that all share characteristics and derivations. One called "nroff" you might find vaquely familiar :-)
http://www.gnu.org/directory/GNU/texinfo.html