As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance.
Closed 11 years ago.
Please identify the most popular lightweight markup languages and compare their strengths and weaknesses. These languages should be general-purpose markup for technical prose, such as for documentation (for example, Haml doesn't count).
See also: Markdown versus ReStructuredText
I know of three main languages used commonly in the greater programming and tech community: Textile, Markdown, and reStructuredText. All three can be learned in a couple of hours or "winged" with the cheat sheet nearby.
Textile
Used by Redmine and the Ruby community
113 questions currently tagged on Stack Overflow
The most similar to HTML, but least readable source
Easiest nested lists of all three languages
Not understandable to non-programmers or the HTML-ignorant
Ideal for complex short documents (with links, nested lists, code, custom HTML); for example: short documentation, how-tos, blog or CMS content
Syntax reference
Markdown
Doesn't seem to have a home language "community" but...
1274 questions tagged on Stack Overflow*
Emphasizes source code readability, similar to email traditions
Straightforward HTML embedding (you just type the tags out)
No way to make tables besides embedding HTML
You know it already if you know Stack Overflow
Easy to learn if you already know reStructuredText
Automatic email address obfuscation for the format <address#example.com> (with angle brackets)
Syntax reference
reStructuredText (A.K.A. ReST)
Popular in the Python community
285 questions tagged on Stack Overflow
A bit persnickety about whitespace and alignment if you ask me
Lists (especially nested lists) and paragraphs always seem to get in fights
Readable by non-programmers
Only format which can build a table of contents (via an extension in the Python reference implementation)
Directly converts to other formats like PDF and XML
Ideal for large documents with lots of prose (e.g. an alternative to docbook for a user manual)
Syntax reference
You might also consider asciidoc
relatively readable markup
straightforward command-line use
some might perceive it as relatively 'picky' (vs. flexible) with respect to syntax
docbook and (x)html output
The Wikipedia page on lightweight markup languages has a good comparison between the various options, as well as showing syntax for common uses (headings, bold, italics, etc.)
I am attempting to cover all the various lightweight markup languages here:
http://www.subspacefield.org/~travis/static_blog_generators.html
As you can see, it started with "how can I make a secure blog" - i.e. one that generates static HTML, and I found myself ensnared in markup languages, templating systems, etc.
Update
I refocused only on LWMLs with python implementations, and theyre here:
http://www.subspacefield.org/~travis/python_lightweight_markup_languages.html
So far I've tried markdown and ReST, and I like the latter better for anything but
HTML snippets embedded in other pages. Tables, cross refs, indirect links, etc...
for documentation?
how about doxygen?
I've use it for some of c/c++ project that I need to documentize.
Even you can 'abuse' it just like doxygen author uses for doxygen documentation
Related
As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance.
Closed 9 years ago.
I am going to develop an application for OS X and I need some scripting engine for it.
The purpose of the scripts is to receive a text on their input (HTML file in most cases), parse it in some way and return the data to my app. These scripts should be easily editable by the users, therefore they should have some common used syntax like C or pascal.
Can you suggest some lightweight solution for this?
Thanks!
PS. I am new to OS X development, trying to switch from Windows...
Two suggestions:
Javascript, try the V8 engine. http://code.google.com/p/v8/ Very popular, likely familiar syntax to many.
Lua. http://www.lua.org Extremely lightweight and simple to connect. If your script editors write scripts for World of Warcraft, for example, they will know Lua.
In general AppleScript/Automator actions are easy for the end user to work with since the technology includes a GUI for building scripts without much programming knowledge. For experienced developers used to other languages, they can be a bit too friendly/loose and have a somewhat different syntax (more like plain English). The good thing is that they can also call other languages as needed, so a developer familiar with Perl or whatever could incorporate that into an AppleScript or Automator action.
Since you're talking about parsing text, Perl itself would be a good solution - again there's some difference in syntax, but the scripts can be rather compact and the basics of parsing aren't too difficult to learn. I haven't personally incorporated Perl into an OS X app, I've just used it on the command line, so I don't know if there are any pitfalls to that approach.
One additional advantage to AppleScript is that you can make your application itself scriptable so that users could automate the functions of your application into a larger workflow.
I would suggest downloading the free TextWrangler application by Bare Bones Software, or a similar developer's text editor, to see how they incorporate scripting into the application. This may give you additional insight into your approach.
LUA seems to be a good choice.
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 5 years ago.
Improve this question
I'm looking into writing documentation about some functions but do not want to write the documentation in the source code.
Is there a template I can follow, e.g XML, or something which can generate some sort of Javadoc-ish looking style documentation?
There's docbook, but to be fair, docbook excels at book or manual style documentation. It does do website documentation, but its websites tend to not be as heavily interlinked as javadoc. This is an example of a docbook document rendered to a website.
Docbook excels when you have one "source document" that doesn't have a presentation in the real world, and a few "rendered documents" that all must contain correct, up to date information built from the source document.
It is hard to understand what you are looking for, mainly because it seems that you are not exactly sure yourself. Javadoc is documentation that was purpose designed to document Java code, so a "javadoc like documentation without source code" is a hard idea to follow. Perhaps if you sat down and thought about the main sections of documentation, you'd find an outline (which might heavily include the navigation you want to use). Then it would be much easier to fill in the blanks, because you have blanks.
You can use the javadoc engine to generate documentation. It is very configurable; and supports two kinds of plugins. One to add additional "tags" and one to add / override additional "layouts". However, these tags and layouts operate on an API that tends to be Java source code oriented, such that a "javadoc comment before a class" calls a method that effectively handles the javadoc for this class. As such, without Java source code (or something very like it) you have the wrong underlying API (unless you can bend it to your needs).
Maybe you are looking for something like Doxygen, an API-documentation tool that can also be used to write other documents (f.ex. the manual of doxygen was produced with Doxygen itself without normal source code.)
Another tool would be Sphinx, which can also be used for API-documentation and also manuals without source code (ex: Python documentation).
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 5 years ago.
Improve this question
I'm the author of a fairly sized (and growing) framework. It primarily exposes JavaScript APIs, but also has public APIs in Ruby and a growing CoffeeScript segment. (CoffeeScript will eventually encompass most of the project, but there will always be a significant pure-JavaScript presence.)
Up until now, I've been documenting the JavaScript with PDoc and the Ruby with RDoc. Though I've no issues with RDoc, unfortunately PDoc is aging, high-maintenance, and requires a heck of a lot of typing that feels like superfluous clutter. Also, the transition of most of the code to CoffeeScript renders PDoc much less useful than it was.
Example of the project's current documentation
I've experimented with Rocco in a local branch and it works better than I expected. What's really nice is that it works with all my code, from Ruby to Coffee to JS. It's nice to see all the documentation in one place. It's kind of cool to see the source code next to the documentation, too, and this makes it very clear what a particular code segment is actually doing.
However, I am a bit worried about the overall structure. Docco/Rocco seems great for niche projects with very few public APIs, but its read-the-entire-project style strikes me as a double-edged sword. Though it's very informative, having to vertically scroll through the files without even a table of contents (not to mention, knowing which file to go to in the first place!) seems like it would make it difficult to actually find anything. Also, the default template required some hacking because the list of files was too long to be displayed. Not a huge deal but an annoyance, and a hint that this project may be out of Rocco's league.
I'm now considering CoffeeDoc. Judging just by the example, it seems promising, but it is of course Coffee-centric, which brings me back to running 3 separate documentation tools: RDoc, CoffeeDoc and -- what? JSDoc?
I'm not completely adverse to running separate tools for the separate sources, but it becomes hard to reconcile that into a coherent result that doesn't feel like 3 separate Web sites.
So I guess my question is: what tool do you use or suggest? What language(s) does it support? Is it easy to browse, read, and actually find a needle in the haystack that is your project? I'm even considering rolling my own tool at this point, except that I can't believe no one else has encountered a problem like this (and I don't really want to waste time if I don't have to).
Sphinx directly supports javascript. Documentation of Ruby and CoffeeScript is supported through extensions (https://bitbucket.org/birkenfeld/sphinx-contrib/).
From the website:
The following features are present, work fine and can be seen “in action” in the Python docs:
Output formats: HTML (including Windows HTML Help), LaTeX (for printable PDF versions), manual pages, plain text
Extensive cross-references: semantic markup and automatic links for functions, classes, citations, glossary terms and similar pieces of information
Hierarchical structure: easy definition of a document tree, with automatic links to siblings, parents and children
Automatic indices: general index as well as a module index
Code handling: automatic highlighting using the Pygments highlighter
Extensions: automatic testing of code snippets, inclusion of docstrings from Python modules (API docs), and more
As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance.
Closed 11 years ago.
my development style brings me to write a lot of throw-away "assisting" code,
whether for automatic generation of code parts, semi-automated testing, and generally to build dummies, prototypes or temporary "sparring partners" for the main development; I know I'm not the only one...
since I frequently work both under windows and Unicies, I'd like to non-exclusively focus on a single "swiss army knife" tool that can work in both the environments with limited differences, that would allow me to do usual stuff like text parsing, db access, sockets, nontrivial filesystem and process manipulation
until now under unix I've used a bit of perl and massive amounts of shell scripts, but the latter are a bit limited and perl... despite being very capable and having modules for an incredible array of duties, sincerely I find it too "hostile" for me for something that goes beyond 100 lines of code.
what would you suggest?
scripting is not a requirement, it would be ok to use more static-styled languages IF it makes development faster (getting programs to actually do their work and possibly in a human readable state) and if it doesn't become nightmarish to handle errors/exception and to adapt to dynamic environments (e.g. I don't like to hardwire data /db table structure in my code, especially by hand).
I've been intrigued by python, ruby, but maybe groovy (with its ability to access the huge class library and his compact syntax) or something else is better suited
thanks a lot in advance!
(meanwhile, on a completely different note, scala looks really tempting just for the cleanliness of it, but that's - probably - a completely different story, unless you tell me the opposite...?)
Python is arguably one of the best choices. Its biggest benefit is that it has a huge built-in library for doing all sorts of stuff. It is also mature, very cross-platform, actively developed, and has many support options (mailing lists, newsgroups, etc).
In addition, it has a built-in GUI toolkit (tkinter) for those times when you need to write a quick GUI to get input from a user or display output from a running process. And if you don't like tkinter, there are other cross-platform GUI toolkits available.
I suggest Python.
For me it has a sweet spot of good libraries, documentation, community, cross-platform functionality, and ease of writing/reading.
It fills a similar niche to Perl's, but if you find Perl to be 'hostile' for longer scripts, you will probably like Python, especially when compared to Ruby, which feels more Perl-y, IMHO.
As an aside, all of these are quite easy to just try out - why not do that?
Then you can decide for yourself instead of trusting the questionable wisdom of an online forum (:
I think that Python and Ruby are your best bets, depending on exactly how you think and code.
I personally find Python EXTREMELY readable and its syntax is highly intuitive. I've heard Python described as "pseudo-code plus colons."
On the other hand, once you get around its slightly bizarre syntax, Ruby makes for high-speed development. It's built around DRY principles and convention-before-configuration, which is great for rapid prototyping.
There are other languages--especially Haskell and the Lisp dialects--that can make for super-rapid prototyping, but they don't have as large a supportive community, so there's a shortage in library and discussion supply.
As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance.
Closed 10 years ago.
I have a .rtf document (with an image, it's not just text), what haskell libraries are there out there to help me in my quest, or is it way easier than it appears?
Some years ago, I wrote a parser (in Perl) for a very limited and specialized subset of RTF, and even that was a huge project. It would be great if you want to write a general RTF parser in Haskell; but if you need to get work done, I recommend using an existing product.
Besides MS Word and web services suggested by others, here are a few other open source possibilities:
OpenOffice.Org has a good cross-platform RTF parser, though it might take some work to get it to run without human intervention.
GNU UnRtf
rtfreader, a port to Unix of Microsoft's reference parser.
rtf2latex2e
rtf2html
rtf2tex, rtf2latex, rtf2text, and rtf2troff for Unix from the early 1990's are still available, they might even still work on modern systems.
All except the last are available on MacPorts. Check your local Linux distribution for availability there. Follow the above links to see which of the above are available for Windows.
All of the above are in C, so it's possible to create Haskell bindings to them using FFI, with varying degrees of difficulty. The only one which I would expect to be really hard is OpenOffice.Org.
Call a web service to do the work such as the PDF Converter Services. It supports RTF.
I worked on this product so obviously I am biased. It works very well though, lots of happy users.
The first tool I would turn to is pandoc, however, it looks like it can only write .rtf, not parse it. Similarly txt2rtf supports writing .rtf, not reading it.
On the pdf side, HPDF has support for generating pdfs, and HsHaruPDF has some support for reading pdfs. line2pdf can generate pdf from ascii input.
Is it possible to convert the .rtf into a form pandoc can recognize?