A Powerful, but Minimal Document Markup Language? 66
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?"
DocBook (Score:4, Informative)
You're looking for ReStructured text, my friend (Score:5, Informative)
Re:You're looking for ReStructured text, my friend (Score:2)
This is what I use: (Score:2, Informative)
suck it up. (Score:3, Interesting)
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.
Re:suck it up. (Score:4, Insightful)
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.
Re:suck it up. (Score:1)
XML and XSL are so easy to use at this point that creating an adhoc markup language would be reasonably easy.
On a tangent, does anyone know if thoughts have been made about moving TeX to XML?
Re:suck it up. (Score:2)
Questions like, "Why does it say, '<section> does not match </para>?' I'm not a computer person; I just want it to work," certainly come to mind. And you know what? The luddite is right in this case.
Re:suck it up. (Score:1)
Re:suck it up. (Score:1)
Er... (Score:3, Informative)
Wiki! (Score:3, Informative)
Re:Wiki! (Score:2, Informative)
Wiki? (Score:2)
GNML in parent post links to tubgirl via redirect (Score:1, Offtopic)
Thanks to all the moderators who didn't bother following links.
Re:GNML in parent post links to tubgirl via redire (Score:1, Offtopic)
<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
Stick with Docbook, get a good editor (Score:3, Informative)
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 [xmlmind.com] 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.
XHTML? (Score:5, Insightful)
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.
XHTML w/ CSS (Score:2)
Re:XHTML? (Score:2)
Re:XHTML? (Score:1)
I think there is a missconception about using TWO different languajes of a single document, but is like vim [vim.org], once you get to know how to use it, it's as good as it can get.
Re:XHTML? (Score:2)
XHTML is a step in the wrong direction.
Re:XHTML? (Score:3, Informative)
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
Re:XHTML? (Score:3, Informative)
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
Re:XHTML? (Score:2)
Except that all (X)HTML tools include sundry items like "bold," "italic," "18pt sans-serif," and "horizontal line," and "red." These are all presentation concerns that have no place in standardized documentation.
I guess that's why I clearly stated a SANE subset of XHTML. He has the ability to define the specific subset of XHTML he wishes to support. As someone mentioned good XHTML contains no formatting information. Rather all formatting information is provided via a stylesheet that references class
Re:XHTML? (Score:2)
Pray tell, how would this be done? With the crap XML editors out there that are only vaguely better than using Notepad? If there were good XML editors, he would just use DocBook XML. Hint: If you have to interact with the tags, it's not a good editor. <para> especially. Correction: <para> included. <br /> especially.
A WYSIWYG with XHTML? Show me one without presentational controls and I'll listen. If
Re:XHTML? (Score:2)
A WYSIWYG with XHTML? Show me one without presentational controls and I'll listen.
Well, I've used ewebeditpro [ektron.com], and it has the ability to enable only the markup that you are looking for. That means that you can disable the bold button. In fact to can disable any button you want. You can create new buttons. That allows the guy who's specifying the format to configure the editor, and once again all is well with the world. This is of course the only one that I'm familiar with, but I'm sure that any per
Conflicting requirements (Score:5, Insightful)
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.
Re:Conflicting requirements (Score:2, Informative)
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,
Re:Conflicting requirements (Score:2)
Thank you.
Re:Conflicting requirements (Score:2)
On the contrary, they are not necessarily. What he's asking for is a complete lack of presentation (eg. a section header rather than 18pt bold on
Waterloo Script! (Score:1, Informative)
Re:Waterloo Script! (Score:2)
Re:Waterloo Script! (Score:2)
I hope you have a spare System/370 lying around to run it... (look at the bottom of the linked-to page). On the bright side, it does run in 1 meg of RAM... or 0.5 meg if you discard the built-in spell-checker.
No mainframe needed (Score:2)
Wiki? (Score:3, Informative)
PhpWiki TextFormattingRules [sourceforge.net]
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
UML (Score:2)
Yes I know this isn't what UML is but I've got Karma to burn
Re:UML (Score:1)
YAML yaml yaml... (Score:2, Informative)
http://www.yaml.org/
Re:YAML yaml yaml... (Score:2)
Good luck getting the offtopic :)
Re:YAML yaml yaml... (Score:1)
Small Markup: three suggestions (Score:3, Informative)
Another approach is simply to define your own markup language. Since your needs are simple, you probably don't need to validate [montana.edu] your documents, so an informal description of a well-formed [developer.com] 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 [w3.org].
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 [yahoo.com]
txt2tags // ONE source, MULTI targets (Score:3, Informative)
Simplified DocBook (Score:3, Interesting)
Markdown (Score:4, Informative)
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/ [daringfireball.net]
There is also a flavour which guarantees XML-wellformedness, called xMarkdown (you can find a link to it on the Markdown list).
groff (Score:2)
================
`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, `
Re:groff (Score:1)
A good intro text for Troff systems, Gnu or otherwise, is UNIX Text Processing by Dougherty and O'Reilly.
Good book. I think its out of print though.
Re:groff (Score:2)
Doco (Score:1)
Re:Doco (Score:1)
Wiki is what you want.... (Score:2, Informative)
A wiki brings a lot to the ta
ReSTructured Text and DocUtils (Score:3, Interesting)
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
LaTeX (Score:3, Informative)
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.
use lisp or scheme with macros ... (Score:1)
HTML, sed, printer (Score:3, Interesting)
kprinter -j none --nodialog destfile.html
If you want PDFs instead of hardcopy, use CUPS and add "-P nameofPDFqueue".
Slightly-modified standard markup. (Score:1)
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
Textile, I say! (Score:1)
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/t
Asciidoc (Score:2)
Take a look at: http://www.methods.co.nz/asciidoc/userguide.html
Brilliant for minimal markup, easy readability and conversion into other formats.
texinfo (Score:2)
http://www.gnu.org/directory/GNU/texinfo.html [gnu.org]