output format

[iannsp]

what about Doc support more then MarkDown as output format?

[alganet]

May be useful, but I don't see this as a priority. Markdown is a kind of a lingua franca for documentation and there is a lot of converters out there. From the Markdown itself we can generate HTML, PDF, even slide presentations using landslide.js!

We also discussed (but, shame on us, never documented this) to reuse the generated Markdown. For example, if the user changes the order of the classes documented, Doc could be able to regenerate it incrementally keeping the desired order. If the user adds his own sections to the generated README, we could keep them. Replicating this to other formats could slow us down, while Markdown only keeps the retroparsing simple.

Were you thinking on any particular format?

[iannsp]

add other mainstream format as man pages, for instance

[alganet]

Just Googled this! http://rtomayko.github.com/ronn/ronn.1.html

Not sure about the usage or how good the man page output is, but we could research it. I believe almost every text form could be extracted from the Markdown itself! =D

[iannsp]

and what about latex?

[alganet]

Latex is definitely a plus one. It's probably the most flexible and powerful format we could ever think. We could even add graphics and such.

There are tools like MultiMarkdown and Lunamark that can convert Markdown to almost any other format including Latex. We didn't research these tools deeply, just explored some possibilities. It may be more straightforward to use an external tool for this when we need it. I can see Latex being useful in the future, but we have a lot of other features that could be done first that I don't believe we should focus on this now.

We discussed Markdown but never documented why we decided to stick with it as our first documentarion format: It's readable by humans as a plain text file, it can be used as the default README.md for our own GitHub projects, can be used in http://documentup.com to generate an HTML, browseable documentation and it's very simple to parse and reuse.

All of these qualities can be used right now by our own projects: we can start automagically document our components without much effort and put an online documentation automatically with DocumentUp.

Another format we considered as a complementary format, not a main one, is the GraphViz declaration file for generating architectural graphs, but we didn't feel that this was the right time to implement it, since it gives us almost nothing to integrate with another projects.

[augustohp]

Found this some time ago, this can be useful to support many other file formats that can be geberated from Markdown: Pandoc

[alganet]

Both Pandoc and Gitit (from the same author) could be really useful. I have a kind of platonic love for Haskell: in love with the idea but afraid of trying things out, just flirting with it).

[nickl-]

I was just going to add then saw @alganet one step ahead of me

Just Googled this! http://rtomayko.github.com/ronn/

Not sure about the usage or how good the man page output is, but we could research it. I believe almost every text form could be extracted from the Markdown itself! =D

Or am I one step ahead because I've used it =) see git-extras for examples. I wrote a script that creates and maintains an index which gets generated as hyperlinks in the html which you can see here on my gh-pages nickl-/git-extra as examples.

Verdict: ronn is a ruby gem not my most favourite things in this world but I can't complain. It installed first time and kinda does it's own thing you just point it at the markdown and it will do the rest. Which can be good and bad, for example it generates the html in the man naming convention .1.html which could be odd.

It has quite extensive documentation and I have to admit that when I needed something (to generate the links as seen on the gh_pages, I really can't complain that it was difficult to find the information or that it was difficult to implement. That said it still feels like you have to weigh the pro's and cons you either loose some functionality on the markdown which then affects the man pages and so for. They don't all seem to be exact replicas, understandably there will be differences based on limitations. I don't know what exactly is involved in man pages but all it takes is one look in these generated files and I concur happy being a panda and grateful to Ryan Tomayko for making the effort. This is how I know to make man pages and will definitely use it again.

[iannsp]

we need keep in mind the dependencies control... I do no what effects can become to surface if we start add dependencies from another projects. I prefer the ideia of interfaces for this tools, most like "select a template engine" for a system....

[augustohp]

I like minding the dependencies, but I will be just an ass**\ now by saying: do we currently need to support another format?

There are many tools that can transform markdown to another format (man pages and latex, for example). That is not where I would focus our efforts on now IMHO. We have huge mountains to climb with Doc and a lot of them have to do with code analysis, if we are not able to properly document a project, there is not a lot of importance on how we are going to display it.

@nickl- git-extras is awesome!

[alganet]

I like the "drivers" idea, but I really believe that these drivers should be very simple (50 lines top each one).

There are some things safe to depend. Default things (like GNU Make, PEAR, PSR-0), easily-available things (GitHub, Packagist, libxml2 for DOMDocument, Apache, jQuery), easily installable things (VirtualBox, FireBug, XDebug).

Pandoc is easily available in all operating systems, have default packages in most distributions and is easy to manually install. The Haskell Platform is also available in all possible imaginable environments.

Being drivers only tools called by shell execs in around 50 lines, we can add lots of them and support virtually anything, maintaining heavily those who are most used!

[augustohp]

Could not agree more with something. I like that idea.

But how this issue stands? Open, closed, in discussion, wishlist? It is closed for me.

[augustohp]

I am closing this since with Markdown we can reuse another tool to generate another documentation formats.