mojombo / tomdoc

A flexible code documentation specification with human readers in mind.
333 stars 47 forks source link

Any Markup Support #5

Closed trans closed 14 years ago

trans commented 14 years ago

Does TomDoc support any markup at all? Bold, italic, hyperlinks, etc? While I fully understand the goal of readable plan text, at the same time we want to produce even nicer production output. There must be a reasonable middle ground.

defunkt commented 14 years ago

Use whatever markup you want. TomDoc isn't RDoc and shouldn't put that kind of stuff into the spec.

For my tomdoc generator I'd like to eventually support whatever - Markdown, Textile, RDoc, anything.

I love that TomDoc is so syntactically sparse that swapping out markups is possible.

mojombo commented 14 years ago

I personally don't much care to put markup in my docs and I don't think TomDoc should take a stance. Like Chris said, if formatters want to respect various markups then that's their choice. I'd encourage writing in a plain way that doesn't require a lot of fancy formatting over cluttering things with a ton of markup.

trans commented 14 years ago

I agree. But light markup like ~italic~, bold, underline, +code+ and link[http://...] can be pretty useful.

So if TomDoc is formatter neutral how does one apply a custom formatter?

anibali commented 14 years ago

For readability of plain text documentation I prefer using backticks for code/commands. Using + or @ doesn't quite seem to hold much meaning for human readers... I suppose it's just a matter of opinion, though.